Tool use

Steps 3 and 4: run it and send back the result

Use a dictionary to match each tool name to a Python function. Call the function with the block's input. Then reply with a tool_result block that quotes the same id:

FUNCTIONS = {"get_campaign": get_campaign}

result = FUNCTIONS[block["name"]](**block["input"])     # get_campaign(campaign_id="cmp_104")
messages.append({"role": "assistant", "content": response["content"]})   # the model's turn, unchanged
messages.append({"role": "user", "content": [
    {"type": "tool_result", "tool_use_id": block["id"], "content": json.dumps(result)},
]})

The **block["input"] part unpacks the input dictionary into named arguments. So {"campaign_id": "cmp_104"} becomes campaign_id="cmp_104".

The API enforces three rules:

• The model's turn goes back unchanged, including its text and tool_use blocks.
• Every tool_use needs a tool_result with the matching tool_use_id, in the very next user message. If the model asked for two tools at once, send both results in that one message.
• content must be text (or content blocks). Turn dictionaries into JSON text with json.dumps.

When a tool fails, don't crash and don't hide it. Send the error back with "is_error": True. The model will usually explain the problem or try something else:

{"type": "tool_result", "tool_use_id": block["id"], "is_error": True,
 "content": "Error: no campaign with id cmp_999"}

import json

def get_campaign(campaign_id):
    data = {"cmp_104": {"spend": 1200, "clicks": 3400, "conversions": 85}}
    return data[campaign_id]

FUNCTIONS = {"get_campaign": get_campaign}
block = {"type": "tool_use", "id": "toolu_01", "name": "get_campaign", "input": {"campaign_id": "cmp_104"}}
result = FUNCTIONS[block["name"]](**block["input"])
reply = {"type": "tool_result", "tool_use_id": block["id"], "content": json.dumps(result)}
print(reply["tool_use_id"])
print(reply["content"])

Controlling when tools are used

• tool_choice is {"type": "auto"} by default: the model decides. {"type": "none"} turns tools off for one request while keeping them defined.
• Current top models (including Claude Opus 5.5) reject forcing a specific tool with {"type": "any"} or {"type": "tool"}. Instead, say what you expect in the prompt ("Use the get_campaign tool to answer"). Then check that a call happened.
• Add "strict": True to a tool definition to guarantee its inputs match the schema exactly.
• If all you wanted was JSON back, you don't need a tool. Use structured output.

For marketers: good candidates for tools are the lookups you do by hand while writing. Checking a campaign's numbers, a product's stock, a customer's order status. Start with read-only tools. Tools that change things (send, publish, spend money) need extra care, and the next lessons cover it.

Mistakes that break a tool call

The model never runs anything. It's easy to read a tool_use block as something that already happened. It's a request. Until your code runs the function and sends the answer back, nothing has occurred. That's also your safety valve: your code can refuse.

Don't assume where the block is. The tool request isn't always content[0]. The model may write a sentence first, then ask for the tool. Look through the blocks for type == "tool_use".

Keep the assistant's turn exactly as it was. Your next request must include the assistant message containing the tool_use, unedited, followed by a user message with the matching tool_result. Drop it or change it, and the API rejects the request, because the result no longer answers anything.

Send errors back rather than crashing. If a tool fails, return the problem with is_error: true. The model reads it and can often recover, for example by fixing a mistyped id.

Describe when, not only what. "Gets campaign data" tells the model what the tool is. "Use this when the user asks about a specific campaign's spend or clicks, and you have its id" tells it when to reach for it, and that's what really changes its choices.