Retool Agents best practices
Best practices for Retool Agents.
Follow these best practices when building and deploying Retool Agents.
Write effective instructions and tool descriptions
Clear, well-written instructions help the agent choose the right tools and complete tasks in fewer steps, which reduces both latency and cost. Specific tool descriptions help the agent select the right tool on the first attempt. Descriptions are limited to 2,000 characters — use that space to clarify when and how each tool should be used.
Limit and configure tools
Connect only the tools required for the agent's specific function. A shorter tool list reduces the chance of the agent selecting an inappropriate tool and improves decision-making speed. Configure explicit timeout thresholds for each tool to prevent long-running calls from blocking the agent. The default tool handler timeout is 10 seconds; child agent tools allow up to 8 hours maximum.
Minimize tool output
Agents inject tool output directly into the LLM context. Large outputs consume tokens quickly and can push the agent toward the model's context limit. Return only the data the agent needs for the next step.
Tool output is limited to 1 MB. If a tool returns more than 1 MB, the call fails with an error.
Choose the right model
Use the fastest model that can handle your agent's task effectively. More capable models cost more and are slower—reserve them for tasks that genuinely require advanced reasoning.
Manage iteration limits
Agents run up to 10 iterations by default, with a maximum of 50. Start with the default and increase only if your task genuinely requires more steps. Higher iteration limits increase both runtime and cost.
Example
A data summarization agent that fetches from one source and formats the output rarely needs more than 3–5 iterations. An agent that orchestrates multiple sub-agents to gather and reconcile data from several systems may need 15–20.
Test thoroughly
Use the built-in chat interface to test agents against the latest saved version before deploying to users. Use evals after significant changes to instructions or tool descriptions to compare results across versions and catch regressions early. Test with unusual inputs, missing data, and failure scenarios — not just the default or error-free user journey.
Monitor and debug
Use agent run logs to debug unexpected behavior. Logs include inputs, outputs, thoughts, and runtime details for every tool and LLM call. Use the monitoring page to track runs, errors, token usage, cost, and runtime in production. Periodically review the monitoring page to identify agents with high error rates, excessive token usage, or unexpected runtime patterns.
Logs are retained for 30 days. If a run's logs are no longer available, you'll see a message indicating they've expired.
Handle errors in custom tools
Return descriptive error messages from custom tools so the LLM can understand what went wrong and attempt recovery. Generic or empty error responses make it harder for the agent to adapt.
Use version descriptions
When saving an agent configuration, include a description of what changed and whether it was a major, minor, or patch update. This makes it easier to identify which version introduced a regression.
Scope access carefully
Follow the principle of least privilege when permissioning agents. Grant only the access required for the agent's function, and limit tool access to only the data the agent needs. Use OAuth to authenticate tools where possible so that data access is scoped to the user's permissions rather than a shared service account. Use role-based access control to ensure that agent builders can only connect tools and resources they're authorized to use.
Example
An agent that answers HR questions should only have access to HR data — not finance or engineering resources — even if the agent builder has broader access.