Prompting guidance for agents

Best practices for writing effective instructions for Retool Agents.

Agents Availability
Cloud	Public beta	Available on all plans
Self-hosted Edge 3.234 or later	Public beta	Available on all plans
Self-hosted Stable 3.253 or later	Public beta	Available on all plans

Agents perform best with clear, specific instructions. Use the following guidance when writing instructions for Retool Agents.

State the agent's purpose clearly

Specify the agent's role and goal at the start of the instructions so the model has the right frame for every decision it makes.

Example

You are a data analyst agent tasked with identifying anomalies in daily sales data.

Break down complex tasks

Use numbered steps to guide the agent through multi-step processes. This reduces ambiguity and makes it easier to debug which step failed when something goes wrong.

Example

1. Pull sales data from the provided database.
2. Calculate the weekly average sales figures.
3. Identify any days with sales deviations greater than ±15% from the weekly average.

Be precise with validation rules

State validation requirements and decision-making criteria explicitly. Don't rely on the model to infer acceptable values or formats.

Example

All phone numbers must contain exactly 10 digits. If a provided number doesn't meet this criterion, flag it and request correction.

Include error handling guidance

Tell the agent what to do when a tool fails, data is missing, or something unexpected happens. Without explicit guidance, the agent may stall or retry indefinitely.

Example

If data retrieval fails due to an API error, notify the administrator immediately with the specific error message and retry once after 5 minutes.

Keep tool outputs scoped and small

When writing tool instructions, explicitly constrain tool output size to avoid hitting the 1 MB tool output limit.

• Return only fields needed for the current step.
• Apply server-side filters (date ranges, status, IDs) before returning data.
• Paginate large datasets instead of returning full result sets.
• Summarize large text/blob responses and fetch full detail only when needed.

Refer to Tool limitations for limit details.

Provide user and context information

Use embedded expressions to give the agent dynamic context about the current user, date, and time zone. For example, {{ timezone }} evaluates to the IANA time zone name of the user's browser.

Example

You are a helpful assistant chatting with {{ current_user.name }}. Today is {{ new Date() }} in the {{ timezone }} time zone.

Refer to the Configuration section of the Quickstart guide for additional instruction guidance.

Example instructions

Task-specific

You are a data analysis assistant. When analyzing the provided dataset:
1. First identify the key metrics present
2. Calculate relevant statistical measures
3. Present insights in bullet points
4. If you spot any anomalies, highlight them separately

Context-rich

You are helping with Retool app debugging. Given the error message:
- First identify the component type involved
- Check for common configuration issues
- Suggest specific fixes
- Provide example code if relevant
Only use features available in the current Retool version.

Role-based

Act as a SQL query optimizer. For any query provided:
1. Analyze the query structure
2. Identify potential performance bottlenecks
3. Suggest specific optimizations
4. Explain the reasoning behind each suggestion

Common instruction pitfalls

Issue	Do	Don't
Vague or ambiguous instructions	Write specific instructions that include numbers or percentages when relevant.	Write short instructions that don't give the model enough context.
Too much information	Include only context directly relevant to the current task.	Include unnecessary historical context or irrelevant details.
No error handling	Specify what the agent should do when it encounters missing data or errors.	Leave edge cases and error scenarios unaddressed.
Inconsistent output format	Define the output format once, upfront, and keep it consistent.	Omit format requirements or change them mid-conversation.
Assuming prior context	Include necessary context in each instruction.	Reference information from previous conversations without restating it.
Imprecise tool usage	Specify which tool to use for particular tasks when the choice isn't obvious.	Leave tool selection entirely up to the model without guidance.
Missing validation criteria	Include specific acceptable ranges or values.	Omit what makes a response acceptable.
Unclear task order	Use "first", "second", "then" to sequence steps explicitly.	Leave the order of operations implied.
No response length guidance	Specify the desired level of detail or length (e.g., "summarize in 3–5 bullet points").	Leave response length undefined.