LLM Best Practices

Tool Call

2 min read

View markdown source

Definition

A tool call (also called a function call) is a structured output block generated by a model that names a tool and provides JSON-encoded arguments. The caller is responsible for executing the tool and returning its result in a subsequent message. The model then uses the result to continue its response.

In the Anthropic Messages API, a tool call appears as a tool_use content block with fields: type, id, name, and input (a JSON object of arguments).

The caller runs the named function, then sends back a tool_result block referencing the tool_use_id. The model continues generating with the result in context.

Tool schemas are defined as JSON Schema objects in the tools parameter of the API request. The model does not execute tools; it only generates the call. The caller controls execution, allowing it to validate arguments, apply rate limits, audit logs, or deny unsafe calls.

stop_reason = "tool_use" indicates the model paused its completion to request tool execution.

When it applies

Use tool calls to let a model access real-time data (search, databases, APIs), perform calculations, or take actions (send email, write a file). Define narrow tools with clear descriptions and strict schemas. Validate tool inputs before executing; the model may hallucinate argument values. Return structured, concise results; long tool output fills context quickly.

Example

import anthropic
 
client = anthropic.Anthropic()
tools = [{
    "name": "lookup_order",
    "description": "Look up an order by order ID and return its status.",
    "input_schema": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"]
    }
}]
 
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=512,
    tools=tools,
    messages=[{"role": "user", "content": "What is the status of order #12345?"}]
)
 
if response.stop_reason == "tool_use":
    tool_block = next(b for b in response.content if b.type == "tool_use")
    order_status = lookup_order(tool_block.input["order_id"])
    # Continue conversation with tool_result...
  • function-calling - the older synonym for tool call, still used in OpenAI API documentation.
  • structured-output - tool calls are one form of structured output; schemas constrain arguments.
  • schema-validated - JSON Schema validation should gate tool execution.
  • completion - a completion with stop_reason = "tool_use" contains a tool call.
  • mcp - MCP is a protocol that standardizes tool discovery and execution across hosts.

Citing this term

See Tool Call (llmbestpractices.com/glossary/tool-call).

Graph View

Backlinks