Skip to main content

Tool calls

Despite the suggestive terminology, a language model cannot directly execute code, open network sockets, query databases, or modify files. When a model "calls a tool", it simply outputs structured text—typically a JSON block specifying a function name and key-value arguments. The responsibility for executing that request falls entirely upon the calling application.

Whether your caller is a twenty-line script or an advanced autonomous harness with interactive approval prompts, the execution decision remains with the host software. If a model emits a structured block requesting a database deletion and that database vanishes a moment later, the model didn't delete it; the host application evaluated the request and executed the command.

Anatomizing a tool definition​

A represents an external action the calling environment is prepared to execute on behalf of the model. To make a capability discoverable, the caller registers a in the request payload, providing a name, a description, and a JSON Schema detailing expected arguments:

{
  "name": "get_weather",
  "description": "Get the current weather for a city. Use when the user asks about conditions right now, not a forecast.",
  "input_schema": {
    "type": "object",
    "properties": {
      "city": { "type": "string", "description": "City name, e.g. Leeds" },
      "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
    },
    "required": ["city"]
  }
}

Because JSON schemas are dense with punctuation and symbols, they consume significantly more tokens per character than standard English prose. A single schema with descriptive parameter documentation easily spans 200 to 500 tokens. Registering twenty tools across several connected MCP servers can quickly add 4,000 to 8,000 tokens of static overhead to every request. Because API requests are stateless, these schemas must be re-transmitted on each turn—making prompt caching crucial for managing costs.

Your registered tool list functions as a budget: exposing dozens of tools consumes substantial standing context and increases the risk of the model selecting an incorrect or ambiguous tool.

The tool-calling cycle​

A typical tool execution follows a coordinated five-step sequence:

  1. The caller packages the tool definitions, conversation history, and user question into the request.
  2. The model recognizes that answering requires external data, halts prose generation, and emits a structured block.
  3. The caller parses the tool call and executes the real-world operation (such as making an HTTP request or querying a database).
  4. The caller formats the operation's output into a message, appends it to the transcript, and sends a follow-up request to the model.
  5. The model reads the execution output in the updated history and generates its conversational response.

Notice that on step 5, the model has no innate memory of requesting the tool on step 2. It understands the workflow purely because the caller resent the original question, the tool invocation, and the resulting payload within the message history.

Providers also refer to this mechanism as . While API parameter names vary across vendors, the underlying protocol is identical.

An interaction can conclude with the model providing direct text, or with an execution refusal:

Declining to run a tool is a completely valid conversational state. If a user rejects a file deletion prompt, the harness returns a message stating "Action declined by user". The model digests that feedback, adjusts its plan, and offers an alternative approach.

Tool outputs become prompt context​

Whatever data a tool returns is serialized into the message history as plain text. It consumes tokens, incurs billing, and impacts attention like any other prompt element.

If a database tool returns a 200 KB raw JSON response, that single invocation injects approximately 50,000 tokens into the conversation history. On a 200,000-token window, a quarter of your available capacity is spent on redundant database keys the model will never inspect. Optimization belongs in the tool implementation: filter fields to what is strictly necessary, paginate long lists, and return compact summaries.

Schema design directly drives accuracy​

When a model selects which tool to invoke, it relies entirely on the tool names and documentation strings supplied in the schema. It cannot inspect the underlying source code or test an endpoint experimentally.

Ambiguous descriptions lead to frequent invocation mistakes. A tool generically named search with the description "searches data" will be called indiscriminately for unrelated tasks. Similarly, registering both get_user and lookup_customer without specifying which connects to the CRM versus internal authentication will cause the model to alternate unpredictably between them.

Leveraging JSON Schema validations—such as strict enum constraints and explicit required lists—prevents invalid calls before they happen. An enum specifying ["celsius", "fahrenheit"] eliminates invalid variations like "C" or "metric". Many providers also offer strict schema modes that enforce schema adherence during token decoding, mathematically guaranteeing that emitted JSON matches your schema specification.

However, syntactic schema compliance does not guarantee factual validity. A model can emit a syntactically valid order_id that was fabricated or hallucinated from conversational context. The executing environment must always validate arguments, enforce user authorization boundaries, and sanitize inputs before performing backend operations.

Writing a tool schema

Name the tool after the action it performs. Use one verb and one noun.

  • Write a description that says when to use the tool.
  • Add a second sentence that says when not to use it.
  • Give every parameter a description.
  • Use an enum for any parameter with a fixed set of values.
  • Mark a parameter required when the tool cannot run without it.
  • Return the smallest useful result. Page long lists.
  • Validate every argument in the executing code before you act on it.
  • Do not offer two tools whose descriptions overlap. Merge them or rename them.

Handling parallel tool calls​

Modern models can emit multiple tool invocation requests in a single generation step. These allow the caller to execute independent tasks concurrently—such as fetching weather across four cities or reading three separate files—collapsing multiple sequential round-trips into one.

When processing parallel calls, the harness must return a corresponding result for every requested tool call ID; omitting an ID results in an API validation error. If you are registering tools that trigger irreversible side effects, many providers allow disabling parallel tool execution to ensure actions occur strictly one at a time.

Resilient error handling​

Tools inevitably experience real-world failures: network timeouts, database connection errors, or missing records.

