Tool Description

A tool description is the text that tells a model what a tool does, when to use it, and what its arguments mean. It is the only thing the model has: it cannot read the implementation, test the endpoint, or ask a colleague what the field called status actually accepts. Every tool description is therefore part of the prompt, not documentation attached to it. Teams write them as an afterthought and then debug the consequences somewhere else. An agent that picks the wrong tool, invents an argument, calls the same tool twice with slightly different wording, or ignores a perfectly good tool in favour of a worse one is usually not suffering from a weak model — it is working from descriptions written by somebody who already knew the answer. The give-away is that the failures cluster on the tools with the vaguest text. The version that works reads like an instruction to a capable new colleague with no access to the codebase. Say what the tool does in concrete terms, state the conditions under which it should be chosen, and — the part most often missing — say when it should not be. Where two tools overlap, each description should name the other and draw the line, because the model is choosing between them and nothing else in the system tells it how. Parameters need the same treatment: what the value means, what format it takes, where it comes from, and what happens if it is wrong. Descriptions have to be maintained like prompts, not like comments. When a tool's behaviour changes, its description is a live input to production decisions, and a stale one produces confidently wrong calls rather than a compilation error. Changing wording changes behaviour, which means descriptions belong under version control and inside whatever evaluation covers the agent. Quantity matters as much as quality. A long list of tools makes every choice harder and fills context that the task needs, and the usual improvement in a struggling agent is not a better description but fewer tools in front of it — scoped to the task at hand rather than to everything the platform can do.