Claude Tool Use Explained: Give Claude the Ability to Act
Out of the box, Claude can read, reason, and write — but it cannot do. It cannot check the current weather, query your database, look up a live stock price, or send a Slack message. Its knowledge has a training cutoff, and it has no way to take action in external systems.
Tool use changes that. By defining tools — functions that Claude can choose to call — you give Claude the ability to reach outside its own knowledge and take real actions in the world. This is the capability that turns Claude from a conversational AI into a productive agent.
What is Claude Tool Use?
Claude tool use (also called function calling) lets you define JSON Schema tool definitions that Claude can call during a conversation. When Claude needs real-world data or needs to take an action, it returns a tool_use block with the tool name and arguments. Your application runs the actual function and returns the result as a tool_result block. Claude then uses that result to generate its final response.
Tool use is the foundation of everything in Module 4 of this series. Whether you want Claude to browse the web, analyse images, or orchestrate multi-step workflows, tool use is the underlying mechanism.
How Tool Use Works: The Core Loop
Tool use in Claude is not Claude autonomously running code. The loop works like this:
- You define tools: You send Claude a list of available tools as part of your API request, each with a name, description, and input schema
- Claude decides whether to call a tool: Based on the user's message and the available tools, Claude decides if it needs to call a tool to answer correctly
- Claude returns a tool_use block: Instead of a text response, Claude returns a structured tool call with the tool name and arguments
- Your code runs the tool: You extract the tool call, execute the actual function in your code, and get the result
- You send the result back to Claude: You add the tool result to the conversation and call the API again
- Claude generates the final response: Claude uses the tool result to produce its final answer to the user
Your code always controls execution. Claude requests tools; your code runs them. This design is intentional — it keeps humans in control of side effects.
Claude Never Executes Code Directly
In standard tool use, Claude produces a tool call request — a structured JSON object with a function name and arguments. Your application code receives that request and executes the actual function. Claude has no direct access to your systems, databases, or APIs — it can only request that your code run them on its behalf. This is the fundamental safety boundary in tool use.
Defining a Tool
Tools are defined using JSON Schema syntax. Each tool needs three things: a name, a description, and an input_schema.
The description is critical — Claude reads it to decide when to use the tool. A clear, accurate description is more important than anything else in your tool definition.
A Complete Tool Use Example
Here is a full working example of the tool use loop from start to finish.
Controlling Tool Choice
By default, Claude decides whether to use a tool. You can override this behaviour:
- tool_choice: auto: Claude decides whether to use a tool (default)
- tool_choice: any: Claude must use at least one of the provided tools
- tool_choice: tool (with name): Claude must use the specific named tool — useful for structured output extraction
- tool_choice: none: Claude must not use any tools, even if provided
Parallel Tool Calls
Claude can call multiple tools in a single response when it needs information from several sources to answer a question. For example, if a user asks to compare the weather in London and Paris, Claude might call get_weather twice in parallel. Your implementation must handle lists of tool_use blocks, not just a single one. Always iterate over all blocks in the content array.
Defining Good Tool Descriptions
The quality of your tool description directly determines when and how Claude uses your tool. Follow these practices:
- Explain when to use it: "Use this when the user asks about current stock prices or market data" is more helpful than "Gets stock prices"
- Describe parameter constraints: If a city name must be in English, say so in the parameter description
- Describe the return value: Tell Claude what data comes back so it knows how to use the result in its response
- Note limitations: "Only returns data for major cities with populations over 100,000" prevents Claude from calling the tool for inputs that will fail
Multi-Tool Applications
Real applications typically provide Claude with several tools. The principles remain the same:
Claude will select the appropriate tool based on the task at hand. For complex requests, it may call multiple tools in sequence — using the result of one to inform the next.
Start with One Tool, Add More Gradually
When building a tool-using application for the first time, start with a single, well-defined tool and make it work end-to-end before adding more. The most common mistake is defining five tools at once and struggling to debug which tool is causing unexpected behaviour. One tool at a time lets you verify each integration in isolation.
Error Handling in Tool Use
When a tool call fails — network error, invalid input, service unavailable — you should return the error to Claude as a tool result rather than crashing.
Claude will incorporate the error into its response and either attempt a different approach or inform the user gracefully.
Summary
Tool use is the capability that turns Claude from a conversational model into an active participant in your application's workflows. The core pattern is always the same: define tools with clear descriptions and schemas, pass them to the API, handle tool_use blocks by executing your functions, return the results, and let Claude compose the final response.
Everything in the rest of Module 4 — web search, vision, computer use, and the Files API — builds directly on this tool use foundation. Next up: Claude Web Search Tool: Real-Time Data in Your AI App.
Tool use also underpins the agent loop. The Claude agentic loop explained post shows how a sequence of tool calls builds up complex agent behaviour. For a practical build that uses multiple tools together, see build a code review assistant with Claude.
The Anthropic tool use documentation is the authoritative reference for tool schema syntax, tool_choice options, parallel tool calls, and the is_error field for returning tool errors. The JSON Schema specification documents all available property types and constraints for input_schema definitions.
This post is part of the Anthropic AI Tutorial Series. Previous post: Prompt Engineering Refresher: 10 Techniques Every Developer Should Know.
External references: