Claude API Tool Use for AI Applications
Claude API tool use enables you to give Claude access to external functions — database queries, API calls, calculations, or any custom logic. Instead of asking Claude to generate answers from training data alone, you let it decide when to call your tools and use the results to provide accurate, grounded responses. In other words, tool use turns a language model from a closed system into one that can reach into your databases, your services, and your business logic.
This guide covers practical patterns for implementing tool use with the Claude API, from basic function calling to complex multi-step workflows. Whether you are building a customer support bot, data analysis agent, or automation pipeline, these patterns will help you ship reliable AI features. Moreover, the same mechanism that powers function calling also powers structured data extraction, so a single concept unlocks two distinct capabilities.
How Tool Use Works
The tool use flow has three steps: you define available tools, Claude decides which to call and with what parameters, and you execute the function and return results. Claude then uses those results to formulate its final response. Importantly, the tools never run on Anthropic’s servers — your code executes them, which means you stay in full control of credentials, side effects, and what data leaves your environment.
Mechanically, everything flows through one endpoint: the Messages API. You pass a tools array in the request, and when Claude wants to invoke something, the response contains a tool_use content block instead of (or alongside) plain text. You run the function, then send the answer back as a tool_result block in the next user message. Consequently, there is no separate “functions API” to learn — tool use is just a particular shape of the standard request and response.
import anthropic
client = anthropic.Anthropic()
# Define tools Claude can use
tools = [
{
"name": "get_weather",
"description": "Get current weather for a city. Use this when "
"the user asks about weather conditions.",
"input_schema": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "City name, e.g. 'San Francisco'"
},
"units": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "Temperature units"
}
},
"required": ["city"]
}
},
{
"name": "search_products",
"description": "Search product catalog by name, category, or "
"price range. Returns matching products.",
"input_schema": {
"type": "object",
"properties": {
"query": {"type": "string"},
"category": {"type": "string"},
"max_price": {"type": "number"},
"in_stock": {"type": "boolean"}
},
"required": ["query"]
}
}
]
# Send message with tools
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=1024,
tools=tools,
messages=[
{"role": "user", "content": "What's the weather in Tokyo?"}
]
)
# Check if Claude wants to use a tool
for block in response.content:
if block.type == "tool_use":
print(f"Tool: {block.name}")
print(f"Input: {block.input}")
# Execute the tool and return results
Writing Tool Descriptions That Claude Can Actually Use
The single biggest lever on tool-use reliability is the description field. Claude reads it to decide whether to call the tool and when, so a vague description leads to a tool that fires at the wrong time — or never fires at all. As a rule, describe the trigger condition, not just the mechanics. “Searches products” tells Claude what the tool does; “Use this when the user mentions a product name, category, or budget” tells Claude when to reach for it.
The same discipline applies to each property. A field documented as “City name, e.g. ‘San Francisco'” produces cleaner inputs than a bare "type": "string", because the example anchors the format. Furthermore, enum constraints are worth using wherever a parameter has a fixed set of valid values — they prevent Claude from inventing a unit like "kelvin" that your function never handles. Finally, keep the tool set small and focused. A handful of well-named tools outperforms a sprawling library, since fewer choices means fewer chances to pick the wrong one. When you genuinely need a large catalog, look at tool-search patterns rather than loading every schema into context at once.
Complete Tool Use Loop
A single request rarely finishes the job. Claude calls a tool, you return the result, and Claude often calls another tool based on what it learned — so production code needs a loop that keeps going until Claude is done. The pattern below appends each tool_use response and each tool_result back into the running messages list, then re-sends, until stop_reason comes back as "end_turn".
def run_conversation(user_message: str, tools: list, tool_handlers: dict):
messages = [{"role": "user", "content": user_message}]
while True:
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=4096,
tools=tools,
messages=messages,
)
# If Claude responds with text only, we're done
if response.stop_reason == "end_turn":
return extract_text(response)
# Process tool calls
messages.append({"role": "assistant", "content": response.content})
tool_results = []
for block in response.content:
if block.type == "tool_use":
handler = tool_handlers.get(block.name)
if handler:
try:
result = handler(**block.input)
tool_results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": json.dumps(result),
})
except Exception as e:
tool_results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": f"Error: {str(e)}",
"is_error": True,
})
messages.append({"role": "user", "content": tool_results})
# Register tool handlers
handlers = {
"get_weather": lambda city, units="celsius": fetch_weather(city, units),
"search_products": lambda **kwargs: search_catalog(**kwargs),
}
answer = run_conversation("Find laptops under $1000", tools, handlers)
Two details in that loop matter more than they look. First, you must append the entire response.content back as the assistant turn — not just the text — because the tool_use block carries the id that the matching tool_result references. Drop it, and the next request fails validation. Second, when a handler raises, returning a tool_result with "is_error": true lets Claude see the failure and adapt — it might retry with different arguments or explain the problem to the user, rather than the whole request crashing. Notably, the Anthropic SDKs also ship a higher-level tool runner that automates this loop, but writing it by hand once is worth doing because it shows exactly where you can insert logging, approval gates, or conditional execution.
Structured Outputs with Tool Use
Furthermore, you can use tool definitions to force Claude to return data in a specific structure — even when you don’t actually call an external function. The trick is tool_choice: setting it to {"type": "tool", "name": "..."} forces Claude to “call” a single tool, and since the tool’s input_schema is just JSON Schema, you get back a validated object instead of free-form prose.
# Use tool_choice to force structured output
structured_tool = {
"name": "extract_invoice_data",
"description": "Extract structured data from invoice text",
"input_schema": {
"type": "object",
"properties": {
"vendor_name": {"type": "string"},
"invoice_number": {"type": "string"},
"date": {"type": "string", "format": "date"},
"line_items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"description": {"type": "string"},
"quantity": {"type": "integer"},
"unit_price": {"type": "number"},
"total": {"type": "number"}
},
"required": ["description", "quantity", "total"]
}
},
"subtotal": {"type": "number"},
"tax": {"type": "number"},
"total": {"type": "number"}
},
"required": ["vendor_name", "invoice_number", "total"]
}
}
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=1024,
tools=[structured_tool],
tool_choice={"type": "tool", "name": "extract_invoice_data"},
messages=[{
"role": "user",
"content": f"Extract data from this invoice:\n{invoice_text}"
}]
)
# Claude is forced to return structured data matching the schema
invoice_data = response.content[0].input
This pattern shines for extraction, classification, and any task where downstream code needs to parse the result. Instead of writing brittle regular expressions against a paragraph of text, you read block.input as a dictionary that already matches your schema. That said, Claude also supports a dedicated structured-outputs mode (output_config.format) for cases where you want a JSON response without framing it as a tool. As a result, choose the forced-tool approach when the structure is conceptually a “function the model is filling in,” and the response-format approach when you simply want the assistant’s final answer constrained to a shape.
Production Patterns
Error Handling and Retries
Tool use loops make multiple API calls per user turn, which multiplies your exposure to transient failures. Rate limits and overloads are retryable; bad requests and authentication errors are not. The Anthropic SDKs already retry 429 and 5xx responses with exponential backoff by default, but a tool-heavy agent often benefits from an explicit wrapper so you can tune backoff and add your own observability.
from anthropic import RateLimitError, APIError
import time
def robust_tool_call(messages, tools, max_retries=3):
for attempt in range(max_retries):
try:
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=4096,
tools=tools,
messages=messages,
)
return response
except RateLimitError:
wait = 2 ** attempt
time.sleep(wait)
except APIError as e:
if attempt == max_retries - 1:
raise
time.sleep(1)
raise Exception("Max retries exceeded")
Beyond API-level retries, plan for the tools themselves failing. A weather service times out; a product query returns nothing; a database connection drops. As shown in the loop earlier, the right move is to surface that failure to Claude as a tool_result with is_error set, rather than swallowing it. Claude is generally good at recovering — it will rephrase a search, ask the user for clarification, or note that the data is unavailable. In addition, cap your loop iterations. A misbehaving prompt or a tool that keeps returning ambiguous results can otherwise spin indefinitely, so a simple counter that breaks after, say, ten tool rounds is cheap insurance.
Latency, Cost, and Observability
Every tool round trip is a full API call, so a three-step workflow costs roughly three times the latency and tokens of a single response. Tool definitions also add input tokens to every request in the conversation, since the full schema is re-sent each turn. Consequently, two habits pay off: keep tool schemas lean, and consider prompt caching for the stable parts of your prompt — the system message and tool definitions rarely change between turns, so caching them avoids paying to re-process the same bytes repeatedly.
Observability matters just as much. Because the model is choosing tools autonomously, you want to know which tools it picked, how often each one failed, and where time went. Logging the tool name, input, latency, and error flag for every call gives you the data to spot a tool that Claude over-triggers or a description that needs sharpening. For a deeper treatment of designing agent loops around these constraints, the AI Agents Tool Use & Function Calling guide walks through orchestration patterns that build directly on what is shown here.
When NOT to Use Tool Use
Tool use adds latency and cost (extra tokens for tool definitions). Consequently, skip it when Claude can answer from its training data, when you just need text generation (summaries, translations), or when a simple prompt template produces reliable enough output. As a result, reserve tool use for tasks that genuinely require external data or actions. A good test: if the answer doesn’t depend on something Claude cannot know — a live price, a record in your database, the outcome of a calculation it shouldn’t be guessing at — then a plain message is simpler, cheaper, and faster.
There is also a middle ground worth naming. If you only need a structured response and never actually execute a function, reach for structured outputs rather than a forced tool — it expresses the intent more directly. And if your workflow is genuinely a fixed pipeline (“summarize, then translate, then format”), orchestrating those steps in your own code is often clearer than handing the whole flow to the model and hoping it sequences the tools correctly. In short, tool use is the right answer when the task is open-ended and depends on external state, not when you already know every step in advance.
Key Takeaways
Tool use bridges the gap between language models and real-world systems. Well-defined tool schemas with clear descriptions produce the most reliable results. Start with 2-3 focused tools, measure accuracy, and expand gradually. Above all, treat the description field as part of your prompt engineering, handle tool failures as data rather than crashes, and bound your loops so an agent can never run away.
Related Reading
- AI Agents Tool Use & Function Calling
- Building AI Agents with LangChain
- Model Context Protocol (MCP) Guide
External Resources
In conclusion, Claude API tool use is an essential topic for modern software development. By applying the patterns and practices covered in this guide, you can build more robust, scalable, and maintainable systems. Start with the fundamentals, iterate on your implementation, and continuously measure results to ensure you are getting the most value from these approaches.