Law 21 · Instruction & Output
The Tool Description Is the Prompt
An agent is only as capable as its tools are legible.
The principle
The agent decides what to call based on how a tool reads, not on what it actually does. A vague description — 'searches the database' — gets passed over for a tool the model understands better, even a worse one. Thin tool descriptions cause more failures than thin instructions ever do.
Why it happens
The model never sees your tool's implementation; at decision time it only sees the name, the description, and the argument schema, so tool routing is fundamentally a text-comprehension task over those few sentences. Studies of real tool ecosystems find the large majority of tool descriptions contain at least one quality problem, with many failing to clearly state their purpose, and rewriting them to spell out behavior measurably raises task success. The effect is sharp enough that vendors documenting their own tool APIs recommend at least three to four sentences per description covering what it does, when to use it and when not to, and what it returns. A terse searches the database loses to a richer competitor not because the underlying tool is worse but because the model cannot recover intent the words never carried.
Watch for
- The agent reaches for a general or external tool when a specific local one would have answered the query directly.
- Two tools with overlapping descriptions get confused, and the agent picks the wrong one or oscillates between them.
- A tool description is under one sentence or omits when to use it, what it returns, or the shape of its arguments.
In practice
You ship two retrieval tools: query_db described as 'searches the database' and web_search described as 'searches the web for current information, returns titles, snippets, and URLs'. The agent keeps hitting the web for facts that live in your Postgres because it has no idea query_db covers customer orders, date ranges, and status filters. You blame the model and consider fine-tuning. The real fix takes ten minutes: rewrite the description to spell out what tables it covers, when to prefer it over web search, the exact arg shape, and a sample return. Treat each tool description like an onboarding doc for a sharp engineer who has never seen your schema.
Apply it
- Write each description like API docs for a new engineer: what it does, when to use it and when not to, expected inputs, and a sample return.
- Disambiguate overlapping tools by stating in each description what it covers that the others do not.
- When tool selection is unreliable, rewrite the descriptions before changing the model or adding routing logic.
The takeaway
Write tool descriptions like you're onboarding a sharp new engineer: what it does, when to use it (and when not to), what it expects, what it returns. The description is the interface the model actually reasons over.