Throwing an uncaught exception out of the agent loop aborts the entire conversation. In contrast, returning the error message to the model as the tool result allows it to self-correct. For example, when handed Error: order 88213 not found in active orders, the model will often pivot to query historical archives or search by customer name. Providing descriptive, actionable error strings helps the model decide its next recovery step.

Structured output without execution​

When an application needs predictable data formatting without invoking external tools, it uses . In this pattern, the caller supplies a JSON Schema and constrains the model's textual completion to match that schema. No external code executes; the model simply produces guaranteed valid JSON.

Use structured output when extracting structured records from unstructured text, such as parsing an invoice into database fields. Use tool calling when the model must dynamically retrieve information or trigger actions in external systems.

Once tool calling is operational, the natural progression is orchestrating multi-step autonomous workflows—the foundation of the agentic loop. Expanding toolsets via modular extensions is covered in skills, plugins, and MCP.

Terms introduced​

  • Tool: a capability the caller is willing to run when the model asks for it.
  • Tool definition: the name, description, and JSON Schema sent in the context so the model knows a tool exists.
  • Tool call: a structured block the model emits naming a tool and its arguments. It executes nothing.
  • Tool result: the tool's output, appended to the conversation as a message and sent back to the model.
  • Function calling: another name for tool calling, used by several vendors for the same mechanism.
  • Parallel tool calls: several tool-call blocks in one reply, which the caller may run concurrently.
  • Structured output: forcing the model's reply to match a JSON Schema, with no tool and no execution involved.

How providers do it

The loop is the same everywhere. What differs is what the pieces are called and, in one case, whether the result goes back as a message or as its own item.

ConceptAnthropicOpenAIGoogle
Tools parametertoolstoolstools
Schema fieldinput_schemaparametersparameters
Model's calltool_use blockfunction_call output itemfunction_call step
Result goes back astool_result block in a user messagefunction_call_output input itemfunction_result input
Arguments arrive asA parsed object in inputA JSON-encoded string in argumentsAn object in arguments
Disable parallel callstool_choice.disable_parallel_tool_useparallel_tool_calls: falseNo documented flag
Strict tool schemastrict: truestrict: truetool_choice mode validated
Structured outputoutput_config.formattext.formatresponse_format
Built-in server-side toolsWeb search, web fetch, code execution, advisor, tool searchRemote MCP tool; others not checkedgoogle_search, code_execution, google_maps, computer_use, file_search

Every row is confirmed except Google's parallel-call flag, which no current documentation appears to offer, and the breadth of OpenAI's built-in tool list. Both are marked unconfirmed in the tabs below.

The row that costs the most to get wrong is the arguments one. OpenAI hands you a JSON string to parse; the other two hand you an object. Code that assumes the wrong one fails on the first tool call rather than in testing.

What this maps to: The Messages API takes a tools array and answers with a tool_use content block. Anthropic calls the whole thing tool use, and notes that "function calling" means the same. It draws a line between client tools, which your code executes, and server tools, which run on Anthropic's infrastructure and return their results inside the same response.

QuestionAnswerStatus
What is the tools parameter calledtools, an array on the Messages API requestconfirmed
What is in a tool definitionname, description, and input_schema (a JSON Schema object)confirmed
What is the response block calledtool_use, carrying id, name, and input. The message ends with stop_reason: "tool_use"confirmed
How does a result go backA tool_result block in a user message, with tool_use_id matching the call and content holding the outputconfirmed
Are parallel tool calls supportedYes. Turn them off with tool_choice: {"type": "auto", "disable_parallel_tool_use": true}confirmed
What else can tool_choice doauto, any, tool (name one), and noneconfirmed
Is the schema enforcedYes, with strict: true on a custom tool definition. Requires additionalProperties: falseconfirmed
Is there a structured output modeYes. output_config: {"format": {"type": "json_schema", "schema": {...}}}, strictly enforced and not a betaconfirmed
Are there server-side built-in toolsYes: web search, web fetch, code execution, advisor, and a tool search tool for working with very large tool setsconfirmed
Are there client tools with Anthropic's own schemaYes: bash, text editor, memory, computer use, browser use. Your code still executes themconfirmed
What do the definitions costBeyond the tokens in tools itself, the API inserts a tool-use system prompt. On Claude Opus 5 that is 286 tokens for auto or none, and 406 for any or toolconfirmed

Their vocabulary

Standard termTheir term
Tool callTool use, tool_use block
Tool resulttool_result block
Tool definition schemainput_schema
Structured outputStructured outputs, output_config.format
Tool the provider executesServer tool
Tool your code executesClient tool

Where to look

The usage block on every response reports input and output tokens, so the cost of a fat tool list shows up there. Server tools that bill per use, such as web search, publish their rates on their own documentation page rather than in the token count.

Last verified: 2026-09-09 against platform.claude.com/docs/en/agents-and-tools/tool-use/overview and platform.claude.com/docs/en/build-with-claude/structured-outputs.

Check your understanding

0 of 4 answered

  1. A database tool returns a 200KB JSON blob for one lookup. Why is that a problem?
  2. A harness offers `get_user` against the CRM and `lookup_customer` against the auth database. The model keeps calling the wrong one. What is the cause?
  3. A model replies with a tool call for `delete_branch`. What has happened to the branch at that moment?
  4. One vendor's documentation says "function calling" and another says "tool use". How much does the difference matter?