What is tool calling for AI agents?

You have called a chat endpoint. You send messages, you get text back. Then someone tells you their agent files tickets and runs the test suite, and the obvious question is: how? The model produces tokens. Tokens do not run a test suite.

Tool calling is the answer, and the mechanics are less magical than the vocabulary around them. Here is what goes over the wire, why the descriptions matter more than the model, and why the hard engineering is on the security side.

What actually crosses the wire

Alongside your messages you send a list of tool definitions. Each one is three things: a name, a description in prose, and a JSON Schema for the parameters. No code is uploaded. The API never sees your function — it sees a contract.

tools = [
    {
        "name": "get_order_status",
        "description": (
            "Look up the current status of a customer order by its order ID. "
            "Use this whenever the user asks where an order is, whether it "
            "shipped, or when it will arrive. Do NOT use it to change an "
            "order or to look a customer up by email. Returns JSON with "
            "status, carrier, tracking_number and estimated_delivery (ISO "
            "8601 date), or an error string if the order does not exist."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "order_id": {
                    "type": "string",
                    "description": "Order ID like ORD-4821. Case sensitive.",
                },
            },
            "required": ["order_id"],
            "additionalProperties": False,
        },
    }
]

When the model decides a tool is the right move, it produces a structured block instead of prose. In the Anthropic Messages API that block has type tool_use and carries an id, the tool name, and an input object shaped like your schema; stop_reason comes back as tool_use rather than end_turn. Other providers name the fields differently.

Here is the part people skip past. The model does not execute anything. It emits a request. Your process reads that block, dispatches to your function, and gets a value. Every side effect — the row updated, the refund issued, the shell command run — is your code's doing. The entire security surface of an agent lives in your executor, not in the model.

You then send the whole conversation back, with the result attached as a tool_result block matched to the tool_use by id, in a user-role message. The model reads it and either answers or asks for another tool. That is the entire mechanism.

The schema and the description are the prompt

The description and the schema are the only things the model knows about your tool. It has never seen the implementation or the ticket explaining why the parameter is called since_ts. If tool choice is bad, look there first: it is the cause far more often than the model is. The classic failure is two tools called search_docs and search_web, both described as "search for information". The model picks by coin flip and you conclude it is bad at tool use. You gave it two identical contracts. Write descriptions like onboarding notes for someone competent who has never seen your system.

• When to reach for it instead of a sibling tool.
• Units and formats: seconds or milliseconds, UTC or local, inclusive or exclusive.
• What it returns on success, and how it fails.

In the schema, enums beat free-form strings and additionalProperties false stops the model inventing fields. If you have forty tools, the problem is surface area, not wording.

The loop, and the four places it goes wrong

An agent is that round trip in a while loop. Nothing more. Here it is with no framework — worth writing once by hand even if you never ship it, because every framework wraps exactly this.

import json
import anthropic

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Where is order ORD-4821?"}]

for _ in range(12):  # hard cap: never loop forever
    resp = client.messages.create(
        model="claude-opus-5",
        max_tokens=16000,
        tools=tools,
        messages=messages,
    )
    if resp.stop_reason != "tool_use":
        break

    messages.append({"role": "assistant", "content": resp.content})

    results = []
    for block in resp.content:
        if block.type != "tool_use":
            continue
        try:
            out = dispatch(block.name, block.input)   # your code, your risk
            results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": json.dumps(out)[:20_000],  # cap the payload
            })
        except Exception as exc:
            # Return the failure AS A RESULT. Do not raise out of the loop.
            results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": f"error: {exc}",
                "is_error": True,
            })

    # All results from one assistant turn go back in ONE user message.
    messages.append({"role": "user", "content": results})

print(next(b.text for b in resp.content if b.type == "text"))

Four things break in production, all visible in that snippet. First, loops that do not terminate: a model retrying a tool that keeps failing will burn your budget, so cap the iterations and log it when you hit the cap. Second, tool errors. An exception escaping the loop kills the conversation; a tool_result with is_error set lets the model read the failure and try something sensible.

Third, parallel calls. One assistant turn can contain several tool_use blocks. Run them concurrently if you like, but return every result in a single user message — splitting them quietly teaches the model to stop calling tools in parallel. Fourth, token growth. Tool results are conversation history, so a 40,000-row CSV dumped into one result is re-sent and re-billed every turn after. Truncate, or write the output to a file and return the path.

