Claude API Tool Use Guide: How Function Calling Works

Tool use (also called function calling) lets Claude call functions you define, or tools Anthropic provides, to do things it cannot do from text alone — fetching external data, writing files, running calculations, and more. This guide explains how tool use works for newcomers. (As of June 2026. Details and the tool list may change, so check the official docs for the latest.)

What tool use is — think of it as a "contract"

Tool use is a contract between your application and the model. You specify what operations are available and the shape of their inputs and outputs; Claude decides when and how to call them. The key point: the model never executes anything on its own. It emits a structured request, your code (or Anthropic's servers) runs the operation, and the result flows back into the conversation.

This makes the model behave less like a text generator and more like a function you call. You can integrate it the same way you would any typed API: define the schema, handle the callback, return a result. The difference is that the caller is a language model choosing which function to invoke based on the conversation.

The three places tools run

The primary axis along which tools differ is where the code executes. Every tool falls into one of three buckets, and the bucket determines what your app is responsible for.

• 1. User-defined tools (client-executed): you write the schema, you run the code, you return the results. The vast majority of tool-use traffic is here, typically calling application-specific logic (a database query, an HTTP call, a file write).
• 2. Anthropic-schema tools (client-executed): for common operations — running shell commands, editing files, controlling a browser, managing scratchpad memory — Anthropic publishes the schema and your app handles execution. These tools are bash, text_editor, computer, and memory. The execution model is identical to user-defined tools, but because these schemas are trained-in, Claude tends to call them more reliably than a custom equivalent.
• 3. Server-executed tools: web_search, web_fetch, code_execution, and tool_search are run by Anthropic. You enable the tool in your request and the server handles the rest — so you never construct a tool_result block for these.

The agentic loop, step by step (client tools)

Client-executed tools (user-defined + Anthropic-schema) require your app to drive a loop. Since the model can't run your code, every tool call is a round trip: the model asks, you execute, you report back, the model continues.

1. Send a request with your tools array and the user message.
2. Claude responds with stop_reason: "tool_use" and one or more tool_use blocks.
3. Execute each tool and format the outputs as tool_result blocks.
4. Send a new request with the original messages, the assistant's response, and the tool_result blocks.
5. Repeat from step 2 while stop_reason is "tool_use".

The loop exits when stop_reason is any other value (end_turn, max_tokens, stop_sequence, refusal) — meaning Claude produced a final answer or stopped for a reason your app should handle.

How to define a tool

Client tools (both user- and Anthropic-defined) go in the top-level tools parameter of the API request. Each tool definition typically includes a name (name), a description (description), and an input schema (input_schema, in JSON Schema form). The more specific your description, the more accurately the model calls the tool.

{
  "name": "get_weather",
  "description": "Get the current weather for a given city",
  "input_schema": {
    "type": "object",
    "properties": {
      "city": { "type": "string", "description": "City name" }
    },
    "required": ["city"]
  }
}

When the model decides to use the tool, the response contains a tool_use block (tool name + a JSON object of arguments). Your app extracts the arguments, runs the operation, and returns the output in a tool_result block on the next request. Claude never sees your implementation — only the schema you provided and the result you returned.

// tool_use block returned by Claude (example)
{
  "type": "tool_use",
  "id": "toolu_01A...",
  "name": "get_weather",
  "input": { "city": "Seoul" }
}

// tool_result block your app sends back on the next request
{
  "type": "tool_result",
  "tool_use_id": "toolu_01A...",
  "content": "Sunny, 22C"
}

The code above is an example to illustrate the shape (follow the official docs for exact fields and identifier formats). When you define tools, the API automatically adds a special system prompt that enables tool use, and those extra tokens count toward your cost.

When to use tools (and when not to)

Tool use fits when the task needs something the model can't do from text alone:

• Actions with side effects: sending an email, writing a file, updating a record. The model can describe these, but only a tool can perform them.
• Fresh or external data: current prices, today's weather, database contents — anything outside the training data or specific to your system.
• Structured, guaranteed-shape output: when you need a JSON object with specific fields rather than free-form prose.

Conversely, if the model's existing knowledge or reasoning is enough, a plain text response without tools is simpler and faster.

Server tools and pause_turn

Server-executed tools run their own loop inside Anthropic's infrastructure. A single request from your app might trigger several web searches or code executions; the model searches, reads results, and searches again — all without your app participating.

This internal loop has an iteration limit. If the model hits the cap while still working, the response comes back with stop_reason: "pause_turn" instead of end_turn. A paused turn means the work isn't finished, so re-send the conversation (including the paused response) to let the model continue where it left off.

Summary

Tool use is a contract: "the model decides, your code executes." Remember three things: (1) the model only requests calls, it never executes; (2) tools split by execution location into user-defined, Anthropic-schema, and server-executed; (3) for client tools, your app drives the tool_use → execute → tool_result loop. For deeper implementation (defining tools, handling calls, parallel use), see the official Claude tool use docs.

This article is an introductory explanation based on Anthropic's official documentation. API behavior, fields, and the tool list may be updated, so always verify the latest spec in the official docs before implementing. (Official source: docs.claude.com)