Anthropic Advanced Tool Use on the Claude Developer Platform: Tool Search Tool, Programmatic Tool Calling, and Tool Use Examples

Anthropic has released three beta features on the Claude Developer Platform — Tool Search Tool, Programmatic Tool Calling, and Tool Use Examples — designed to let Claude work with very large tool libraries without exhausting its context window. The company says these features enabled internal builds that were not possible with conventional tool use patterns, including Claude for Excel, which uses Programmatic Tool Calling to read and modify spreadsheets with thousands of rows.

The problem Anthropic is solving

Anthropic frames the goal as agents that work seamlessly across hundreds or thousands of tools — an IDE assistant integrating git operations, file manipulation, package managers, testing frameworks, and deployment pipelines, or an operations coordinator connecting Slack, GitHub, Google Drive, Jira, company databases, and dozens of MCP servers at once.

Three constraints block that today:

• Context bloat from tool definitions. Tool results and definitions can consume 50,000+ tokens before an agent even reads a request. Agents should discover and load tools on demand, keeping only what is relevant to the current task.
• Inference overhead from natural-language tool calling. Each invocation requires a full inference pass, and intermediate results pile up in context whether or not they are useful. Code is a natural fit for orchestration logic such as loops, conditionals, and data transformations.
• Schema limits on usage knowledge. JSON schemas define what is structurally valid but cannot express when to include optional parameters, which combinations make sense, or what conventions an API expects.

Tool Search Tool: on-demand tool discovery

Tool Search Tool lets Claude use search tools to access thousands of tools without consuming its context window. Instead of loading all tool definitions upfront, Claude only sees the tools it actually needs for the current task.

The token cost of loading every tool upfront

Anthropic illustrates the problem with a five-server MCP setup:

Server	Tools	Approx. tokens
GitHub	35	~26K
Slack	11	~21K
Sentry	5	~3K
Grafana	5	~3K
Splunk	2	~2K

That is 58 tools consuming approximately 55K tokens before the conversation starts. Adding servers such as Jira — which alone uses ~17K tokens — pushes overhead toward 100K+ tokens. Anthropic reports seeing tool definitions consume 134K tokens before optimization.

Token cost is not the only issue. Anthropic states that the most common failures are wrong tool selection and incorrect parameters, especially when tools have similar names such as notification-send-user versus notification-send-channel.

How much context Tool Search Tool preserves

Anthropic reports that Tool Search Tool preserves 191,300 tokens of context compared to 122,800 tokens with Claude's traditional approach.

Traditional approach:

• All tool definitions loaded upfront (~72K tokens for 50+ MCP tools)
• Conversation history and system prompt compete for the remaining space
• Total context consumption: ~77K tokens before any work begins

With Tool Search Tool:

• Only the Tool Search Tool loaded upfront (~500 tokens)
• Tools discovered on demand (3–5 relevant tools, ~3K tokens)
• Total context consumption: ~8.7K tokens, preserving 95% of the context window

Anthropic describes this as an 85% reduction in token usage while maintaining access to the full tool library.

Accuracy improvements on MCP evaluations

Anthropic reports significant accuracy improvements on MCP evaluations when working with large tool libraries:

• Opus 4: improved from 49% to 74%
• Opus 4.5: improved from 79.5% to 88.1%

How Tool Search Tool works

You provide all your tool definitions to the API but mark tools with defer_loading: true to make them discoverable on demand. Deferred tools are not loaded into Claude's context initially. Claude sees only the Tool Search Tool itself plus any tools marked defer_loading: false — the most critical, frequently used tools.

When Claude needs specific capabilities, it searches for relevant tools. The Tool Search Tool returns references to matching tools, which are then expanded into full definitions in Claude's context. For example, if Claude needs to interact with GitHub, it searches for "github," and only github.createPullRequest and github.listIssues get loaded — not the other 50+ tools from Slack, Jira, and Google Drive.

For MCP servers, you can defer loading entire servers while keeping specific high-use tools loaded.

The Claude Developer Platform provides regex-based and BM25-based search tools out of the box, and you can also implement custom search tools using embeddings or other strategies.

