Tool use and function calling

Tools are the agent's hands

A tool is a function your code can run, described to the model as a name, a natural-language description and a JSON Schema for its inputs. When the model decides a tool would help, it does not call anything — it emits a structured tool-call block: the tool's name and a JSON object of arguments that conforms to the schema. Your harness validates the arguments, runs the function, and sends the output back as a tool-result message. The model then continues with that result in its context, and may call more tools or answer. This is function calling (OpenAI's term) or tool use (Anthropic's); both APIs implement the same shape:

Models are trained to produce these blocks reliably, which is what the 2023 free-text agents lacked (10.1 What is an agent? Loops, autonomy and workflows vs agents). Structured outputs (9.6 Generation side: context assembly, citations, structured outputs and tool calling) are the same machinery used to force a final answer into a schema.

The schema is a prompt

The model chooses tools by reading their descriptions, so the description is prompt engineering (8.4 Prompting as programming). Anthropic's Writing effective tools for agents (September 2025) distills what works:

• Fewer, better tools. Consolidate: one search_customers with filters beats five near-duplicates. Each tool competes for the model's attention.
• Describe when to use and when not to, units and formats, defaults and examples. Name parameters unambiguously (user_id not id). Use enum and required rather than prose rules.
• Namespace related tools (github_create_issue, github_list_prs) so the model can tell providers apart.
• Return meaningful, high-signal context, not raw dumps: resolve ids to names, include what the model will need next, and offer a response_format of "concise" vs "detailed".
• Be token-efficient: paginate, truncate with a note on how to get more, filter server-side.
• Evaluate tools with real tasks and iterate on descriptions — the post describes letting an agent rewrite tool descriptions based on transcripts of its own failures.

The loop in code

A complete minimal agent in Python with the Anthropic SDK shape (the OpenAI version differs only in field names):

import json
import anthropic

client = anthropic.Anthropic()
MODEL = "claude-sonnet-5-5"   # use the current model id from the docs

TOOLS = [{
    "name": "get_weather",
    "description": "Current weather for a city. Use for any question about present conditions; "
                   "do NOT use for forecasts or historical data.",
    "input_schema": {
        "type": "object",
        "properties": {
            "city": {"type": "string", "description": "City name, e.g. 'Paris'"},
            "units": {"type": "string", "enum": ["celsius", "fahrenheit"], "default": "celsius"}
        },
        "required": ["city"]
    }
}]

def get_weather(city: str, units: str = "celsius") -> str:
    # In real life: call an API. Return compact, model-friendly text or JSON.
    return json.dumps({"city": city, "temperature": 21, "units": units, "sky": "clear"})

HANDLERS = {"get_weather": get_weather}

def run_agent(task: str, max_steps: int = 10) -> str:
    messages = [{"role": "user", "content": task}]
    for step in range(max_steps):
        resp = client.messages.create(
            model=MODEL, max_tokens=1024, tools=TOOLS,
            system="You are a careful assistant. Use tools when they help; otherwise answer directly.",
            messages=messages,
        )
        messages.append({"role": "assistant", "content": resp.content})
        if resp.stop_reason != "tool_use":                      # model is done
            return "".join(b.text for b in resp.content if b.type == "text")
        results = []
        for block in resp.content:                              # may contain several tool_use blocks
            if block.type != "tool_use":
                continue
            try:
                output = HANDLERS[block.name](**block.input)
                results.append({"type": "tool_result", "tool_use_id": block.id, "content": output})
            except Exception as exc:                            # send errors back, don't crash
                results.append({"type": "tool_result", "tool_use_id": block.id,
                                "content": f"Error: {type(exc).__name__}: {exc}", "is_error": True})
        messages.append({"role": "user", "content": results})
    return "Stopped: step budget exhausted."

print(run_agent("Is it warm in Lisbon right now?"))

Read the transcript it produces: user → assistant (tool_use) → user (tool_result) → assistant (text). Every agent framework you will meet is this loop with more bookkeeping.

Parallel calls, errors, budgets

• Parallel tool calls. A single assistant turn may contain several tool-call blocks (e.g. three searches). Execute them concurrently and return one result per id, in any order; a missing result breaks the conversation.
• Errors are information. Return failures as tool results (flagged as errors) so the model can retry with different arguments or choose another route. Make the error text actionable ("city not found; try the English name").
• Budgets and loop detection. Cap steps, wall-clock time and tokens; detect repeated identical calls; make tools idempotent where you can, because the model may retry.
• Validate before executing. Schema-check arguments; never pass model output to a shell unsanitized; check permissions per tool (10.10 Agent safety and security).

Code execution: the universal tool

Give the model a sandboxed interpreter and it can compose arbitrary logic — loops over data, math, parsing — in one step instead of twenty tool calls. Two 2025 refinements make this central:

• Tools as code APIs. Anthropic's Code execution with MCP (November 2025) presents MCP servers as importable functions in a filesystem; the agent writes code that calls several tools and only the final result enters the context. In their example this cut token usage by more than 98%, because intermediate data stays in the sandbox instead of round-tripping through the model.
• Tool search and programmatic tool calling (advanced tool use, November 2025): with hundreds of tools, load definitions on demand instead of stuffing them all into the prompt, and let the model orchestrate tool calls from code.

Intuition. Every tool result you send back is paid for twice: once as output of the tool and again as input on every later step. Doing work inside a tool (or a sandbox) rather than through the model is the biggest lever on agent cost.

Computer use as a tool interface

Computer use reduces a GUI to a tiny tool set: screenshot, click(x, y), type(text), key(name), scroll. It is universal — any software a human can use — but slow (one screenshot per action), expensive (images are many tokens) and exposed to whatever text appears on screen (10.10 Agent safety and security). Prefer an API or a DOM/accessibility-tree tool when one exists; reserve pixels for the long tail (10.8 Coding agents and computer use).

Where this shows up later

• The ReAct trace in 10.3 Reasoning and planning for agents is this loop with explicit reasoning between calls; the context you send each step is engineered in 10.4 Memory and context engineering.
• MCP (10.7 MCP and interoperability (plus Agent Skills and A2A)) standardizes how tool definitions and results cross process and network boundaries.
• Tool results are the main channel for prompt injection — the security model of 10.10 Agent safety and security starts here; production concerns (timeouts, idempotency, tracing) continue in 10.11 Building production agents.