-
Notifications
You must be signed in to change notification settings - Fork 8.9k
fix(routes/anthropic): fix page parsing logic #20693
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Contributor
|
Successfully generated as following: http://localhost:1200/anthropic/engineering - Success ✔️<?xml version="1.0" encoding="UTF-8"?>
<rss xmlns:atom="http://www.w3.org/2005/Atom" version="2.0">
<channel>
<title>Anthropic Engineering</title>
<link>https://www.anthropic.com/engineering</link>
<atom:link href="http://localhost:1200/anthropic/engineering" rel="self" type="application/rss+xml"></atom:link>
<description>Latest engineering posts from Anthropic - Powered by RSSHub</description>
<generator>RSSHub</generator>
<webMaster>[email protected] (RSSHub)</webMaster>
<language>en</language>
<image>
<url>https://www.anthropic.com/images/icons/apple-touch-icon.png</url>
<title>Anthropic Engineering</title>
<link>https://www.anthropic.com/engineering</link>
</image>
<lastBuildDate>Fri, 12 Dec 2025 17:24:18 GMT</lastBuildDate>
<ttl>5</ttl>
<item>
<title>Introducing advanced tool use on the Claude Developer Platform</title>
<description><section class="page-wrapper HeroEngineering-module-scss-module__j1ivRa__hero" aria-label="Engineering Article Hero"><a class="body-2 bold HeroEngineering-module-scss-module__j1ivRa__hubLink" href="https://www.anthropic.com/engineering">Engineering at Anthropic</a><div class="HeroEngineering-module-scss-module__j1ivRa__content"><div class="HeroEngineering-module-scss-module__j1ivRa__header"><div class="HeroEngineering-module-scss-module__j1ivRa__heroImage"><img alt="Illustration for advanced tool use article." loading="lazy" width="1000" height="1000" decoding="async" data-nimg="1" src="https://www-cdn.anthropic.com/images/4zrzovbb/website/151600be7f9c23247aad8dcb6aacb2e1ab024f44-1000x1000.svg" referrerpolicy="no-referrer"></div><h1 class="headline-1">Introducing advanced tool use on the Claude Developer Platform</h1></div><div class="HeroEngineering-module-scss-module__j1ivRa__metadata"><p class="body-2 HeroEngineering-module-scss-module__j1ivRa__date">Published <!-- -->Nov 24, 2025</p><p class="body-large-1 HeroEngineering-module-scss-module__j1ivRa__summary">We’ve added three new beta features that let Claude discover, learn, and execute tools dynamically. Here’s how they work.</p></div></div></section><div class="page-wrapper"><article><div class=""><div class="Body-module-scss-module__z40yvW__body" data-theme="ivory"><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">The future of AI agents is one where models work seamlessly across hundreds or thousands of tools. An IDE assistant that integrates git operations, file manipulation, package managers, testing frameworks, and deployment pipelines. An operations coordinator that connects Slack, GitHub, Google Drive, Jira, company databases, and dozens of MCP servers simultaneously.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">To <a href="https://www.anthropic.com/research/building-effective-agents" target="_blank" rel="noopener noreferrer">build effective agents</a>, they need to work with unlimited tool libraries without stuffing every definition into context upfront. Our blog article on using <a href="https://www.anthropic.com/engineering/code-execution-with-mcp" target="_blank" rel="noopener noreferrer">code execution with MCP</a> discussed how tool results and definitions can sometimes consume 50,000+ tokens before an agent reads a request. Agents should discover and load tools on-demand, keeping only what's relevant for the current task.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Agents also need the ability to call tools from code. When using natural language tool calling, each invocation requires a full inference pass, and intermediate results pile up in context whether they're useful or not. Code is a natural fit for orchestration logic, such as loops, conditionals, and data transformations. Agents need the flexibility to choose between code execution and inference based on the task at hand.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Agents also need to learn correct tool usage from examples, not just schema definitions. JSON schemas define what's structurally valid, but can't express usage patterns: when to include optional parameters, which combinations make sense, or what conventions your API expects.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Today, we're releasing three features that make this possible:</p><ul class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><li><strong>Tool Search Tool, </strong>which allows Claude to use search tools to access thousands of tools without consuming its context window</li><li><strong>Programmatic Tool Calling</strong>, which allows Claude to invoke tools in a code execution environment reducing the impact on the model’s context window</li><li><strong>Tool Use Examples</strong>, which provides a universal standard for demonstrating how to effectively use a given tool</li></ul><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">In internal testing, we’ve found these features have helped us build things that wouldn’t have been possible with conventional tool use patterns. For example,<strong> <a href="https://www.claude.com/claude-for-excel" target="_blank" rel="noopener noreferrer">Claude for Excel</a> </strong>uses Programmatic Tool Calling to read and modify spreadsheets with thousands of rows without overloading the model’s context window.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Based on our experience, we believe these features open up new possibilities for what you can build with Claude.</p><div class="Body-module-scss-module__z40yvW__media-column Body-module-scss-module__z40yvW__inline"><div class="Video-module-scss-module__qJNyFq__post-wrapper"><figure class="Video-module-scss-module__qJNyFq__post-video-container"><!--$!--><template data-dgst="BAILOUT_TO_CLIENT_SIDE_RENDERING"></template><!--/$--></figure></div></div><h2 class="Body-module-scss-module__z40yvW__reading-column headline-4 post-heading" id="tool-search-tool">Tool Search Tool</h2><h3 class="Body-module-scss-module__z40yvW__reading-column headline-5 post-section" id="the-challenge">The challenge</h3><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">MCP tool definitions provide important context, but as more servers connect, those tokens can add up. Consider a five-server setup:</p><ul class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><li>GitHub: 35 tools (~26K tokens)</li><li>Slack: 11 tools (~21K tokens)</li><li>Sentry: 5 tools (~3K tokens)</li><li>Grafana: 5 tools (~3K tokens)</li><li>Splunk: 2 tools (~2K tokens)</li></ul><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">That's 58 tools consuming approximately 55K tokens before the conversation even starts. Add more servers like Jira (which alone uses ~17K tokens) and you're quickly approaching 100K+ token overhead. At Anthropic, we've seen tool definitions consume 134K tokens before optimization.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">But token cost isn't the only issue. The most common failures are wrong tool selection and incorrect parameters, especially when tools have similar names like <code class="InlineCodeBlock-module-scss-module__nsPAba__code">notification-send-user</code> vs. <code class="InlineCodeBlock-module-scss-module__nsPAba__code">notification-send-channel</code>.</p><h3 class="Body-module-scss-module__z40yvW__reading-column headline-5 post-section" id="our-solution">Our solution</h3><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Instead of loading all tool definitions upfront, the Tool Search Tool discovers tools on-demand. Claude only sees the tools it actually needs for the current task.</p><div class="Body-module-scss-module__z40yvW__media-column Body-module-scss-module__z40yvW__inline"><figure class="ImageWithCaption-module-scss-module__Duq99q__e-imageWithCaption"><img alt="Tool Search Tool diagram" loading="lazy" width="1999" height="1125" decoding="async" data-nimg="1" src="https://www-cdn.anthropic.com/images/4zrzovbb/website/f359296f770706608901eadaffbff4ca0b67874c-1999x1125.png" referrerpolicy="no-referrer"><figcaption class="caption"><em>Tool Search Tool preserves 191,300 tokens of context compared to 122,800 with Claude’s traditional approach.</em></figcaption></figure></div><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"></p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Traditional approach:</p><ul class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><li>All tool definitions loaded upfront (~72K tokens for 50+ MCP tools)</li><li>Conversation history and system prompt compete for remaining space</li><li>Total context consumption: ~77K tokens before any work begins</li></ul><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">With the Tool Search Tool:</p><ul class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><li>Only the Tool Search Tool loaded upfront (~500 tokens)</li><li>Tools discovered on-demand as needed (3-5 relevant tools, ~3K tokens)</li><li>Total context consumption: ~8.7K tokens, preserving 95% of context window</li></ul><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">This represents an 85% reduction in token usage while maintaining access to your full tool library. Internal testing showed significant accuracy improvements on MCP evaluations when working with large tool libraries. Opus 4 improved from 49% to 74%, and Opus 4.5 improved from 79.5% to 88.1% with Tool Search Tool enabled.</p><h3 class="Body-module-scss-module__z40yvW__reading-column headline-5 post-section" id="how-the-tool-search-tool-works">How the Tool Search Tool works</h3><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">The Tool Search Tool lets Claude dynamically discover tools instead of loading all definitions upfront. You provide all your tool definitions to the API, but mark tools with <code class="InlineCodeBlock-module-scss-module__nsPAba__code">defer_loading: true</code> to make them discoverable on-demand. Deferred tools aren't loaded into Claude's context initially. Claude only sees the Tool Search Tool itself plus any tools with <code class="InlineCodeBlock-module-scss-module__nsPAba__code">defer_loading: false</code> (your most critical, frequently-used tools).</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">When Claude needs specific capabilities, it searches for relevant tools. The Tool Search Tool returns references to matching tools, which get expanded into full definitions in Claude's context.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">For example, if Claude needs to interact with GitHub, it searches for "github," and only <code class="InlineCodeBlock-module-scss-module__nsPAba__code">github.createPullRequest</code> and <code class="InlineCodeBlock-module-scss-module__nsPAba__code">github.listIssues</code> get loaded—not your other 50+ tools from Slack, Jira, and Google Drive.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">This way, Claude has access to your full tool library while only paying the token cost for tools it actually needs.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><strong>Prompt caching note: </strong>Tool Search Tool doesn't break prompt caching because deferred tools are excluded from the initial prompt entirely. They're only added to context after Claude searches for them, so your system prompt and core tool definitions remain cacheable.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><strong>Implementation:</strong></p><div class="Body-module-scss-module__z40yvW__media-column Body-module-scss-module__z40yvW__inline"><div class="CodeBlock-module-scss-module__PbWBnq__codeBlock"><pre class="" style="--height:300px;--height-expanded:0px"><code class="plaintext">{
"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
]
}
</code></pre><div class="CodeBlock-module-scss-module__PbWBnq__controls"><button aria-label="Copy code"><svg class="Icon-module-scss-module__lqbdHG__icon" width="11" height="15" viewBox="0 0 11 15"><path d="M5.4 0C6.39875 0 7.26819 0.543814 7.73525 1.35H9.45C10.1956 1.35 10.8 1.95442 10.8 2.7V13.5C10.8 14.2456 10.1956 14.85 9.45 14.85H1.35C0.604415 14.85 2.17436e-08 14.2456 0 13.5V2.7C1.7395e-07 1.95442 0.604415 1.35 1.35 1.35H3.06475C3.53181 0.543814 4.40125 0 5.4 0ZM1.35 2.25C1.10147 2.25 0.9 2.45147 0.9 2.7V13.5C0.9 13.7485 1.10147 13.95 1.35 13.95H9.45C9.69853 13.95 9.9 13.7485 9.9 13.5V2.7C9.9 2.45147 9.69853 2.25 9.45 2.25H8.06221C8.08677 2.39637 8.1 2.54665 8.1 2.7V3.6C8.1 3.84853 7.89853 4.05 7.65 4.05H3.15C2.90147 4.05 2.7 3.84853 2.7 3.6V2.7C2.7 2.54665 2.71323 2.39637 2.73779 2.25H1.35ZM7.68603 10.6233C7.78376 10.395 8.04828 10.2886 8.27666 10.386C8.50499 10.4838 8.61143 10.7483 8.51396 10.9767C8.24856 11.5967 7.73014 12.15 7.01982 12.15C6.58192 12.1499 6.21722 11.9397 5.93965 11.6332C5.66215 11.9395 5.29801 12.1499 4.86035 12.15C4.42229 12.15 4.05692 11.9398 3.7793 11.6332C3.50175 11.9395 3.13773 12.15 2.7 12.15C2.45147 12.15 2.25 11.9485 2.25 11.7C2.25 11.4515 2.45147 11.25 2.7 11.25C2.8912 11.25 3.16726 11.0879 3.36621 10.6233L3.39697 10.5636C3.47806 10.4321 3.62261 10.35 3.78018 10.35C3.9602 10.3501 4.1233 10.4578 4.19414 10.6233C4.39309 11.0878 4.66917 11.25 4.86035 11.25C5.05156 11.2498 5.32773 11.0877 5.52656 10.6233L5.55732 10.5636C5.63837 10.4323 5.78229 10.3501 5.93965 10.35C6.11974 10.35 6.28275 10.4578 6.35361 10.6233C6.55251 11.0878 6.82862 11.2499 7.01982 11.25C7.21102 11.25 7.48708 11.0879 7.68603 10.6233ZM7.68603 7.02334C7.78376 6.79501 8.04828 6.68857 8.27666 6.78604C8.50499 6.88376 8.61143 7.14828 8.51396 7.37666C8.24856 7.99675 7.73014 8.55 7.01982 8.55C6.58192 8.54994 6.21722 8.3397 5.93965 8.0332C5.66215 8.33947 5.29801 8.54989 4.86035 8.55C4.42229 8.55 4.05692 8.33983 3.7793 8.0332C3.50175 8.33945 3.13773 8.55 2.7 8.55C2.45147 8.55 2.25 8.34853 2.25 8.1C2.25 7.85147 2.45147 7.65 2.7 7.65C2.8912 7.65 3.16726 7.48791 3.36621 7.02334L3.39697 6.96357C3.47806 6.83213 3.62261 6.75 3.78018 6.75C3.9602 6.75007 4.1233 6.85783 4.19414 7.02334C4.39309 7.48782 4.66917 7.65 4.86035 7.65C5.05156 7.6498 5.32773 7.48772 5.52656 7.02334L5.55732 6.96357C5.63837 6.83232 5.78229 6.75012 5.93965 6.75C6.11974 6.75 6.28275 6.85778 6.35361 7.02334C6.55251 7.48782 6.82862 7.6499 7.01982 7.65C7.21102 7.65 7.48708 7.48786 7.68603 7.02334ZM5.4 0.9C4.40589 0.9 3.6 1.70589 3.6 2.7V3.15H7.2V2.7C7.2 1.70589 6.39411 0.9 5.4 0.9Z" fill="currentColor"></path></svg><span class="body-3">Copy</span></button></div></div></div><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">For MCP servers, you can defer loading entire servers while keeping specific high-use tools loaded:</p><div class="Body-module-scss-module__z40yvW__media-column Body-module-scss-module__z40yvW__inline"><div class="CodeBlock-module-scss-module__PbWBnq__codeBlock"><pre class="" style="--height:300px;--height-expanded:0px"><code class="plaintext">{
"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
}
}</code></pre><div class="CodeBlock-module-scss-module__PbWBnq__controls"><button aria-label="Copy code"><svg class="Icon-module-scss-module__lqbdHG__icon" width="11" height="15" viewBox="0 0 11 15"><path d="M5.4 0C6.39875 0 7.26819 0.543814 7.73525 1.35H9.45C10.1956 1.35 10.8 1.95442 10.8 2.7V13.5C10.8 14.2456 10.1956 14.85 9.45 14.85H1.35C0.604415 14.85 2.17436e-08 14.2456 0 13.5V2.7C1.7395e-07 1.95442 0.604415 1.35 1.35 1.35H3.06475C3.53181 0.543814 4.40125 0 5.4 0ZM1.35 2.25C1.10147 2.25 0.9 2.45147 0.9 2.7V13.5C0.9 13.7485 1.10147 13.95 1.35 13.95H9.45C9.69853 13.95 9.9 13.7485 9.9 13.5V2.7C9.9 2.45147 9.69853 2.25 9.45 2.25H8.06221C8.08677 2.39637 8.1 2.54665 8.1 2.7V3.6C8.1 3.84853 7.89853 4.05 7.65 4.05H3.15C2.90147 4.05 2.7 3.84853 2.7 3.6V2.7C2.7 2.54665 2.71323 2.39637 2.73779 2.25H1.35ZM7.68603 10.6233C7.78376 10.395 8.04828 10.2886 8.27666 10.386C8.50499 10.4838 8.61143 10.7483 8.51396 10.9767C8.24856 11.5967 7.73014 12.15 7.01982 12.15C6.58192 12.1499 6.21722 11.9397 5.93965 11.6332C5.66215 11.9395 5.29801 12.1499 4.86035 12.15C4.42229 12.15 4.05692 11.9398 3.7793 11.6332C3.50175 11.9395 3.13773 12.15 2.7 12.15C2.45147 12.15 2.25 11.9485 2.25 11.7C2.25 11.4515 2.45147 11.25 2.7 11.25C2.8912 11.25 3.16726 11.0879 3.36621 10.6233L3.39697 10.5636C3.47806 10.4321 3.62261 10.35 3.78018 10.35C3.9602 10.3501 4.1233 10.4578 4.19414 10.6233C4.39309 11.0878 4.66917 11.25 4.86035 11.25C5.05156 11.2498 5.32773 11.0877 5.52656 10.6233L5.55732 10.5636C5.63837 10.4323 5.78229 10.3501 5.93965 10.35C6.11974 10.35 6.28275 10.4578 6.35361 10.6233C6.55251 11.0878 6.82862 11.2499 7.01982 11.25C7.21102 11.25 7.48708 11.0879 7.68603 10.6233ZM7.68603 7.02334C7.78376 6.79501 8.04828 6.68857 8.27666 6.78604C8.50499 6.88376 8.61143 7.14828 8.51396 7.37666C8.24856 7.99675 7.73014 8.55 7.01982 8.55C6.58192 8.54994 6.21722 8.3397 5.93965 8.0332C5.66215 8.33947 5.29801 8.54989 4.86035 8.55C4.42229 8.55 4.05692 8.33983 3.7793 8.0332C3.50175 8.33945 3.13773 8.55 2.7 8.55C2.45147 8.55 2.25 8.34853 2.25 8.1C2.25 7.85147 2.45147 7.65 2.7 7.65C2.8912 7.65 3.16726 7.48791 3.36621 7.02334L3.39697 6.96357C3.47806 6.83213 3.62261 6.75 3.78018 6.75C3.9602 6.75007 4.1233 6.85783 4.19414 7.02334C4.39309 7.48782 4.66917 7.65 4.86035 7.65C5.05156 7.6498 5.32773 7.48772 5.52656 7.02334L5.55732 6.96357C5.63837 6.83232 5.78229 6.75012 5.93965 6.75C6.11974 6.75 6.28275 6.85778 6.35361 7.02334C6.55251 7.48782 6.82862 7.6499 7.01982 7.65C7.21102 7.65 7.48708 7.48786 7.68603 7.02334ZM5.4 0.9C4.40589 0.9 3.6 1.70589 3.6 2.7V3.15H7.2V2.7C7.2 1.70589 6.39411 0.9 5.4 0.9Z" fill="currentColor"></path></svg><span class="body-3">Copy</span></button></div></div></div><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">The Claude Developer Platform provides regex-based and BM25-based search tools out of the box, but you can also implement custom search tools using embeddings or other strategies.</p><h3 class="Body-module-scss-module__z40yvW__reading-column headline-5 post-section" id="when-to-use-the-tool-search-tool">When to use the Tool Search Tool</h3><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Like any architectural decision, enabling the Tool Search Tool involves trade-offs. The feature adds a search step before tool invocation, so it delivers the best ROI when the context savings and accuracy improvements outweigh additional latency.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><strong>Use it when:</strong></p><ul class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><li>Tool definitions consuming &gt;10K tokens</li><li>Experiencing tool selection accuracy issues</li><li>Building MCP-powered systems with multiple servers</li><li>10+ tools available</li></ul><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><strong>Less beneficial when:</strong></p><ul class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><li>Small tool library (&lt;10 tools)</li><li>All tools used frequently in every session</li><li>Tool definitions are compact</li></ul><h2 class="Body-module-scss-module__z40yvW__reading-column headline-4 post-heading" id="programmatic-tool-calling">Programmatic Tool Calling</h2><h3 class="Body-module-scss-module__z40yvW__reading-column headline-5 post-section" id="the-challenge">The challenge</h3><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Traditional tool calling creates two fundamental problems as workflows become more complex:</p><ul class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><li><strong>Context pollution from intermediate results</strong>: 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.</li><li><strong>Inference overhead and manual synthesis</strong>: 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.</li></ul><h3 class="Body-module-scss-module__z40yvW__reading-column headline-5 post-section" id="our-solution">Our solution</h3><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Programmatic Tool Calling enables Claude to orchestrate tools through code rather than through 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 actually enters its context window.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Claude excels at writing code and by letting it express orchestration logic in Python rather than through natural language tool invocations, you get more reliable, precise control flow. Loops, conditionals, data transformations, and error handling are all explicit in code rather than implicit in Claude's reasoning.</p><h4 class="Body-module-scss-module__z40yvW__reading-column headline-6 post-subsection" id="example-budget-compliance-check">Example: Budget compliance check</h4><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Consider a common business task: "Which team members exceeded their Q3 travel budget?"</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">You have three tools available:</p><ul class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><li><code class="InlineCodeBlock-module-scss-module__nsPAba__code">get_team_members(department)</code> - Returns team member list with IDs and levels</li><li><code class="InlineCodeBlock-module-scss-module__nsPAba__code">get_expenses(user_id, quarter)</code> - Returns expense line items for a user</li><li><code class="InlineCodeBlock-module-scss-module__nsPAba__code">get_budget_by_level(level)</code> - Returns budget limits for an employee level</li></ul><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><strong>Traditional approach</strong>:</p><ul class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><li>Fetch team members → 20 people</li><li>For each person, fetch their Q3 expenses → 20 tool calls, each returning 50-100 line items (flights, hotels, meals, receipts)</li><li>Fetch budget limits by employee level</li><li>All of this enters Claude's context: 2,000+ expense line items (50 KB+)</li><li>Claude manually sums each person's expenses, looks up their budget, compares expenses against budget limits</li><li>More round-trips to the model, significant context consumption</li></ul><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><strong>With Programmatic Tool Calling</strong>:</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Instead of each tool result returning to Claude, 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're processed by the script rather than consumed by the model. The script continues executing, and Claude only sees the final output.</p><div class="Body-module-scss-module__z40yvW__media-column Body-module-scss-module__z40yvW__inline"><figure class="ImageWithCaption-module-scss-module__Duq99q__e-imageWithCaption"><img alt="Programmatic tool calling flow" loading="lazy" width="1999" height="1491" decoding="async" data-nimg="1" src="https://www-cdn.anthropic.com/images/4zrzovbb/website/65737d69a3290ed5c1f3c3b8dc873645a9dcc2eb-1999x1491.png" referrerpolicy="no-referrer"><figcaption class="caption">Programmatic Tool Calling enables Claude to orchestrate tools through code rather than through individual API round-trips, allowing for parallel tool execution.</figcaption></figure></div><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Here's what Claude's orchestration code looks like for the budget compliance task:</p><div class="Body-module-scss-module__z40yvW__media-column Body-module-scss-module__z40yvW__inline"><div class="CodeBlock-module-scss-module__PbWBnq__codeBlock"><pre class="" style="--height:300px;--height-expanded:0px"><code class="plaintext">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 &gt; budget["travel_limit"]:
exceeded.append({
"name": member["name"],
"spent": total,
"limit": budget["travel_limit"]
})
print(json.dumps(exceeded))</code></pre><div class="CodeBlock-module-scss-module__PbWBnq__controls"><button aria-label="Copy code"><svg class="Icon-module-scss-module__lqbdHG__icon" width="11" height="15" viewBox="0 0 11 15"><path d="M5.4 0C6.39875 0 7.26819 0.543814 7.73525 1.35H9.45C10.1956 1.35 10.8 1.95442 10.8 2.7V13.5C10.8 14.2456 10.1956 14.85 9.45 14.85H1.35C0.604415 14.85 2.17436e-08 14.2456 0 13.5V2.7C1.7395e-07 1.95442 0.604415 1.35 1.35 1.35H3.06475C3.53181 0.543814 4.40125 0 5.4 0ZM1.35 2.25C1.10147 2.25 0.9 2.45147 0.9 2.7V13.5C0.9 13.7485 1.10147 13.95 1.35 13.95H9.45C9.69853 13.95 9.9 13.7485 9.9 13.5V2.7C9.9 2.45147 9.69853 2.25 9.45 2.25H8.06221C8.08677 2.39637 8.1 2.54665 8.1 2.7V3.6C8.1 3.84853 7.89853 4.05 7.65 4.05H3.15C2.90147 4.05 2.7 3.84853 2.7 3.6V2.7C2.7 2.54665 2.71323 2.39637 2.73779 2.25H1.35ZM7.68603 10.6233C7.78376 10.395 8.04828 10.2886 8.27666 10.386C8.50499 10.4838 8.61143 10.7483 8.51396 10.9767C8.24856 11.5967 7.73014 12.15 7.01982 12.15C6.58192 12.1499 6.21722 11.9397 5.93965 11.6332C5.66215 11.9395 5.29801 12.1499 4.86035 12.15C4.42229 12.15 4.05692 11.9398 3.7793 11.6332C3.50175 11.9395 3.13773 12.15 2.7 12.15C2.45147 12.15 2.25 11.9485 2.25 11.7C2.25 11.4515 2.45147 11.25 2.7 11.25C2.8912 11.25 3.16726 11.0879 3.36621 10.6233L3.39697 10.5636C3.47806 10.4321 3.62261 10.35 3.78018 10.35C3.9602 10.3501 4.1233 10.4578 4.19414 10.6233C4.39309 11.0878 4.66917 11.25 4.86035 11.25C5.05156 11.2498 5.32773 11.0877 5.52656 10.6233L5.55732 10.5636C5.63837 10.4323 5.78229 10.3501 5.93965 10.35C6.11974 10.35 6.28275 10.4578 6.35361 10.6233C6.55251 11.0878 6.82862 11.2499 7.01982 11.25C7.21102 11.25 7.48708 11.0879 7.68603 10.6233ZM7.68603 7.02334C7.78376 6.79501 8.04828 6.68857 8.27666 6.78604C8.50499 6.88376 8.61143 7.14828 8.51396 7.37666C8.24856 7.99675 7.73014 8.55 7.01982 8.55C6.58192 8.54994 6.21722 8.3397 5.93965 8.0332C5.66215 8.33947 5.29801 8.54989 4.86035 8.55C4.42229 8.55 4.05692 8.33983 3.7793 8.0332C3.50175 8.33945 3.13773 8.55 2.7 8.55C2.45147 8.55 2.25 8.34853 2.25 8.1C2.25 7.85147 2.45147 7.65 2.7 7.65C2.8912 7.65 3.16726 7.48791 3.36621 7.02334L3.39697 6.96357C3.47806 6.83213 3.62261 6.75 3.78018 6.75C3.9602 6.75007 4.1233 6.85783 4.19414 7.02334C4.39309 7.48782 4.66917 7.65 4.86035 7.65C5.05156 7.6498 5.32773 7.48772 5.52656 7.02334L5.55732 6.96357C5.63837 6.83232 5.78229 6.75012 5.93965 6.75C6.11974 6.75 6.28275 6.85778 6.35361 7.02334C6.55251 7.48782 6.82862 7.6499 7.01982 7.65C7.21102 7.65 7.48708 7.48786 7.68603 7.02334ZM5.4 0.9C4.40589 0.9 3.6 1.70589 3.6 2.7V3.15H7.2V2.7C7.2 1.70589 6.39411 0.9 5.4 0.9Z" fill="currentColor"></path></svg><span class="body-3">Copy</span></button></div></div></div><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Claude's context receives only the final result: the two to three people who exceeded their budget. The 2,000+ line items, the intermediate sums, and the budget lookups do not affect Claude’s context, reducing consumption from 200KB of raw expense data to just 1KB of results.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">The efficiency gains are substantial:</p><ul class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><li><strong>Token savings</strong>: 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.</li><li><strong>Reduced latency</strong>: 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.</li><li><strong>Improved accuracy</strong>: 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%; <a href="https://arxiv.org/abs/2311.12983" target="_blank" rel="noopener noreferrer">GIA benchmarks</a> from 46.5% to 51.2%.</li></ul><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Production workflows involve messy data, conditional logic, and operations that need to scale. Programmatic Tool Calling lets Claude handle that complexity programmatically while keeping its focus on actionable results rather than raw data processing.</p><h3 class="Body-module-scss-module__z40yvW__reading-column headline-5 post-section" id="how-programmatic-tool-calling-works">How Programmatic Tool Calling works</h3><h4 class="Body-module-scss-module__z40yvW__reading-column headline-6 post-subsection" id="1-mark-tools-as-callable-from-code">1. Mark tools as callable from code</h4><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Add code_execution to tools, and set allowed_callers to opt-in tools for programmatic execution:</p><div class="Body-module-scss-module__z40yvW__media-column Body-module-scss-module__z40yvW__inline"><div class="CodeBlock-module-scss-module__PbWBnq__codeBlock"><pre class="" style="--height:300px;--height-expanded:0px"><code class="plaintext">{
"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",
...
}
]
}</code></pre><div class="CodeBlock-module-scss-module__PbWBnq__controls"><button aria-label="Copy code"><svg class="Icon-module-scss-module__lqbdHG__icon" width="11" height="15" viewBox="0 0 11 15"><path d="M5.4 0C6.39875 0 7.26819 0.543814 7.73525 1.35H9.45C10.1956 1.35 10.8 1.95442 10.8 2.7V13.5C10.8 14.2456 10.1956 14.85 9.45 14.85H1.35C0.604415 14.85 2.17436e-08 14.2456 0 13.5V2.7C1.7395e-07 1.95442 0.604415 1.35 1.35 1.35H3.06475C3.53181 0.543814 4.40125 0 5.4 0ZM1.35 2.25C1.10147 2.25 0.9 2.45147 0.9 2.7V13.5C0.9 13.7485 1.10147 13.95 1.35 13.95H9.45C9.69853 13.95 9.9 13.7485 9.9 13.5V2.7C9.9 2.45147 9.69853 2.25 9.45 2.25H8.06221C8.08677 2.39637 8.1 2.54665 8.1 2.7V3.6C8.1 3.84853 7.89853 4.05 7.65 4.05H3.15C2.90147 4.05 2.7 3.84853 2.7 3.6V2.7C2.7 2.54665 2.71323 2.39637 2.73779 2.25H1.35ZM7.68603 10.6233C7.78376 10.395 8.04828 10.2886 8.27666 10.386C8.50499 10.4838 8.61143 10.7483 8.51396 10.9767C8.24856 11.5967 7.73014 12.15 7.01982 12.15C6.58192 12.1499 6.21722 11.9397 5.93965 11.6332C5.66215 11.9395 5.29801 12.1499 4.86035 12.15C4.42229 12.15 4.05692 11.9398 3.7793 11.6332C3.50175 11.9395 3.13773 12.15 2.7 12.15C2.45147 12.15 2.25 11.9485 2.25 11.7C2.25 11.4515 2.45147 11.25 2.7 11.25C2.8912 11.25 3.16726 11.0879 3.36621 10.6233L3.39697 10.5636C3.47806 10.4321 3.62261 10.35 3.78018 10.35C3.9602 10.3501 4.1233 10.4578 4.19414 10.6233C4.39309 11.0878 4.66917 11.25 4.86035 11.25C5.05156 11.2498 5.32773 11.0877 5.52656 10.6233L5.55732 10.5636C5.63837 10.4323 5.78229 10.3501 5.93965 10.35C6.11974 10.35 6.28275 10.4578 6.35361 10.6233C6.55251 11.0878 6.82862 11.2499 7.01982 11.25C7.21102 11.25 7.48708 11.0879 7.68603 10.6233ZM7.68603 7.02334C7.78376 6.79501 8.04828 6.68857 8.27666 6.78604C8.50499 6.88376 8.61143 7.14828 8.51396 7.37666C8.24856 7.99675 7.73014 8.55 7.01982 8.55C6.58192 8.54994 6.21722 8.3397 5.93965 8.0332C5.66215 8.33947 5.29801 8.54989 4.86035 8.55C4.42229 8.55 4.05692 8.33983 3.7793 8.0332C3.50175 8.33945 3.13773 8.55 2.7 8.55C2.45147 8.55 2.25 8.34853 2.25 8.1C2.25 7.85147 2.45147 7.65 2.7 7.65C2.8912 7.65 3.16726 7.48791 3.36621 7.02334L3.39697 6.96357C3.47806 6.83213 3.62261 6.75 3.78018 6.75C3.9602 6.75007 4.1233 6.85783 4.19414 7.02334C4.39309 7.48782 4.66917 7.65 4.86035 7.65C5.05156 7.6498 5.32773 7.48772 5.52656 7.02334L5.55732 6.96357C5.63837 6.83232 5.78229 6.75012 5.93965 6.75C6.11974 6.75 6.28275 6.85778 6.35361 7.02334C6.55251 7.48782 6.82862 7.6499 7.01982 7.65C7.21102 7.65 7.48708 7.48786 7.68603 7.02334ZM5.4 0.9C4.40589 0.9 3.6 1.70589 3.6 2.7V3.15H7.2V2.7C7.2 1.70589 6.39411 0.9 5.4 0.9Z" fill="currentColor"></path></svg><span class="body-3">Copy</span></button></div></div></div><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">The API converts these tool definitions into Python functions that Claude can call.</p><h4 class="Body-module-scss-module__z40yvW__reading-column headline-6 post-subsection" id="2-claude-writes-orchestration-code">2. Claude writes orchestration code</h4><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Instead of requesting tools one at a time, Claude generates Python code:</p><div class="Body-module-scss-module__z40yvW__media-column Body-module-scss-module__z40yvW__inline"><div class="CodeBlock-module-scss-module__PbWBnq__codeBlock"><pre class="" style="--height:300px;--height-expanded:0px"><code class="plaintext">{
"type": "server_tool_use",
"id": "srvtoolu_abc",
"name": "code_execution",
"input": {
"code": "team = get_team_members('engineering')\n..." # the code example above
}
}</code></pre><div class="CodeBlock-module-scss-module__PbWBnq__controls"><button aria-label="Copy code"><svg class="Icon-module-scss-module__lqbdHG__icon" width="11" height="15" viewBox="0 0 11 15"><path d="M5.4 0C6.39875 0 7.26819 0.543814 7.73525 1.35H9.45C10.1956 1.35 10.8 1.95442 10.8 2.7V13.5C10.8 14.2456 10.1956 14.85 9.45 14.85H1.35C0.604415 14.85 2.17436e-08 14.2456 0 13.5V2.7C1.7395e-07 1.95442 0.604415 1.35 1.35 1.35H3.06475C3.53181 0.543814 4.40125 0 5.4 0ZM1.35 2.25C1.10147 2.25 0.9 2.45147 0.9 2.7V13.5C0.9 13.7485 1.10147 13.95 1.35 13.95H9.45C9.69853 13.95 9.9 13.7485 9.9 13.5V2.7C9.9 2.45147 9.69853 2.25 9.45 2.25H8.06221C8.08677 2.39637 8.1 2.54665 8.1 2.7V3.6C8.1 3.84853 7.89853 4.05 7.65 4.05H3.15C2.90147 4.05 2.7 3.84853 2.7 3.6V2.7C2.7 2.54665 2.71323 2.39637 2.73779 2.25H1.35ZM7.68603 10.6233C7.78376 10.395 8.04828 10.2886 8.27666 10.386C8.50499 10.4838 8.61143 10.7483 8.51396 10.9767C8.24856 11.5967 7.73014 12.15 7.01982 12.15C6.58192 12.1499 6.21722 11.9397 5.93965 11.6332C5.66215 11.9395 5.29801 12.1499 4.86035 12.15C4.42229 12.15 4.05692 11.9398 3.7793 11.6332C3.50175 11.9395 3.13773 12.15 2.7 12.15C2.45147 12.15 2.25 11.9485 2.25 11.7C2.25 11.4515 2.45147 11.25 2.7 11.25C2.8912 11.25 3.16726 11.0879 3.36621 10.6233L3.39697 10.5636C3.47806 10.4321 3.62261 10.35 3.78018 10.35C3.9602 10.3501 4.1233 10.4578 4.19414 10.6233C4.39309 11.0878 4.66917 11.25 4.86035 11.25C5.05156 11.2498 5.32773 11.0877 5.52656 10.6233L5.55732 10.5636C5.63837 10.4323 5.78229 10.3501 5.93965 10.35C6.11974 10.35 6.28275 10.4578 6.35361 10.6233C6.55251 11.0878 6.82862 11.2499 7.01982 11.25C7.21102 11.25 7.48708 11.0879 7.68603 10.6233ZM7.68603 7.02334C7.78376 6.79501 8.04828 6.68857 8.27666 6.78604C8.50499 6.88376 8.61143 7.14828 8.51396 7.37666C8.24856 7.99675 7.73014 8.55 7.01982 8.55C6.58192 8.54994 6.21722 8.3397 5.93965 8.0332C5.66215 8.33947 5.29801 8.54989 4.86035 8.55C4.42229 8.55 4.05692 8.33983 3.7793 8.0332C3.50175 8.33945 3.13773 8.55 2.7 8.55C2.45147 8.55 2.25 8.34853 2.25 8.1C2.25 7.85147 2.45147 7.65 2.7 7.65C2.8912 7.65 3.16726 7.48791 3.36621 7.02334L3.39697 6.96357C3.47806 6.83213 3.62261 6.75 3.78018 6.75C3.9602 6.75007 4.1233 6.85783 4.19414 7.02334C4.39309 7.48782 4.66917 7.65 4.86035 7.65C5.05156 7.6498 5.32773 7.48772 5.52656 7.02334L5.55732 6.96357C5.63837 6.83232 5.78229 6.75012 5.93965 6.75C6.11974 6.75 6.28275 6.85778 6.35361 7.02334C6.55251 7.48782 6.82862 7.6499 7.01982 7.65C7.21102 7.65 7.48708 7.48786 7.68603 7.02334ZM5.4 0.9C4.40589 0.9 3.6 1.70589 3.6 2.7V3.15H7.2V2.7C7.2 1.70589 6.39411 0.9 5.4 0.9Z" fill="currentColor"></path></svg><span class="body-3">Copy</span></button></div></div></div><h4 class="Body-module-scss-module__z40yvW__reading-column headline-6 post-subsection" id="3-tools-execute-without-hitting-claudes-context">3. Tools execute without hitting Claude's context</h4><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">When the code calls get_expenses(), you receive a tool request with a caller field:</p><div class="Body-module-scss-module__z40yvW__media-column Body-module-scss-module__z40yvW__inline"><div class="CodeBlock-module-scss-module__PbWBnq__codeBlock"><pre class="" style="--height:300px;--height-expanded:0px"><code class="plaintext">{
"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"
}
}</code></pre><div class="CodeBlock-module-scss-module__PbWBnq__controls"><button aria-label="Copy code"><svg class="Icon-module-scss-module__lqbdHG__icon" width="11" height="15" viewBox="0 0 11 15"><path d="M5.4 0C6.39875 0 7.26819 0.543814 7.73525 1.35H9.45C10.1956 1.35 10.8 1.95442 10.8 2.7V13.5C10.8 14.2456 10.1956 14.85 9.45 14.85H1.35C0.604415 14.85 2.17436e-08 14.2456 0 13.5V2.7C1.7395e-07 1.95442 0.604415 1.35 1.35 1.35H3.06475C3.53181 0.543814 4.40125 0 5.4 0ZM1.35 2.25C1.10147 2.25 0.9 2.45147 0.9 2.7V13.5C0.9 13.7485 1.10147 13.95 1.35 13.95H9.45C9.69853 13.95 9.9 13.7485 9.9 13.5V2.7C9.9 2.45147 9.69853 2.25 9.45 2.25H8.06221C8.08677 2.39637 8.1 2.54665 8.1 2.7V3.6C8.1 3.84853 7.89853 4.05 7.65 4.05H3.15C2.90147 4.05 2.7 3.84853 2.7 3.6V2.7C2.7 2.54665 2.71323 2.39637 2.73779 2.25H1.35ZM7.68603 10.6233C7.78376 10.395 8.04828 10.2886 8.27666 10.386C8.50499 10.4838 8.61143 10.7483 8.51396 10.9767C8.24856 11.5967 7.73014 12.15 7.01982 12.15C6.58192 12.1499 6.21722 11.9397 5.93965 11.6332C5.66215 11.9395 5.29801 12.1499 4.86035 12.15C4.42229 12.15 4.05692 11.9398 3.7793 11.6332C3.50175 11.9395 3.13773 12.15 2.7 12.15C2.45147 12.15 2.25 11.9485 2.25 11.7C2.25 11.4515 2.45147 11.25 2.7 11.25C2.8912 11.25 3.16726 11.0879 3.36621 10.6233L3.39697 10.5636C3.47806 10.4321 3.62261 10.35 3.78018 10.35C3.9602 10.3501 4.1233 10.4578 4.19414 10.6233C4.39309 11.0878 4.66917 11.25 4.86035 11.25C5.05156 11.2498 5.32773 11.0877 5.52656 10.6233L5.55732 10.5636C5.63837 10.4323 5.78229 10.3501 5.93965 10.35C6.11974 10.35 6.28275 10.4578 6.35361 10.6233C6.55251 11.0878 6.82862 11.2499 7.01982 11.25C7.21102 11.25 7.48708 11.0879 7.68603 10.6233ZM7.68603 7.02334C7.78376 6.79501 8.04828 6.68857 8.27666 6.78604C8.50499 6.88376 8.61143 7.14828 8.51396 7.37666C8.24856 7.99675 7.73014 8.55 7.01982 8.55C6.58192 8.54994 6.21722 8.3397 5.93965 8.0332C5.66215 8.33947 5.29801 8.54989 4.86035 8.55C4.42229 8.55 4.05692 8.33983 3.7793 8.0332C3.50175 8.33945 3.13773 8.55 2.7 8.55C2.45147 8.55 2.25 8.34853 2.25 8.1C2.25 7.85147 2.45147 7.65 2.7 7.65C2.8912 7.65 3.16726 7.48791 3.36621 7.02334L3.39697 6.96357C3.47806 6.83213 3.62261 6.75 3.78018 6.75C3.9602 6.75007 4.1233 6.85783 4.19414 7.02334C4.39309 7.48782 4.66917 7.65 4.86035 7.65C5.05156 7.6498 5.32773 7.48772 5.52656 7.02334L5.55732 6.96357C5.63837 6.83232 5.78229 6.75012 5.93965 6.75C6.11974 6.75 6.28275 6.85778 6.35361 7.02334C6.55251 7.48782 6.82862 7.6499 7.01982 7.65C7.21102 7.65 7.48708 7.48786 7.68603 7.02334ZM5.4 0.9C4.40589 0.9 3.6 1.70589 3.6 2.7V3.15H7.2V2.7C7.2 1.70589 6.39411 0.9 5.4 0.9Z" fill="currentColor"></path></svg><span class="body-3">Copy</span></button></div></div></div><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">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.</p><h4 class="Body-module-scss-module__z40yvW__reading-column headline-6 post-subsection" id="4-only-final-output-enters-context">4. Only final output enters context</h4><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">When the code finishes running, only the results of the code are returned to Claude:</p><div class="Body-module-scss-module__z40yvW__media-column Body-module-scss-module__z40yvW__inline"><div class="CodeBlock-module-scss-module__PbWBnq__codeBlock"><pre class="" style="--height:300px;--height-expanded:0px"><code class="plaintext">{
"type": "code_execution_tool_result",
"tool_use_id": "srvtoolu_abc",
"content": {
"stdout": "[{\"name\": \"Alice\", \"spent\": 12500, \"limit\": 10000}...]"
}
}</code></pre><div class="CodeBlock-module-scss-module__PbWBnq__controls"><button aria-label="Copy code"><svg class="Icon-module-scss-module__lqbdHG__icon" width="11" height="15" viewBox="0 0 11 15"><path d="M5.4 0C6.39875 0 7.26819 0.543814 7.73525 1.35H9.45C10.1956 1.35 10.8 1.95442 10.8 2.7V13.5C10.8 14.2456 10.1956 14.85 9.45 14.85H1.35C0.604415 14.85 2.17436e-08 14.2456 0 13.5V2.7C1.7395e-07 1.95442 0.604415 1.35 1.35 1.35H3.06475C3.53181 0.543814 4.40125 0 5.4 0ZM1.35 2.25C1.10147 2.25 0.9 2.45147 0.9 2.7V13.5C0.9 13.7485 1.10147 13.95 1.35 13.95H9.45C9.69853 13.95 9.9 13.7485 9.9 13.5V2.7C9.9 2.45147 9.69853 2.25 9.45 2.25H8.06221C8.08677 2.39637 8.1 2.54665 8.1 2.7V3.6C8.1 3.84853 7.89853 4.05 7.65 4.05H3.15C2.90147 4.05 2.7 3.84853 2.7 3.6V2.7C2.7 2.54665 2.71323 2.39637 2.73779 2.25H1.35ZM7.68603 10.6233C7.78376 10.395 8.04828 10.2886 8.27666 10.386C8.50499 10.4838 8.61143 10.7483 8.51396 10.9767C8.24856 11.5967 7.73014 12.15 7.01982 12.15C6.58192 12.1499 6.21722 11.9397 5.93965 11.6332C5.66215 11.9395 5.29801 12.1499 4.86035 12.15C4.42229 12.15 4.05692 11.9398 3.7793 11.6332C3.50175 11.9395 3.13773 12.15 2.7 12.15C2.45147 12.15 2.25 11.9485 2.25 11.7C2.25 11.4515 2.45147 11.25 2.7 11.25C2.8912 11.25 3.16726 11.0879 3.36621 10.6233L3.39697 10.5636C3.47806 10.4321 3.62261 10.35 3.78018 10.35C3.9602 10.3501 4.1233 10.4578 4.19414 10.6233C4.39309 11.0878 4.66917 11.25 4.86035 11.25C5.05156 11.2498 5.32773 11.0877 5.52656 10.6233L5.55732 10.5636C5.63837 10.4323 5.78229 10.3501 5.93965 10.35C6.11974 10.35 6.28275 10.4578 6.35361 10.6233C6.55251 11.0878 6.82862 11.2499 7.01982 11.25C7.21102 11.25 7.48708 11.0879 7.68603 10.6233ZM7.68603 7.02334C7.78376 6.79501 8.04828 6.68857 8.27666 6.78604C8.50499 6.88376 8.61143 7.14828 8.51396 7.37666C8.24856 7.99675 7.73014 8.55 7.01982 8.55C6.58192 8.54994 6.21722 8.3397 5.93965 8.0332C5.66215 8.33947 5.29801 8.54989 4.86035 8.55C4.42229 8.55 4.05692 8.33983 3.7793 8.0332C3.50175 8.33945 3.13773 8.55 2.7 8.55C2.45147 8.55 2.25 8.34853 2.25 8.1C2.25 7.85147 2.45147 7.65 2.7 7.65C2.8912 7.65 3.16726 7.48791 3.36621 7.02334L3.39697 6.96357C3.47806 6.83213 3.62261 6.75 3.78018 6.75C3.9602 6.75007 4.1233 6.85783 4.19414 7.02334C4.39309 7.48782 4.66917 7.65 4.86035 7.65C5.05156 7.6498 5.32773 7.48772 5.52656 7.02334L5.55732 6.96357C5.63837 6.83232 5.78229 6.75012 5.93965 6.75C6.11974 6.75 6.28275 6.85778 6.35361 7.02334C6.55251 7.48782 6.82862 7.6499 7.01982 7.65C7.21102 7.65 7.48708 7.48786 7.68603 7.02334ZM5.4 0.9C4.40589 0.9 3.6 1.70589 3.6 2.7V3.15H7.2V2.7C7.2 1.70589 6.39411 0.9 5.4 0.9Z" fill="currentColor"></path></svg><span class="body-3">Copy</span></button></div></div></div><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">This is all Claude sees, not the 2000+ expense line items processed along the way.</p><h3 class="Body-module-scss-module__z40yvW__reading-column headline-5 post-section" id="when-to-use-programmatic-tool-calling">When to use Programmatic Tool Calling</h3><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Programmatic Tool Calling adds a code execution step to your workflow. This extra overhead pays off when the token savings, latency improvements, and accuracy gains are substantial.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><strong>Most beneficial when:</strong></p><ul class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><li>Processing large datasets where you only need aggregates or summaries</li><li>Running multi-step workflows with three or more dependent tool calls</li><li>Filtering, sorting, or transforming tool results before Claude sees them</li><li>Handling tasks where intermediate data shouldn't influence Claude's reasoning</li><li>Running parallel operations across many items (checking 50 endpoints, for example)</li></ul><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><strong>Less beneficial when:</strong></p><ul class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><li>Making simple single-tool invocations</li><li>Working on tasks where Claude should see and reason about all intermediate results</li><li>Running quick lookups with small responses</li></ul><h2 class="Body-module-scss-module__z40yvW__reading-column headline-4 post-heading" id="tool-use-examples">Tool Use Examples</h2><h3 class="Body-module-scss-module__z40yvW__reading-column headline-5 post-section" id="the-challenge">The challenge</h3><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">JSON Schema excels at defining structure–types, required fields, allowed enums–but it can't express usage patterns: when to include optional parameters, which combinations make sense, or what conventions your API expects.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Consider a support ticket API:</p><div class="Body-module-scss-module__z40yvW__media-column Body-module-scss-module__z40yvW__inline"><div class="CodeBlock-module-scss-module__PbWBnq__codeBlock"><pre class="" style="--height:300px;--height-expanded:0px"><code class="plaintext">{
"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"]
}
}</code></pre><div class="CodeBlock-module-scss-module__PbWBnq__controls"><button aria-label="Copy code"><svg class="Icon-module-scss-module__lqbdHG__icon" width="11" height="15" viewBox="0 0 11 15"><path d="M5.4 0C6.39875 0 7.26819 0.543814 7.73525 1.35H9.45C10.1956 1.35 10.8 1.95442 10.8 2.7V13.5C10.8 14.2456 10.1956 14.85 9.45 14.85H1.35C0.604415 14.85 2.17436e-08 14.2456 0 13.5V2.7C1.7395e-07 1.95442 0.604415 1.35 1.35 1.35H3.06475C3.53181 0.543814 4.40125 0 5.4 0ZM1.35 2.25C1.10147 2.25 0.9 2.45147 0.9 2.7V13.5C0.9 13.7485 1.10147 13.95 1.35 13.95H9.45C9.69853 13.95 9.9 13.7485 9.9 13.5V2.7C9.9 2.45147 9.69853 2.25 9.45 2.25H8.06221C8.08677 2.39637 8.1 2.54665 8.1 2.7V3.6C8.1 3.84853 7.89853 4.05 7.65 4.05H3.15C2.90147 4.05 2.7 3.84853 2.7 3.6V2.7C2.7 2.54665 2.71323 2.39637 2.73779 2.25H1.35ZM7.68603 10.6233C7.78376 10.395 8.04828 10.2886 8.27666 10.386C8.50499 10.4838 8.61143 10.7483 8.51396 10.9767C8.24856 11.5967 7.73014 12.15 7.01982 12.15C6.58192 12.1499 6.21722 11.9397 5.93965 11.6332C5.66215 11.9395 5.29801 12.1499 4.86035 12.15C4.42229 12.15 4.05692 11.9398 3.7793 11.6332C3.50175 11.9395 3.13773 12.15 2.7 12.15C2.45147 12.15 2.25 11.9485 2.25 11.7C2.25 11.4515 2.45147 11.25 2.7 11.25C2.8912 11.25 3.16726 11.0879 3.36621 10.6233L3.39697 10.5636C3.47806 10.4321 3.62261 10.35 3.78018 10.35C3.9602 10.3501 4.1233 10.4578 4.19414 10.6233C4.39309 11.0878 4.66917 11.25 4.86035 11.25C5.05156 11.2498 5.32773 11.0877 5.52656 10.6233L5.55732 10.5636C5.63837 10.4323 5.78229 10.3501 5.93965 10.35C6.11974 10.35 6.28275 10.4578 6.35361 10.6233C6.55251 11.0878 6.82862 11.2499 7.01982 11.25C7.21102 11.25 7.48708 11.0879 7.68603 10.6233ZM7.68603 7.02334C7.78376 6.79501 8.04828 6.68857 8.27666 6.78604C8.50499 6.88376 8.61143 7.14828 8.51396 7.37666C8.24856 7.99675 7.73014 8.55 7.01982 8.55C6.58192 8.54994 6.21722 8.3397 5.93965 8.0332C5.66215 8.33947 5.29801 8.54989 4.86035 8.55C4.42229 8.55 4.05692 8.33983 3.7793 8.0332C3.50175 8.33945 3.13773 8.55 2.7 8.55C2.45147 8.55 2.25 8.34853 2.25 8.1C2.25 7.85147 2.45147 7.65 2.7 7.65C2.8912 7.65 3.16726 7.48791 3.36621 7.02334L3.39697 6.96357C3.47806 6.83213 3.62261 6.75 3.78018 6.75C3.9602 6.75007 4.1233 6.85783 4.19414 7.02334C4.39309 7.48782 4.66917 7.65 4.86035 7.65C5.05156 7.6498 5.32773 7.48772 5.52656 7.02334L5.55732 6.96357C5.63837 6.83232 5.78229 6.75012 5.93965 6.75C6.11974 6.75 6.28275 6.85778 6.35361 7.02334C6.55251 7.48782 6.82862 7.6499 7.01982 7.65C7.21102 7.65 7.48708 7.48786 7.68603 7.02334ZM5.4 0.9C4.40589 0.9 3.6 1.70589 3.6 2.7V3.15H7.2V2.7C7.2 1.70589 6.39411 0.9 5.4 0.9Z" fill="currentColor"></path></svg><span class="body-3">Copy</span></button></div></div></div><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">The schema defines what's valid, but leaves critical questions unanswered:</p><ul class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><li><strong>Format ambiguity: </strong>Should <code class="InlineCodeBlock-module-scss-module__nsPAba__code">due_date</code> use "2024-11-06", "Nov 6, 2024", or "2024-11-06T00:00:00Z"?</li><li><strong>ID conventions: </strong>Is <code class="InlineCodeBlock-module-scss-module__nsPAba__code">reporter.id</code> a UUID, "USR-12345", or just "12345"?</li><li><strong>Nested structure usage: </strong>When should Claude populate <code class="InlineCodeBlock-module-scss-module__nsPAba__code">reporter.contact</code>?</li><li><strong>Parameter correlations: </strong>How do <code class="InlineCodeBlock-module-scss-module__nsPAba__code">escalation.level</code> and <code class="InlineCodeBlock-module-scss-module__nsPAba__code">escalation.sla_hours</code> relate to priority?</li></ul><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">These ambiguities can lead to malformed tool calls and inconsistent parameter usage.</p><h3 class="Body-module-scss-module__z40yvW__reading-column headline-5 post-section" id="our-solution">Our solution</h3><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Tool Use Examples let you provide sample tool calls directly in your tool definitions. Instead of relying on schema alone, you show Claude concrete usage patterns:</p><div class="Body-module-scss-module__z40yvW__media-column Body-module-scss-module__z40yvW__inline"><div class="CodeBlock-module-scss-module__PbWBnq__codeBlock"><pre class="" style="--height:300px;--height-expanded:0px"><code class="plaintext">{
"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": "[email protected]",
"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"
}
]
}</code></pre><div class="CodeBlock-module-scss-module__PbWBnq__controls"><button aria-label="Copy code"><svg class="Icon-module-scss-module__lqbdHG__icon" width="11" height="15" viewBox="0 0 11 15"><path d="M5.4 0C6.39875 0 7.26819 0.543814 7.73525 1.35H9.45C10.1956 1.35 10.8 1.95442 10.8 2.7V13.5C10.8 14.2456 10.1956 14.85 9.45 14.85H1.35C0.604415 14.85 2.17436e-08 14.2456 0 13.5V2.7C1.7395e-07 1.95442 0.604415 1.35 1.35 1.35H3.06475C3.53181 0.543814 4.40125 0 5.4 0ZM1.35 2.25C1.10147 2.25 0.9 2.45147 0.9 2.7V13.5C0.9 13.7485 1.10147 13.95 1.35 13.95H9.45C9.69853 13.95 9.9 13.7485 9.9 13.5V2.7C9.9 2.45147 9.69853 2.25 9.45 2.25H8.06221C8.08677 2.39637 8.1 2.54665 8.1 2.7V3.6C8.1 3.84853 7.89853 4.05 7.65 4.05H3.15C2.90147 4.05 2.7 3.84853 2.7 3.6V2.7C2.7 2.54665 2.71323 2.39637 2.73779 2.25H1.35ZM7.68603 10.6233C7.78376 10.395 8.04828 10.2886 8.27666 10.386C8.50499 10.4838 8.61143 10.7483 8.51396 10.9767C8.24856 11.5967 7.73014 12.15 7.01982 12.15C6.58192 12.1499 6.21722 11.9397 5.93965 11.6332C5.66215 11.9395 5.29801 12.1499 4.86035 12.15C4.42229 12.15 4.05692 11.9398 3.7793 11.6332C3.50175 11.9395 3.13773 12.15 2.7 12.15C2.45147 12.15 2.25 11.9485 2.25 11.7C2.25 11.4515 2.45147 11.25 2.7 11.25C2.8912 11.25 3.16726 11.0879 3.36621 10.6233L3.39697 10.5636C3.47806 10.4321 3.62261 10.35 3.78018 10.35C3.9602 10.3501 4.1233 10.4578 4.19414 10.6233C4.39309 11.0878 4.66917 11.25 4.86035 11.25C5.05156 11.2498 5.32773 11.0877 5.52656 10.6233L5.55732 10.5636C5.63837 10.4323 5.78229 10.3501 5.93965 10.35C6.1 |
TonyRL
reviewed
Dec 12, 2025
lib/routes/anthropic/engineering.ts
Outdated
Comment on lines
58
to
63
| [class^="PostDetail_post-heading"], | ||
| [class^="ArticleDetail_sidebar-container"], | ||
| [class^="QuoteCarousel_carousel-controls"], | ||
| [class^="PostDetail_b-social-share"], | ||
| [class^="LandingPageSection_root"], | ||
| [class^="CodeBlock_controls"] |
Collaborator
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
None of them matches a single element.
lib/routes/anthropic/engineering.ts
Outdated
| const $ = load(response); | ||
|
|
||
| const content = $('div[class^="Body_body__"]'); | ||
| const content = $('#main-content'); |
Collaborator
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Suggested change
| const content = $('#main-content'); | |
| const content = $('article > div > div[class*="__body"]'); |
Contributor
|
Successfully generated as following: http://localhost:1200/anthropic/engineering - Success ✔️<?xml version="1.0" encoding="UTF-8"?>
<rss xmlns:atom="http://www.w3.org/2005/Atom" version="2.0">
<channel>
<title>Anthropic Engineering</title>
<link>https://www.anthropic.com/engineering</link>
<atom:link href="http://localhost:1200/anthropic/engineering" rel="self" type="application/rss+xml"></atom:link>
<description>Latest engineering posts from Anthropic - Powered by RSSHub</description>
<generator>RSSHub</generator>
<webMaster>[email protected] (RSSHub)</webMaster>
<language>en</language>
<image>
<url>https://www.anthropic.com/images/icons/apple-touch-icon.png</url>
<title>Anthropic Engineering</title>
<link>https://www.anthropic.com/engineering</link>
</image>
<lastBuildDate>Sat, 13 Dec 2025 05:24:29 GMT</lastBuildDate>
<ttl>5</ttl>
<item>
<title>Introducing advanced tool use on the Claude Developer Platform</title>
<description><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">The future of AI agents is one where models work seamlessly across hundreds or thousands of tools. An IDE assistant that integrates git operations, file manipulation, package managers, testing frameworks, and deployment pipelines. An operations coordinator that connects Slack, GitHub, Google Drive, Jira, company databases, and dozens of MCP servers simultaneously.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">To <a href="https://www.anthropic.com/research/building-effective-agents" target="_blank" rel="noopener noreferrer">build effective agents</a>, they need to work with unlimited tool libraries without stuffing every definition into context upfront. Our blog article on using <a href="https://www.anthropic.com/engineering/code-execution-with-mcp" target="_blank" rel="noopener noreferrer">code execution with MCP</a> discussed how tool results and definitions can sometimes consume 50,000+ tokens before an agent reads a request. Agents should discover and load tools on-demand, keeping only what's relevant for the current task.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Agents also need the ability to call tools from code. When using natural language tool calling, each invocation requires a full inference pass, and intermediate results pile up in context whether they're useful or not. Code is a natural fit for orchestration logic, such as loops, conditionals, and data transformations. Agents need the flexibility to choose between code execution and inference based on the task at hand.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Agents also need to learn correct tool usage from examples, not just schema definitions. JSON schemas define what's structurally valid, but can't express usage patterns: when to include optional parameters, which combinations make sense, or what conventions your API expects.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Today, we're releasing three features that make this possible:</p><ul class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><li><strong>Tool Search Tool, </strong>which allows Claude to use search tools to access thousands of tools without consuming its context window</li><li><strong>Programmatic Tool Calling</strong>, which allows Claude to invoke tools in a code execution environment reducing the impact on the model’s context window</li><li><strong>Tool Use Examples</strong>, which provides a universal standard for demonstrating how to effectively use a given tool</li></ul><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">In internal testing, we’ve found these features have helped us build things that wouldn’t have been possible with conventional tool use patterns. For example,<strong> <a href="https://www.claude.com/claude-for-excel" target="_blank" rel="noopener noreferrer">Claude for Excel</a> </strong>uses Programmatic Tool Calling to read and modify spreadsheets with thousands of rows without overloading the model’s context window.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Based on our experience, we believe these features open up new possibilities for what you can build with Claude.</p><div class="Body-module-scss-module__z40yvW__media-column Body-module-scss-module__z40yvW__inline"><div class="Video-module-scss-module__qJNyFq__post-wrapper"><figure class="Video-module-scss-module__qJNyFq__post-video-container"><!--$!--><template data-dgst="BAILOUT_TO_CLIENT_SIDE_RENDERING"></template><!--/$--></figure></div></div><h2 class="Body-module-scss-module__z40yvW__reading-column headline-4 post-heading" id="tool-search-tool">Tool Search Tool</h2><h3 class="Body-module-scss-module__z40yvW__reading-column headline-5 post-section" id="the-challenge">The challenge</h3><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">MCP tool definitions provide important context, but as more servers connect, those tokens can add up. Consider a five-server setup:</p><ul class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><li>GitHub: 35 tools (~26K tokens)</li><li>Slack: 11 tools (~21K tokens)</li><li>Sentry: 5 tools (~3K tokens)</li><li>Grafana: 5 tools (~3K tokens)</li><li>Splunk: 2 tools (~2K tokens)</li></ul><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">That's 58 tools consuming approximately 55K tokens before the conversation even starts. Add more servers like Jira (which alone uses ~17K tokens) and you're quickly approaching 100K+ token overhead. At Anthropic, we've seen tool definitions consume 134K tokens before optimization.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">But token cost isn't the only issue. The most common failures are wrong tool selection and incorrect parameters, especially when tools have similar names like <code class="InlineCodeBlock-module-scss-module__nsPAba__code">notification-send-user</code> vs. <code class="InlineCodeBlock-module-scss-module__nsPAba__code">notification-send-channel</code>.</p><h3 class="Body-module-scss-module__z40yvW__reading-column headline-5 post-section" id="our-solution">Our solution</h3><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Instead of loading all tool definitions upfront, the Tool Search Tool discovers tools on-demand. Claude only sees the tools it actually needs for the current task.</p><div class="Body-module-scss-module__z40yvW__media-column Body-module-scss-module__z40yvW__inline"><figure class="ImageWithCaption-module-scss-module__Duq99q__e-imageWithCaption"><img alt="Tool Search Tool diagram" loading="lazy" width="1999" height="1125" decoding="async" data-nimg="1" src="https://www-cdn.anthropic.com/images/4zrzovbb/website/f359296f770706608901eadaffbff4ca0b67874c-1999x1125.png" referrerpolicy="no-referrer"><figcaption class="caption"><em>Tool Search Tool preserves 191,300 tokens of context compared to 122,800 with Claude’s traditional approach.</em></figcaption></figure></div><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"></p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Traditional approach:</p><ul class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><li>All tool definitions loaded upfront (~72K tokens for 50+ MCP tools)</li><li>Conversation history and system prompt compete for remaining space</li><li>Total context consumption: ~77K tokens before any work begins</li></ul><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">With the Tool Search Tool:</p><ul class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><li>Only the Tool Search Tool loaded upfront (~500 tokens)</li><li>Tools discovered on-demand as needed (3-5 relevant tools, ~3K tokens)</li><li>Total context consumption: ~8.7K tokens, preserving 95% of context window</li></ul><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">This represents an 85% reduction in token usage while maintaining access to your full tool library. Internal testing showed significant accuracy improvements on MCP evaluations when working with large tool libraries. Opus 4 improved from 49% to 74%, and Opus 4.5 improved from 79.5% to 88.1% with Tool Search Tool enabled.</p><h3 class="Body-module-scss-module__z40yvW__reading-column headline-5 post-section" id="how-the-tool-search-tool-works">How the Tool Search Tool works</h3><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">The Tool Search Tool lets Claude dynamically discover tools instead of loading all definitions upfront. You provide all your tool definitions to the API, but mark tools with <code class="InlineCodeBlock-module-scss-module__nsPAba__code">defer_loading: true</code> to make them discoverable on-demand. Deferred tools aren't loaded into Claude's context initially. Claude only sees the Tool Search Tool itself plus any tools with <code class="InlineCodeBlock-module-scss-module__nsPAba__code">defer_loading: false</code> (your most critical, frequently-used tools).</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">When Claude needs specific capabilities, it searches for relevant tools. The Tool Search Tool returns references to matching tools, which get expanded into full definitions in Claude's context.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">For example, if Claude needs to interact with GitHub, it searches for "github," and only <code class="InlineCodeBlock-module-scss-module__nsPAba__code">github.createPullRequest</code> and <code class="InlineCodeBlock-module-scss-module__nsPAba__code">github.listIssues</code> get loaded—not your other 50+ tools from Slack, Jira, and Google Drive.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">This way, Claude has access to your full tool library while only paying the token cost for tools it actually needs.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><strong>Prompt caching note: </strong>Tool Search Tool doesn't break prompt caching because deferred tools are excluded from the initial prompt entirely. They're only added to context after Claude searches for them, so your system prompt and core tool definitions remain cacheable.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><strong>Implementation:</strong></p><div class="Body-module-scss-module__z40yvW__media-column Body-module-scss-module__z40yvW__inline"><div class="CodeBlock-module-scss-module__PbWBnq__codeBlock"><pre class="" style="--height:300px;--height-expanded:0px"><code class="plaintext">{
"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
]
}
</code></pre><div class="CodeBlock-module-scss-module__PbWBnq__controls"><button aria-label="Copy code"><svg class="Icon-module-scss-module__lqbdHG__icon" width="11" height="15" viewBox="0 0 11 15"><path d="M5.4 0C6.39875 0 7.26819 0.543814 7.73525 1.35H9.45C10.1956 1.35 10.8 1.95442 10.8 2.7V13.5C10.8 14.2456 10.1956 14.85 9.45 14.85H1.35C0.604415 14.85 2.17436e-08 14.2456 0 13.5V2.7C1.7395e-07 1.95442 0.604415 1.35 1.35 1.35H3.06475C3.53181 0.543814 4.40125 0 5.4 0ZM1.35 2.25C1.10147 2.25 0.9 2.45147 0.9 2.7V13.5C0.9 13.7485 1.10147 13.95 1.35 13.95H9.45C9.69853 13.95 9.9 13.7485 9.9 13.5V2.7C9.9 2.45147 9.69853 2.25 9.45 2.25H8.06221C8.08677 2.39637 8.1 2.54665 8.1 2.7V3.6C8.1 3.84853 7.89853 4.05 7.65 4.05H3.15C2.90147 4.05 2.7 3.84853 2.7 3.6V2.7C2.7 2.54665 2.71323 2.39637 2.73779 2.25H1.35ZM7.68603 10.6233C7.78376 10.395 8.04828 10.2886 8.27666 10.386C8.50499 10.4838 8.61143 10.7483 8.51396 10.9767C8.24856 11.5967 7.73014 12.15 7.01982 12.15C6.58192 12.1499 6.21722 11.9397 5.93965 11.6332C5.66215 11.9395 5.29801 12.1499 4.86035 12.15C4.42229 12.15 4.05692 11.9398 3.7793 11.6332C3.50175 11.9395 3.13773 12.15 2.7 12.15C2.45147 12.15 2.25 11.9485 2.25 11.7C2.25 11.4515 2.45147 11.25 2.7 11.25C2.8912 11.25 3.16726 11.0879 3.36621 10.6233L3.39697 10.5636C3.47806 10.4321 3.62261 10.35 3.78018 10.35C3.9602 10.3501 4.1233 10.4578 4.19414 10.6233C4.39309 11.0878 4.66917 11.25 4.86035 11.25C5.05156 11.2498 5.32773 11.0877 5.52656 10.6233L5.55732 10.5636C5.63837 10.4323 5.78229 10.3501 5.93965 10.35C6.11974 10.35 6.28275 10.4578 6.35361 10.6233C6.55251 11.0878 6.82862 11.2499 7.01982 11.25C7.21102 11.25 7.48708 11.0879 7.68603 10.6233ZM7.68603 7.02334C7.78376 6.79501 8.04828 6.68857 8.27666 6.78604C8.50499 6.88376 8.61143 7.14828 8.51396 7.37666C8.24856 7.99675 7.73014 8.55 7.01982 8.55C6.58192 8.54994 6.21722 8.3397 5.93965 8.0332C5.66215 8.33947 5.29801 8.54989 4.86035 8.55C4.42229 8.55 4.05692 8.33983 3.7793 8.0332C3.50175 8.33945 3.13773 8.55 2.7 8.55C2.45147 8.55 2.25 8.34853 2.25 8.1C2.25 7.85147 2.45147 7.65 2.7 7.65C2.8912 7.65 3.16726 7.48791 3.36621 7.02334L3.39697 6.96357C3.47806 6.83213 3.62261 6.75 3.78018 6.75C3.9602 6.75007 4.1233 6.85783 4.19414 7.02334C4.39309 7.48782 4.66917 7.65 4.86035 7.65C5.05156 7.6498 5.32773 7.48772 5.52656 7.02334L5.55732 6.96357C5.63837 6.83232 5.78229 6.75012 5.93965 6.75C6.11974 6.75 6.28275 6.85778 6.35361 7.02334C6.55251 7.48782 6.82862 7.6499 7.01982 7.65C7.21102 7.65 7.48708 7.48786 7.68603 7.02334ZM5.4 0.9C4.40589 0.9 3.6 1.70589 3.6 2.7V3.15H7.2V2.7C7.2 1.70589 6.39411 0.9 5.4 0.9Z" fill="currentColor"></path></svg><span class="body-3">Copy</span></button></div></div></div><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">For MCP servers, you can defer loading entire servers while keeping specific high-use tools loaded:</p><div class="Body-module-scss-module__z40yvW__media-column Body-module-scss-module__z40yvW__inline"><div class="CodeBlock-module-scss-module__PbWBnq__codeBlock"><pre class="" style="--height:300px;--height-expanded:0px"><code class="plaintext">{
"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
}
}</code></pre><div class="CodeBlock-module-scss-module__PbWBnq__controls"><button aria-label="Copy code"><svg class="Icon-module-scss-module__lqbdHG__icon" width="11" height="15" viewBox="0 0 11 15"><path d="M5.4 0C6.39875 0 7.26819 0.543814 7.73525 1.35H9.45C10.1956 1.35 10.8 1.95442 10.8 2.7V13.5C10.8 14.2456 10.1956 14.85 9.45 14.85H1.35C0.604415 14.85 2.17436e-08 14.2456 0 13.5V2.7C1.7395e-07 1.95442 0.604415 1.35 1.35 1.35H3.06475C3.53181 0.543814 4.40125 0 5.4 0ZM1.35 2.25C1.10147 2.25 0.9 2.45147 0.9 2.7V13.5C0.9 13.7485 1.10147 13.95 1.35 13.95H9.45C9.69853 13.95 9.9 13.7485 9.9 13.5V2.7C9.9 2.45147 9.69853 2.25 9.45 2.25H8.06221C8.08677 2.39637 8.1 2.54665 8.1 2.7V3.6C8.1 3.84853 7.89853 4.05 7.65 4.05H3.15C2.90147 4.05 2.7 3.84853 2.7 3.6V2.7C2.7 2.54665 2.71323 2.39637 2.73779 2.25H1.35ZM7.68603 10.6233C7.78376 10.395 8.04828 10.2886 8.27666 10.386C8.50499 10.4838 8.61143 10.7483 8.51396 10.9767C8.24856 11.5967 7.73014 12.15 7.01982 12.15C6.58192 12.1499 6.21722 11.9397 5.93965 11.6332C5.66215 11.9395 5.29801 12.1499 4.86035 12.15C4.42229 12.15 4.05692 11.9398 3.7793 11.6332C3.50175 11.9395 3.13773 12.15 2.7 12.15C2.45147 12.15 2.25 11.9485 2.25 11.7C2.25 11.4515 2.45147 11.25 2.7 11.25C2.8912 11.25 3.16726 11.0879 3.36621 10.6233L3.39697 10.5636C3.47806 10.4321 3.62261 10.35 3.78018 10.35C3.9602 10.3501 4.1233 10.4578 4.19414 10.6233C4.39309 11.0878 4.66917 11.25 4.86035 11.25C5.05156 11.2498 5.32773 11.0877 5.52656 10.6233L5.55732 10.5636C5.63837 10.4323 5.78229 10.3501 5.93965 10.35C6.11974 10.35 6.28275 10.4578 6.35361 10.6233C6.55251 11.0878 6.82862 11.2499 7.01982 11.25C7.21102 11.25 7.48708 11.0879 7.68603 10.6233ZM7.68603 7.02334C7.78376 6.79501 8.04828 6.68857 8.27666 6.78604C8.50499 6.88376 8.61143 7.14828 8.51396 7.37666C8.24856 7.99675 7.73014 8.55 7.01982 8.55C6.58192 8.54994 6.21722 8.3397 5.93965 8.0332C5.66215 8.33947 5.29801 8.54989 4.86035 8.55C4.42229 8.55 4.05692 8.33983 3.7793 8.0332C3.50175 8.33945 3.13773 8.55 2.7 8.55C2.45147 8.55 2.25 8.34853 2.25 8.1C2.25 7.85147 2.45147 7.65 2.7 7.65C2.8912 7.65 3.16726 7.48791 3.36621 7.02334L3.39697 6.96357C3.47806 6.83213 3.62261 6.75 3.78018 6.75C3.9602 6.75007 4.1233 6.85783 4.19414 7.02334C4.39309 7.48782 4.66917 7.65 4.86035 7.65C5.05156 7.6498 5.32773 7.48772 5.52656 7.02334L5.55732 6.96357C5.63837 6.83232 5.78229 6.75012 5.93965 6.75C6.11974 6.75 6.28275 6.85778 6.35361 7.02334C6.55251 7.48782 6.82862 7.6499 7.01982 7.65C7.21102 7.65 7.48708 7.48786 7.68603 7.02334ZM5.4 0.9C4.40589 0.9 3.6 1.70589 3.6 2.7V3.15H7.2V2.7C7.2 1.70589 6.39411 0.9 5.4 0.9Z" fill="currentColor"></path></svg><span class="body-3">Copy</span></button></div></div></div><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">The Claude Developer Platform provides regex-based and BM25-based search tools out of the box, but you can also implement custom search tools using embeddings or other strategies.</p><h3 class="Body-module-scss-module__z40yvW__reading-column headline-5 post-section" id="when-to-use-the-tool-search-tool">When to use the Tool Search Tool</h3><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Like any architectural decision, enabling the Tool Search Tool involves trade-offs. The feature adds a search step before tool invocation, so it delivers the best ROI when the context savings and accuracy improvements outweigh additional latency.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><strong>Use it when:</strong></p><ul class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><li>Tool definitions consuming &gt;10K tokens</li><li>Experiencing tool selection accuracy issues</li><li>Building MCP-powered systems with multiple servers</li><li>10+ tools available</li></ul><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><strong>Less beneficial when:</strong></p><ul class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><li>Small tool library (&lt;10 tools)</li><li>All tools used frequently in every session</li><li>Tool definitions are compact</li></ul><h2 class="Body-module-scss-module__z40yvW__reading-column headline-4 post-heading" id="programmatic-tool-calling">Programmatic Tool Calling</h2><h3 class="Body-module-scss-module__z40yvW__reading-column headline-5 post-section" id="the-challenge">The challenge</h3><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Traditional tool calling creates two fundamental problems as workflows become more complex:</p><ul class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><li><strong>Context pollution from intermediate results</strong>: 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.</li><li><strong>Inference overhead and manual synthesis</strong>: 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.</li></ul><h3 class="Body-module-scss-module__z40yvW__reading-column headline-5 post-section" id="our-solution">Our solution</h3><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Programmatic Tool Calling enables Claude to orchestrate tools through code rather than through 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 actually enters its context window.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Claude excels at writing code and by letting it express orchestration logic in Python rather than through natural language tool invocations, you get more reliable, precise control flow. Loops, conditionals, data transformations, and error handling are all explicit in code rather than implicit in Claude's reasoning.</p><h4 class="Body-module-scss-module__z40yvW__reading-column headline-6 post-subsection" id="example-budget-compliance-check">Example: Budget compliance check</h4><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Consider a common business task: "Which team members exceeded their Q3 travel budget?"</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">You have three tools available:</p><ul class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><li><code class="InlineCodeBlock-module-scss-module__nsPAba__code">get_team_members(department)</code> - Returns team member list with IDs and levels</li><li><code class="InlineCodeBlock-module-scss-module__nsPAba__code">get_expenses(user_id, quarter)</code> - Returns expense line items for a user</li><li><code class="InlineCodeBlock-module-scss-module__nsPAba__code">get_budget_by_level(level)</code> - Returns budget limits for an employee level</li></ul><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><strong>Traditional approach</strong>:</p><ul class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><li>Fetch team members → 20 people</li><li>For each person, fetch their Q3 expenses → 20 tool calls, each returning 50-100 line items (flights, hotels, meals, receipts)</li><li>Fetch budget limits by employee level</li><li>All of this enters Claude's context: 2,000+ expense line items (50 KB+)</li><li>Claude manually sums each person's expenses, looks up their budget, compares expenses against budget limits</li><li>More round-trips to the model, significant context consumption</li></ul><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><strong>With Programmatic Tool Calling</strong>:</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Instead of each tool result returning to Claude, 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're processed by the script rather than consumed by the model. The script continues executing, and Claude only sees the final output.</p><div class="Body-module-scss-module__z40yvW__media-column Body-module-scss-module__z40yvW__inline"><figure class="ImageWithCaption-module-scss-module__Duq99q__e-imageWithCaption"><img alt="Programmatic tool calling flow" loading="lazy" width="1999" height="1491" decoding="async" data-nimg="1" src="https://www-cdn.anthropic.com/images/4zrzovbb/website/65737d69a3290ed5c1f3c3b8dc873645a9dcc2eb-1999x1491.png" referrerpolicy="no-referrer"><figcaption class="caption">Programmatic Tool Calling enables Claude to orchestrate tools through code rather than through individual API round-trips, allowing for parallel tool execution.</figcaption></figure></div><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Here's what Claude's orchestration code looks like for the budget compliance task:</p><div class="Body-module-scss-module__z40yvW__media-column Body-module-scss-module__z40yvW__inline"><div class="CodeBlock-module-scss-module__PbWBnq__codeBlock"><pre class="" style="--height:300px;--height-expanded:0px"><code class="plaintext">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 &gt; budget["travel_limit"]:
exceeded.append({
"name": member["name"],
"spent": total,
"limit": budget["travel_limit"]
})
print(json.dumps(exceeded))</code></pre><div class="CodeBlock-module-scss-module__PbWBnq__controls"><button aria-label="Copy code"><svg class="Icon-module-scss-module__lqbdHG__icon" width="11" height="15" viewBox="0 0 11 15"><path d="M5.4 0C6.39875 0 7.26819 0.543814 7.73525 1.35H9.45C10.1956 1.35 10.8 1.95442 10.8 2.7V13.5C10.8 14.2456 10.1956 14.85 9.45 14.85H1.35C0.604415 14.85 2.17436e-08 14.2456 0 13.5V2.7C1.7395e-07 1.95442 0.604415 1.35 1.35 1.35H3.06475C3.53181 0.543814 4.40125 0 5.4 0ZM1.35 2.25C1.10147 2.25 0.9 2.45147 0.9 2.7V13.5C0.9 13.7485 1.10147 13.95 1.35 13.95H9.45C9.69853 13.95 9.9 13.7485 9.9 13.5V2.7C9.9 2.45147 9.69853 2.25 9.45 2.25H8.06221C8.08677 2.39637 8.1 2.54665 8.1 2.7V3.6C8.1 3.84853 7.89853 4.05 7.65 4.05H3.15C2.90147 4.05 2.7 3.84853 2.7 3.6V2.7C2.7 2.54665 2.71323 2.39637 2.73779 2.25H1.35ZM7.68603 10.6233C7.78376 10.395 8.04828 10.2886 8.27666 10.386C8.50499 10.4838 8.61143 10.7483 8.51396 10.9767C8.24856 11.5967 7.73014 12.15 7.01982 12.15C6.58192 12.1499 6.21722 11.9397 5.93965 11.6332C5.66215 11.9395 5.29801 12.1499 4.86035 12.15C4.42229 12.15 4.05692 11.9398 3.7793 11.6332C3.50175 11.9395 3.13773 12.15 2.7 12.15C2.45147 12.15 2.25 11.9485 2.25 11.7C2.25 11.4515 2.45147 11.25 2.7 11.25C2.8912 11.25 3.16726 11.0879 3.36621 10.6233L3.39697 10.5636C3.47806 10.4321 3.62261 10.35 3.78018 10.35C3.9602 10.3501 4.1233 10.4578 4.19414 10.6233C4.39309 11.0878 4.66917 11.25 4.86035 11.25C5.05156 11.2498 5.32773 11.0877 5.52656 10.6233L5.55732 10.5636C5.63837 10.4323 5.78229 10.3501 5.93965 10.35C6.11974 10.35 6.28275 10.4578 6.35361 10.6233C6.55251 11.0878 6.82862 11.2499 7.01982 11.25C7.21102 11.25 7.48708 11.0879 7.68603 10.6233ZM7.68603 7.02334C7.78376 6.79501 8.04828 6.68857 8.27666 6.78604C8.50499 6.88376 8.61143 7.14828 8.51396 7.37666C8.24856 7.99675 7.73014 8.55 7.01982 8.55C6.58192 8.54994 6.21722 8.3397 5.93965 8.0332C5.66215 8.33947 5.29801 8.54989 4.86035 8.55C4.42229 8.55 4.05692 8.33983 3.7793 8.0332C3.50175 8.33945 3.13773 8.55 2.7 8.55C2.45147 8.55 2.25 8.34853 2.25 8.1C2.25 7.85147 2.45147 7.65 2.7 7.65C2.8912 7.65 3.16726 7.48791 3.36621 7.02334L3.39697 6.96357C3.47806 6.83213 3.62261 6.75 3.78018 6.75C3.9602 6.75007 4.1233 6.85783 4.19414 7.02334C4.39309 7.48782 4.66917 7.65 4.86035 7.65C5.05156 7.6498 5.32773 7.48772 5.52656 7.02334L5.55732 6.96357C5.63837 6.83232 5.78229 6.75012 5.93965 6.75C6.11974 6.75 6.28275 6.85778 6.35361 7.02334C6.55251 7.48782 6.82862 7.6499 7.01982 7.65C7.21102 7.65 7.48708 7.48786 7.68603 7.02334ZM5.4 0.9C4.40589 0.9 3.6 1.70589 3.6 2.7V3.15H7.2V2.7C7.2 1.70589 6.39411 0.9 5.4 0.9Z" fill="currentColor"></path></svg><span class="body-3">Copy</span></button></div></div></div><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Claude's context receives only the final result: the two to three people who exceeded their budget. The 2,000+ line items, the intermediate sums, and the budget lookups do not affect Claude’s context, reducing consumption from 200KB of raw expense data to just 1KB of results.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">The efficiency gains are substantial:</p><ul class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><li><strong>Token savings</strong>: 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.</li><li><strong>Reduced latency</strong>: 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.</li><li><strong>Improved accuracy</strong>: 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%; <a href="https://arxiv.org/abs/2311.12983" target="_blank" rel="noopener noreferrer">GIA benchmarks</a> from 46.5% to 51.2%.</li></ul><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Production workflows involve messy data, conditional logic, and operations that need to scale. Programmatic Tool Calling lets Claude handle that complexity programmatically while keeping its focus on actionable results rather than raw data processing.</p><h3 class="Body-module-scss-module__z40yvW__reading-column headline-5 post-section" id="how-programmatic-tool-calling-works">How Programmatic Tool Calling works</h3><h4 class="Body-module-scss-module__z40yvW__reading-column headline-6 post-subsection" id="1-mark-tools-as-callable-from-code">1. Mark tools as callable from code</h4><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Add code_execution to tools, and set allowed_callers to opt-in tools for programmatic execution:</p><div class="Body-module-scss-module__z40yvW__media-column Body-module-scss-module__z40yvW__inline"><div class="CodeBlock-module-scss-module__PbWBnq__codeBlock"><pre class="" style="--height:300px;--height-expanded:0px"><code class="plaintext">{
"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",
...
}
]
}</code></pre><div class="CodeBlock-module-scss-module__PbWBnq__controls"><button aria-label="Copy code"><svg class="Icon-module-scss-module__lqbdHG__icon" width="11" height="15" viewBox="0 0 11 15"><path d="M5.4 0C6.39875 0 7.26819 0.543814 7.73525 1.35H9.45C10.1956 1.35 10.8 1.95442 10.8 2.7V13.5C10.8 14.2456 10.1956 14.85 9.45 14.85H1.35C0.604415 14.85 2.17436e-08 14.2456 0 13.5V2.7C1.7395e-07 1.95442 0.604415 1.35 1.35 1.35H3.06475C3.53181 0.543814 4.40125 0 5.4 0ZM1.35 2.25C1.10147 2.25 0.9 2.45147 0.9 2.7V13.5C0.9 13.7485 1.10147 13.95 1.35 13.95H9.45C9.69853 13.95 9.9 13.7485 9.9 13.5V2.7C9.9 2.45147 9.69853 2.25 9.45 2.25H8.06221C8.08677 2.39637 8.1 2.54665 8.1 2.7V3.6C8.1 3.84853 7.89853 4.05 7.65 4.05H3.15C2.90147 4.05 2.7 3.84853 2.7 3.6V2.7C2.7 2.54665 2.71323 2.39637 2.73779 2.25H1.35ZM7.68603 10.6233C7.78376 10.395 8.04828 10.2886 8.27666 10.386C8.50499 10.4838 8.61143 10.7483 8.51396 10.9767C8.24856 11.5967 7.73014 12.15 7.01982 12.15C6.58192 12.1499 6.21722 11.9397 5.93965 11.6332C5.66215 11.9395 5.29801 12.1499 4.86035 12.15C4.42229 12.15 4.05692 11.9398 3.7793 11.6332C3.50175 11.9395 3.13773 12.15 2.7 12.15C2.45147 12.15 2.25 11.9485 2.25 11.7C2.25 11.4515 2.45147 11.25 2.7 11.25C2.8912 11.25 3.16726 11.0879 3.36621 10.6233L3.39697 10.5636C3.47806 10.4321 3.62261 10.35 3.78018 10.35C3.9602 10.3501 4.1233 10.4578 4.19414 10.6233C4.39309 11.0878 4.66917 11.25 4.86035 11.25C5.05156 11.2498 5.32773 11.0877 5.52656 10.6233L5.55732 10.5636C5.63837 10.4323 5.78229 10.3501 5.93965 10.35C6.11974 10.35 6.28275 10.4578 6.35361 10.6233C6.55251 11.0878 6.82862 11.2499 7.01982 11.25C7.21102 11.25 7.48708 11.0879 7.68603 10.6233ZM7.68603 7.02334C7.78376 6.79501 8.04828 6.68857 8.27666 6.78604C8.50499 6.88376 8.61143 7.14828 8.51396 7.37666C8.24856 7.99675 7.73014 8.55 7.01982 8.55C6.58192 8.54994 6.21722 8.3397 5.93965 8.0332C5.66215 8.33947 5.29801 8.54989 4.86035 8.55C4.42229 8.55 4.05692 8.33983 3.7793 8.0332C3.50175 8.33945 3.13773 8.55 2.7 8.55C2.45147 8.55 2.25 8.34853 2.25 8.1C2.25 7.85147 2.45147 7.65 2.7 7.65C2.8912 7.65 3.16726 7.48791 3.36621 7.02334L3.39697 6.96357C3.47806 6.83213 3.62261 6.75 3.78018 6.75C3.9602 6.75007 4.1233 6.85783 4.19414 7.02334C4.39309 7.48782 4.66917 7.65 4.86035 7.65C5.05156 7.6498 5.32773 7.48772 5.52656 7.02334L5.55732 6.96357C5.63837 6.83232 5.78229 6.75012 5.93965 6.75C6.11974 6.75 6.28275 6.85778 6.35361 7.02334C6.55251 7.48782 6.82862 7.6499 7.01982 7.65C7.21102 7.65 7.48708 7.48786 7.68603 7.02334ZM5.4 0.9C4.40589 0.9 3.6 1.70589 3.6 2.7V3.15H7.2V2.7C7.2 1.70589 6.39411 0.9 5.4 0.9Z" fill="currentColor"></path></svg><span class="body-3">Copy</span></button></div></div></div><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">The API converts these tool definitions into Python functions that Claude can call.</p><h4 class="Body-module-scss-module__z40yvW__reading-column headline-6 post-subsection" id="2-claude-writes-orchestration-code">2. Claude writes orchestration code</h4><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Instead of requesting tools one at a time, Claude generates Python code:</p><div class="Body-module-scss-module__z40yvW__media-column Body-module-scss-module__z40yvW__inline"><div class="CodeBlock-module-scss-module__PbWBnq__codeBlock"><pre class="" style="--height:300px;--height-expanded:0px"><code class="plaintext">{
"type": "server_tool_use",
"id": "srvtoolu_abc",
"name": "code_execution",
"input": {
"code": "team = get_team_members('engineering')\n..." # the code example above
}
}</code></pre><div class="CodeBlock-module-scss-module__PbWBnq__controls"><button aria-label="Copy code"><svg class="Icon-module-scss-module__lqbdHG__icon" width="11" height="15" viewBox="0 0 11 15"><path d="M5.4 0C6.39875 0 7.26819 0.543814 7.73525 1.35H9.45C10.1956 1.35 10.8 1.95442 10.8 2.7V13.5C10.8 14.2456 10.1956 14.85 9.45 14.85H1.35C0.604415 14.85 2.17436e-08 14.2456 0 13.5V2.7C1.7395e-07 1.95442 0.604415 1.35 1.35 1.35H3.06475C3.53181 0.543814 4.40125 0 5.4 0ZM1.35 2.25C1.10147 2.25 0.9 2.45147 0.9 2.7V13.5C0.9 13.7485 1.10147 13.95 1.35 13.95H9.45C9.69853 13.95 9.9 13.7485 9.9 13.5V2.7C9.9 2.45147 9.69853 2.25 9.45 2.25H8.06221C8.08677 2.39637 8.1 2.54665 8.1 2.7V3.6C8.1 3.84853 7.89853 4.05 7.65 4.05H3.15C2.90147 4.05 2.7 3.84853 2.7 3.6V2.7C2.7 2.54665 2.71323 2.39637 2.73779 2.25H1.35ZM7.68603 10.6233C7.78376 10.395 8.04828 10.2886 8.27666 10.386C8.50499 10.4838 8.61143 10.7483 8.51396 10.9767C8.24856 11.5967 7.73014 12.15 7.01982 12.15C6.58192 12.1499 6.21722 11.9397 5.93965 11.6332C5.66215 11.9395 5.29801 12.1499 4.86035 12.15C4.42229 12.15 4.05692 11.9398 3.7793 11.6332C3.50175 11.9395 3.13773 12.15 2.7 12.15C2.45147 12.15 2.25 11.9485 2.25 11.7C2.25 11.4515 2.45147 11.25 2.7 11.25C2.8912 11.25 3.16726 11.0879 3.36621 10.6233L3.39697 10.5636C3.47806 10.4321 3.62261 10.35 3.78018 10.35C3.9602 10.3501 4.1233 10.4578 4.19414 10.6233C4.39309 11.0878 4.66917 11.25 4.86035 11.25C5.05156 11.2498 5.32773 11.0877 5.52656 10.6233L5.55732 10.5636C5.63837 10.4323 5.78229 10.3501 5.93965 10.35C6.11974 10.35 6.28275 10.4578 6.35361 10.6233C6.55251 11.0878 6.82862 11.2499 7.01982 11.25C7.21102 11.25 7.48708 11.0879 7.68603 10.6233ZM7.68603 7.02334C7.78376 6.79501 8.04828 6.68857 8.27666 6.78604C8.50499 6.88376 8.61143 7.14828 8.51396 7.37666C8.24856 7.99675 7.73014 8.55 7.01982 8.55C6.58192 8.54994 6.21722 8.3397 5.93965 8.0332C5.66215 8.33947 5.29801 8.54989 4.86035 8.55C4.42229 8.55 4.05692 8.33983 3.7793 8.0332C3.50175 8.33945 3.13773 8.55 2.7 8.55C2.45147 8.55 2.25 8.34853 2.25 8.1C2.25 7.85147 2.45147 7.65 2.7 7.65C2.8912 7.65 3.16726 7.48791 3.36621 7.02334L3.39697 6.96357C3.47806 6.83213 3.62261 6.75 3.78018 6.75C3.9602 6.75007 4.1233 6.85783 4.19414 7.02334C4.39309 7.48782 4.66917 7.65 4.86035 7.65C5.05156 7.6498 5.32773 7.48772 5.52656 7.02334L5.55732 6.96357C5.63837 6.83232 5.78229 6.75012 5.93965 6.75C6.11974 6.75 6.28275 6.85778 6.35361 7.02334C6.55251 7.48782 6.82862 7.6499 7.01982 7.65C7.21102 7.65 7.48708 7.48786 7.68603 7.02334ZM5.4 0.9C4.40589 0.9 3.6 1.70589 3.6 2.7V3.15H7.2V2.7C7.2 1.70589 6.39411 0.9 5.4 0.9Z" fill="currentColor"></path></svg><span class="body-3">Copy</span></button></div></div></div><h4 class="Body-module-scss-module__z40yvW__reading-column headline-6 post-subsection" id="3-tools-execute-without-hitting-claudes-context">3. Tools execute without hitting Claude's context</h4><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">When the code calls get_expenses(), you receive a tool request with a caller field:</p><div class="Body-module-scss-module__z40yvW__media-column Body-module-scss-module__z40yvW__inline"><div class="CodeBlock-module-scss-module__PbWBnq__codeBlock"><pre class="" style="--height:300px;--height-expanded:0px"><code class="plaintext">{
"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"
}
}</code></pre><div class="CodeBlock-module-scss-module__PbWBnq__controls"><button aria-label="Copy code"><svg class="Icon-module-scss-module__lqbdHG__icon" width="11" height="15" viewBox="0 0 11 15"><path d="M5.4 0C6.39875 0 7.26819 0.543814 7.73525 1.35H9.45C10.1956 1.35 10.8 1.95442 10.8 2.7V13.5C10.8 14.2456 10.1956 14.85 9.45 14.85H1.35C0.604415 14.85 2.17436e-08 14.2456 0 13.5V2.7C1.7395e-07 1.95442 0.604415 1.35 1.35 1.35H3.06475C3.53181 0.543814 4.40125 0 5.4 0ZM1.35 2.25C1.10147 2.25 0.9 2.45147 0.9 2.7V13.5C0.9 13.7485 1.10147 13.95 1.35 13.95H9.45C9.69853 13.95 9.9 13.7485 9.9 13.5V2.7C9.9 2.45147 9.69853 2.25 9.45 2.25H8.06221C8.08677 2.39637 8.1 2.54665 8.1 2.7V3.6C8.1 3.84853 7.89853 4.05 7.65 4.05H3.15C2.90147 4.05 2.7 3.84853 2.7 3.6V2.7C2.7 2.54665 2.71323 2.39637 2.73779 2.25H1.35ZM7.68603 10.6233C7.78376 10.395 8.04828 10.2886 8.27666 10.386C8.50499 10.4838 8.61143 10.7483 8.51396 10.9767C8.24856 11.5967 7.73014 12.15 7.01982 12.15C6.58192 12.1499 6.21722 11.9397 5.93965 11.6332C5.66215 11.9395 5.29801 12.1499 4.86035 12.15C4.42229 12.15 4.05692 11.9398 3.7793 11.6332C3.50175 11.9395 3.13773 12.15 2.7 12.15C2.45147 12.15 2.25 11.9485 2.25 11.7C2.25 11.4515 2.45147 11.25 2.7 11.25C2.8912 11.25 3.16726 11.0879 3.36621 10.6233L3.39697 10.5636C3.47806 10.4321 3.62261 10.35 3.78018 10.35C3.9602 10.3501 4.1233 10.4578 4.19414 10.6233C4.39309 11.0878 4.66917 11.25 4.86035 11.25C5.05156 11.2498 5.32773 11.0877 5.52656 10.6233L5.55732 10.5636C5.63837 10.4323 5.78229 10.3501 5.93965 10.35C6.11974 10.35 6.28275 10.4578 6.35361 10.6233C6.55251 11.0878 6.82862 11.2499 7.01982 11.25C7.21102 11.25 7.48708 11.0879 7.68603 10.6233ZM7.68603 7.02334C7.78376 6.79501 8.04828 6.68857 8.27666 6.78604C8.50499 6.88376 8.61143 7.14828 8.51396 7.37666C8.24856 7.99675 7.73014 8.55 7.01982 8.55C6.58192 8.54994 6.21722 8.3397 5.93965 8.0332C5.66215 8.33947 5.29801 8.54989 4.86035 8.55C4.42229 8.55 4.05692 8.33983 3.7793 8.0332C3.50175 8.33945 3.13773 8.55 2.7 8.55C2.45147 8.55 2.25 8.34853 2.25 8.1C2.25 7.85147 2.45147 7.65 2.7 7.65C2.8912 7.65 3.16726 7.48791 3.36621 7.02334L3.39697 6.96357C3.47806 6.83213 3.62261 6.75 3.78018 6.75C3.9602 6.75007 4.1233 6.85783 4.19414 7.02334C4.39309 7.48782 4.66917 7.65 4.86035 7.65C5.05156 7.6498 5.32773 7.48772 5.52656 7.02334L5.55732 6.96357C5.63837 6.83232 5.78229 6.75012 5.93965 6.75C6.11974 6.75 6.28275 6.85778 6.35361 7.02334C6.55251 7.48782 6.82862 7.6499 7.01982 7.65C7.21102 7.65 7.48708 7.48786 7.68603 7.02334ZM5.4 0.9C4.40589 0.9 3.6 1.70589 3.6 2.7V3.15H7.2V2.7C7.2 1.70589 6.39411 0.9 5.4 0.9Z" fill="currentColor"></path></svg><span class="body-3">Copy</span></button></div></div></div><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">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.</p><h4 class="Body-module-scss-module__z40yvW__reading-column headline-6 post-subsection" id="4-only-final-output-enters-context">4. Only final output enters context</h4><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">When the code finishes running, only the results of the code are returned to Claude:</p><div class="Body-module-scss-module__z40yvW__media-column Body-module-scss-module__z40yvW__inline"><div class="CodeBlock-module-scss-module__PbWBnq__codeBlock"><pre class="" style="--height:300px;--height-expanded:0px"><code class="plaintext">{
"type": "code_execution_tool_result",
"tool_use_id": "srvtoolu_abc",
"content": {
"stdout": "[{\"name\": \"Alice\", \"spent\": 12500, \"limit\": 10000}...]"
}
}</code></pre><div class="CodeBlock-module-scss-module__PbWBnq__controls"><button aria-label="Copy code"><svg class="Icon-module-scss-module__lqbdHG__icon" width="11" height="15" viewBox="0 0 11 15"><path d="M5.4 0C6.39875 0 7.26819 0.543814 7.73525 1.35H9.45C10.1956 1.35 10.8 1.95442 10.8 2.7V13.5C10.8 14.2456 10.1956 14.85 9.45 14.85H1.35C0.604415 14.85 2.17436e-08 14.2456 0 13.5V2.7C1.7395e-07 1.95442 0.604415 1.35 1.35 1.35H3.06475C3.53181 0.543814 4.40125 0 5.4 0ZM1.35 2.25C1.10147 2.25 0.9 2.45147 0.9 2.7V13.5C0.9 13.7485 1.10147 13.95 1.35 13.95H9.45C9.69853 13.95 9.9 13.7485 9.9 13.5V2.7C9.9 2.45147 9.69853 2.25 9.45 2.25H8.06221C8.08677 2.39637 8.1 2.54665 8.1 2.7V3.6C8.1 3.84853 7.89853 4.05 7.65 4.05H3.15C2.90147 4.05 2.7 3.84853 2.7 3.6V2.7C2.7 2.54665 2.71323 2.39637 2.73779 2.25H1.35ZM7.68603 10.6233C7.78376 10.395 8.04828 10.2886 8.27666 10.386C8.50499 10.4838 8.61143 10.7483 8.51396 10.9767C8.24856 11.5967 7.73014 12.15 7.01982 12.15C6.58192 12.1499 6.21722 11.9397 5.93965 11.6332C5.66215 11.9395 5.29801 12.1499 4.86035 12.15C4.42229 12.15 4.05692 11.9398 3.7793 11.6332C3.50175 11.9395 3.13773 12.15 2.7 12.15C2.45147 12.15 2.25 11.9485 2.25 11.7C2.25 11.4515 2.45147 11.25 2.7 11.25C2.8912 11.25 3.16726 11.0879 3.36621 10.6233L3.39697 10.5636C3.47806 10.4321 3.62261 10.35 3.78018 10.35C3.9602 10.3501 4.1233 10.4578 4.19414 10.6233C4.39309 11.0878 4.66917 11.25 4.86035 11.25C5.05156 11.2498 5.32773 11.0877 5.52656 10.6233L5.55732 10.5636C5.63837 10.4323 5.78229 10.3501 5.93965 10.35C6.11974 10.35 6.28275 10.4578 6.35361 10.6233C6.55251 11.0878 6.82862 11.2499 7.01982 11.25C7.21102 11.25 7.48708 11.0879 7.68603 10.6233ZM7.68603 7.02334C7.78376 6.79501 8.04828 6.68857 8.27666 6.78604C8.50499 6.88376 8.61143 7.14828 8.51396 7.37666C8.24856 7.99675 7.73014 8.55 7.01982 8.55C6.58192 8.54994 6.21722 8.3397 5.93965 8.0332C5.66215 8.33947 5.29801 8.54989 4.86035 8.55C4.42229 8.55 4.05692 8.33983 3.7793 8.0332C3.50175 8.33945 3.13773 8.55 2.7 8.55C2.45147 8.55 2.25 8.34853 2.25 8.1C2.25 7.85147 2.45147 7.65 2.7 7.65C2.8912 7.65 3.16726 7.48791 3.36621 7.02334L3.39697 6.96357C3.47806 6.83213 3.62261 6.75 3.78018 6.75C3.9602 6.75007 4.1233 6.85783 4.19414 7.02334C4.39309 7.48782 4.66917 7.65 4.86035 7.65C5.05156 7.6498 5.32773 7.48772 5.52656 7.02334L5.55732 6.96357C5.63837 6.83232 5.78229 6.75012 5.93965 6.75C6.11974 6.75 6.28275 6.85778 6.35361 7.02334C6.55251 7.48782 6.82862 7.6499 7.01982 7.65C7.21102 7.65 7.48708 7.48786 7.68603 7.02334ZM5.4 0.9C4.40589 0.9 3.6 1.70589 3.6 2.7V3.15H7.2V2.7C7.2 1.70589 6.39411 0.9 5.4 0.9Z" fill="currentColor"></path></svg><span class="body-3">Copy</span></button></div></div></div><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">This is all Claude sees, not the 2000+ expense line items processed along the way.</p><h3 class="Body-module-scss-module__z40yvW__reading-column headline-5 post-section" id="when-to-use-programmatic-tool-calling">When to use Programmatic Tool Calling</h3><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Programmatic Tool Calling adds a code execution step to your workflow. This extra overhead pays off when the token savings, latency improvements, and accuracy gains are substantial.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><strong>Most beneficial when:</strong></p><ul class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><li>Processing large datasets where you only need aggregates or summaries</li><li>Running multi-step workflows with three or more dependent tool calls</li><li>Filtering, sorting, or transforming tool results before Claude sees them</li><li>Handling tasks where intermediate data shouldn't influence Claude's reasoning</li><li>Running parallel operations across many items (checking 50 endpoints, for example)</li></ul><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><strong>Less beneficial when:</strong></p><ul class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><li>Making simple single-tool invocations</li><li>Working on tasks where Claude should see and reason about all intermediate results</li><li>Running quick lookups with small responses</li></ul><h2 class="Body-module-scss-module__z40yvW__reading-column headline-4 post-heading" id="tool-use-examples">Tool Use Examples</h2><h3 class="Body-module-scss-module__z40yvW__reading-column headline-5 post-section" id="the-challenge">The challenge</h3><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">JSON Schema excels at defining structure–types, required fields, allowed enums–but it can't express usage patterns: when to include optional parameters, which combinations make sense, or what conventions your API expects.</p><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Consider a support ticket API:</p><div class="Body-module-scss-module__z40yvW__media-column Body-module-scss-module__z40yvW__inline"><div class="CodeBlock-module-scss-module__PbWBnq__codeBlock"><pre class="" style="--height:300px;--height-expanded:0px"><code class="plaintext">{
"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"]
}
}</code></pre><div class="CodeBlock-module-scss-module__PbWBnq__controls"><button aria-label="Copy code"><svg class="Icon-module-scss-module__lqbdHG__icon" width="11" height="15" viewBox="0 0 11 15"><path d="M5.4 0C6.39875 0 7.26819 0.543814 7.73525 1.35H9.45C10.1956 1.35 10.8 1.95442 10.8 2.7V13.5C10.8 14.2456 10.1956 14.85 9.45 14.85H1.35C0.604415 14.85 2.17436e-08 14.2456 0 13.5V2.7C1.7395e-07 1.95442 0.604415 1.35 1.35 1.35H3.06475C3.53181 0.543814 4.40125 0 5.4 0ZM1.35 2.25C1.10147 2.25 0.9 2.45147 0.9 2.7V13.5C0.9 13.7485 1.10147 13.95 1.35 13.95H9.45C9.69853 13.95 9.9 13.7485 9.9 13.5V2.7C9.9 2.45147 9.69853 2.25 9.45 2.25H8.06221C8.08677 2.39637 8.1 2.54665 8.1 2.7V3.6C8.1 3.84853 7.89853 4.05 7.65 4.05H3.15C2.90147 4.05 2.7 3.84853 2.7 3.6V2.7C2.7 2.54665 2.71323 2.39637 2.73779 2.25H1.35ZM7.68603 10.6233C7.78376 10.395 8.04828 10.2886 8.27666 10.386C8.50499 10.4838 8.61143 10.7483 8.51396 10.9767C8.24856 11.5967 7.73014 12.15 7.01982 12.15C6.58192 12.1499 6.21722 11.9397 5.93965 11.6332C5.66215 11.9395 5.29801 12.1499 4.86035 12.15C4.42229 12.15 4.05692 11.9398 3.7793 11.6332C3.50175 11.9395 3.13773 12.15 2.7 12.15C2.45147 12.15 2.25 11.9485 2.25 11.7C2.25 11.4515 2.45147 11.25 2.7 11.25C2.8912 11.25 3.16726 11.0879 3.36621 10.6233L3.39697 10.5636C3.47806 10.4321 3.62261 10.35 3.78018 10.35C3.9602 10.3501 4.1233 10.4578 4.19414 10.6233C4.39309 11.0878 4.66917 11.25 4.86035 11.25C5.05156 11.2498 5.32773 11.0877 5.52656 10.6233L5.55732 10.5636C5.63837 10.4323 5.78229 10.3501 5.93965 10.35C6.11974 10.35 6.28275 10.4578 6.35361 10.6233C6.55251 11.0878 6.82862 11.2499 7.01982 11.25C7.21102 11.25 7.48708 11.0879 7.68603 10.6233ZM7.68603 7.02334C7.78376 6.79501 8.04828 6.68857 8.27666 6.78604C8.50499 6.88376 8.61143 7.14828 8.51396 7.37666C8.24856 7.99675 7.73014 8.55 7.01982 8.55C6.58192 8.54994 6.21722 8.3397 5.93965 8.0332C5.66215 8.33947 5.29801 8.54989 4.86035 8.55C4.42229 8.55 4.05692 8.33983 3.7793 8.0332C3.50175 8.33945 3.13773 8.55 2.7 8.55C2.45147 8.55 2.25 8.34853 2.25 8.1C2.25 7.85147 2.45147 7.65 2.7 7.65C2.8912 7.65 3.16726 7.48791 3.36621 7.02334L3.39697 6.96357C3.47806 6.83213 3.62261 6.75 3.78018 6.75C3.9602 6.75007 4.1233 6.85783 4.19414 7.02334C4.39309 7.48782 4.66917 7.65 4.86035 7.65C5.05156 7.6498 5.32773 7.48772 5.52656 7.02334L5.55732 6.96357C5.63837 6.83232 5.78229 6.75012 5.93965 6.75C6.11974 6.75 6.28275 6.85778 6.35361 7.02334C6.55251 7.48782 6.82862 7.6499 7.01982 7.65C7.21102 7.65 7.48708 7.48786 7.68603 7.02334ZM5.4 0.9C4.40589 0.9 3.6 1.70589 3.6 2.7V3.15H7.2V2.7C7.2 1.70589 6.39411 0.9 5.4 0.9Z" fill="currentColor"></path></svg><span class="body-3">Copy</span></button></div></div></div><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">The schema defines what's valid, but leaves critical questions unanswered:</p><ul class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><li><strong>Format ambiguity: </strong>Should <code class="InlineCodeBlock-module-scss-module__nsPAba__code">due_date</code> use "2024-11-06", "Nov 6, 2024", or "2024-11-06T00:00:00Z"?</li><li><strong>ID conventions: </strong>Is <code class="InlineCodeBlock-module-scss-module__nsPAba__code">reporter.id</code> a UUID, "USR-12345", or just "12345"?</li><li><strong>Nested structure usage: </strong>When should Claude populate <code class="InlineCodeBlock-module-scss-module__nsPAba__code">reporter.contact</code>?</li><li><strong>Parameter correlations: </strong>How do <code class="InlineCodeBlock-module-scss-module__nsPAba__code">escalation.level</code> and <code class="InlineCodeBlock-module-scss-module__nsPAba__code">escalation.sla_hours</code> relate to priority?</li></ul><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">These ambiguities can lead to malformed tool calls and inconsistent parameter usage.</p><h3 class="Body-module-scss-module__z40yvW__reading-column headline-5 post-section" id="our-solution">Our solution</h3><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">Tool Use Examples let you provide sample tool calls directly in your tool definitions. Instead of relying on schema alone, you show Claude concrete usage patterns:</p><div class="Body-module-scss-module__z40yvW__media-column Body-module-scss-module__z40yvW__inline"><div class="CodeBlock-module-scss-module__PbWBnq__codeBlock"><pre class="" style="--height:300px;--height-expanded:0px"><code class="plaintext">{
"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": "[email protected]",
"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"
}
]
}</code></pre><div class="CodeBlock-module-scss-module__PbWBnq__controls"><button aria-label="Copy code"><svg class="Icon-module-scss-module__lqbdHG__icon" width="11" height="15" viewBox="0 0 11 15"><path d="M5.4 0C6.39875 0 7.26819 0.543814 7.73525 1.35H9.45C10.1956 1.35 10.8 1.95442 10.8 2.7V13.5C10.8 14.2456 10.1956 14.85 9.45 14.85H1.35C0.604415 14.85 2.17436e-08 14.2456 0 13.5V2.7C1.7395e-07 1.95442 0.604415 1.35 1.35 1.35H3.06475C3.53181 0.543814 4.40125 0 5.4 0ZM1.35 2.25C1.10147 2.25 0.9 2.45147 0.9 2.7V13.5C0.9 13.7485 1.10147 13.95 1.35 13.95H9.45C9.69853 13.95 9.9 13.7485 9.9 13.5V2.7C9.9 2.45147 9.69853 2.25 9.45 2.25H8.06221C8.08677 2.39637 8.1 2.54665 8.1 2.7V3.6C8.1 3.84853 7.89853 4.05 7.65 4.05H3.15C2.90147 4.05 2.7 3.84853 2.7 3.6V2.7C2.7 2.54665 2.71323 2.39637 2.73779 2.25H1.35ZM7.68603 10.6233C7.78376 10.395 8.04828 10.2886 8.27666 10.386C8.50499 10.4838 8.61143 10.7483 8.51396 10.9767C8.24856 11.5967 7.73014 12.15 7.01982 12.15C6.58192 12.1499 6.21722 11.9397 5.93965 11.6332C5.66215 11.9395 5.29801 12.1499 4.86035 12.15C4.42229 12.15 4.05692 11.9398 3.7793 11.6332C3.50175 11.9395 3.13773 12.15 2.7 12.15C2.45147 12.15 2.25 11.9485 2.25 11.7C2.25 11.4515 2.45147 11.25 2.7 11.25C2.8912 11.25 3.16726 11.0879 3.36621 10.6233L3.39697 10.5636C3.47806 10.4321 3.62261 10.35 3.78018 10.35C3.9602 10.3501 4.1233 10.4578 4.19414 10.6233C4.39309 11.0878 4.66917 11.25 4.86035 11.25C5.05156 11.2498 5.32773 11.0877 5.52656 10.6233L5.55732 10.5636C5.63837 10.4323 5.78229 10.3501 5.93965 10.35C6.11974 10.35 6.28275 10.4578 6.35361 10.6233C6.55251 11.0878 6.82862 11.2499 7.01982 11.25C7.21102 11.25 7.48708 11.0879 7.68603 10.6233ZM7.68603 7.02334C7.78376 6.79501 8.04828 6.68857 8.27666 6.78604C8.50499 6.88376 8.61143 7.14828 8.51396 7.37666C8.24856 7.99675 7.73014 8.55 7.01982 8.55C6.58192 8.54994 6.21722 8.3397 5.93965 8.0332C5.66215 8.33947 5.29801 8.54989 4.86035 8.55C4.42229 8.55 4.05692 8.33983 3.7793 8.0332C3.50175 8.33945 3.13773 8.55 2.7 8.55C2.45147 8.55 2.25 8.34853 2.25 8.1C2.25 7.85147 2.45147 7.65 2.7 7.65C2.8912 7.65 3.16726 7.48791 3.36621 7.02334L3.39697 6.96357C3.47806 6.83213 3.62261 6.75 3.78018 6.75C3.9602 6.75007 4.1233 6.85783 4.19414 7.02334C4.39309 7.48782 4.66917 7.65 4.86035 7.65C5.05156 7.6498 5.32773 7.48772 5.52656 7.02334L5.55732 6.96357C5.63837 6.83232 5.78229 6.75012 5.93965 6.75C6.11974 6.75 6.28275 6.85778 6.35361 7.02334C6.55251 7.48782 6.82862 7.6499 7.01982 7.65C7.21102 7.65 7.48708 7.48786 7.68603 7.02334ZM5.4 0.9C4.40589 0.9 3.6 1.70589 3.6 2.7V3.15H7.2V2.7C7.2 1.70589 6.39411 0.9 5.4 0.9Z" fill="currentColor"></path></svg><span class="body-3">Copy</span></button></div></div></div><p class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text">From these three examples, Claude learns:</p><ul class="Body-module-scss-module__z40yvW__reading-column body-2 serif post-text"><li><strong>Format conventions</strong>: Dates use YYYY-MM-DD, user IDs follow USR-XXXXX, labels use kebab-case</li><li><strong>Nested structure patterns</strong>: How to construct the reporter object with it |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Involved Issue / 该 PR 相关 Issue
Close #
Example for the Proposed Route(s) / 路由地址示例
New RSS Route Checklist / 新 RSS 路由检查表
PuppeteerNote / 说明