Sign in Get started

AI Engineering Tutorial · Tools and Agents · Lesson 12 of 25

Tool Calling

Let the model ask your code to run functions (look up an order, search docs) and use the results in its answer.

Create a free account to save this page, take notes and track your progress. Sign in

How tool calling works

  1. You describe tools to the model: name, description and a JSON schema for the inputs.
  2. The model replies with a tool call (stop_reason: tool_use) naming a tool and its arguments.
  3. Your code runs the function and sends the result back as a tool result.
  4. The model uses the result to answer, or calls another tool.

The model never runs code itself; your application decides what actually happens.

tools = [{
    "name": "get_order_status",
    "description": "Get the shipping status of an order by its 5-digit order number.",
    "input_schema": {"type": "object", "properties": {"order_id": {"type": "string", "pattern": "^[0-9]{5}$"}},
                     "required": ["order_id"]},
}]
Run the tool the model asked for and build the tool resultTry it yourself
ORDERS = {"10042": "shipped, arrives Friday", "10043": "processing"}

def get_order_status(order_id):
    return ORDERS.get(order_id, "no such order")

# what the model sends back when it wants a tool (stubbed)
model_reply = {"stop_reason": "tool_use",
               "content": [{"type": "tool_use", "id": "toolu_1", "name": "get_order_status", "input": {"order_id": "10042"}}]}
results = []
for block in model_reply["content"]:
    if block["type"] == "tool_use":
        output = {"get_order_status": get_order_status}[block["name"]](**block["input"])
        results.append({"type": "tool_result", "tool_use_id": block["id"], "content": output})
print(results)

Output

[{'type': 'tool_result', 'tool_use_id': 'toolu_1', 'content': 'shipped, arrives Friday'}]

See Tool use overview.

Test yourself

Who executes the function when a model 'calls a tool'?

  1. The model provider's servers
  2. Your application code
  3. The user's browser automatically
  4. Nobody; it is simulated
Show answer

Answer: Your application code

The model only requests the call; your code runs it and returns the result.

Was this page helpful?