●SUNSET — The legacy Workbench and experimental prompt tool APIs retire tomorrow, August 17, one day out●LATEST — Version 2.1.233, released August 15, is current: GitLab merge request URLs now work with --worktree and the claude agents view, where MRs appear as !N●SECURITY — Windows paths written with the NT \??\ device prefix no longer bypass UNC validation, closing an NTLM credential-leak vector●TODO — Todo and task tracking tools are off by default on Opus 4.8, Sonnet 5, Fable 5, Mythos 5, and newer models; set CLAUDE_CODE_ENABLE_TODO_TOOLS=1 to bring them back●FORK — Version 2.1.232, released August 14, makes subagent_type: 'fork' the default, so a forked subagent inherits the full conversation and prompt cache●MENTION — Typing @ in the prompt now mentions another Claude session by name, and SendMessage reaches that session directly●SUNSET — The legacy Workbench and experimental prompt tool APIs retire tomorrow, August 17, one day out●LATEST — Version 2.1.233, released August 15, is current: GitLab merge request URLs now work with --worktree and the claude agents view, where MRs appear as !N●SECURITY — Windows paths written with the NT \??\ device prefix no longer bypass UNC validation, closing an NTLM credential-leak vector●TODO — Todo and task tracking tools are off by default on Opus 4.8, Sonnet 5, Fable 5, Mythos 5, and newer models; set CLAUDE_CODE_ENABLE_TODO_TOOLS=1 to bring them back●FORK — Version 2.1.232, released August 14, makes subagent_type: 'fork' the default, so a forked subagent inherits the full conversation and prompt cache●MENTION — Typing @ in the prompt now mentions another Claude session by name, and SendMessage reaches that session directly
Claude API Advanced Tool Use: Tool Search, Programmatic Tool Calling, and Tool Use Examples
Master Claude API's advanced tool use features (Tool Search, Programmatic Tool Calling, Tool Use Examples) now GA. Build production-grade agents with 85% token reduction, 37% latency improvement, and 90% parameter accuracy.
When building agents with the Claude API, scaling up your tool library creates a serious problem. Including 100 tool definitions in every prompt consumes 55,000+ tokens before any real work happens. Costs skyrocket, latency balloons, and your usable context window shrinks dramatically.
Anthropic's three advanced tool use capabilities — now generally available since February 2026 — solve this at scale:
Tool Search Tool — Dynamically discover tools on demand, reducing token usage by 85%
Programmatic Tool Calling — Orchestrate multi-tool workflows in code, cutting latency by 37%
Tool Use Examples — Add usage examples to tool definitions, boosting complex parameter accuracy from 72% to 90%
Prerequisites: familiarity with basic Claude API tool use (beginner guide).
No beta headers required — all three features are now GA.
✦
Thank you for reading this far.
Continue Reading
What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.
WHAT YOU'LL LEARN
✦Detailed specification of Claude API tool use and complex tool-chaining pattern implementation
✦Production techniques for tool call optimization, error handling, and retry logic
✦Intelligent implementation of multi-tool dependency management and dynamic tool selection
Secure payment via Stripe · Cancel anytime
✦
Unlock This Article
Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.
The naive approach sends all tool definitions upfront:
# ❌ Inefficient — token count explodes as tools growresponse = client.messages.create( model=MODEL, max_tokens=4096, tools=[tool_1, tool_2, ..., tool_100], # All 100 tools every request messages=[{"role": "user", "content": user_query}])
With 100 tools, you're burning 55k+ tokens on definitions alone — leaving far less context for actual work.
The New Architecture
User query
↓
[Tool Search] → Claude searches for relevant tools dynamically
↓
Only needed tools loaded (85% token reduction)
↓
[Programmatic Tool Calling] → Tools called from within code
↓
Intermediate results stay out of context (37% latency cut)
↓
Only final result returned to Claude
Step-by-Step Implementation
Step 1: Tool Search Tool
Tool Search lets Claude discover tools from a catalog on demand. Tools marked defer_loading: true aren't expanded in the initial request — Claude searches for them as needed.
import anthropicimport jsonclient = anthropic.Anthropic()# ── Tool catalog (simulating a large enterprise setup) ──TOOL_CATALOG = { "get_weather": { "name": "get_weather", "description": "Get current weather conditions for a specified city", "input_schema": { "type": "object", "properties": { "city": {"type": "string", "description": "City name (e.g., Tokyo, New York)"}, "unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "default": "celsius"} }, "required": ["city"] } }, "search_database": { "name": "search_database", "description": "Search the product database and return relevant records", "input_schema": { "type": "object", "properties": { "query": {"type": "string", "description": "Search query"}, "limit": {"type": "integer", "description": "Maximum results to return", "default": 10} }, "required": ["query"] } }, "send_email": { "name": "send_email", "description": "Send an email to a specified recipient", "input_schema": { "type": "object", "properties": { "to": {"type": "string"}, "subject": {"type": "string"}, "body": {"type": "string"} }, "required": ["to", "subject", "body"] } }, # ... 100+ more tools in production}def tool_search_handler(query: str, limit: int = 5) -> list[dict]: """ Search tool catalog using keyword matching. In production, use Elasticsearch or pgvector for semantic search. """ results = [] query_lower = query.lower() for tool_name, tool_def in TOOL_CATALOG.items(): score = 0 if query_lower in tool_def["description"].lower(): score += 2 if any(word in tool_def["name"] for word in query_lower.split()): score += 1 if score > 0: results.append({"tool": tool_def, "score": score}) results.sort(key=lambda x: x["score"], reverse=True) return [r["tool"] for r in results[:limit]]def run_agent_with_tool_search(user_query: str) -> str: """Agent loop using Tool Search for dynamic tool discovery.""" tool_search_tool = { "name": "tool_search", "description": "Search the tool catalog to discover available tools. Use this when you need a tool that may exist but isn't currently available.", "input_schema": { "type": "object", "properties": { "query": { "type": "string", "description": "What kind of tool to look for (e.g., 'weather', 'database search')" }, "limit": { "type": "integer", "description": "Max tools to return", "default": 5 } }, "required": ["query"] } } messages = [{"role": "user", "content": user_query}] available_tools = [tool_search_tool] # Start with only Tool Search loaded_tools = {} max_iterations = 10 for _ in range(max_iterations): response = client.messages.create( model="claude-opus-4-6-20260205", max_tokens=4096, tools=available_tools, messages=messages ) if response.stop_reason == "end_turn": for block in response.content: if hasattr(block, "text"): return block.text return "Done" tool_results = [] for block in response.content: if block.type != "tool_use": continue if block.name == "tool_search": # Load discovered tools into available set found_tools = tool_search_handler( block.input["query"], block.input.get("limit", 5) ) for tool in found_tools: if tool["name"] not in loaded_tools: loaded_tools[tool["name"]] = tool available_tools.append(tool) result = f"Loaded {len(found_tools)} tools: {[t['name'] for t in found_tools]}" elif block.name in loaded_tools: result = execute_tool(block.name, block.input) else: result = f"Tool '{block.name}' not found" tool_results.append({ "type": "tool_result", "tool_use_id": block.id, "content": str(result) }) messages.append({"role": "assistant", "content": response.content}) messages.append({"role": "user", "content": tool_results}) return "Max iterations reached"def execute_tool(tool_name: str, tool_input: dict) -> Any: """Execute tool — connect to real APIs in production.""" if tool_name == "get_weather": return {"city": tool_input["city"], "temp": 22, "condition": "sunny"} elif tool_name == "search_database": return {"results": [f"Product {i}" for i in range(tool_input.get("limit", 3))]} elif tool_name == "send_email": return {"status": "sent", "message_id": "msg_001"} return {"error": "Unimplemented tool"}if __name__ == "__main__": result = run_agent_with_tool_search( "Check the weather in Tokyo and search the product database for laptops" ) print(result)# Expected output:# Tokyo weather: 22°C, sunny.# Database results: Product 0, Product 1, Product 2 found.
Step 2: Programmatic Tool Calling
Programmatic Tool Calling lets Claude orchestrate tool calls from within Python code. Intermediate results are processed in a sandboxed execution environment and never touch the conversation context — dramatically improving efficiency for multi-step workflows.
import anthropicimport jsonimport statisticsimport randomclient = anthropic.Anthropic()def run_programmatic_tool_calling(task: str) -> str: """ Multi-step data pipeline using Programmatic Tool Calling. Claude orchestrates tools internally; only the final result enters the conversation context. """ tools = [ { "name": "fetch_sales_data", "description": "Fetch sales records for a date range as JSON", "input_schema": { "type": "object", "properties": { "start_date": {"type": "string", "description": "Start date (YYYY-MM-DD)"}, "end_date": {"type": "string", "description": "End date (YYYY-MM-DD)"}, "region": {"type": "string", "default": "all"} }, "required": ["start_date", "end_date"] } }, { "name": "calculate_statistics", "description": "Calculate mean, median, and standard deviation for a list of numbers", "input_schema": { "type": "object", "properties": { "values": {"type": "array", "items": {"type": "number"}}, "metrics": {"type": "array", "items": {"type": "string"}} }, "required": ["values"] } }, { "name": "generate_report", "description": "Generate a summary report and post it to Slack", "input_schema": { "type": "object", "properties": { "title": {"type": "string"}, "summary": {"type": "string"}, "data": {"type": "object"} }, "required": ["title", "summary"] } } ] messages = [{"role": "user", "content": task}] while True: response = client.messages.create( model="claude-opus-4-6-20260205", max_tokens=8192, tools=tools, messages=messages ) if response.stop_reason == "end_turn": for block in response.content: if hasattr(block, "text"): return block.text return "Task complete" if response.stop_reason != "tool_use": break tool_results = [] for block in response.content: if block.type != "tool_use": continue result = dispatch_tool(block.name, block.input) tool_results.append({ "type": "tool_result", "tool_use_id": block.id, "content": json.dumps(result, ensure_ascii=False) }) messages.append({"role": "assistant", "content": response.content}) messages.append({"role": "user", "content": tool_results}) return "Processing complete"def dispatch_tool(name: str, inputs: dict) -> dict: """Tool execution dispatcher — connect to real services in production.""" if name == "fetch_sales_data": data = [{"date": f"2026-03-{i:02d}", "amount": random.randint(10000, 100000)} for i in range(1, 20)] return {"data": data, "total_rows": len(data)} elif name == "calculate_statistics": values = inputs["values"] metrics = inputs.get("metrics", ["mean", "median", "stdev"]) result = {} if "mean" in metrics: result["mean"] = statistics.mean(values) if "median" in metrics: result["median"] = statistics.median(values) if "stdev" in metrics and len(values) > 1: result["stdev"] = statistics.stdev(values) return result elif name == "generate_report": print(f"📊 Generating report: {inputs['title']}") return {"status": "sent", "channel": "#sales-reports"} return {"error": f"Unknown tool: {name}"}if __name__ == "__main__": result = run_programmatic_tool_calling( "Fetch March 2026 sales data, calculate statistics, " "and send a summary report to Slack" ) print(result)# Expected output:# March sales analysis complete.# Mean: $55,234 | Median: $52,000 | Std Dev: $18,432# Report sent to #sales-reports.
Step 3: Tool Use Examples for Higher Accuracy
Tool Use Examples provide Claude with concrete usage patterns beyond JSON Schema definitions. The input_examples field dramatically improves accuracy for tools with complex or optional parameters.
class ProductionAgent: """ Production-grade agent integrating all three advanced tool features: - Tool Search → 85% token reduction - Programmatic Tool Calling → 37% latency improvement - Tool Use Examples → 90% parameter accuracy """ def __init__(self, tool_catalog: dict): self.client = anthropic.Anthropic() self.tool_catalog = tool_catalog self.loaded_tools = {} self.model = "claude-opus-4-6-20260205" def run(self, user_query: str, max_iterations: int = 15) -> str: messages = [{"role": "user", "content": user_query}] available_tools = [self._tool_search_definition()] for _ in range(max_iterations): response = self.client.messages.create( model=self.model, max_tokens=8192, tools=available_tools, messages=messages ) if response.stop_reason == "end_turn": return self._extract_text(response) tool_results = self._handle_tool_calls(response.content, available_tools) messages.append({"role": "assistant", "content": response.content}) messages.append({"role": "user", "content": tool_results}) return "Max iterations reached" def _handle_tool_calls(self, content, available_tools: list) -> list: results = [] for block in content: if block.type != "tool_use": continue if block.name == "tool_search": found = self._search_tools(block.input["query"], available_tools) result = f"Loaded: {[t['name'] for t in found]}" else: result = self._execute(block.name, block.input) results.append({ "type": "tool_result", "tool_use_id": block.id, "content": json.dumps(result) }) return results def _search_tools(self, query: str, available_tools: list) -> list: found = [] for name, tool in self.tool_catalog.items(): if query.lower() in tool["description"].lower() and name not in self.loaded_tools: self.loaded_tools[name] = tool available_tools.append(tool) found.append(tool) return found def _execute(self, name: str, inputs: dict) -> Any: if name in self.tool_catalog: return {"result": f"Executed {name}", "inputs": inputs} return {"error": f"Tool '{name}' not found"} def _tool_search_definition(self) -> dict: return { "name": "tool_search", "description": "Search for available tools in the catalog", "input_schema": { "type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"] } } def _extract_text(self, response) -> str: for block in response.content: if hasattr(block, "text"): return block.text return "Complete"
Semantic Tool Search for Large Catalogs
For production with 100+ tools, upgrade from keyword matching to semantic search:
# pip install sentence-transformers faiss-cpufrom sentence_transformers import SentenceTransformerimport faissimport numpy as npclass SemanticToolSearch: def __init__(self, tool_catalog: dict): self.model = SentenceTransformer("paraphrase-multilingual-MiniLM-L12-v2") self.tools = list(tool_catalog.values()) descriptions = [t["description"] for t in self.tools] embeddings = self.model.encode(descriptions) self.index = faiss.IndexFlatL2(embeddings.shape[1]) self.index.add(embeddings.astype(np.float32)) def search(self, query: str, k: int = 5) -> list[dict]: query_vec = self.model.encode([query]).astype(np.float32) distances, indices = self.index.search(query_vec, k) return [self.tools[i] for i in indices[0] if distances[0][list(indices[0]).index(i)] < 1.5]
Troubleshooting
Error: Missing tool_result after tool_use
# ❌ Wrong — adding a user message without tool_resultmessages.append({"role": "assistant", "content": response.content})# Direct user message here will cause an API error# ✅ Correct — always return tool_result for every tool_use blocktool_results = [ {"type": "tool_result", "tool_use_id": block.id, "content": "..."} for block in response.content if block.type == "tool_use"]messages.append({"role": "user", "content": tool_results})
Tool Search returns no results
# ❌ Query too specifictool_search_handler("function that retrieves Tokyo weather in celsius")# ✅ Use short, general keywordstool_search_handler("weather") # Short keywords work better
Context grows too large in multi-step workflows
# ✅ Truncate large tool results before returning themdef truncate_result(result: dict, max_chars: int = 500) -> str: result_str = json.dumps(result) if len(result_str) > max_chars: return result_str[:max_chars] + "...[truncated]" return result_str
Performance & Security
Cost Comparison
Approach
Token Usage
Cost
Traditional (all tools upfront)
100%
Baseline
Tool Search + dynamic loading
15%
−85%
+ Programmatic Tool Calling
10%
−90%
Security Best Practices
Validate all inputs: Use JSON Schema validation before executing any tool
Sandbox code execution: Use Claude's built-in code execution tool for untrusted operations
Cap iterations: Always set max_iterations (recommended: 10–20)
Audit logging: Log every tool call and result for compliance and debugging
Handling Runtime Tool Failures and Input Validation at Scale
Everything so far assumed the tool runs cleanly once Claude calls it. In an agent that orchestrates hundreds of tools, though, timeouts and permission errors are routine. Running my own agents as an indie developer, I found the harder problem was rarely the failure itself — it was deciding how to report that failure back to Claude.
When a tool execution fails and you swallow the error, the agent happily continues on a false premise. The is_error field on tool_result is how you make that branch explicit.
def handle_tool_execution(tool_use_block): """Run the tool; surface failures to Claude via is_error.""" try: result = call_external_api(tool_use_block.input) return { "type": "tool_result", "tool_use_id": tool_use_block.id, "content": json.dumps(result), } except ExternalAPIError as e: return { "type": "tool_result", "tool_use_id": tool_use_block.id, "content": f"API error: {e} (status {e.status_code})", "is_error": True, } except Exception as e: return { "type": "tool_result", "tool_use_id": tool_use_block.id, "content": f"Unexpected error: {e}", "is_error": True, }
Given is_error: true, Claude plans its next move on the assumption that the tool failed. Tell it a weather API returned a 503, and it will acknowledge the gap and fall back to general seasonal guidance instead of inventing a reading. With a large catalog, the tool that Tool Search surfaces is not guaranteed to be callable, so an honest failure path belongs in the loop by default.
The second half is validating input before execution. Claude sometimes passes an integer as a string, and feeding that straight into arithmetic throws at runtime.
def execute_tool_safely(tool_name: str, tool_input: dict) -> str: """Validate and coerce input types before running the tool.""" if tool_name == "calculate_price": quantity = tool_input.get("quantity") if isinstance(quantity, str): try: quantity = int(quantity) except ValueError: return json.dumps({"error": "quantity must be an integer"}) unit_price = tool_input.get("unit_price", 0) return json.dumps({"total": quantity * unit_price}) return json.dumps({"error": f"unknown tool: {tool_name}"})
The "always validate tool input against a JSON Schema" bullet from the security section is, in practice, about absorbing this kind of type drift before it reaches your code. Pair the is_error path with a pre-execution validation path, and the agent stays predictable even as the tool count climbs.
Summary & Next Steps
In this guide you implemented all three advanced Claude API tool use features:
Tool Search Tool: Dynamic tool discovery with 85% token reduction — scales to any catalog size
Claude Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.