Tool use (function calling)

Definition

Tool use, also called function calling, lets Claude call functions that you define or that Anthropic provides. Claude determines when to call a tool based on the user’s request and the tool’s description. It then returns a structured call that your application runs (client tools) or that Anthropic runs (server tools).

Tools differ primarily by where the code runs. For tools you define, you write the schema and your application runs each call.

At a glance

Client tools, including user-defined tools and tools with Anthropic-defined schemas such as bash and text_editor, run in your application. Server tools run on Anthropic’s infrastructure, with no handler code in your application.

In the get_weather example, the first request defines a get_weather tool.
Claude answers the question by calling that tool.
The response carries a tool_use block.
Your code runs the lookup.
Your code runs the operation and sends back a tool_result.
A second request sends the result back in a tool_result block.
This lets Claude reply with the answer.

The source does not state the order of these points, so they are listed without arrows.

How it works

With the default tool_choice of auto, Claude determines on each turn whether to call a tool or respond directly. This boundary is steerable through your system prompt. To require a tool call rather than rely on prompting, set tool_choice.

When you use tools, the API also automatically includes a special system prompt for the model that enables tool use. If no tools are provided, then a tool choice of none uses 0 additional system prompt tokens. When you send a tool use prompt, like other API requests, the response includes both input and output token counts in the reported usage metrics.

Client-side tools are priced the same as other Claude API requests, although server-side tools can incur additional charges based on their specific usage. For server-side tools, there is additional usage-based pricing, for example web search charges per search performed.

Example

A minimal example uses a server tool, the Web search tool, which Anthropic runs for you; Claude runs the search on Anthropic’s infrastructure and returns the cited results in the same response. To have Claude call a function that you define, pass a tool with an input_schema, then run the call when Claude returns a tool_use block. To skip writing the round trip yourself, use the tool runner, where the SDK runs your tools and sends the results back automatically.

For Anthropic-schema client tools, Anthropic publishes the schema and trains Claude on it, and your application still runs each call and returns the tool_result. The Memory tool stores and retrieves information across conversations in files you control, the Bash tool runs shell commands in a persistent session that maintains state, and the Text editor tool views and modifies text files to debug, fix, and improve code. The Computer use tool takes screenshots and controls the mouse and keyboard in a desktop environment, and the Browser use tool navigates, reads, and interacts with webpages in your own browser environment.

Among server tools, the Web search tool searches the web for information beyond the knowledge cutoff with cited sources, the Web fetch tool retrieves the full content of specified webpages and PDF documents, and the Code execution tool runs Python and Bash code in a sandboxed container to analyze data and generate files. The Tool search tool works with thousands of tools by discovering and loading them on demand, and the MCP connector connects to remote MCP servers from the Messages API without a separate MCP client.

Related tools listed on this site.