AI Agent Tools: How Function Calling Works

Step 1: Define tools with a name, description, and schema

Each tool has a name, a description that tells the model when to use it, and a JSON schema for its inputs. Descriptions matter a great deal: say what the tool does, when to use it, and any side effects. This course uses a small order-support agent as its example.

TOOLS = [
    {
        "name": "lookup_order",
        "description": "Look up an order by ID. Returns its status, total, and whether it was refunded.",
        "input_schema": {
            "type": "object",
            "properties": {
                "order_id": {"type": "string", "description": "The order ID, for example 1042"}
            },
            "required": ["order_id"],
        },
    },
    {
        "name": "issue_refund",
        "description": "Issue a full refund for a delivered order. This cannot be undone.",
        "input_schema": {
            "type": "object",
            "properties": {
                "order_id": {"type": "string", "description": "The order ID to refund"}
            },
            "required": ["order_id"],
        },
    },
]

Step 2: Let the model request a tool

Pass the tools with your request. If the model decides it needs one, the response has stop_reason set to tool_use and contains a tool_use block with an ID, the tool name, and the arguments it chose.

import anthropic

client = anthropic.Anthropic()
MODEL = "claude-opus-5-5"

response = client.messages.create(
    model=MODEL,
    max_tokens=16000,
    tools=TOOLS,
    messages=[{"role": "user", "content": "Where is order 1042?"}],
)

print(response.stop_reason)   # tool_use
for block in response.content:
    if block.type == "tool_use":
        print(block.id, block.name, block.input)

Step 3: Run the tool and return the result

Execute the requested function yourself, then send a new request containing the original messages, the assistant's reply with its tool_use block, and a user message with a tool_result that carries the same tool_use_id. Always append the assistant's content exactly as received.

messages = [
    {"role": "user", "content": "Where is order 1042?"},
    {"role": "assistant", "content": response.content},
    {
        "role": "user",
        "content": [{
            "type": "tool_result",
            "tool_use_id": block.id,
            "content": lookup_order(block.input["order_id"]),
        }],
    },
]

followup = client.messages.create(
    model=MODEL, max_tokens=16000, tools=TOOLS, messages=messages
)

Step 4: Report errors instead of hiding them

If a tool fails, return the error text with is_error set to true. The model can then correct its arguments, try something else, or explain the problem to the user, which is far better than silent failure.

{
    "type": "tool_result",
    "tool_use_id": block.id,
    "content": "Error: order 9999 not found. Check the ID and try again.",
    "is_error": True,
}

Step 5: Design tools well

Give tools clear single purposes, descriptive names, and precise parameter descriptions. Return concise, useful results rather than huge dumps. Where available, mark tool schemas strict so arguments always match the schema, and note that the newest models do not allow forcing a specific tool call, so steer with instructions instead.