The idea
You describe functions to the model: a name, a description and a JSON schema for the arguments. When the model decides a tool would help, it stops and returns a tool call such as get_weather({"city": "Dublin"}) instead of text. The model never runs anything itself.
Your code executes the function, then sends the result back as a tool result message. The model reads it and either answers or calls another tool. That round trip is the basic unit of every agent.
Tool descriptions are prompts. Say what the tool does, when to use it, what it returns and what it cannot do. Clear names and argument descriptions matter more than clever system prompts.
Tools are how a model touches the real world: databases, APIs, files, search. Everything in this area builds on this one mechanism.
Picture it
Words to know
- Tool / functionA capability you describe to the model and execute in your code.
- tool_use / tool_resultThe model’s call request and your reply with the output.
Try it without code
Watch a tool call in a chat app
- In a chat app with web search, ask about today’s news.
- Notice the "searching" step before the answer.
- That pause is a tool call and a tool result.
Use it in code
One tool, one round trip.
import anthropic
client = anthropic.Anthropic()
tools = [{"name": "get_weather",
"description": "Current weather for a city. Returns temperature in C and conditions.",
"input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}}]
def get_weather(city):
return {"city": city, "temp_c": 11, "conditions": "rain"} # call a real API here
messages = [{"role": "user", "content": "Should I bring an umbrella in Dublin?"}]
msg = client.messages.create(model="claude-sonnet-5-5", max_tokens=500, tools=tools, messages=messages)
call = next(b for b in msg.content if b.type == "tool_use")
messages += [{"role": "assistant", "content": msg.content},
{"role": "user", "content": [{"type": "tool_result", "tool_use_id": call.id,
"content": str(get_weather(**call.input))}]}]
final = client.messages.create(model="claude-sonnet-5-5", max_tokens=500, tools=tools, messages=messages)
print(final.content[0].text)Write two tools (a calculator and a currency converter) and ask questions that need one, both, or neither.
Common mistakes
- Executing tool calls without validating arguments.
- One-word tool descriptions.
- Returning huge raw API responses as tool results.