Tool Distribution & tool_choice Config
Controlling which tools Claude uses and when. Too many tools (18+) degrade selection reliability. Scoping tools to agent roles with 4-5 per agent, using tool_choice modes (auto, any, forced) to control behavior, and preventing agents from misusing tools outside their specialization.
Quick Reference
- →More tools = worse selection: 18 tools degrade reliability vs 4-5 tools per agent
- →tool_choice: 'auto' -- Claude may return text OR call a tool (default mode)
- →tool_choice: 'any' -- Claude MUST call a tool, but chooses which one
- →tool_choice: {type: 'tool', name: 'X'} -- Claude MUST call tool X specifically
- →Scope tools to agent roles: a synthesis agent should not have web search tools
- →Use forced tool_choice for required first steps (e.g., always extract metadata before analysis)
- →Replace broad tools with constrained versions for specific agents (fetch_url -> load_document)
- →Cross-role tools: provide limited versions for high-frequency needs only
- →When an agent misuses tools outside its specialization, remove those tools -- don't add prompt instructions
- →Test with the exact tool set each agent will receive, not the full system tool set
The Tool Count Problem: Why 18 Tools Fail
Every tool you add to an agent's context increases the complexity of tool selection. With 4-5 well-described tools, Claude can reliably pick the right one. With 18 tools, selection accuracy drops because Claude must evaluate more options, descriptions overlap more, and the model spends more context tokens processing tool definitions. This is not a theoretical concern -- it is a measurable degradation.
Research and production experience show that agents work most reliably with 4-5 tools scoped to their specific role. If you find yourself adding more than 7 tools to a single agent, that's a signal to split the agent into multiple specialized agents.
The problem is compounded when tools from different domains are mixed. A research agent with both web search tools AND database query tools AND file manipulation tools will sometimes search the web when it should query the database, or write to a file when it should return results. Each tool outside the agent's core competency is a potential misrouting target.
| Tool count | Selection reliability | Common symptoms | Fix |
|---|---|---|---|
| 3-5 (scoped) | High -- reliable selection | Rare misrouting | Ideal state, maintain this |
| 6-8 (moderate) | Medium -- occasional errors | Sometimes picks adjacent tool | Review for overlap, consider splitting |
| 10-15 (high) | Low -- frequent errors | Regularly misroutes to wrong domain | Split into specialized agents |
| 18+ (overloaded) | Poor -- unpredictable | Random tool selection, ignores some tools | Major redesign required |