Tool calling
The model asks, your code acts
A model can only produce text. Tool calling lets it ask your code to do something on its behalf, such as look up an order or search documents.
The model never runs the tool itself. It returns a structured request, your code decides whether to run it, and the result goes back to the model.
1. Describe the tool
Each tool has a name, a short description, and an input schema. The description works like a prompt: it tells the model when the tool is useful and when it is not.
2. Follow one request
- Model requests a tool
get_order_status(order_id=4512) - Your code checks and runs itCan this user see order 4512?
- The result goes back
{"status": "shipped", "eta": "Friday"} - Model writes the answer“It has shipped and should arrive Friday.”
3. Treat arguments as untrusted input
Tool arguments are structured output, so validate them like any other: types, ranges, and allowed values.
Then check permissions in code. The model may ask for an order that belongs to someone else, and the prompt cannot be the only thing that stops it.
4. Separate reading from acting
Looking something up is low risk. Sending an email, issuing a refund, or deleting data is not. Ask for confirmation before tools that change something.
5. Return useful results and errors
Keep results short and relevant. If a tool fails, return a clear error the model can act on, such as “order not found”, instead of an empty response.
When is it useful?
When the answer depends on information the model does not have, or when the task needs an action in another system. If the model can answer from the prompt alone, you do not need a tool.