What should a tool description say so an AI agent uses it properly?
A tool description is the only briefing an AI agent gets before it decides whether to call your function and how to call it. If the description only restates the parameter names, the agent guesses at the rest. The four things that actually matter are: when to use the tool, when not to, what values are valid, and what to do when something goes wrong.
Why does the description matter more than the parameter list?
Most developers spend their time on the schema — the parameter names, types and whether each one is required. That is necessary but not sufficient. The schema tells the agent what shape the input must be. The description tells the agent whether this is even the right tool for the job.
An agent choosing between several tools reads the description first. If yours says 'sends an email', the agent has to guess whether that means transactional mail, marketing mail, or a reply to an existing thread. Ambiguity at the selection stage means the wrong tool gets called, and no amount of schema precision fixes that. The description is the selection signal; the schema is the formatting guide.
What does 'when to use and when not to' look like in practice?
Every tool description should open with a single sentence that names the exact situation the tool is built for, followed by one or two sentences that name the situations where it is not the right choice. This is not padding — it is the information the agent needs to route correctly.
For example: 'Use this tool to send a new transactional email to a single recipient. Do not use it to reply to an existing thread (use reply_to_message instead) or to send to a list of more than one address (use bulk_send instead).' That three-sentence block prevents the most common mis-calls without adding any complexity to the schema.
- Positive trigger
- The specific condition under which this tool is the correct choice — written as a concrete situation, not a capability.
- Negative trigger
- The conditions where a different tool should be preferred — name the alternative tool if one exists.
- Boundary case
- The edge the agent is most likely to misjudge: e.g. 'a single address that happens to be a mailing list alias still counts as one recipient here.'
How should allowed values and ranges be written?
Enumerated values should be listed explicitly, not described loosely. 'A string representing the priority' leaves the agent to invent values. 'One of: low, normal, high, urgent' does not. If the schema already enforces an enum, repeat the values in the description anyway — some agent frameworks read the description first and only consult the schema to validate, not to learn.
For numeric parameters, give a range and explain what the boundaries mean in practice. 'An integer between 1 and 100 representing the page size; values above 50 increase latency noticeably' is more useful than 'page size'. The agent can then make a sensible default choice rather than picking an arbitrary number.
| Parameter type | Minimum useful description | What to add if the stakes are higher |
|---|---|---|
| Enum / fixed set | List every allowed value | Note which value is the safe default |
| Integer or float | State the min and max | Explain what happens near the boundaries |
| Free-form string | Give a format example | Note what characters or lengths cause errors |
| Boolean flag | State what true and false each do | Note the default and when to deviate from it |
| Timestamp / date | Specify the expected format (e.g. ISO 8601) | Note the timezone assumption |
How should an error message suggest the next move?
When a tool call fails, the agent receives whatever error text your function returns. If that text says only 'invalid input', the agent has nothing to act on and will either retry with the same bad input or give up. If the error says 'page_size must be between 1 and 100; you sent 0 — try 1', the agent has a concrete correction to make.
This means error handling is part of the tool description work, not separate from it. For each parameter that commonly receives bad values, write a corresponding error message that names the parameter, states what was wrong, and suggests a valid alternative. The description itself can flag this: 'If you receive a range_error, check that start_date is before end_date.' That single line can prevent a loop of failed retries.
Tools connected to an agent operating system like GROX benefit from this especially, because the agent may be running unattended — there is no human in the loop to interpret a cryptic error and adjust. The error message is the only feedback the agent gets, so it needs to be actionable on its own.
Common questions
Do I need to write descriptions for every parameter, or just the tool itself?
Both. The tool-level description handles selection — which tool to call. Parameter-level descriptions handle correctness — how to call it. If you only write one, write the tool-level description first, because a mis-selected tool wastes the call entirely. Then add parameter descriptions for any field where the name alone is ambiguous or where invalid values are common.
How long should a tool description be?
Long enough to cover: what the tool does, when not to use it, and any non-obvious constraints. For a simple tool that does one thing with two parameters, three or four sentences is usually enough. For a tool with several parameters and meaningful error states, a short paragraph per section is reasonable. Brevity is good, but cutting the 'when not to use' clause to save space is a false economy.
Should I describe what the tool returns, not just what it takes?
Yes, particularly if the return value is used in a subsequent step. If the tool returns an ID that must be passed to another tool, say so explicitly: 'Returns a job_id string; pass this to check_job_status to poll for completion.' Without that, the agent may treat the return value as a final answer rather than an intermediate one, and the workflow stalls.
What is the single most common mistake in tool descriptions?
Writing a description that mirrors the function name rather than adding information. If your function is called send_email and the description says 'Sends an email', the agent has learned nothing. The description should answer the question the agent is actually asking: 'Is this the right tool for what I am trying to do right now, and if so, what do I need to know before I call it?'
If you want to connect your own tools or APIs to an agent that can act on them across email, code, trading and more, GROX supports MCP servers and custom connectors — see the Help Centre for setup guides.