Chapter 2 · Practice 1 of 4
Build a few well-chosen tools instead of wrapping every API endpoint
Why it matters
Anthropic's article on writing tools for agents is blunt: more tools do not always lead to better outcomes. Every extra tool is another choice the model can get wrong.
Design tools around tasks, not endpoints:
| Endpoint-shaped | Task-shaped |
|---|---|
list_users, list_events, create_event | schedule_event that finds availability and books |
list_contacts returning everyone | search_contacts with a query |
When related tools are unavoidable, namespace them by service and resource, such as asana_search and asana_projects_search, so the model can tell them apart. The article notes that prefix and suffix naming can affect results, so test both.
Anthropic's context engineering article adds that tools should be self-contained and minimally overlapping: if a person could not say which tool to use in a situation, the model cannot either.
Do
- Combine multi-step operations the agent always does together into one tool
Avoid
- Two tools whose descriptions overlap so much that either could apply