Prompt caching note: Tool Search Tool does not break prompt caching because deferred tools are excluded from the initial prompt entirely. They are only added to context after Claude searches for them, so the system prompt and core tool definitions remain cacheable.

When Tool Search Tool pays off

Anthropic notes the feature adds a search step before tool invocation, so it delivers the best return when context savings and accuracy improvements outweigh the additional latency.

Use it when:

• Tool definitions consume >10K tokens
• You are experiencing tool selection accuracy issues
• You are building MCP-powered systems with multiple servers
• 10+ tools are available

Less beneficial when:

• The tool library is small (<10 tools)
• All tools are used frequently in every session
• Tool definitions are compact

Programmatic Tool Calling: orchestrating tools from code

Programmatic Tool Calling allows Claude to invoke tools in a code execution environment, reducing the impact on the model's context window. Rather than requesting tools one at a time with each result returned to context, Claude writes code that calls multiple tools, processes their outputs, and controls what information actually enters its context window.

The two problems with traditional tool calling

Anthropic identifies two fundamental issues as workflows grow more complex:

• Context pollution from intermediate results. When Claude analyzes a 10MB log file for error patterns, the entire file enters its context window even though Claude only needs a summary of error frequencies. When fetching customer data across multiple tables, every record accumulates in context regardless of relevance.
• Inference overhead and manual synthesis. Each tool call requires a full model inference pass. After receiving results, Claude must "eyeball" the data to extract relevant information, reason about how pieces fit together, and decide what to do next — all through natural language processing. A five-tool workflow means five inference passes plus Claude parsing each result, comparing values, and synthesizing conclusions.

Worked example: Q3 travel budget compliance

Anthropic uses the task "Which team members exceeded their Q3 travel budget?" with three tools:

• get_team_members(department) — returns team member list with IDs and levels
• get_expenses(user_id, quarter) — returns expense line items for a user
• get_budget_by_level(level) — returns budget limits for an employee level

Traditional approach: fetch team members (20 people); for each person fetch Q3 expenses (20 tool calls, each returning 50–100 line items covering flights, hotels, meals, and receipts); fetch budget limits by employee level. All of this enters Claude's context — 2,000+ expense line items (50 KB+) — and Claude must manually sum each person's expenses, look up their budget, and compare expenses against budget limits, with more round-trips to the model.

With Programmatic Tool Calling: Claude writes a Python script that orchestrates the entire workflow. The script runs in the Code Execution tool (a sandboxed environment), pausing when it needs results from your tools. When you return tool results via the API, they are processed by the script rather than consumed by the model. The script continues executing, and Claude only sees the final output — the two to three people who exceeded budget. Anthropic reports this reduces consumption from 200KB of raw expense data to just 1KB of results.

Measured efficiency gains

• Token savings: Average usage dropped from 43,588 to 27,297 tokens, a 37% reduction on complex research tasks.
• Reduced latency: Each API round-trip requires model inference (hundreds of milliseconds to seconds). Orchestrating 20+ tool calls in a single code block eliminates 19+ inference passes, because the API handles tool execution without returning to the model each time.
• Improved accuracy: Internal knowledge retrieval improved from 25.6% to 28.5%; GIA benchmarks improved from 46.5% to 51.2%.

How Programmatic Tool Calling works

1. Mark tools as callable from code. Add code_execution to tools and set allowed_callers to opt in tools for programmatic execution. The API converts these tool definitions into Python functions that Claude can call.
2. Claude writes orchestration code. Instead of requesting tools one at a time, Claude generates Python code.
3. Tools execute without hitting Claude's context. When the code calls a tool such as get_expenses(), you receive a tool request with a caller field. You provide the result, which is processed in the Code Execution environment rather than Claude's context. This request-response cycle repeats for each tool call in the code.
4. Only final output enters context. When the code finishes running, only the results of the code are returned to Claude — not the 2,000+ expense line items processed along the way.

When Programmatic Tool Calling pays off

Most beneficial when:

• Processing large datasets where you only need aggregates or summaries
• Running multi-step workflows with three or more dependent tool calls
• Filtering, sorting, or transforming tool results before Claude sees them
• Handling tasks where intermediate data should not influence Claude's reasoning
• Running parallel operations across many items (checking 50 endpoints, for example)

