Tool Use and Function Calling

A language model can't query a database, hit an API, or send an email — underneath all the tooling, it's still just predicting the next token in a sequence. Tool calling (also called function calling) gives it a structured way to ask your application to do those things on its behalf, instead of trying to describe the action in prose and hoping you parse it correctly.

The full loop has five steps, and it's the same shape on every provider: you send a request describing the tools available (name, description, and an input schema); the model may respond not with prose but with a request to call one of those tools, naming which one and with what arguments; your application executes that call — the model never runs any code itself; you send the result back to the model as a new message; and the model either replies with a final answer or asks for another tool call. Nothing about this loop is automatic unless you build it yourself or use a framework that runs it for you.

from openai import OpenAI
import json

client = OpenAI()
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get current weather for a city.",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
            "additionalProperties": False,
        },
    },
}]

messages = [{"role": "user", "content": "What's the weather in Lisbon?"}]
response = client.chat.completions.create(model="gpt-5.6", messages=messages, tools=tools)
call = response.choices[0].message.tool_calls[0]
args = json.loads(call.function.arguments)
result = get_weather(args["city"])

messages.append(response.choices[0].message)
messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)})
final = client.chat.completions.create(model="gpt-5.6", messages=messages, tools=tools)
print(final.choices[0].message.content)

OpenAI's Chat Completions API nests a function's definition inside a function object: {"type": "function", "function": {"name": ..., "description": ..., "parameters": ...}}. The newer Responses API flattens that same definition — type, name, description, and parameters sit directly on the tool object, with no nested wrapper. The two APIs also differ in how a call comes back: Chat Completions puts it on message.tool_calls, each with an id; Responses returns a top-level function_call item with a call_id. Both shapes describe the same underlying capability, so picking one is mostly about which endpoint the rest of your integration already uses.

Anthropic's Messages API skips the nested-function wrapper entirely: a tool is {"name": ..., "description": ..., "input_schema": ...}, and a call comes back as a tool_use content block in the response, carrying its own id, the tool's name, and the parsed input object.

import anthropic

client = anthropic.Anthropic()
tools = [{
    "name": "get_weather",
    "description": "Get current weather for a city.",
    "input_schema": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
    },
}]

messages = [{"role": "user", "content": "What's the weather in Lisbon?"}]
response = client.messages.create(model="claude-opus-5-5", max_tokens=1024, tools=tools, messages=messages)
call = next(b for b in response.content if b.type == "tool_use")
result = get_weather(call.input["city"])

messages.append({"role": "assistant", "content": response.content})
messages.append({"role": "user", "content": [
    {"type": "tool_result", "tool_use_id": call.id, "content": str(result)}
]})
final = client.messages.create(model="claude-opus-5-5", max_tokens=1024, tools=tools, messages=messages)
print(final.content)

Sending the result back uses a different shape on each provider, and mismatching it is a common source of broken loops. OpenAI's Chat Completions API expects a new message with role: "tool" and a tool_call_id matching the call you're responding to; its Responses API expects a function_call_output item carrying the matching call_id. Anthropic expects a tool_result content block with a tool_use_id matching the tool_use block's id, sent inside the next user message. Each provider also gives you a distinct signal that a tool call is what came back instead of a final answer — OpenAI's finish_reason is "tool_calls", Anthropic's stop_reason is "tool_use" — and checking that signal, rather than assuming, is what makes a loop reliable across turns where the model sometimes just answers in prose instead.

A single model turn doesn't have to request just one tool. Given a question like "what's the weather in Lisbon and Tokyo?", a model can — and by default, on both major providers, will — return more than one tool call in the same response: two tool_use blocks from Anthropic, or two entries in tool_calls from OpenAI. This is a real efficiency win: instead of two full round trips to the model, one per city, you get both requests up front and can execute them concurrently.

The rule that trips people up is what happens next: every call in that batch needs a matching result before you send anything back. Anthropic's documentation is explicit that all tool_result blocks belong in a single next user message, not spread across separate turns — the model is waiting on the whole batch, not the first one to finish.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=[weather_tool],
    messages=[{"role": "user", "content": "What's the weather in Lisbon and Tokyo?"}],
)
tool_uses = [b for b in response.content if b.type == "tool_use"]
print(f"Model requested {len(tool_uses)} tool calls")

Both providers let you turn parallel calling off when you specifically want at most one tool used per turn — useful when a workflow genuinely can't handle two actions landing at once, or when you're debugging and want to see calls one at a time. On Anthropic, this lives inside tool_choice: setting disable_parallel_tool_use: true alongside tool_choice: {"type": "auto"} caps the model at zero or one tool calls, while the same flag alongside type: "any" or type: "tool" forces exactly one. OpenAI's equivalent is a top-level parallel_tool_calls: false on the request.

tool_choice itself controls a related but separate question — not how many tools, but which: OpenAI's values are "auto" (default), "required" (call at least one), a forced specific function, or "none"; Anthropic's are "auto", "any" (call some tool), a forced named tool, or "none" — different vocabulary, the same four underlying behaviors.

response = client.chat.completions.create(
    model="gpt-5.6",
    messages=[{"role": "user", "content": "What's the weather in Lisbon and Tokyo?"}],
    tools=[weather_tool],
    parallel_tool_calls=False,
)

Once a project accumulates dozens of tools, exposing every schema on every request gets expensive and can hurt accuracy — the model has to weigh more options each turn, and every schema counts against your context and your bill. OpenAI's answer is to group related tools into namespaces and let tool_search defer loading a tool's full definition until the model actually decides it's relevant, rather than paying that token cost up front on every call. Its own guidance suggests keeping the initially available set small — under roughly twenty tools at the start of a turn — and reaching for deferred loading once you're past that.

Anthropic doesn't ship an identically named feature, but the underlying advice is the same: keep the active tool set focused, because too many tools can confuse a model into calling the wrong one or missing an obviously relevant one entirely.

Strict schema validation and business-logic validation solve different problems, and conflating them is the most common mistake in a tool integration. A schema — even with strict: true enforced — guarantees that a refund_order call has a well-typed order_id string and a numeric amount. It says nothing about whether that order actually exists, whether the amount requested is within what's actually owed, or whether the caller is authorized to issue it at all. Those are business-rule checks your application still has to run, every time, after the schema has already passed.

OpenAI's own guidance on defining functions is explicit about this: validate inputs before execution, and when something's wrong, return an informative error message rather than a bare failure — the model can often recover and retry sensibly if it's told what was wrong, and will otherwise just guess again in the dark.

def execute_refund(order_id: str, amount: float) -> str:
    order = orders.get(order_id)
    if order is None:
        return f"Error: no order found with id {order_id}."
    if amount > order.remaining_refundable:
        return f"Error: {amount} exceeds the {order.remaining_refundable} still refundable."
    if not caller_is_authorized(order):
        return "Error: this caller is not authorized to refund this order."

    process_refund(order, amount)
    return f"Refunded {amount} on order {order_id}."

This split matters because strict mode can create a false sense of safety. A well-formed call isn't the same thing as a safe or a correct one, and treating schema compliance as the finish line is exactly what lets a plausible-looking but wrong order_id, or an amount outside policy, sail through untouched. The fix isn't a stricter schema — JSON Schema has no way to express "this order belongs to this customer" or "this amount is under the refund limit" — it's a second, separate layer of checks that runs after the schema has already passed, against your actual data and your actual authorization rules. Treat the two as a pipeline: schema validation first, business validation second, and only then execution.

The prompting lesson established that instructions and data deserve separate channels, and a tool result deserves exactly the same treatment — arguably more, because it can come from a source further outside your control than a user's typed message: a scraped web page, a customer's own free-text field, an external API's error response. Anthropic's own guidance on mitigating prompt injection recommends putting untrusted third-party content only inside tool_result blocks, never in a system prompt or a plain user text block, and states two further concrete habits: make the nature and source of returned content explicit — that this is, say, OCR text from an uploaded image or the body of an inbound email from an unknown sender — and state the policy plainly in your system prompt, that content returned from tools must never be treated as an instruction that overrides the system prompt or the user's original request.