Key takeaway: The model’s only information about a tool is its name, description and parameter schema. Ambiguity there produces wrong calls, and no amount of prompt engineering elsewhere compensates.
The Description Is the Interface
An agent selecting among tools reads their descriptions and decides. A description reading “queries the orders table” tells the model almost nothing useful — it does not say what a query returns, which arguments are required, what happens when nothing matches, or when this tool is preferable to a similar one.
The result is wrong tool selection, missing arguments and calls made in the wrong order. Those are usually diagnosed as model limitations and are more often specification failures.
A description that works reads like guidance to a capable person who has never seen your system: what it does, when to use it, when not to, and what it returns.
Failure Modes and Their Causes
| Symptom | Usual cause |
|---|---|
| Wrong tool chosen | Two descriptions overlap |
| Missing required argument | Not marked required in the schema |
| Invented argument value | No enum, no example |
| Repeated identical calls | Result did not indicate completion |
| Gives up after one failure | Error message was not actionable |
| Calls tools in wrong order | Dependency not stated in description |
Overlapping tools are the most common problem in agents with many capabilities. If search_orders and find_order_by_id both exist with similar descriptions, the model picks inconsistently. Merging them, or describing precisely when each applies, resolves it.
Error messages matter more for agents than for humans, because the model can only act on what the message says. Returning “invalid request” gives it nothing. Returning “start_date must be before end_date; received start 2026-05-01, end 2026-04-01” lets it correct the call on the next attempt, which turns a failure into a self-repair.
Designing the Tool Surface
Keep the set small. Model reliability degrades as tool count grows. Fifteen well-chosen tools outperform forty granular ones, and the difference is substantial. Where many capabilities are needed, group them behind a smaller number of tools with a mode parameter, or route to different tool sets by task.
Make each tool do one complete thing. A tool that returns a customer record is better than three tools returning fragments the model must assemble.
Constrain arguments with enums and formats. A status parameter accepting one of four named values cannot receive an invented one. This is the cheapest reliability improvement available.
Return structured results with an explicit outcome. A response saying {"found": 0, "results": []} is unambiguous. An empty array alone invites a retry, because the model cannot tell whether the call failed or the answer is genuinely nothing.
Scoping for Safety
Tool design is also the security boundary. A tool that executes arbitrary SQL gives an agent — and anyone who can influence its input through prompt injection — the ability to read or modify anything.
Scope each tool to the narrowest operation that satisfies the use case, and enforce authorisation in the tool implementation against the requesting user rather than trusting the model to respect it.
Require confirmation for irreversible actions, and show the user the concrete operation rather than the model’s summary of it.
The Bottom Line
Write tool descriptions for someone unfamiliar with your system, stating when to use and when not to. Keep the set small, use enums and required flags in the schema, return explicit outcomes, and make error messages specific enough that the model can correct itself.