MCP, in one honest paragraph

The Model Context Protocol is a standard interface for exposing tools, so one server works across many clients instead of every application writing its own adapter for every integration. A server declares its tools; a client discovers them and hands them to a model; the client still runs the loop above. That is genuinely useful, and it is why an integration written once shows up in several agent products. It is not a different execution model. Something still executes the call, and the security questions do not change — they move. The process executing might now be a server you did not write.

The security part, which is the real reason this matters

Sooner or later someone adds a run_code or run_bash tool, because it is the most useful tool you can give a model — one tool replaces fifty. It is also the most dangerous, because its schema is "a string" and its capability is "whatever the machine can do".

Prompt injection makes this concrete. Your agent reads things: a web page, a PR description, a support email, the output of a previous tool. That text lands in the same context window that decides which tool to call next, and there is no privileged channel marking some tokens as data and others as instructions. An issue comment telling the agent to run a helpful setup script from a URL is indistinguishable from you asking for it.

The defence is not a better system prompt. Prompt-level mitigations reduce the rate; they do not change what happens when one gets through. The defence is the boundary the tool runs behind, chosen so a successful injection is contained rather than catastrophic.

• Isolation: the code runs somewhere that is not your agent's process, ideally not sharing a kernel with it.
• No ambient credentials: no instance metadata endpoint, no ~/.aws, no environment full of API keys. Pass one scoped token, or nothing.
• Scoped egress: an allowlist of hosts the task needs, not the open internet by default.
• Resource and wall-clock limits, so a runaway loop costs a bounded amount.
• Disposability: one environment per session, destroyed afterwards.

Giving an agent a code execution tool means giving it a machine

That framing decides the design: what kind of machine, and how cheaply can you throw it away? If a fresh environment takes thirty seconds to start, you will reuse one across users, and reuse is where state leaks.

That is the part PandaStack builds. A sandbox is a Firecracker microVM with its own kernel and KVM hardware isolation — not a container sharing yours, not a V8 isolate. Snapshot-restore puts create at 179ms p50 and 203ms p99, so a sandbox per session is a default rather than an optimisation you defer. Because it is a real VM you get root, apt, several processes at once, and arbitrary ports. Fork and snapshot are copy-on-write: branch a prepared environment for a speculative step, or reset after a bad run.

# pip install pandastack anthropic
from pandastack import Sandbox

_sessions = {}

def _ctx(session_id: str):
    """One sandbox per conversation, not one per process."""
    if session_id not in _sessions:
        sb = Sandbox.create(template="code-interpreter", ttl_seconds=1800)
        _sessions[session_id] = (sb, sb.create_code_context())
    return _sessions[session_id][1]

RUN_CODE = {
    "name": "run_code",
    "description": (
        "Run Python in an isolated Linux sandbox and return stdout, stderr "
        "and any error. Variables and imports persist between calls in the "
        "same conversation, so build work up step by step. Use print(...) "
        "for anything you want to see. The sandbox has no access to "
        "production systems or credentials."
    ),
    "input_schema": {
        "type": "object",
        "properties": {"code": {"type": "string"}},
        "required": ["code"],
        "additionalProperties": False,
    },
}

def run_code(session_id: str, code: str) -> dict:
    ex = _ctx(session_id).run_code(code)
    return {
        "stdout": ex.stdout[-8000:],
        "stderr": ex.stderr[-2000:],
        "error": ex.error,
    }

def close(session_id: str):
    sb, _ = _sessions.pop(session_id, (None, None))
    if sb:
        sb.delete()   # the boundary only helps if you actually destroy it

Firecracker is not the only reasonable shape. Hardened container runtimes are lighter if a shared kernel is acceptable, and WebAssembly fits pure computation with no filesystem or network. We picked microVMs because agents want a whole Linux userland behind a hardware boundary.

What to build first

1. Write the loop by hand once, with two narrow tools and no framework.
2. Spend real effort on the descriptions. They are cheaper to fix than a model swap.
3. Cap the iterations, return errors as results, log every call with its inputs and duration.
4. Treat every tool result as untrusted input, especially anything that touched the internet.
5. Put code execution behind a real boundary before the first demo. Retrofitting isolation is a rewrite.

The model asks. Your code answers. Everything that can go wrong lives on the answering side, which is also the only side you control.