A tool description should answer five questions
A tool description is a contract between the builder and the agent. A good one answers five questions.
When to use it. Not a feature list. The situations where this tool is the right call, and where it is not. Without this, the agent reaches for it everywhere.
What inputs it requires. Every field, what it means, which ones are mandatory. Vague inputs are where silent failures begin.
What result to expect. What success looks like when it comes back. An agent that cannot recognize success cannot check its own work.
What errors it can throw. Every failure mode, stated plainly. An agent meeting an undocumented error will misread it.
What permission rules apply. Who may call it. What needs approval. What is off limits. This is the line between useful and dangerous.
Five questions. Most tool descriptions answer one. Which one does your team skip most often.
