Tools are the agent's hands. Their design strongly affects how well the agent performs.
Clear Names and Descriptions
The model chooses tools from their names and descriptions. Explain what the tool does, when to use it, when not to, and what it returns. Write as you would for a new colleague.
Simple, Well-Typed Inputs
Use descriptive parameter names, types, enums for fixed options, and examples. Avoid parameters that are easy to confuse.
Do One Thing Well
Tools with a clear purpose are chosen more reliably than Swiss-army tools with many modes. But avoid dozens of near-identical tools either — consolidate where it simplifies.
Useful Outputs
- Return what the model needs, not everything available.
- Use readable formats and meaningful identifiers rather than opaque IDs.
- Paginate or truncate large results, and say so.
Helpful Errors
"File not found: /src/app.py. Did you mean /src/main.py?" helps an agent recover; a stack trace doesn't.
Match Tools to Tasks
Design tools around what the agent needs to accomplish, not just around existing API endpoints.
Test With the Model
Watch agents use your tools. Misused tools usually point to unclear descriptions or awkward interfaces; iterate.