Claude API Tool Use: The Complete 2025 Developer Guide
Claude API Tool Use: The Complete 2025 Developer Guide
Published: April 4, 2026
What Is Claude API Tool Use and Why It Matters in 2025
If you have ever watched an LLM confidently hallucinate a database result it could have just looked up, you already understand why Claude API tool use is one of the most important capabilities in modern AI development. Tool use gives Claude the ability to call developer-defined or Anthropic-provided functions—querying APIs, executing code, browsing the web, and even controlling desktop GUIs—all coordinated through a structured agentic loop that keeps the model grounded in real data.
By late 2025, Anthropic had transformed this from a basic function-calling mechanism into a full agentic platform. The release of three advanced tool use beta features—Programmatic Tool Calling, Tool Search, and Tool Use Examples—alongside the Claude Agent SDK, Agent Skills, and native parallel tool calling in Claude 4+ models, means developers can now build production-grade autonomous agents that handle complex, multi-step workflows with measurably fewer tokens and API round-trips.
This guide covers everything you need to know: the core agentic loop, the two-category tool split, every major advanced pattern released through 2025, and the best practices Anthropic recommends for shipping reliable agents.
Refer to the official Claude API tool use overview alongside this guide for the canonical reference.
How Claude API Tool Use Works: The Agentic Loop Explained
The Four-Step Tool Use Lifecycle
At its core, Claude API tool use follows a predictable four-step cycle:
- Define — You supply tool schemas alongside the messages array in your API request.
- Signal — Claude returns a
stopreasonof"tooluse"along with one or moretool_usecontent blocks, each containing a uniqueid,name, and structuredinputconforming to the tool's JSON schema. - Execute — Your application runs the tool and captures the result.
- Return — You send the result back in a
tool_resultcontent block keyed to the originalid, and the conversation continues.
Here is the minimal pattern in Python:
import anthropic
client = anthropic.Anthropic()
tools = [
{
"name": "get_weather",
"description": "Returns current weather for a given city.",
"input_schema": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name"}
},
"required": ["city"]
}
}
]
response = client.messages.create(
model="claude-opus-4-6",
max_tokens=1024,
tools=tools,
messages=[{"role": "user", "content": "What's the weather in Tokyo?"}]
)
# Claude signals it wants to call a tool
if response.stop_reason == "tool_use":
tool_use_block = next(b for b in response.content if b.type == "tool_use")
tool_result = fetch_weather(tool_use_block.input["city"]) # your function
# Send the result back
followup = client.messages.create(
model="claude-opus-4-6",
max_tokens=1024,
tools=tools,
messages=[
{"role": "user", "content": "What's the weather in Tokyo?"},
{"role": "assistant", "content": response.content},
{
"role": "user",
"content": [{
"type": "tool_result",
"tool_use_id": tool_use_block.id,
"content": tool_result
}]
}
]
)
Client Tools vs. Server Tools: Key Differences
Anthropic splits tools into two categories with a crucial operational difference:
| Category | Examples | Executed By | |---|---|---| | Client tools | Custom functions, bash, text_editor | Your application | | Server tools | websearch, codeexecution, webfetch, toolsearch | Anthropic's infrastructure |
Server tools are zero-overhead for you as a developer—Claude calls them and the results arrive without any execution handling on your side. Client tools require you to implement the execution logic, but give you full control over what runs in your environment.
For a complete breakdown of both categories, the implementation guide on the Claude developer platform covers every edge case including parallel calls, error shapes, and naming conventions.
Strict Schema Validation and Why It Matters
For production agents, invalid tool inputs are silent killers. Anthropic's strict: true flag (enabled via the structured-outputs-2025-11-13 beta header) provides guaranteed schema conformance—Claude's tool call inputs will always match your schema exactly. Add it to any tool definition where a malformed parameter would cause a downstream failure:
{
"name": "github_create_issue",
"description": "Creates a GitHub issue in a repository.",
"strict": True,
"input_schema": {
"type": "object",
"properties": {
"repo": {"type": "string"},
"title": {"type": "string"},
"body": {"type": "string"}
},
"required": ["repo", "title", "body"],
"additionalProperties": False
}
}
Advanced Claude API Tool Use Features in 2025
Programmatic Tool Calling: Multi-Tool Orchestration in One Pass
The biggest efficiency leap in 2025's tool use update is Programmatic Tool Calling (PTC). Instead of executing one tool per API round-trip, Claude writes Python code that orchestrates multiple tools in a single inference pass.
The numbers are significant: on complex research tasks, Anthropic measured average token usage dropping from 43,588 tokens to 27,297 tokens—a 37% reduction. A 20-tool workflow that previously required 20 separate API calls can complete in one code execution block.
Enable PTC with the interleaved-thinking-2025-05-14 beta header and a computerusesandbox tool in your request. Claude will return a code content block containing Python that calls your tools programmatically:
# Claude generates something like this in a single response:
results = []
for repo in ["api-service", "frontend", "data-pipeline"]:
prs = github_list_prs(repo=repo, state="open")
for pr in prs:
if pr["review_requested"]:
results.append(slack_send_message(
channel="#eng-review",
text=f"PR needs review: {pr['url']}"
))
Tool Search: Dynamically Discovering Tools from Large Libraries
Large MCP server setups present a brutal context problem: tool definitions alone can consume 50,000–134,000 tokens before a single user message is processed. Tool Search solves this by letting Claude discover tools on-demand using BM25 natural language queries or regex patterns.
Configure deferred loading in your tool definitions:
{
"name": "tool_search",
"type": "tool_search",
"tools": [
{"name": "salesforce_get_contact", "defer_loading": True, "description": "..."},
{"name": "salesforce_update_deal", "defer_loading": True, "description": "..."},
# ... thousands more
]
}
Claude will issue a tool_search call—{"query": "salesforce contact lookup", "mode": "bm25"}—before using any deferred tool, loading only what it needs. This is the key to scaling Claude API tool use to enterprise-scale MCP deployments. Full configuration details live in the Tool Search documentation.
Tool Use Examples: Guided Reasoning for Complex Workflows
The third November 2025 beta feature addresses a subtler problem: Claude selecting the right parameters when a tool has many options. Tool Use Examples attach concrete usage patterns directly to a tool schema:
{
"name": "database_query",
"description": "Executes a SQL query against the analytics database.",
"examples": [
{
"input": {"query": "SELECT COUNT(*) FROM users WHERE created_at > '2025-01-01'"},
"description": "Count new users since a date"
},
{
"input": {"query": "SELECT product_id, SUM(revenue) FROM orders GROUP BY product_id ORDER BY 2 DESC LIMIT 10"},
"description": "Top 10 products by revenue"
}
],
"input_schema": { ... }
}
This is especially powerful for domain-specific query languages or tools with non-obvious parameter formats.
Parallel Tool Calling: Concurrent Execution for Faster Agents
Claude 4+ models natively support parallel tool use with built-in token-efficient handling. When Claude identifies multiple independent calls, it returns several tool_use blocks in a single response. You must execute all of them and return all results together in one user message:
# Claude returns multiple tool_use blocks in one response
tool_calls = [b for b in response.content if b.type == "tool_use"]
# Execute all calls concurrently
import asyncio
results = await asyncio.gather(*[execute_tool(tc) for tc in tool_calls])
# Return ALL results in one message
tool_results = [
{"type": "tool_result", "tool_use_id": tc.id, "content": result}
for tc, result in zip(tool_calls, results)
]
Returning results one at a time when Claude issued them in parallel is a common mistake that breaks the conversation structure and wastes tokens.
Claude Agent SDK, Agent Skills, and Computer Use Tool
Claude Agent SDK: The @tool Decorator and In-Process MCP Servers
The Claude Agent SDK (formerly the Claude Code SDK) provides a high-level abstraction over the entire tool use loop. Built-in tools include Read, Write, Edit, Bash, and WebSearch. For custom tools, the @tool decorator creates in-process MCP servers without any external server setup:
from claude_agent_sdk import tool, Agent
@tool
def query_internal_api(endpoint: str, params: dict) -> dict:
"""Queries the internal analytics API. Use for revenue and user metrics."""
return requests.get(f"https://api.internal/{endpoint}", params=params).json()
agent = Agent(
model="claude-opus-4-6",
tools=[query_internal_api],
allowed_tools=["Bash", "WebSearch", "query_internal_api"]
)
result = await agent.run("Summarize last quarter's revenue by product line.")
The SDK also handles automatic context compaction for long-running tasks—critical for agents that accumulate hundreds of tool results across many turns.
Agent Skills: Pre-Built Office and PDF Capabilities
Launched in October 2025, Agent Skills are modular capability packages that Claude loads dynamically. Without writing a single line of tool wiring, you can enable Claude to produce:
- PowerPoint (
.pptx) presentations - Excel (
.xlsx) workbooks with formulas and charts - Word (
.docx) documents with formatting - PDF files with custom layouts
Skills are loaded from a SKILL.md manifest and execute inside the code execution container, making them safe and reproducible.
Computer Use Tool: Desktop Automation with Claude
The computer use tool (beta, header: computer-use-2025-11-24) enables Claude to interact with desktop GUI environments via screenshot capture and mouse/keyboard control. Available on Claude Opus 4.6 and Sonnet 4.6, it holds state-of-the-art results on WebArena browser navigation benchmarks.
It is a schema-less Anthropic-defined tool—you declare it but don't handle execution yourself:
tools = [{"type": "computer_use_20251124", "name": "computer", "display_width_px": 1280, "display_height_px": 800}]
The computer use tool documentation covers available actions (screenshot, left_click, type, scroll, zoom) and the security isolation requirements for any production deployment.
Production Error Handling: Circuit Breakers and Retry Patterns
When a tool call fails, always return a structured error with is_error: true rather than raising an exception that breaks the loop:
try:
result = execute_tool(tool_name, tool_input)
content = json.dumps(result)
is_error = False
except Exception as e:
content = f"Tool execution failed: {str(e)}. Check parameters and retry."
is_error = True
tool_result = {
"type": "tool_result",
"tool_use_id": tool_use_id,
"content": content,
"is_error": is_error
}
For high-availability production systems, the Collabnix Claude API integration guide provides battle-tested patterns for circuit breakers and Prometheus metrics instrumentation around tool execution.
Claude API Tool Use Best Practices for Production Systems
Start Simple: Anthropic's Design Principle for Agentic Systems
Anthropic's Building Effective Agents research is direct: start with the simplest pattern that works and add complexity only when you can measure the benefit. Most production use cases don't need Programmatic Tool Calling on day one—a clean single-tool loop with good error handling will outperform an over-engineered framework.
Tool Naming Conventions and Description Engineering
Meaningful namespacing prevents Claude from guessing which tool to call:
- ✅
githublistprs,slacksendmessage,postgresrunquery - ❌
list_items,send,query
Tool descriptions should read like documentation written for a careful engineer: explain what the tool does, what it doesn't do, when to use it versus an alternative, and what format the output takes. This is the highest-leverage prompt engineering you can do for agentic reliability.
Context Management at Scale with MCP and Tool Search
For any deployment integrating more than 20 tools, the math on context consumption is unforgiving. Adopt these practices from the start:
- Mark rarely-used tools with
defer_loading: trueand enable Tool Search. - Enable automatic tool call clearing (
context-management-2025-06-27beta header) for long multi-turn sessions—Claude will automatically drop old tool results as token limits approach. - Return only high-signal information in tool responses. Strip pagination metadata, drop null fields, and summarize large payloads before returning them.
AWS Bedrock Tool Use: Automatic Tool Call Clearing and Streaming
Claude tool use on AWS Bedrock supports the same feature set including automatic tool call clearing, fine-grained tool streaming, and computer use—with model-specific availability. If you're running Claude in a Bedrock-hosted environment, the tool streaming API lets you process tool call inputs token-by-token, enabling faster UI responses for long-input tools.
Frequently Asked Questions About Claude API Tool Use
What is the difference between tool use and function calling in Claude's API?
They are the same capability under different names. Anthropic uses "tool use" in its official documentation; "function calling" is the terminology popularized by OpenAI's API. The mechanics are equivalent: you define a schema, the model signals a call, your code executes it, and the result returns to the conversation.
How many tools can I pass to Claude at once in 2025?
There is no hard-coded limit, but context window consumption scales with the number and complexity of tool definitions. In practice, large MCP setups without Tool Search can burn 50,000–134,000 tokens in definitions alone. Use Tool Search with defer_loading: true for libraries exceeding 20–30 tools, and adopt the Tool Search documentation patterns for dynamic discovery.
Does Claude API tool use work on AWS Bedrock?
Yes. AWS Bedrock supports the full Claude tool use feature set including client tools, server tools, parallel tool calling, computer use, automatic tool call clearing (beta), and fine-grained streaming for tool inputs. Check the Bedrock documentation for per-model feature availability.
What is Programmatic Tool Calling and how does it differ from standard tool use?
Standard tool use executes one tool call per API round-trip. Programmatic Tool Calling lets Claude write Python code that orchestrates multiple tools in a single inference pass, reducing token usage by an average of 37% on complex tasks and eliminating redundant API calls entirely. It is best suited for research workflows, data aggregation tasks, and any scenario requiring conditional multi-tool logic.
How do I handle tool errors and prevent infinite agentic loops?
Always return is_error: true with an informative message rather than raising exceptions. Set a maximum iteration count in your agentic loop (typically 10–20 steps) and break on repeated identical tool calls. Use strict: true on critical tool schemas to eliminate malformed-input errors at the source. For long-running sessions, enable automatic tool call clearing to prevent context overflow from causing unexpected loop behavior.
Start Building with Claude API Tool Use Today
Claude API tool use in 2025 is no longer just function calling—it's a complete agentic infrastructure with parallel execution, dynamic tool discovery, one-pass multi-tool orchestration, and modular skill packages that handle real office workflows out of the box.
Your Next Steps as a Claude Tool Use Developer
- Start with the official tool use overview to understand the client/server tool split and the full agentic loop model.
- Implement the basic four-step lifecycle with one or two client tools before reaching for the Agent SDK.
- Read Building Effective Agents before designing your system architecture—Anthropic's simplicity-first principle will save you significant refactoring time.
- Add Programmatic Tool Calling and Tool Search once your baseline agent is working and you can measure the token and latency improvements in your specific workload.
- Enable strict schema validation on every tool that touches a production system.
The gap between a toy demo and a production Claude agent comes down to three things: understanding the agentic loop deeply, engineering your tool descriptions carefully, and managing context aggressively. This guide gives you the foundation for all three.
