Your tool descriptions are the real prompt

Many agent failures trace back to the tool, not the model. The tool was described in a way the model couldn't use correctly.

A tool description is the only documentation the model gets. Treat it like the docs for a new teammate who can't ask questions.

What helps:

1. 1A name that says what it does. search_orders_by_customer beats query2.
2. 2A description that says when to use it and when not to. 'Use this to look up an order by ID. Don't use it to search by name.'
3. 3Few, clear parameters, with types and an example value for anything ambiguous.
4. 4Errors that explain the fix. 'customer_id must be 8 digits' teaches the model. 'Invalid input' doesn't.
5. 5Results that are small and relevant. Return the fields the model needs, not a 5,000-line JSON dump.

Also keep the list short. Every tool costs context, and the more look-alike tools you offer, the more often the model picks the wrong one. If two tools overlap, merge them or remove one.

You can test this without a model. Hand the tool list to a person who hasn't seen your system and ask them to complete three tasks. Wherever they hesitate, the model will too.

Which of your tools would confuse a new hire?