Tool Use & Function Calling
Defining tools and parsing structured outputs
Skills taught: llms.tools
How Tool Use Works
Tools (function calling) let the LLM request data or actions from your code. The model returns a structured tool call; you execute it and return the result. This gives LLMs access to real-time data, databases, APIs, and any capability your code can provide.
- Tool Definition
- A JSON Schema description of a function: its name, description (what it does, when to use it), and input_schema (the typed parameters). The model decides whether and when to call tools based entirely on these descriptions.
- Tool Result
- The output your code returns after executing a tool call. Sent back as a tool_result message with the matching tool_use_id. The model reads the result and decides what to do next.
import anthropic, json
client = anthropic.Anthropic()
# Step 1: Define tools
tools = [
{
"name": "get_weather",
"description": "Get the current weather for a city. Use when the user asks about weather.",
"input_schema": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name, e.g. 'Paris'"},
"units": {"type": "string", "enum": ["celsius", "fahrenheit"], "default": "celsius"}
},
"required": ["city"]
}
}
]
# Step 2: First call — model may request a tool
response = client.messages.create(
model="claude-haiku-5-5",
max_tokens=1024,
tools=tools,
messages=[{"role": "user", "content": "What's the weather in Paris right now?"}]
)
print(f"Stop reason: {response.stop_reason}") # tool_use
if response.stop_reason == "tool_use":
tool_call = next(b for b in response.content if b.type == "tool_use")
print(f"Model wants to call: {tool_call.name}")
print(f"With input: {tool_call.input}")
# {"city": "Paris", "units": "celsius"}
import anthropic, json
client = anthropic.Anthropic()
def get_weather(city: str, units: str = "celsius") -> dict:
"""Your actual implementation — calls a real weather API."""
# Stub for demo
return {"city": city, "temperature": 18, "units": units, "condition": "Partly cloudy"}
tools = [{"name": "get_weather", "description": "Get current weather",
"input_schema": {"type": "object",
"properties": {"city": {"type": "string"}, "units": {"type": "string", "enum": ["celsius","fahrenheit"]}},
"required": ["city"]}}]
messages = [{"role": "user", "content": "What is the weather in Tokyo and in London?"}]
# Agentic loop
while True:
response = client.messages.create(
model="claude-haiku-5-5", max_tokens=1024, tools=tools, messages=messages
)
if response.stop_reason == "end_turn":
print(response.content[0].text)
break
# Collect all tool calls (may be multiple)
tool_results = []
for block in response.content:
if block.type == "tool_use":
result = get_weather(**block.input)
tool_results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": json.dumps(result)
})
# Add assistant response + tool results, continue
messages.append({"role": "assistant", "content": response.content})
messages.append({"role": "user", "content": tool_results})
Forced Structured Output with tool_choice
The most reliable way to get guaranteed JSON output is to define an extraction tool and force the model to always call it using tool_choice. This avoids the model outputting markdown, explanations, or malformed JSON.
import anthropic, json
client = anthropic.Anthropic()
# Define an extraction schema as a 'fake' tool
extract_tool = {
"name": "extract_contact",
"description": "Extract contact information from text",
"input_schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"email": {"type": "string"},
"company": {"type": "string"},
"phone": {"type": ["string", "null"]}
},
"required": ["name", "email", "company"]
}
}
text = "Reach out to Aisha Patel at aisha@technova.io — she heads engineering at TechNova."
response = client.messages.create(
model="claude-haiku-5-5",
max_tokens=512,
tools=[extract_tool],
tool_choice={"type": "tool", "name": "extract_contact"}, # force this tool
messages=[{"role": "user", "content": f"Extract contact info from: {text}"}]
)
tool_block = next(b for b in response.content if b.type == "tool_use")
contact = tool_block.input # Guaranteed well-typed dict
print(json.dumps(contact, indent=2))
Tip: Write clear, specific tool descriptions. The model decides whether and when to call tools based entirely on them. 'Get weather for a city' is better than 'weather tool'.
Warning: Never give the LLM tools with dangerous side effects (delete database, send real emails) unless you have a human-in-the-loop confirmation step. Always validate tool inputs before executing them.
Frequently Asked Questions
Can I give a model multiple tools?
Yes. Pass an array of tool definitions. The model selects the most appropriate one(s), or none if it can answer without a tool. It may also call multiple tools in parallel (one per content block).
What is the difference between tool_choice 'auto' and 'tool'?
'auto' (default) lets the model decide whether to use tools. {'type': 'tool', 'name': 'X'} forces a specific tool — use this for guaranteed structured output extraction.
Can tools call other tools?
Not directly — the model calls tools, your code executes them. But in an agentic loop, the model can call tool A, see the result, then call tool B based on that result — effectively chaining tools.