Tools and function calling: how a model gets things done

A model on its own can only write text. It can't read your files, query a database or send an email. Tools change that, and they're the foundation of every agent, MCP server and AI feature that does real work. The trick is simple once you see who does what.

1. The idea

Tool use, also called function calling, works in four steps:

1. You describe the tools. Each has a name, a description (what it does and when to use it), and an input schema: the arguments it takes, written as JSON Schema.
2. The model decides to call one. Instead of answering in prose, it replies with a structured request: the tool's name and the arguments, as JSON. That's the order ticket.
3. Your code runs it. The model never executes anything. Your program calls the real function, API or database, with all the usual checks.
4. You send the result back, and the model continues: it answers, or asks for another tool.

Some tools run on the vendor's side instead (server tools such as web search or code execution): you switch them on, and the vendor runs them for you. Either way, the model only ever asks; something else does.

2. How it works

Step through a real exchange with an order-status tool. The JSON uses the Claude API's field names; the other APIs use the same shape with different names (see the table below).

All three can request several tools at once (parallel calls), let you force or forbid tool use (tool_choice or its equivalent), and offer a strict mode that guarantees the arguments match your schema.

3. Try it yourself: be the model

You're the model. The app gave you these four tools; for each request, choose what to do. Getting this right is exactly what the description text in a tool definition is for.

4. Why it matters at work

Whether you write tools for a product, build an MCP server (Module 16), or just choose which ones to connect, the same rules apply. Anthropic's engineers reported spending more time on their tools than on their prompts when building their coding agent.

1. Write descriptions for the model. Say what the tool does, when to use it, and when not to: "Look up an order by its number. Use when the customer gives an order number; don't use for refunds."
2. Few, sharp tools beat many vague ones. Every definition is sent with every request (it costs tokens) and every extra tool is another chance to pick the wrong one.
3. Return small, structured results. Ten relevant rows, not the whole table. Paginate. Include a hint if the result is cut off.
4. Return useful errors. "No order 4821; order numbers have 5 digits" lets the model recover; a stack trace doesn't.
5. Enforce permissions in your code, never in the prompt. Check that this user may see this order inside the tool. The model can be talked into anything (Module 18).
6. Mark irreversible tools and confirm them. "Creates a refund. Irreversible." Have your app ask a human before running it.
7. Treat tool results as untrusted data. A web page or document a tool returns may contain text that tries to give the model new instructions. That's prompt injection, and it's why the rules above matter.

5. In your five tools

Coding agents are tool use in action: reading files, searching, editing and running commands are all tools. Every tool lets you see the calls and decide which ones need your approval. Checked October 2026.

6. Remember it

7. Common mistakes

8. Hands-on lab (30 minutes)

1. Read a trajectory. Give a coding agent a small task and open its detailed view (expand the tool calls; Ctrl+O in Antigravity CLI). List every tool it called and why.
2. Approvals. Open the permissions settings in two tools. Which tools run without asking, and which ask first? Would you change any?
3. Write a tool definition. For one real action in your product, write the name, the description (when to use it, when not to) and the input schema. Run it through the "be the model" test: would a newcomer pick it correctly?
4. Optional, with an API key: run the round trip yourself with the short example below, then add a second tool and ask a question that needs both.

import anthropic, json

client = anthropic.Anthropic()          # reads ANTHROPIC_API_KEY
tools = [{
    "name": "get_order",
    "description": "Look up one order by its 5-digit number. Use when the user gives an order number.",
    "input_schema": {"type": "object",
                     "properties": {"order_id": {"type": "string"}},
                     "required": ["order_id"]},
}]
messages = [{"role": "user", "content": "Where is order 48213?"}]
reply = client.messages.create(model="claude-sonnet-5-5", max_tokens=1024, tools=tools, messages=messages)

call = next(b for b in reply.content if b.type == "tool_use")         # the order ticket
result = {"status": "shipped", "eta": "2026-10-15"}                    # your code cooks (a real lookup goes here)
messages += [{"role": "assistant", "content": reply.content},
             {"role": "user", "content": [{"type": "tool_result", "tool_use_id": call.id,
                                           "content": json.dumps(result)}]}]
final = client.messages.create(model="claude-sonnet-5-5", max_tokens=1024, tools=tools, messages=messages)
print(final.content[0].text)                                           # "It shipped and should arrive on 15 October."

9. Self-check quiz

10. Go deeper