ClaudeTool useLevel 4: Multi-tool systems

How Many Tools Should You Give Claude?

Give Claude as few tools as cover the job, with clearly separate purposes. Anthropic says Claude's ability to pick the right tool degrades past 30 to 50 tools. If you truly need more, or your definitions exceed 10k tokens, use tool search so Claude only loads what each request needs.

Prompt to copy 
Here are my tool definitions, and the 10 most common jobs my agent does:

[paste both]

For each job, list the tools it needs. Then tell me:
1. which tools no job uses
2. which tools a person could confuse, and how to merge or rename them
3. which chains of 2 or 3 calls should be one tool
4. which tools return more fields than the next step uses
5. a namespaced name for each tool, such as github_list_prs

Keep read tools separate from tools that write or delete, so they can be approved separately. Give me the final list.
  • ~55ktokens in tool definitionsfive servers, before any work
  • 85%+typical cut with tool search
  • 30 to 50tools before selection degrades
  • 3 to 5tools loaded for a request
Source: Anthropic's tool search docs, checked 6 November 2026.
Endpoint per toolselection gets harder
  • create_pr, review_pr, merge_pr
  • full records returned
  • all loaded on every request
Fewer, sharpereasier to choose
  • one tool with an action parameter
  • only the fields needed
  • the rest deferred to search
From Anthropic's Define tools and Tool search docs. Above about 10 tools, or 10k tokens of definitions, its docs suggest tool search.

Try it now

  1. 1List the tools your agent has, and count them. Then check your logs for how often each was called.
  2. 2Run the prompt above with your real list of jobs.
  3. 3Remove or merge what it flags, and rerun your usual test requests.
  4. 4You'll know it worked if the same jobs finish with fewer calls and no wrong picks. If you're using MCP in Claude Code, tool search is already on by default.

Use it when

Use this when you're designing an agent's tools, when you're adding your second or third MCP server, or when logs show Claude choosing the wrong tool or making extra calls to find what it needs.

Skip it when

Don't merge tools that have very different risks. Keeping a read tool apart from a delete tool lets you approve or block them separately. And Anthropic says standard tool calling is the better fit when you have fewer than 10 tools, so skip tool search there.

Why it works

Every definition counts toward the context window. Anthropic's docs say a typical setup with GitHub, Slack, Sentry, Grafana and Splunk can use about 55k tokens before Claude does any work, and that tool search typically cuts this by over 85 percent, loading the 3 to 5 tools needed. Its tool-writing guide adds that more tools don't always lead to better outcomes, and that tools which just wrap API endpoints often fail, because agents have limited context. Its context guide offers a simple test: if a person can't tell which tool to use, neither can an agent.

Example

A support agent has 22 tools, including get_customer, get_customer_orders, get_customer_tickets and get_customer_invoices. You merge those four into customers_get with an include parameter, and a search replaces a tool that lists every customer. The refund tool stays on its own, so a person can approve it separately.

Going further

To use tool search, add tool_search_tool_regex_20251119 or tool_search_tool_bm25_20251119, and set defer_loading: true on the rest. You still send every full definition on each request, since the API needs them to run the search. At least one tool has to stay non-deferred, or you get a 400 error, and the docs suggest keeping your 3 to 5 most used tools loaded. A request can defer up to 10,000 tools. A deferred tool can't also carry cache_control. Adding keywords and prefixes like slack_ helps a search match the whole group.

Common mistakes

  • Generating one tool per API endpoint from an OpenAPI file, then wondering why Claude picks the wrong one.
  • Merging read and delete into one tool to reduce the count, and losing the ability to approve deletes separately.
  • Setting defer_loading: true on every tool, including the search tool, which returns a 400 error.
  • Returning full records, so each call fills the context with fields no step uses.

Sources

Checked 6 November 2026. Products change often, so confirm details with the vendor.

Related

Best practice How Do You Write Tool Descriptions Claude Can Use? Best practice Which Connector or MCP Server Should You Add First? Concept What Is Context Engineering, and How Do You Do It in Claude? Technique How Do You Keep a Long Claude Draft Consistent Across Chats?

Beyond the course

Glossary Context window Pricing guide Claude pricing, plans and models