Less beneficial when:

• Making simple single-tool invocations
• Working on tasks where Claude should see and reason about all intermediate results
• Running quick lookups with small responses

Tool Use Examples: teaching conventions schemas cannot express

Tool Use Examples provides a universal standard for demonstrating how to effectively use a given tool. It lets you provide sample tool calls directly in your tool definitions, so Claude learns concrete usage patterns rather than relying on schema alone.

The ambiguity JSON Schema leaves behind

Anthropic uses a support ticket API to illustrate. The schema defines what is valid but leaves critical questions unanswered:

• Format ambiguity: Should due_date use "2024-11-06", "Nov 6, 2024", or "2024-11-06T00:00:00Z"?
• ID conventions: Is reporter.id a UUID, "USR-12345", or just "12345"?
• Nested structure usage: When should Claude populate reporter.contact?
• Parameter correlations: How do escalation.level and escalation.sla_hours relate to priority?

These ambiguities can lead to malformed tool calls and inconsistent parameter usage.

What Claude learns from examples

From three sample calls in a support ticket API, Anthropic states Claude learns:

• Format conventions: Dates use YYYY-MM-DD, user IDs follow USR-XXXXX, labels use kebab-case
• Nested structure patterns: How to construct the reporter object with its nested contact object
• Optional parameter correlations: Critical bugs have full contact info plus escalation with tight SLAs; feature requests have a reporter but no contact or escalation; internal tasks have a title only

In Anthropic's internal testing, tool use examples improved accuracy from 72% to 90% on complex parameter handling.

When Tool Use Examples pay off

Anthropic notes that examples add tokens to tool definitions, so they are most valuable when accuracy improvements outweigh the additional cost.

Most beneficial when:

• Complex nested structures where valid JSON does not imply correct usage
• Tools with many optional parameters where inclusion patterns matter
• APIs with domain-specific conventions not captured in schemas
• Similar tools where examples clarify which one to use (e.g., create_ticket versus create_incident)

Less beneficial when:

• Simple single-parameter tools with obvious usage
• Standard formats like URLs or emails that Claude already understands
• Validation concerns better handled by JSON Schema constraints

Best practices for combining the three features

Anthropic recommends starting with the biggest bottleneck rather than adopting all three features at once:

• Context bloat from tool definitions → Tool Search Tool
• Large intermediate results polluting context → Programmatic Tool Calling
• Parameter errors and malformed calls → Tool Use Examples

The features are complementary: Tool Search Tool ensures the right tools are found, Programmatic Tool Calling ensures efficient execution, and Tool Use Examples ensure correct invocation.

Setting up Tool Search Tool for better discovery

Tool search matches against names and descriptions, so clear, descriptive definitions improve discovery accuracy. Anthropic recommends adding system prompt guidance so Claude knows what is available, and keeping your three to five most-used tools always loaded while deferring the rest — balancing immediate access for common operations with on-demand discovery for everything else.

Setting up Programmatic Tool Calling for correct execution

Because Claude writes code to parse tool outputs, return formats should be documented clearly so Claude writes correct parsing logic. Tools that benefit most from programmatic orchestration are those that can run in parallel (independent operations) and operations that are safe to retry (idempotent).

Setting up Tool Use Examples for parameter accuracy

Anthropic's guidance for crafting examples:

• Use realistic data (real city names, plausible prices, not "string" or "value")
• Show variety with minimal, partial, and full specification patterns
• Keep it concise: 1–5 examples per tool
• Focus on ambiguity — only add examples where correct usage is not obvious from the schema

Availability and getting started

The three features are available in beta. To enable them, add the beta header and include the tools you need. Anthropic points to documentation and cookbook notebooks for each feature:

• Tool Search Tool — documentation and a cookbook notebook on tool search with embeddings
• Programmatic Tool Calling — documentation and a cookbook notebook on PTC
• Tool Use Examples — documentation under implementing tool use

Anthropic positions these features as moving tool use "from simple function calling toward intelligent orchestration," arguing that as agents tackle more complex workflows spanning dozens of tools and large datasets, dynamic discovery, efficient execution, and reliable invocation become foundational.