Tool use and function calling

What it isCopy Anchor Link

You describe tools with a name, a description and a JSON schema for arguments. When the model decides a tool is needed, it returns a tool call instead of text. Your program executes it and sends the result back as a new message. The model then continues, possibly calling more tools. This round trip is the core of every agent.

What makes it workCopy Anchor Link

The description is the interface. Say what the tool does, when to use it and what the arguments mean. Return results the model can read: concise, with clear errors that suggest what to try next. Validate arguments before running anything. Treat tool results as untrusted input, since they can contain text that tries to steer the model.

A worked example: one round tripCopy Anchor Link

1. You send the user question plus a tool description: name track_order, description "Look up the status of an order by id", parameter order_id (string).
2. The model replies with a tool call: track_order(order_id="8123").
3. Your code runs it: status "shipped, arrives Friday".
4. You send that result back.
5. The model answers: "Your order shipped and should arrive Friday." The model decided when to call and with what. Your code controlled what actually ran.

Writing a good descriptionCopy Anchor Link

Write for a new colleague: what it does, when to use it, what each argument means, and an example. If two tools sound alike, say how they differ.

How the loop worksCopy Anchor Link

Think of a short loop. Your code sends the messages and tool list. If the reply contains a tool call, your code runs it, adds the result and sends everything again. If the reply is plain text, the loop ends.

Trace for the question "Is order 8123 late, and what is the refund policy?" The model calls track_order. Your code returns "shipped, arrives Friday". The model calls get_policy. Your code returns the policy text. The model then writes the final answer. That is three model calls, and each one resends the earlier messages and results. More tools and longer results mean more tokens. Always set a maximum number of loop steps.

A second example: when a tool is not the answerCopy Anchor Link

A tool for adding two numbers is fine, since code is exact where the model can slip. A tool that returns the capital of France wastes a round trip, because the model already knows. Add a tool when the answer needs live data, private data or an action. Skip it when the model can answer alone.

Narrow versus broad toolsCopy Anchor Link

A broad tool such as run_sql(query) can answer many questions, but it can also delete a table. A narrow tool such as get_order(id) is limited by design. Prefer narrow tools for anything with side effects.

What goes wrongCopy Anchor Link

The model picks the wrong tool because two descriptions sound alike. Log every call during tests and count the wrong picks.

The arguments are slightly off, such as "#8123" instead of "8123". Validate and return an error that shows the expected format, so the model can correct itself.

The loop never ends because the model keeps calling tools. The step cap stops it.

A huge result floods the context. Return only what the model needs.

Try it yourselfCopy Anchor Link

Define two tools with nearly identical descriptions and ask five questions that need one or the other. Count wrong choices. Rewrite the descriptions to say when each applies, and rerun. Expect fewer wrong choices.

Common mistakeCopy Anchor Link

Letting the model's arguments flow straight into a database query or shell command. Always validate first.

Where this connectsCopy Anchor Link

Tool arguments come from a model that can be tricked by the text it reads. Read Prompt injection and the lethal trifecta before you connect a tool that can send, delete or spend, and see Tool errors and validation for how to check arguments.

The codeCopy Anchor Link

A tool is a name, a description and a JSON schema for its arguments. The model returns a tool request. Your code runs it and sends the result back.

tools = [{
    "name": "track_order",
    "description": "Look up the status of an order by its id. Use when the customer asks where an order is.",
    "input_schema": {
        "type": "object",
        "properties": {"order_id": {"type": "string", "description": "The order number, such as 8123"}},
        "required": ["order_id"],
    },
}]

messages = [{"role": "user", "content": "Where is order 8123?"}]
reply = client.messages.create(model="claude-sonnet-5-5", max_tokens=300, tools=tools, messages=messages)

if reply.stop_reason == "tool_use":
    call = next(b for b in reply.content if b.type == "tool_use")
    result = "shipped, arrives Friday"  # your real lookup goes here, using call.input["order_id"]
    messages += [
        {"role": "assistant", "content": reply.content},
        {"role": "user", "content": [{"type": "tool_result", "tool_use_id": call.id, "content": result}]},
    ]
    final = client.messages.create(model="claude-sonnet-5-5", max_tokens=300, tools=tools, messages=messages)
    print(final.content[0].text)