report added

2026-02-18 11:47:14 +05:00
parent 2ac297cca4
commit 232c3d146a
21 changed files with 577 additions and 14 deletions
@@ -0,0 +1,142 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1100 620" font-family="Segoe UI, Arial, sans-serif">
+  <!-- Background -->
+  <rect width="1100" height="620" fill="#ffffff" rx="8"/>
+
+  <!-- Title -->
+  <text x="550" y="38" text-anchor="middle" font-size="22" font-weight="700" fill="#1a1a1a">Programmatic Tool Calling (PTC)</text>
+  <text x="550" y="58" text-anchor="middle" font-size="13" fill="#888">Claude Opus 4.6 / Sonnet 4.6 — Now Generally Available</text>
+
+  <!-- Divider -->
+  <line x1="550" y1="75" x2="550" y2="600" stroke="#d0d0d0" stroke-width="1.5" stroke-dasharray="6,4"/>
+
+  <!-- LEFT SIDE: Traditional -->
+  <text x="275" y="95" text-anchor="middle" font-size="16" font-weight="600" fill="#444">Traditional Tool Calling</text>
+  <text x="275" y="113" text-anchor="middle" font-size="12" fill="#999">3 tools = 3 inference passes</text>
+
+  <!-- Round Trip 1 -->
+  <rect x="60" y="135" width="110" height="40" rx="6" fill="#FFF3E0" stroke="#F57C00" stroke-width="1.5"/>
+  <text x="115" y="160" text-anchor="middle" font-size="13" font-weight="600" fill="#E65100">Claude</text>
+
+  <line x1="170" y1="148" x2="280" y2="148" stroke="#E53935" stroke-width="1.5" marker-end="url(#arrowRed)"/>
+  <text x="225" y="142" text-anchor="middle" font-size="10" fill="#E53935">Tool call 1</text>
+
+  <rect x="280" y="135" width="110" height="40" rx="6" fill="#FFCDD2" stroke="#E53935" stroke-width="1.5"/>
+  <text x="335" y="160" text-anchor="middle" font-size="13" font-weight="600" fill="#B71C1C">Action</text>
+
+  <line x1="280" y1="168" x2="170" y2="168" stroke="#43A047" stroke-width="1.5" marker-end="url(#arrowGreen)"/>
+  <text x="225" y="182" text-anchor="middle" font-size="10" fill="#43A047">Response 1</text>
+
+  <!-- Round Trip 2 -->
+  <rect x="60" y="210" width="110" height="40" rx="6" fill="#FFF3E0" stroke="#F57C00" stroke-width="1.5"/>
+  <text x="115" y="235" text-anchor="middle" font-size="13" font-weight="600" fill="#E65100">Claude</text>
+
+  <line x1="170" y1="223" x2="280" y2="223" stroke="#E53935" stroke-width="1.5" marker-end="url(#arrowRed)"/>
+  <text x="225" y="217" text-anchor="middle" font-size="10" fill="#E53935">Tool call 2</text>
+
+  <rect x="280" y="210" width="110" height="40" rx="6" fill="#C8E6C9" stroke="#43A047" stroke-width="1.5"/>
+  <text x="335" y="235" text-anchor="middle" font-size="13" font-weight="600" fill="#1B5E20">Action</text>
+
+  <line x1="280" y1="243" x2="170" y2="243" stroke="#43A047" stroke-width="1.5" marker-end="url(#arrowGreen)"/>
+  <text x="225" y="257" text-anchor="middle" font-size="10" fill="#43A047">Response 2</text>
+
+  <!-- Round Trip 3 -->
+  <rect x="60" y="285" width="110" height="40" rx="6" fill="#FFF3E0" stroke="#F57C00" stroke-width="1.5"/>
+  <text x="115" y="310" text-anchor="middle" font-size="13" font-weight="600" fill="#E65100">Claude</text>
+
+  <line x1="170" y1="298" x2="280" y2="298" stroke="#E53935" stroke-width="1.5" marker-end="url(#arrowRed)"/>
+  <text x="225" y="292" text-anchor="middle" font-size="10" fill="#E53935">Tool call 3</text>
+
+  <rect x="280" y="285" width="110" height="40" rx="6" fill="#BBDEFB" stroke="#1E88E5" stroke-width="1.5"/>
+  <text x="335" y="310" text-anchor="middle" font-size="13" font-weight="600" fill="#0D47A1">Action</text>
+
+  <line x1="280" y1="318" x2="170" y2="318" stroke="#43A047" stroke-width="1.5" marker-end="url(#arrowGreen)"/>
+  <text x="225" y="332" text-anchor="middle" font-size="10" fill="#43A047">Response 3</text>
+
+  <!-- Final Answer Left -->
+  <rect x="60" y="360" width="110" height="40" rx="6" fill="#FFF3E0" stroke="#F57C00" stroke-width="1.5"/>
+  <text x="115" y="385" text-anchor="middle" font-size="13" font-weight="600" fill="#E65100">Claude</text>
+
+  <line x1="170" y1="380" x2="250" y2="380" stroke="#F57C00" stroke-width="1.5" marker-end="url(#arrowOrange)"/>
+
+  <rect x="250" y="360" width="140" height="40" rx="6" fill="#F5F5F5" stroke="#9E9E9E" stroke-width="1.5"/>
+  <text x="320" y="385" text-anchor="middle" font-size="13" font-weight="600" fill="#424242">Final Answer</text>
+
+  <!-- Token cost left -->
+  <rect x="85" y="425" width="290" height="55" rx="6" fill="#FFF8E1" stroke="#FFC107" stroke-width="1"/>
+  <text x="230" y="447" text-anchor="middle" font-size="12" font-weight="600" fill="#F57F17">Token Cost: HIGH</text>
+  <text x="230" y="465" text-anchor="middle" font-size="11" fill="#795548">All 3 responses enter context window</text>
+
+  <!-- RIGHT SIDE: Programmatic -->
+  <text x="825" y="95" text-anchor="middle" font-size="16" font-weight="600" fill="#444">Programmatic Tool Calling</text>
+  <text x="825" y="113" text-anchor="middle" font-size="12" fill="#999">3 tools = 1 inference pass</text>
+
+  <!-- Claude box -->
+  <rect x="590" y="145" width="110" height="50" rx="6" fill="#FFF3E0" stroke="#F57C00" stroke-width="1.5"/>
+  <text x="645" y="175" text-anchor="middle" font-size="13" font-weight="600" fill="#E65100">Claude</text>
+
+  <!-- Arrow to Script -->
+  <line x1="700" y1="170" x2="780" y2="170" stroke="#1565C0" stroke-width="1.5" marker-end="url(#arrowBlue)"/>
+  <text x="740" y="163" text-anchor="middle" font-size="10" fill="#1565C0">Bash(..)</text>
+
+  <!-- Script container -->
+  <rect x="780" y="130" width="260" height="260" rx="8" fill="#F5F5F5" stroke="#9E9E9E" stroke-width="1.5"/>
+  <text x="910" y="155" text-anchor="middle" font-size="14" font-weight="700" fill="#424242">Python Script</text>
+  <line x1="795" y1="165" x2="1025" y2="165" stroke="#BDBDBD" stroke-width="1"/>
+
+  <!-- Tool calls inside script -->
+  <rect x="805" y="180" width="210" height="30" rx="4" fill="#FFCDD2" stroke="#E53935" stroke-width="1"/>
+  <text x="910" y="200" text-anchor="middle" font-size="11" font-weight="500" fill="#B71C1C">await query_database(sql_1)</text>
+
+  <rect x="805" y="220" width="210" height="30" rx="4" fill="#C8E6C9" stroke="#43A047" stroke-width="1"/>
+  <text x="910" y="240" text-anchor="middle" font-size="11" font-weight="500" fill="#1B5E20">await query_database(sql_2)</text>
+
+  <rect x="805" y="260" width="210" height="30" rx="4" fill="#BBDEFB" stroke="#1E88E5" stroke-width="1"/>
+  <text x="910" y="280" text-anchor="middle" font-size="11" font-weight="500" fill="#0D47A1">await query_database(sql_3)</text>
+
+  <!-- Processing inside script -->
+  <rect x="805" y="305" width="210" height="30" rx="4" fill="#E8EAF6" stroke="#5C6BC0" stroke-width="1"/>
+  <text x="910" y="325" text-anchor="middle" font-size="11" font-weight="500" fill="#283593">filter + aggregate results</text>
+
+  <rect x="805" y="345" width="210" height="30" rx="4" fill="#EDE7F6" stroke="#7E57C2" stroke-width="1"/>
+  <text x="910" y="365" text-anchor="middle" font-size="11" font-weight="500" fill="#4527A0">print(summary)</text>
+
+  <!-- Arrow back: only stdout -->
+  <line x1="780" y1="350" x2="700" y2="350" stroke="#43A047" stroke-width="2" marker-end="url(#arrowGreen)"/>
+  <text x="740" y="340" text-anchor="middle" font-size="10" font-weight="600" fill="#43A047">stdout only</text>
+
+  <!-- Claude receives -->
+  <rect x="590" y="330" width="110" height="50" rx="6" fill="#FFF3E0" stroke="#F57C00" stroke-width="1.5"/>
+  <text x="645" y="360" text-anchor="middle" font-size="13" font-weight="600" fill="#E65100">Claude</text>
+
+  <!-- Final answer right -->
+  <line x1="645" y1="380" x2="645" y2="410" stroke="#F57C00" stroke-width="1.5" marker-end="url(#arrowOrange)"/>
+
+  <rect x="575" y="410" width="140" height="40" rx="6" fill="#F5F5F5" stroke="#9E9E9E" stroke-width="1.5"/>
+  <text x="645" y="435" text-anchor="middle" font-size="13" font-weight="600" fill="#424242">Final Answer</text>
+
+  <!-- Token cost right -->
+  <rect x="585" y="475" width="455" height="55" rx="6" fill="#E8F5E9" stroke="#43A047" stroke-width="1"/>
+  <text x="812" y="497" text-anchor="middle" font-size="12" font-weight="600" fill="#2E7D32">Token Cost: ~37% LOWER</text>
+  <text x="812" y="515" text-anchor="middle" font-size="11" fill="#795548">Only stdout summary enters context — raw tool results stay in sandbox</text>
+
+  <!-- Key insight box -->
+  <rect x="30" y="550" width="1040" height="50" rx="6" fill="#E3F2FD" stroke="#1565C0" stroke-width="1"/>
+  <text x="550" y="572" text-anchor="middle" font-size="13" font-weight="600" fill="#0D47A1">Key: Claude pre-bakes decision paths in code. Tool results go to the script, not the context window.</text>
+  <text x="550" y="590" text-anchor="middle" font-size="12" fill="#1565C0">Intermediate data is processed programmatically — only the final summary reaches Claude.</text>
+
+  <!-- Arrow markers -->
+  <defs>
+    <marker id="arrowRed" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto">
+      <polygon points="0 0, 8 3, 0 6" fill="#E53935"/>
+    </marker>
+    <marker id="arrowGreen" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto">
+      <polygon points="0 0, 8 3, 0 6" fill="#43A047"/>
+    </marker>
+    <marker id="arrowBlue" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto">
+      <polygon points="0 0, 8 3, 0 6" fill="#1565C0"/>
+    </marker>
+    <marker id="arrowOrange" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto">
+      <polygon points="0 0, 8 3, 0 6" fill="#F57C00"/>
+    </marker>
+  </defs>
+</svg>
@@ -0,0 +1,138 @@
+<svg viewBox="0 0 900 580" xmlns="http://www.w3.org/2000/svg" style="font-family: system-ui, -apple-system, sans-serif;">
+  <defs>
+    <!-- Gradients -->
+    <linearGradient id="cliGradient" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#667eea"/>
+      <stop offset="100%" style="stop-color:#764ba2"/>
+    </linearGradient>
+    <linearGradient id="sdkGradient" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#34d399"/>
+      <stop offset="100%" style="stop-color:#059669"/>
+    </linearGradient>
+    <linearGradient id="questionGradient" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#4facfe"/>
+      <stop offset="100%" style="stop-color:#00f2fe"/>
+    </linearGradient>
+    <linearGradient id="claudeGradient" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#d4a574"/>
+      <stop offset="100%" style="stop-color:#c4956a"/>
+    </linearGradient>
+
+    <!-- Drop Shadow -->
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="2" dy="4" stdDeviation="4" flood-opacity="0.15"/>
+    </filter>
+
+    <!-- Glow effect for hover -->
+    <filter id="glow">
+      <feGaussianBlur stdDeviation="3" result="coloredBlur"/>
+      <feMerge>
+        <feMergeNode in="coloredBlur"/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+
+    <!-- Arrow markers -->
+    <marker id="arrowheadCli" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+      <polygon points="0 0, 10 3.5, 0 7" fill="#667eea"/>
+    </marker>
+    <marker id="arrowheadSdk" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+      <polygon points="0 0, 10 3.5, 0 7" fill="#059669"/>
+    </marker>
+  </defs>
+
+  <!-- Background -->
+  <rect width="900" height="580" fill="#f8fafc" rx="12"/>
+
+  <!-- Title -->
+  <text x="450" y="35" text-anchor="middle" font-size="18" font-weight="700" fill="#1e293b">Same Question, Different Paths: Why Outputs May Vary</text>
+
+  <!-- THE QUESTION - Central element at top -->
+  <g filter="url(#shadow)">
+    <rect x="275" y="55" width="350" height="70" rx="12" fill="url(#questionGradient)"/>
+    <text x="450" y="82" text-anchor="middle" font-size="11" fill="#fff" font-weight="600">USER QUESTION</text>
+    <text x="450" y="105" text-anchor="middle" font-size="15" fill="#fff" font-weight="700">"What is the capital of Norway?"</text>
+  </g>
+
+  <!-- Split arrows from question -->
+  <path d="M 370 125 L 370 145 L 200 145 L 200 165" stroke="#667eea" stroke-width="3" fill="none" marker-end="url(#arrowheadCli)"/>
+  <path d="M 530 125 L 530 145 L 700 145 L 700 165" stroke="#059669" stroke-width="3" fill="none" marker-end="url(#arrowheadSdk)"/>
+
+  <!-- CLI PATH (Left Side) -->
+  <g filter="url(#shadow)">
+    <rect x="50" y="170" width="300" height="50" rx="10" fill="url(#cliGradient)"/>
+    <text x="200" y="200" text-anchor="middle" font-size="14" fill="#fff" font-weight="700">Claude CLI (Claude Code)</text>
+  </g>
+
+  <!-- CLI System Prompt Box -->
+  <g filter="url(#shadow)">
+    <rect x="50" y="235" width="300" height="145" rx="10" fill="#fff" stroke="#667eea" stroke-width="2"/>
+    <text x="200" y="258" text-anchor="middle" font-size="12" fill="#667eea" font-weight="700">SYSTEM PROMPT (modular, ~269+ base)</text>
+    <line x1="70" y1="270" x2="330" y2="270" stroke="#e2e8f0" stroke-width="1"/>
+    <text x="75" y="290" font-size="10" fill="#475569">+ 18+ Tool Instructions (Write, Read, Bash...)</text>
+    <text x="75" y="308" font-size="10" fill="#475569">+ Coding Guidelines &amp; Style Rules</text>
+    <text x="75" y="326" font-size="10" fill="#475569">+ Security &amp; Injection Defense</text>
+    <text x="75" y="344" font-size="10" fill="#475569">+ CLAUDE.md Project Context</text>
+    <text x="75" y="362" font-size="10" fill="#475569">+ Environment (OS, Git, Directory)</text>
+  </g>
+
+  <!-- SDK PATH (Right Side) -->
+  <g filter="url(#shadow)">
+    <rect x="550" y="170" width="300" height="50" rx="10" fill="url(#sdkGradient)"/>
+    <text x="700" y="200" text-anchor="middle" font-size="14" fill="#fff" font-weight="700">Claude Agent SDK</text>
+  </g>
+
+  <!-- SDK System Prompt Box -->
+  <g filter="url(#shadow)">
+    <rect x="550" y="235" width="300" height="145" rx="10" fill="#fff" stroke="#059669" stroke-width="2"/>
+    <text x="700" y="258" text-anchor="middle" font-size="12" fill="#059669" font-weight="700">SYSTEM PROMPT (minimal default)</text>
+    <line x1="570" y1="270" x2="830" y2="270" stroke="#e2e8f0" stroke-width="1"/>
+    <text x="575" y="290" font-size="10" fill="#475569">+ Minimal Tool Instructions</text>
+    <text x="575" y="308" font-size="10" fill="#475569">+ Basic Safety Rules</text>
+    <text x="575" y="326" font-size="10" fill="#94a3b8" font-style="italic">− No Coding Guidelines</text>
+    <text x="575" y="344" font-size="10" fill="#94a3b8" font-style="italic">− No Project Context</text>
+    <text x="575" y="362" font-size="10" fill="#94a3b8" font-style="italic">− No Environment Info</text>
+  </g>
+
+  <!-- Arrows to Claude -->
+  <path d="M 200 380 L 200 400 L 450 400 L 450 420" stroke="#667eea" stroke-width="2" fill="none" marker-end="url(#arrowheadCli)"/>
+  <path d="M 700 380 L 700 400 L 450 400 L 450 420" stroke="#059669" stroke-width="2" fill="none" marker-end="url(#arrowheadSdk)"/>
+
+  <!-- Claude Model (Center) -->
+  <g filter="url(#shadow)">
+    <rect x="325" y="420" width="250" height="55" rx="12" fill="url(#claudeGradient)"/>
+    <text x="450" y="445" text-anchor="middle" font-size="11" fill="#fff" font-weight="600">CLAUDE MODEL</text>
+    <text x="450" y="463" text-anchor="middle" font-size="13" fill="#fff" font-weight="700">Claude Opus 4.5</text>
+  </g>
+
+  <!-- Warning/Inconsistency Box at bottom -->
+  <g filter="url(#shadow)">
+    <rect x="125" y="495" width="650" height="75" rx="12" fill="#fef2f2" stroke="#ef4444" stroke-width="2"/>
+    <text x="450" y="518" text-anchor="middle" font-size="13" fill="#dc2626" font-weight="700">⚠ NO GUARANTEE OF IDENTICAL OUTPUT</text>
+    <text x="450" y="538" text-anchor="middle" font-size="10" fill="#7f1d1d">Even with matching prompts + temperature=0, outputs may differ due to:</text>
+    <text x="450" y="556" text-anchor="middle" font-size="10" fill="#991b1b" font-weight="600">No Seed Parameter · MoE Routing · Floating-Point Variance · Infrastructure Non-Determinism</text>
+  </g>
+
+  <!-- Token comparison badges -->
+  <g>
+    <rect x="75" y="385" width="110" height="22" rx="11" fill="#667eea"/>
+    <text x="130" y="400" text-anchor="middle" font-size="9" fill="#fff" font-weight="600">~269+ base tokens</text>
+  </g>
+  <g>
+    <rect x="715" y="385" width="100" height="22" rx="11" fill="#059669"/>
+    <text x="765" y="400" text-anchor="middle" font-size="9" fill="#fff" font-weight="600">minimal default</text>
+  </g>
+
+  <!-- VS indicator -->
+  <circle cx="450" cy="305" r="22" fill="#1e293b"/>
+  <text x="450" y="310" text-anchor="middle" font-size="12" fill="#fff" font-weight="700">VS</text>
+
+  <!-- Legend -->
+  <g transform="translate(50, 495)">
+    <text x="0" y="0" font-size="9" fill="#64748b" font-weight="600">LEGEND:</text>
+    <rect x="0" y="8" width="12" height="12" rx="2" fill="url(#cliGradient)"/>
+    <text x="16" y="18" font-size="9" fill="#64748b">CLI Path</text>
+    <rect x="55" y="8" width="12" height="12" rx="2" fill="url(#sdkGradient)"/>
+    <text x="71" y="18" font-size="9" fill="#64748b">SDK Path</text>
+  </g>
+</svg>
@@ -0,0 +1,420 @@
+# Claude Advanced Tool Use Patterns
+
+API-level features (now GA) that reduce token consumption, latency, and improve tool accuracy. Released with Opus/Sonnet 4.6.
+
+<table width="100%">
+<tr>
+<td><a href="../">← Back to Claude Code Best Practice</a></td>
+<td align="right"><img src="../!/claude-jumping.svg" alt="Claude" width="60" /></td>
+</tr>
+</table>
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Programmatic Tool Calling (PTC)](#programmatic-tool-calling-ptc)
+3. [Dynamic Filtering for Web Search/Fetch](#dynamic-filtering-for-web-searchfetch)
+4. [Tool Search Tool](#tool-search-tool)
+5. [Tool Use Examples](#tool-use-examples)
+6. [Claude Code Relevance](#claude-code-relevance)
+
+---
+
+## Overview
+
+| Feature | Problem Solved | Token Savings | Availability |
+|---------|---------------|---------------|--------------|
+| Programmatic Tool Calling | Multi-step agent loops burn tokens on round trips | ~37% reduction | API, Foundry (GA) |
+| Dynamic Filtering | Web search/fetch results bloat context with irrelevant content | ~24% fewer input tokens | API, Foundry (GA) |
+| Tool Search Tool | Too many tool definitions bloat context | ~85% reduction | API, Foundry (GA) |
+| Tool Use Examples | Schema alone can't express usage patterns | 72% → 90% accuracy | API, Foundry (GA) |
+
+All features are **generally available** as of February 18, 2026.
+
+**Strategic layering** — start with your biggest bottleneck:
+- Context bloat from tool definitions → Tool Search Tool
+- Large intermediate results → Programmatic Tool Calling
+- Web search noise → Dynamic Filtering
+- Parameter errors → Tool Use Examples
+
+---
+
+## Programmatic Tool Calling (PTC)
+
+<img src="assets/programmatic-tool-calling-diagram.svg" alt="PTC Diagram — Traditional vs Programmatic Tool Calling" width="100%" />
+
+### The Paradigm Shift
+
+**Before (Traditional Tool Calling):**
+```
+User prompt → Claude → Tool call 1 → Response 1 → Claude → Tool call 2 → Response 2 → Claude → Tool call 3 → Response 3 → Claude → Final answer
+```
+Each tool call requires a full model round trip. 3 tools = 3 inference passes.
+
+**After (Programmatic Tool Calling):**
+```
+User prompt → Claude → writes Python script → Script calls Tool 1, Tool 2, Tool 3 internally → stdout → Claude → Final answer
+```
+Claude writes code that orchestrates all tools. Only the final `stdout` enters the context window. 3 tools = 1 inference pass.
+
+### How It Works
+
+1. You define tools with `allowed_callers: ["code_execution_20250825"]`
+2. Claude writes Python that calls those tools as async functions inside a sandbox
+3. When a tool function is called, the sandbox pauses and the API returns a `tool_use` block
+4. You provide the tool result — it goes to the **running code**, not Claude's context
+5. Code resumes, processes results, calls more tools if needed
+6. Only `stdout` from the final execution reaches Claude
+
+### Key Configuration
+
+```json
+{
+  "tools": [
+    {
+      "type": "code_execution_20250825",
+      "name": "code_execution"
+    },
+    {
+      "name": "query_database",
+      "description": "Execute a SQL query. Returns rows as JSON objects with fields: id (str), name (str), revenue (float).",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "sql": { "type": "string", "description": "SQL query to execute" }
+        },
+        "required": ["sql"]
+      },
+      "allowed_callers": ["code_execution_20250825"]
+    }
+  ]
+}
+```
+
+### The `allowed_callers` Field
+
+| Value | Behavior |
+|-------|----------|
+| `["direct"]` | Traditional tool calling only (default if omitted) |
+| `["code_execution_20250825"]` | Only callable from Python sandbox |
+| `["direct", "code_execution_20250825"]` | Both modes available |
+
+**Recommendation:** Choose one mode per tool, not both. This gives Claude clearer guidance.
+
+### The `caller` Field in Responses
+
+Every tool use block includes a `caller` field so you know how it was invoked:
+
+```json
+// Direct (traditional)
+{ "caller": { "type": "direct" } }
+
+// Programmatic (from code execution)
+{ "caller": { "type": "code_execution_20250825", "tool_id": "srvtoolu_abc123" } }
+```
+
+### Advanced Patterns
+
+**Batch processing** — process N items in 1 inference pass:
+```python
+regions = ["West", "East", "Central", "North", "South"]
+results = {}
+for region in regions:
+    data = await query_database(f"SELECT SUM(revenue) FROM sales WHERE region='{region}'")
+    results[region] = data[0]["revenue"]
+
+top = max(results.items(), key=lambda x: x[1])
+print(f"Top region: {top[0]} with ${top[1]:,}")
+```
+
+**Early termination** — stop as soon as success criteria are met:
+```python
+endpoints = ["us-east", "eu-west", "apac"]
+for endpoint in endpoints:
+    status = await check_health(endpoint)
+    if status == "healthy":
+        print(f"Found healthy endpoint: {endpoint}")
+        break
+```
+
+**Conditional tool selection:**
+```python
+file_info = await get_file_info(path)
+if file_info["size"] < 10000:
+    content = await read_full_file(path)
+else:
+    content = await read_file_summary(path)
+print(content)
+```
+
+**Data filtering** — reduce what Claude sees:
+```python
+logs = await fetch_logs(server_id)
+errors = [log for log in logs if "ERROR" in log]
+print(f"Found {len(errors)} errors")
+for error in errors[-10:]:
+    print(error)
+```
+
+### Model Compatibility
+
+| Model | Supported |
+|-------|-----------|
+| Claude Opus 4.6 | Yes |
+| Claude Sonnet 4.6 | Yes |
+| Claude Sonnet 4.5 | Yes |
+| Claude Opus 4.5 | Yes |
+
+### Constraints
+
+| Constraint | Detail |
+|-----------|--------|
+| **Not on Bedrock/Vertex** | API and Foundry only |
+| **No MCP tools** | MCP connector tools cannot be called programmatically |
+| **No web search/fetch** | Web tools not supported in PTC |
+| **No structured outputs** | `strict: true` tools incompatible |
+| **No forced tool choice** | `tool_choice` cannot force PTC |
+| **Container lifetime** | ~4.5 minutes before expiry |
+| **ZDR** | Not covered by Zero Data Retention |
+| **Tool results as strings** | Validate external results for code injection risks |
+
+### When to Use PTC
+
+| Good Use Cases | Less Ideal |
+|----------------|------------|
+| Processing large datasets needing aggregates | Single tool calls with simple responses |
+| 3+ dependent tool calls in sequence | Tools needing immediate user feedback |
+| Filtering/transforming results before Claude sees them | Very fast operations (overhead > benefit) |
+| Parallel operations across many items | |
+| Conditional logic based on intermediate results | |
+
+### Token Efficiency
+
+- Tool results from programmatic calls are **not added to Claude's context** — only final `stdout`
+- Intermediate processing happens in code, not model tokens
+- 10 tools programmatically ≈ 1/10th the tokens of 10 direct calls
+
+---
+
+## Dynamic Filtering for Web Search/Fetch
+
+### The Problem
+
+Web search and fetch tools dump full HTML pages into Claude's context window. Most of that content is irrelevant — navigation, ads, boilerplate. Claude then reasons over all of it, wasting tokens and reducing accuracy.
+
+### The Solution
+
+Claude now **writes and executes Python code to filter web results** before they enter the context window. Instead of reasoning over raw HTML, Claude filters, parses, and extracts only relevant content in a sandbox.
+
+### How It Works
+
+**Before:**
+```
+Query → Search results → Fetch full HTML × N pages → All content enters context → Claude reasons over everything
+```
+
+**After:**
+```
+Query → Search results → Claude writes filtering code → Code extracts relevant content only → Filtered results enter context
+```
+
+### API Configuration
+
+Uses updated tool type versions with a beta header:
+
+```json
+{
+  "model": "claude-opus-4-6",
+  "max_tokens": 4096,
+  "tools": [
+    {
+      "type": "web_search_20260209",
+      "name": "web_search"
+    },
+    {
+      "type": "web_fetch_20260209",
+      "name": "web_fetch"
+    }
+  ]
+}
+```
+
+**Header required:** `anthropic-beta: code-execution-web-tools-2026-02-09`
+
+**Enabled by default** when using the new tool type versions with Sonnet 4.6 and Opus 4.6.
+
+### Benchmark Results
+
+**BrowseComp** (finding specific information on websites):
+
+| Model | Without Filtering | With Filtering | Improvement |
+|-------|-------------------|----------------|-------------|
+| Sonnet 4.6 | 33.3% | **46.6%** | +13.3 pp |
+| Opus 4.6 | 45.3% | **61.6%** | +16.3 pp |
+
+**DeepsearchQA** (multi-step research, F1 score):
+
+| Model | Without Filtering | With Filtering | Improvement |
+|-------|-------------------|----------------|-------------|
+| Sonnet 4.6 | 52.6% | **59.4%** | +6.8 pp |
+| Opus 4.6 | 69.8% | **77.3%** | +7.5 pp |
+
+**Token efficiency:** Average 24% fewer input tokens. Sonnet 4.6 sees cost reduction; Opus 4.6 may increase slightly due to more complex filtering code.
+
+### Use Cases
+
+- Sifting through technical documentation
+- Verifying citations across multiple sources
+- Cross-referencing search results
+- Multi-step research queries
+- Finding specific data points buried in large pages
+
+---
+
+## Tool Search Tool
+
+### The Problem
+
+Loading all tool definitions upfront wastes context. If you have 50 MCP tools at ~1.5K tokens each, that's 75K tokens before the user even asks a question.
+
+### The Solution
+
+Mark infrequently-used tools with `defer_loading: true`. They're excluded from the initial context. Claude discovers them on-demand via a Tool Search Tool.
+
+### Configuration
+
+```json
+{
+  "tools": [
+    {
+      "type": "mcp_toolset",
+      "mcp_server_name": "google-drive",
+      "default_config": { "defer_loading": true },
+      "configs": {
+        "search_files": { "defer_loading": false }
+      }
+    }
+  ]
+}
+```
+
+### Best Practices
+
+- Keep 3-5 most-used tools always loaded, defer the rest
+- Write clear, descriptive tool names and descriptions (search relies on them)
+- Document available capabilities in the system prompt
+
+### When to Use
+
+- Tool definitions consuming > 10K tokens
+- 10+ tools available
+- Multiple MCP servers
+- Tool selection accuracy issues from too many options
+
+### Token Savings
+
+~85% reduction in tool definition tokens (77K → 8.7K in Anthropic's benchmarks).
+
+### Claude Code Equivalent
+
+Claude Code has **MCP tool search auto mode** (enabled by default since v2.1.7). When MCP tool descriptions exceed 10% of context, they're deferred and discovered via `MCPSearch`. Configure the threshold with `ENABLE_TOOL_SEARCH=auto:N` where N is the context percentage (0-100).
+
+---
+
+## Tool Use Examples
+
+### The Problem
+
+JSON schemas define structure but can't express:
+- When to include optional parameters
+- Which parameter combinations make sense
+- Format conventions (date formats, ID patterns)
+- Nested structure usage
+
+### The Solution
+
+Add `input_examples` to tool definitions — concrete usage patterns beyond the schema.
+
+### Configuration
+
+```json
+{
+  "name": "create_ticket",
+  "description": "Create a support ticket",
+  "input_schema": {
+    "type": "object",
+    "properties": {
+      "title": { "type": "string" },
+      "priority": { "type": "string", "enum": ["low", "medium", "high", "critical"] },
+      "assignee": { "type": "string" },
+      "labels": { "type": "array", "items": { "type": "string" } }
+    },
+    "required": ["title"]
+  },
+  "input_examples": [
+    {
+      "title": "Login page returns 500 error",
+      "priority": "critical",
+      "assignee": "oncall-team",
+      "labels": ["bug", "auth", "production"]
+    },
+    {
+      "title": "Add dark mode support",
+      "priority": "low",
+      "labels": ["feature-request", "ui"]
+    },
+    {
+      "title": "Update API docs for v2 endpoints"
+    }
+  ]
+}
+```
+
+### Best Practices
+
+- Use **realistic data**, not placeholder strings like "example_value"
+- Show **variety**: minimal, partial, and full specifications
+- Keep concise: **1-5 examples per tool**
+- Focus on resolving ambiguity — target behavioral clarity over schema completeness
+- Show parameter correlations (e.g., `priority: "critical"` tends to have `assignee`)
+
+### Results
+
+72% → 90% accuracy on complex parameter handling in Anthropic's benchmarks.
+
+---
+
+## Claude Code Relevance
+
+### What applies directly to Claude Code users
+
+| Feature | Claude Code Status | Action |
+|---------|-------------------|--------|
+| Tool Search | Built-in since v2.1.7 as MCPSearch auto mode | Tune `ENABLE_TOOL_SEARCH=auto:N` if you have many MCP tools |
+| Dynamic Filtering | Not available in CLI (API-level web tools) | Relevant for Agent SDK users doing web research |
+| PTC | Not available in CLI | Relevant for Agent SDK users building custom agents |
+| Tool Use Examples | Not configurable in CLI | Relevant for custom MCP server authors |
+
+### For Agent SDK developers
+
+If you're building agents with `@anthropic-ai/claude-agent-sdk`, PTC is immediately actionable:
+
+1. Add `code_execution_20250825` to your tools array
+2. Set `allowed_callers` on tools that benefit from batching/filtering
+3. Implement the tool result loop (pause → provide result → resume)
+4. Return structured data (JSON) from tools for easier programmatic parsing
+
+### For MCP server authors
+
+If you're building custom MCP servers, Tool Use Examples can improve how Claude uses your tools:
+- Add `input_examples` to tool schemas
+- Document return formats clearly in descriptions (PTC needs to parse them)
+
+---
+
+## Sources
+
+- [Anthropic Engineering: Advanced Tool Use](https://www.anthropic.com/engineering/advanced-tool-use)
+- [Programmatic Tool Calling Documentation](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling)
+- [Code Execution Tool Documentation](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool)
+- [Improved Web Search with Dynamic Filtering](https://claude.com/blog/improved-web-search-with-dynamic-filtering)
@@ -7,7 +7,7 @@
 </tr>
 </table>

-![SDK vs CLI System Prompts Diagram](../!/sdk-vs-cli-diagram.svg)
+![SDK vs CLI System Prompts Diagram](assets/sdk-vs-cli-diagram.svg)

 ---

@@ -15,7 +15,7 @@ A summary of customization tips shared by Boris Cherny ([@bcherny](https://x.com

 Boris Cherny highlighted that customizability is one of the things engineers love most about Claude Code — hooks, plugins, LSPs, MCPs, skills, effort, custom agents, status lines, output styles, and more. He shared 12 practical ways developers and teams are customizing their setups.

-<img src="../!/boris/0.webp" alt="Boris Cherny intro tweet" width="50%" />
+<img src="assets/boris/0.webp" alt="Boris Cherny intro tweet" width="50%" />

 ---

@@ -28,7 +28,7 @@ Set up your terminal for the best Claude Code experience:
 - **Newlines**: If using Claude Code in an IDE terminal, Apple Terminal, Warp, or Alacritty, run `/terminal-setup` to enable shift+enter for newlines (so you don't need to type `\`)
 - **Vim mode**: Run `/vim`

-<img src="../!/boris/1.webp" alt="Configure your terminal" width="50%" />
+<img src="assets/boris/1.webp" alt="Configure your terminal" width="50%" />

 ---

@@ -42,7 +42,7 @@ Run `/model` to pick your preferred effort level:

 Boris's preference: High for everything.

-<img src="../!/boris/2.webp" alt="Adjust effort level" width="50%" />
+<img src="assets/boris/2.webp" alt="Adjust effort level" width="50%" />

 ---

@@ -54,7 +54,7 @@ Install from the official Anthropic plugin marketplace, or create your own marke

 Run `/plugin` to get started.

-<img src="../!/boris/3.webp" alt="Install Plugins, MCPs, and Skills" width="50%" />
+<img src="assets/boris/3.webp" alt="Install Plugins, MCPs, and Skills" width="50%" />

 ---

@@ -66,7 +66,7 @@ You can also set the default agent for the main conversation using the `"agent"`

 Run `/agents` to get started.

-<img src="../!/boris/4.webp" alt="Create custom agents" width="50%" />
+<img src="assets/boris/4.webp" alt="Create custom agents" width="50%" />

 ---

@@ -78,7 +78,7 @@ Out of the box, a small set of safe commands are pre-approved. To pre-approve mo

 Full wildcard syntax is supported — e.g., `Bash(bun run *)` or `Edit(/docs/**)`.

-<img src="../!/boris/5.webp" alt="Pre-approve common permissions" width="50%" />
+<img src="assets/boris/5.webp" alt="Pre-approve common permissions" width="50%" />

 ---

@@ -88,7 +88,7 @@ Opt into Claude Code's open source sandbox runtime to improve safety while reduc

 Run `/sandbox` to enable it. Sandboxing runs on your machine and supports both file and network isolation.

-<img src="../!/boris/6.webp" alt="Enable sandboxing" width="50%" />
+<img src="assets/boris/6.webp" alt="Enable sandboxing" width="50%" />

 ---

@@ -98,7 +98,7 @@ Custom status lines show up right below the composer, displaying model, director

 Every team member can have a different statusline. Use `/statusline` to have Claude generate one based on your `.bashrc`/`.zshrc`.

-<img src="../!/boris/7.webp" alt="Add a status line" width="50%" />
+<img src="assets/boris/7.webp" alt="Add a status line" width="50%" />

 ---

@@ -106,7 +106,7 @@ Every team member can have a different statusline. Use `/statusline` to have Cla

 Every key binding in Claude Code is customizable. Run `/keybindings` to re-map any key. Settings live reload so you can see how it feels immediately.

-<img src="../!/boris/8.webp" alt="Customize your keybindings" width="50%" />
+<img src="assets/boris/8.webp" alt="Customize your keybindings" width="50%" />

 ---

@@ -120,7 +120,7 @@ Hooks let you deterministically hook into Claude's lifecycle:

 Ask Claude to add a hook to get started.

-<img src="../!/boris/9.webp" alt="Set up hooks" width="50%" />
+<img src="assets/boris/9.webp" alt="Set up hooks" width="50%" />

 ---

@@ -128,7 +128,7 @@ Ask Claude to add a hook to get started.

 Customize your spinner verbs to add or replace the default list with your own verbs. Check the `settings.json` into source control to share verbs with your team.

-<img src="../!/boris/10.webp" alt="Customize your spinner verbs" width="50%" />
+<img src="assets/boris/10.webp" alt="Customize your spinner verbs" width="50%" />

 ---

@@ -140,7 +140,7 @@ Run `/config` and set an output style to have Claude respond using a different t
 - **Learning** — to have Claude coach you through making code changes
 - **Custom** — create custom output styles to adjust Claude's voice

-<img src="../!/boris/11.webp" alt="Use output styles" width="50%" />
+<img src="assets/boris/11.webp" alt="Use output styles" width="50%" />

 ---

@@ -155,7 +155,7 @@ Claude Code works great out of the box, but when you do customize, check your `s

 With 37 settings and 84 environment variables (use the `"env"` field in your `settings.json` to avoid wrapper scripts), there's a good chance any behavior you want is configurable.

-<img src="../!/boris/12.webp" alt="Customize all the things" width="50%" />
+<img src="assets/boris/12.webp" alt="Customize all the things" width="50%" />

 ---