Claude Advanced Tool Use: MCP Optimization Guide

Anthropic released Advanced Tool Use features for Claude on November 20, 2025, addressing one of the most significant challenges in AI agent development: context pollution from large tool ecosystems. As applications integrate more MCP (Model Context Protocol) servers—databases, APIs, file systems, web scrapers—the token cost of loading all tool definitions into every request becomes prohibitive. A typical application with 50 tools might consume 150K tokens per request just describing available tools, burning through 75% of Claude's 200K context window before any actual work begins.

Advanced Tool Use introduces three features that transform tool management: the Tool Search Tool with defer_loading for dynamic tool discovery, Programmatic Tool Calling for code-based orchestration, and Tool Use Examples for schema-validated inputs. Combined with code-first MCP patterns that auto-generate schemas from TypeScript or Python type annotations, these features achieve 85-98% efficiency improvements while maintaining full tool access.

Advanced Tool Use: Three Features That Change Everything

Tool Search Tool: Dynamic Discovery with defer_loading

The Tool Search Tool fundamentally changes how Claude interacts with large tool sets by introducing a two-phase execution model. In standard tool use, you provide all tool definitions upfront in the initial API request. Claude analyzes the user's query, selects appropriate tools from those provided, and executes them. This works well for applications with 3-5 tools but becomes inefficient with 20+ tools, as tool definitions consume significant prompt tokens that count against context limits and increase API costs.

{
  "name": "query_database",
  "description": "Execute SQL queries against the database. Use for retrieving, filtering, and aggregating data from any table.",
  "defer_loading": true,
  "input_schema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "The SQL query to execute"
      },
      "limit": {
        "type": "integer",
        "description": "Maximum rows to return (default: 100)"
      }
    },
    "required": ["query"]
  }
}

With defer_loading: true, tools aren't loaded into Claude's context initially—they're only loaded when Claude discovers them via Tool Search. The Tool Search Tool contains lightweight metadata about all available tools (names, brief descriptions, categories), consuming approximately 2K tokens regardless of how many tools you have. When Claude receives a user query, it first calls the Tool Search Tool with a natural language description of what it needs.

Search Variants: BM25 vs Regex

Token Savings Breakdown

Programmatic Tool Calling: Code-Based Orchestration

Programmatic Tool Calling enables Claude to orchestrate tools through Python code rather than individual API round-trips. Instead of Claude requesting tools one at a time with each result being returned to its context, Claude writes code that calls multiple tools, processes their outputs, and controls what information enters its context window. This eliminates context pollution from intermediate results that consume token budgets without providing value.

# Claude writes this code to orchestrate multiple tools
def process_sales_pipeline():
    # Fetch 1,000 records - only code sees all of them
    raw_leads = fetch_database_records(
        query="SELECT * FROM leads WHERE status = 'active'",
        limit=1000
    )

    # Process in code - filter, transform, aggregate
    qualified = [
        lead for lead in raw_leads
        if lead['score'] > 80 and lead['last_contact_days'] < 30
    ]

    # Enrich only the top candidates
    for lead in qualified[:10]:
        lead['company_info'] = fetch_company_data(lead['domain'])

    # Only the final 10 enriched leads enter Claude's context
    return {
        'total_processed': len(raw_leads),
        'qualified_count': len(qualified),
        'top_leads': qualified[:10]
    }

Tool Use Examples: Schema-Validated Input Patterns

For tools with complex inputs, nested objects, or format-sensitive parameters, the input_examples field provides schema-validated examples that help Claude understand how to use your tools effectively. While JSON schemas define what's structurally valid, they can't express usage patterns: when to include optional parameters, which combinations make sense, or what conventions your API expects.

{
  "name": "create_report",
  "description": "Generate a formatted report from data sources",
  "input_schema": {
    "type": "object",
    "properties": {
      "data_source": { "type": "string" },
      "format": { "enum": ["pdf", "xlsx", "html"] },
      "filters": { "type": "object" },
      "include_charts": { "type": "boolean" }
    },
    "required": ["data_source", "format"]
  },
  "input_examples": [
    {
      "data_source": "sales_2025",
      "format": "pdf",
      "filters": { "region": "EMEA", "quarter": "Q4" },
      "include_charts": true
    },
    {
      "data_source": "inventory_current",
      "format": "xlsx",
      "filters": { "warehouse": "EU-West", "status": "low_stock" }
    }
  ]
}

MCP vs Function Calling: When to Use Each

Function calling and MCP serve complementary purposes in AI agent development. Understanding when to use each approach helps you make the right architectural decisions for your application's needs.

Code-First MCP Pattern Implementation

Code-first MCP patterns eliminate the traditional separation between code implementation and schema definition by generating schemas automatically from typed function signatures. Instead of writing a tool function and then separately maintaining a JSON schema that describes its parameters, you write a normal TypeScript or Python function with type annotations, and the MCP SDK automatically generates the schema Claude needs.

TypeScript Code-First Pattern

import { tool } from '@anthropic-ai/sdk';

interface QueryDatabaseParams {
  /** The SQL query to execute against the database */
  query: string;
  /** Maximum rows to return (default: 100) */
  limit?: number;
  /** Timeout in milliseconds */
  timeout?: number;
}

// Schema generated automatically from types and JSDoc
export const queryDatabase = tool<QueryDatabaseParams>({
  name: 'query_database',
  description: 'Execute SQL queries against the production database',
  handler: async ({ query, limit = 100, timeout = 5000 }) => {
    const results = await db.query(query, { limit, timeout });
    return { success: true, rowCount: results.length, rows: results };
  }
});

Python Code-First Pattern

from anthropic import tool
from pydantic import BaseModel, Field

class QueryDatabaseParams(BaseModel):
    query: str = Field(description="The SQL query to execute")
    limit: int = Field(default=100, description="Maximum rows to return")
    timeout: int = Field(default=5000, description="Timeout in milliseconds")

@tool
async def query_database(params: QueryDatabaseParams) -> dict:
    """Execute SQL queries against the production database.

    Use this tool when you need to retrieve, filter, or aggregate
    data from any database table. Supports SELECT queries only.
    """
    results = await db.query(params.query, limit=params.limit)
    return {"success": True, "row_count": len(results), "rows": results}

Model Compatibility: Opus 4.5 vs Sonnet 4.5

Cost Optimization: Pricing and Savings Analysis

Stacked Savings Potential

MCP Security: June 2025 Specification Requirements

The June 2025 MCP specification introduced significant security requirements that affect all production deployments. These changes align MCP with enterprise security standards and address vulnerabilities identified in early implementations.

When NOT to Use Advanced Tool Use: Honest Guidance

Common Mistakes: Lessons from Production Deployments

Migration Strategy for Existing Applications

Migrating existing Claude applications to Advanced Tool Use can happen incrementally without disrupting production systems. Start by auditing your current tool usage patterns—identify which tools get used most frequently and which are rarely called.

Conclusion

Claude Advanced Tool Use with the Tool Search Tool, Programmatic Tool Calling, and code-first MCP patterns represents a fundamental improvement in how AI applications manage tool ecosystems. The 85% token reduction from Tool Search with defer_loading eliminates the linear relationship between tool count and API costs, enabling applications to integrate dozens or hundreds of tools without prohibitive overhead.

Combined with the June 2025 MCP security specification (OAuth 2.1, PKCE, RFC 9728), these patterns provide a production-ready foundation for enterprise AI deployments. For teams building serious AI applications, the investment in Advanced Tool Use pays for itself within 1-2 months through API cost savings alone—while actually improving tool selection accuracy from 49% to 74% on complex MCP evaluations.

Frequently Asked Questions