Skip to main content

Tool Use / Function Calling

Intermediate

Tool use lets Claude call functions you define — search, a calculator, your database, any API — and use the results. It's the foundation of every agent.

What you'll learn
  • How the four-step agentic loop works, from tool definitions to final answer
  • How to define a tool in Python with name, description, and JSON-Schema input
  • Why tool descriptions act as prompts that shape when and how Claude calls them
  • How to validate inputs, return errors as results, and use server-side tools safely

The loop​

Tool use is a conversation, not a single call. You hand Claude a menu of tools; Claude picks one and pauses; you run it and report back; Claude folds the result into its answer — repeating as needed.

Guided walkthrough1 of 4
  1. You include a list of tool definitions — each with a name, a description, and a JSON-Schema input.

Defining a tool (Python)​

A tool definition is just a name, a plain-language description, and a JSON-Schema for the input. Pass it in tools, then check stop_reason to know when Claude wants to act.

get_weather tool + first call

tools = [{
  "name": "get_weather",
  "description": "Get current weather for a city.",
  "input_schema": {
      "type": "object",
      "properties": {"city": {"type": "string"}},
      "required": ["city"],
  },
}]

msg = client.messages.create(
  model="claude-sonnet-5", max_tokens=1024,
  tools=tools,
  messages=[{"role": "user", "content": "What's the weather in Rome?"}],
)
# If msg.stop_reason == "tool_use": run the tool, then send a tool_result back.

Tips​

Small choices in how you define and handle tools make a large difference in reliability.

  • Descriptions are prompts. A clear tool description and parameter docs hugely improve when/how Claude calls it.
  • Validate inputs you receive before executing — never trust them blindly.
  • Return errors as results. If a tool fails, send a tool_result describing the error so Claude can recover.
  • Server-side tools. Anthropic also offers built-in tools (e.g. web search, code execution, computer use) — check the docs for the current menu.

:::warning Tools = actions = risk A tool that takes real actions inherits a security model. Apply least privilege and keep a human in the loop for risky calls — see Securing Agents & Tools. :::

Tool-use vocabulary
Press Enter or Space to flip the card. Use the left and right arrow keys to move between cards.Term shown.
1 / 4

Check yourself

0/3
  1. After Claude returns a tool_use block, who runs the tool?
  2. A tool you defined fails at runtime. What's the recommended move?
  3. Why does a clear tool description matter so much?
Key takeaways
  • Tool use is a loop: send tool definitions, Claude returns a tool_use block and stops, you execute and return a tool_result, Claude continues until it answers.
  • A tool definition is a name, a description, and a JSON-Schema input — pass it in tools and check stop_reason == tool_use.
  • Descriptions are prompts; validate inputs before executing; return failures as tool_result errors so Claude can recover.
  • Anthropic also offers server-side tools, and any tool that takes real actions needs least privilege plus a human in the loop.

Next​