Tool Descriptions That Work

A model selects tools from names and descriptions alone. Most selection failures are description failures, not model failures.

Every tool description must state:
1. What it does, in one sentence, in the imperative.
2. When to use it, concretely.
3. When NOT to use it, and which tool to use instead. Missing negative guidance is the single biggest cause of wrong tool selection.
4. Whether it is destructive or irreversible, in the description itself, not only in the schema.
5. What the response looks like and how large it can get.

Also check: no two tool names a model could confuse, no required parameter a model would have to guess, and error messages that tell the model what to do differently rather than only that something failed.