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 like 'searches the database' gets skipped in favor of 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 does not inspect your tool implementation. It sees the tool name, description, and argument schema. That makes tool routing a reading task. If two tools sound similar, or one says only searches the database, the model has little basis for choosing correctly. Real tool ecosystems show many descriptions fail to state purpose clearly, and better descriptions improve success. Write tool docs for the model the way you would onboard an engineer: what it does, when to use it, when not to, and what comes back.
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, and what it returns. That description is the interface the model actually reasons over.