Why is a tool's description field a prompt rather than documentation?

## The description does a job, not a favour A tool description is prompt text. It sits in context on every turn, and the model uses it to answer one question: given what the user just asked, should I call this, and with what? Nothing else about the tool is available to it. So the writing standard is not "is this an accurate account of the function" but "does this text reliably produce the right decision, including the decision *not* to call". That reframing changes what goes in. Reference documentation optimises for completeness and for a reader who can ask follow-up questions. A description optimises for a reader who cannot ask anything, will read it exactly once per turn, and is simultaneously reading a dozen other descriptions. ## The four things a good description carries **1. Capability.** What the tool actually does, in the caller's vocabulary, in one sentence. Prefer the domain's words over your codebase's words: "file a first notice of loss" beats "invoke the FNOL intake pipeline". **2. Preconditions.** What must already be true. For a claims-filing tool: the incident has occurred, the policy is active, the caller has supplied a policy number. Preconditions are how the model learns to gather missing information from the user before calling rather than guessing at it. **3. Argument provenance.** For each non-obvious field, where the value legitimately comes from — the user's own words, a prior tool result, a fixed vocabulary. This is the single most effective defence against invented arguments, and it belongs partly in the per-field descriptions inside the schema. **4. Negative guidance.** The requests that look like a match but are not. This is the field's highest-value content and the most commonly missing. Models are cooperative; a plausible-looking tool in scope will get called unless the text says otherwise. ## A worked rewrite Start with the description as most teams first write it: > Files a claim. Three words, syntactically fine, operationally useless. The model cannot tell whether "I want to know what happened with my claim from March" matches, nor whether a policy number is needed, nor which of six claim categories a burst pipe belongs to. Now the forty-word version: > File a first notice of loss against an active auto or property policy. Requires a policy number and an incident that has already occurred. Do not use to check the status of an existing claim, to quote or compare coverage, or to change policy details. Same capability, and now three decisions are determined by the text: when it applies, what must be collected first, and which adjacent intents route elsewhere. Note the shape — capability, preconditions, then the explicit "do not use" clause. That template travels well. ## Why models over-call, and why negative guidance works An instruction-tuned model biases toward being helpful with the affordances in front of it. If a request is roughly in the neighbourhood of a tool's stated purpose, the model will usually reach for it, because from its position calling something plausible looks better than declining. A description that only states the positive case leaves the entire boundary undefined and the model fills it in optimistically. Stating the boundary explicitly is not redundancy — it is the only place the boundary exists. The reverse failure exists too. Descriptions loaded with warnings and hedges can suppress a tool that should fire, leaving the model to answer from parametric memory when it should have looked something up. The calibration is empirical: change the text, re-run a fixed set of representative user turns, and look at what got called. ## Register and length Write in the imperative, in the second-order voice of an instruction to an assistant. Keep it dense: every sentence should change a decision. Fifty to eighty words is a typical landing zone for a non-trivial tool — long enough for preconditions and exclusions, short enough that it does not dominate the context shared with every other tool's definition. Avoid implementation detail (which service it hits, which table it writes) unless it changes the model's behaviour; the model cannot act on it and it costs tokens on every turn. A useful discipline: after writing, delete every sentence that would not alter what the model does. What survives is the description. ## Where descriptions come from Many frameworks generate the description from a docstring. That is convenient and usually wrong on first pass, because docstrings are written for maintainers — they explain how the function works and omit preconditions and scope, which are exactly the model-relevant parts. Treat generated text as a draft, then rewrite it as instruction and read the serialized definition to confirm what the model receives.