​

Summary

​

Key Insights

“The future of AI agents is one where models work seamlessly across hundreds or thousands of tools.” — Describing the vision for AI agents’ capabilities.

“Agents should discover and load tools on-demand, keeping only what’s relevant for the current task.” — Explaining the need for efficient tool management by AI agents.

“This represents an 85% reduction in token usage while maintaining access to your full tool library.” — Highlighting the efficiency gains from the Tool Search Tool feature.

​

Topics

• Anthropic API
• AI Agents
• Prompt Engineering

​

Full Article

​

Introducing advanced tool use on the Claude Developer Platform

• Tool Search Tool, which allows Claude to use search tools to access thousands of tools without consuming its context window
• Programmatic Tool Calling, which allows Claude to invoke tools in a code execution environment reducing the impact on the model’s context window
• Tool Use Examples, which provides a universal standard for demonstrating how to effectively use a given tool

​

Tool Search Tool

​

The challenge

• GitHub: 35 tools (~26K tokens)
• Slack: 11 tools (~21K tokens)
• Sentry: 5 tools (~3K tokens)
• Grafana: 5 tools (~3K tokens)
• Splunk: 2 tools (~2K tokens)

​

Our solution

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

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

​

How the Tool Search Tool works

{
  "tools": [
    // Include a tool search tool (regex, BM25, or custom)
    {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},

    // Mark tools for on-demand discovery
    {
      "name": "github.createPullRequest",
      "description": "Create a pull request",
      "input_schema": {...},
      "defer_loading": true
    }
    // ... hundreds more deferred tools with defer_loading: true
  ]
}

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-drive",
  "default_config": {"defer_loading": true}, # defer loading the entire server
  "configs": {
    "search_files": {
"defer_loading": false
    }  // Keep most used tool loaded
  }
}

​

When to use the Tool Search Tool

• Tool definitions consuming >10K tokens
• Experiencing tool selection accuracy issues
• Building MCP-powered systems with multiple servers
• 10+ tools available

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

​

Programmatic Tool Calling

​

The challenge

• 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. These intermediate results consume massive token budgets and can push important information out of the context window entirely.
• 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. This is both slow and error-prone.

​

Our solution

​

Example: Budget compliance check

• 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

• Fetch team members → 20 people
• For each person, fetch their Q3 expenses → 20 tool calls, each returning 50-100 line items (flights, hotels, meals, receipts)
• Fetch budget limits by employee level
• All of this enters Claude’s context: 2,000+ expense line items (50 KB+)
• Claude manually sums each person’s expenses, looks up their budget, compares expenses against budget limits
• More round-trips to the model, significant context consumption

team = await get_team_members("engineering")

# Fetch budgets for each unique level
levels = list(set(m["level"] for m in team))
budget_results = await asyncio.gather(*[
    get_budget_by_level(level) for level in levels
])

# Create a lookup dictionary: {"junior": budget1, "senior": budget2, ...}
budgets = {level: budget for level, budget in zip(levels, budget_results)}

# Fetch all expenses in parallel
expenses = await asyncio.gather(*[
    get_expenses(m["id"], "Q3") for m in team
])

# Find employees who exceeded their travel budget
exceeded = []
for member, exp in zip(team, expenses):
    budget = budgets[member["level"]]
    total = sum(e["amount"] for e in exp)
    if total > budget["travel_limit"]:
        exceeded.append({
            "name": member["name"],
            "spent": total,
            "limit": budget["travel_limit"]
        })

print(json.dumps(exceeded))

• Token savings: By keeping intermediate results out of Claude’s context, PTC dramatically reduces token consumption. 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). When Claude orchestrates 20+ tool calls in a single code block, you eliminate 19+ inference passes. The API handles tool execution without returning to the model each time.
• Improved accuracy: By writing explicit orchestration logic, Claude makes fewer errors than when juggling multiple tool results in natural language. Internal knowledge retrieval improved from 25.6% to 28.5%; GIA benchmarks from 46.5% to 51.2%.

​

How Programmatic Tool Calling works

​

1. Mark tools as callable from code

{
  "tools": [
    {
      "type": "code_execution_20250825",
      "name": "code_execution"
    },
    {
      "name": "get_team_members",
      "description": "Get all members of a department...",
      "input_schema": {...},
      "allowed_callers": ["code_execution_20250825"] # opt-in to programmatic tool calling
    },
    {
      "name": "get_expenses",
 	...
    },
    {
      "name": "get_budget_by_level",
	...
    }
  ]
}

​

2. Claude writes orchestration code

{
  "type": "server_tool_use",
  "id": "srvtoolu_abc",
  "name": "code_execution",
  "input": {
    "code": "team = get_team_members('engineering')\n..." # the code example above
  }
}

