Notes
🔍

Tool Description

A tool's description is the sentence or two of natural language attached to it in the tool definition, and it is easy to mistake for documentation. It is not. It is prompt text — the model reads it at decision time, and it is nearly the only evidence the model has about what this tool is for.

What a description has to carry
The schema declares types; the description supplies meaning:

  • What the tool does, and the conditions under which it is the right choice;
  • When not to use it — the boundary against the neighbouring tool, which is where most wrong calls come from;
  • Argument semantics — that a date must be ISO-8601, that an id is the internal one rather than the customer-facing one, that a limit above fifty is rejected;
  • Side effects and cost — whether calling it changes anything, and whether it is slow or expensive.

Treat the text as a prompt to be iterated on. When an agent keeps reaching for the wrong tool, or fills an argument plausibly but wrongly, the fix is almost always a rewritten description rather than a stronger model — and in frameworks that build the description from a function's docstring, that fix is a one-line edit.

Why it matters
Tool descriptions are where tool use quietly succeeds or fails. A vague one produces an agent that calls the right tool at the wrong moment and carries on confidently. They are attack surface as well: under the Model Context Protocol a description arrives from a third-party server straight into the model's context, so a hostile one is instruction text the agent has been handed as fact.

A tool description is the natural-language text attached to a tool definition that tells the model what the tool does and when to use it. Unlike the schema, which constrains argument types, it is prompt text consumed at decision time — so it also needs to state when not to use the tool, what the arguments mean, and any side effects. Vague descriptions are the most common cause of wrong tool calls.

Hand someone a toolbox where nothing is labelled and they will reach for the wrong thing. Label them clearly — for small screws, not for hinges — and they rarely do.

A tool description is that label. When a piece of software offers an AI agent something it can do, it attaches a short plain-English note explaining what the thing is for and when to use it. The agent reads those notes and picks. Get one slightly wrong and the agent will keep choosing it at the wrong moment, quite confidently — which is why these few sentences get rewritten and fussed over far more than anyone expects.