Writing AI Agent Tool Descriptions the Model Actually Uses

Your agent keeps calling the wrong tool, passing a date as free text, or skipping the one function that would have answered the question. You blame the model and reach for a bigger one. The real lever is smaller and cheaper: the words you wrote next to each tool. The model never sees your code. It sees a name, a description, and a JSON schema, and it decides entirely from those.

Why do ai agent tool descriptions decide tool-use reliability?#

Because the model picks and fills every tool from three inputs only: the name, the description, and the parameter schema. It never reads your implementation, so ai agent tool descriptions are the entire interface. A vague description leaves the model guessing at intent, arguments, and units, and guessing is where reliability quietly breaks.

Anthropic's tool use documentation is blunt about this: the single most important factor in tool-use accuracy is a detailed, unambiguous description, and giving the model more description text generally helps more than adding more examples. Think of it as the interface spec a caller reads before wiring anything up. If a new engineer could not use your tool correctly from the description alone, neither can the model, which has strictly less context than that engineer.

The same tool, two descriptions. The vague one leaves the model guessing at intent, arguments, and units; the precise one removes the guess.

The failure modes are predictable once you see the description as the contract. Two tools with overlapping descriptions get confused, so the model routes to the wrong one on ambiguous prompts. A required argument with no hint gets left blank or hallucinated. A constrained field with no enum gets a plausible-but-invalid value. An ambiguous unit turns 5 into 5 seconds, 5 minutes, or 5 dollars depending on the model's mood.

What does a good tool description actually contain?#

A good description states what the tool does and when to use it, and just as importantly when not to. It describes every parameter with type, format, allowed values, and units, gives at least 1 concrete example, and flags side effects: does this call write, charge, send, or delete? Write it like onboarding docs for a careful new hire.

The what-and-when line is the routing signal. "Get the current weather" is weak; "Get the current weather for a city; use only for present conditions, not forecasts" tells the model both the job and the boundary. Every parameter needs its own sentence, because the schema type alone does not carry format or units. A field typed as string could want an ISO 8601 date, a 2-letter country code, or a raw phone number, and only your description disambiguates. Constrained fields get an enum so the model cannot invent values. And side effects belong in the description because a model that knows a tool sends an email will hesitate before firing it twice.

Score any description against these before you ship it. Missing elements are exactly where the model starts guessing.

Here is a compact rubric you can score any description against before you ship it.

How do you write and tighten a tool description?#

Write it in 5 passes, each fixing one class of ambiguity. Name the tool for its job, state what and when in the first line, then document every parameter with type, format, enum, and units. Add 1 example call, note any side effects, and test it against adversarial inputs.

The order matters because early passes remove the ambiguity that later passes depend on. If the name and purpose are unclear, no amount of parameter detail rescues routing. Once the purpose is sharp, parameter documentation stops the argument errors, and the example gives the model a template to copy under pressure. Treat the last pass, adversarial testing, as non-optional: feed it partial inputs, wrong units, and prompts that sit between two tools, and watch where it slips.

Each pass closes one class of ambiguity. Do them in order, because parameter detail cannot rescue an unclear purpose.

This is exactly the discipline behind n8n's $fromAI pattern, where each tool sub-node on the AI Agent exposes a description and the model fills the parameters at run time. The fill accuracy is a direct function of how well you described each field. The same holds whether you wire tools by hand in the Anthropic or OpenAI SDKs or through a builder. If you are assembling these in n8n, the mechanics of attaching and describing tools are covered in our guide to n8n AI agent tools.

Why did the agent pick the wrong tool, and how do you fix it?#

Start from the description, not the model. When an agent misroutes, the cause is almost always one of 4 things: two descriptions overlap, a purpose is too vague to match intent, a required argument has no hint, or a constrained field has no enum. Each one maps to a cheap edit, not a model upgrade.

Overlap is the most common and the most fixable. If search_orders and get_order both say "retrieve order information," the model has no basis to choose, so make each purpose disjoint and say when not to use the other. A blank required argument usually means the description never told the model the field was mandatory or what it looks like, so add the format and an example. Invalid enum values mean you left a constrained field open, so close it. Walk the decision tree below the next time a wrong call shows up in your logs.

Start from the description, not the model. Each branch ends at a specific, cheap edit to the description or schema.

Where do you go from here?#

Rewrite your 3 most-called tools as if onboarding a new hire, then let your logs tell you the rest. The pattern is durable: the model reads only name, description, and schema, so that surface is where reliability is won or lost. Precise descriptions beat a bigger model on tool-use accuracy at a fraction of the cost.

Ship the rewrite, then watch for the tells: blank required args, invalid enums, and misroutes between similar tools. Each one points at a specific line to tighten. If your tools are Model Context Protocol servers, the same description discipline carries over, and our walkthrough of n8n with MCP shows where those descriptions live. When a tool returns data the agent must parse, pair this with clean structured output so the whole loop stays legible.