​

3. Tools execute without hitting Claude’s context

{
  "type": "tool_use",
  "id": "toolu_xyz",
  "name": "get_expenses",
  "input": {"user_id": "emp_123", "quarter": "Q3"},
  "caller": {
    "type": "code_execution_20250825",
    "tool_id": "srvtoolu_abc"
  }
}

​

4. Only final output enters context

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_abc",
  "content": {
    "stdout": "[{\"name\": \"Alice\", \"spent\": 12500, \"limit\": 10000}...]"
  }
}

​

When to use Programmatic Tool Calling

• 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 shouldn’t influence Claude’s reasoning
• Running parallel operations across many items (checking 50 endpoints, for example)

• 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

​

The challenge

{
  "name": "create_ticket",
  "input_schema": {
    "properties": {
      "title": {"type": "string"},
      "priority": {"enum": ["low", "medium", "high", "critical"]},
      "labels": {"type": "array", "items": {"type": "string"}},
      "reporter": {
        "type": "object",
        "properties": {
          "id": {"type": "string"},
          "name": {"type": "string"},
          "contact": {
            "type": "object",
            "properties": {
              "email": {"type": "string"},
              "phone": {"type": "string"}
            }
          }
        }
      },
      "due_date": {"type": "string"},
      "escalation": {
        "type": "object",
        "properties": {
          "level": {"type": "integer"},
          "notify_manager": {"type": "boolean"},
          "sla_hours": {"type": "integer"}
        }
      }
    },
    "required": ["title"]
  }
}

• 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?

​

Our solution

{
    "name": "create_ticket",
    "input_schema": { /* same schema as above */ },
    "input_examples": [
      {
        "title": "Login page returns 500 error",
        "priority": "critical",
        "labels": ["bug", "authentication", "production"],
        "reporter": {
          "id": "USR-12345",
          "name": "Jane Smith",
          "contact": {
            "email": "jane@acme.com",
            "phone": "+1-555-0123"
          }
        },
        "due_date": "2024-11-06",
        "escalation": {
          "level": 2,
          "notify_manager": true,
          "sla_hours": 4
        }
      },
      {
        "title": "Add dark mode support",
        "labels": ["feature-request", "ui"],
        "reporter": {
          "id": "USR-67890",
          "name": "Alex Chen"
        }
      },
      {
        "title": "Update API documentation"
      }
    ]
  }

• 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 + escalation with tight SLAs; feature requests have reporter but no contact/escalation; internal tasks have title only

​

When to use Tool Use Examples

• Complex nested structures where valid JSON doesn’t imply correct usage
• Tools with many optional parameters and 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 vs create_incident)

• 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

​

Layer features strategically

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

​

Set up Tool Search Tool for better discovery

// Good
{
    "name": "search_customer_orders",
    "description": "Search for customer orders by date range, status, or total amount. Returns order details including items, shipping, and payment info."
}

// Bad
{
    "name": "query_db_orders",
    "description": "Execute order query"
}

You have access to tools for Slack messaging, Google Drive file management, 
Jira ticket tracking, and GitHub repository operations. Use the tool search 
to find specific capabilities.

​

Set up Programmatic Tool Calling for correct execution

{
    "name": "get_orders",
    "description": "Retrieve orders for a customer.
Returns:
    List of order objects, each containing:
    - id (str): Order identifier
    - total (float): Order total in USD
    - status (str): One of 'pending', 'shipped', 'delivered'
    - items (list): Array of {sku, quantity, price}
    - created_at (str): ISO 8601 timestamp"
}

• Tools that can run in parallel (independent operations)
• Operations safe to retry (idempotent)

​

Set up Tool Use Examples for parameter accuracy

• 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 isn’t obvious from schema)

​

Getting started

client.beta.messages.create(
    betas=["advanced-tool-use-2025-11-20"],
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    tools=[
        {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
        {"type": "code_execution_20250825", "name": "code_execution"},
        # Your tools with defer_loading, allowed_callers, and input_examples
    ]
)

• Documentation and cookbook for Tool Search Tool
• Documentation and cookbook for Programmatic Tool Calling
• Documentation for Tool Use Examples

​

Acknowledgements

​

Key Takeaways

​

Notable Quotes

The future of AI agents is one where models work seamlessly across hundreds or thousands of tools.

Agents should discover and load tools on-demand, keeping only what’s relevant for the current task.

This represents an 85% reduction in token usage while maintaining access to your full tool library.

​

Related Topics

• [[topics/anthropic-api]]
• [[topics/ai-agents]]
• [[topics/prompt-engineering]]

​

Related Articles