Tools & function calling

Call→01Function calling — the model requests, the runtime acts

The mental model that makes everything else obvious: the model never executes anything. It has no hands. It is a next-token generator trained, on top of plain language modeling, to do one additional thing: when a request can be satisfied by an available tool, emit a special structured block naming the tool and its arguments. Then the model stops — the runtime parses the block, runs the function, and returns the output as a new message, after which the model continues.

A minimal example, in the format DeepSeek’s API and OpenAI’s API both use:

{
  "type": "function",
  "function": {
    "name": "get_quote",
    "arguments": "{\"symbol\": \"AAPL\"}"
  }
}

The arguments are themselves a JSON string — the outer call is structured, but the payload inside is still text the runtime must parse. This is exactly how Anthropic describes it: the model “returns a structured call that your application executes” — your application, not the model.

Result←02The tool-use loop — the unit of agency

An agent is not a model; an agent is a loop. One iteration:

Each pass through steps 1–4 is one tool round trip, and a task is usually several. Watch what that implies for the context window (101-02): every round trip appends the call and the result to the conversation. A ten-step task means ten more chunks of context — tool output is tokens, and tokens are budget.

Two properties make the loop an agent rather than a chat: conditionality (the model chooses, turn by turn, whether to call a tool at all) and feedback (the result is new information the model genuinely did not have). Without feedback, a tool call is theater; with it, the model’s next decision is grounded in the real world.

Call→03Schemas — the contract between model and machine

For the model to call a tool, it must know what the tool is called, what it does, and what arguments it takes. That is the schema:

{
  "name": "get_quote",
  "description": "Get a live stock quote for a ticker symbol",
  "parameters": {
    "type": "object",
    "properties": {
      "symbol": {"type": "string", "description": "Ticker, e.g. AAPL"}
    },
    "required": ["symbol"]
  }
}

Three parts, three lessons:

• The name is the handle the model emits. Names read like code (get_quote, not “fetch me the number for a stock please”) because the model must reproduce them exactly.
• The description is advertising copy. The model chooses tools by matching the request against descriptions — Anthropic: “Claude determines when to call a tool based on the user’s request and the tool’s description.” A vague description means the tool never gets called; an overpromising one means it gets called for the wrong jobs.
• The parameters are a JSON Schema — types, enums, required fields — which is what the runtime validates the call against before executing.

Result←04Why tools are what turn a chatbot into an agent

A model without tools is an oracle: it can answer, argue, and predict, but it cannot do — cannot read your files, run your commands, fetch today’s prices, or edit your code. Add tools, and two things change at once.

First, the model gains hands on the world. It can run terminal, edit a file, search the web, query a database. Anthropic’s tool-use GA announcement: “Tool use, which enables Claude to interact with external tools and APIs,” lets it “perform tasks, manipulate data, and provide more dynamic — and accurate — responses.”

Second — less obvious and just as important — tools are the model’s only source of fresh ground truth. Every fact the model “knows” from training can be stale or wrong (101-06’s whole subject). A tool result is new information, fetched at the moment of use: when Hermes answers “what is the current price of X,” it calls the FMP MCP tool and reads the result rather than trusting its weights. That is grounding in its purest form — the loop forces the model to argue from evidence it just obtained.

Call→05Parallel tool calls — one turn, many tools

The loop as described is serial: one call, one result, one decision. But modern models — OpenAI, Anthropic, DeepSeek’s API — can emit multiple tool calls in a single turn; the runtime executes them concurrently and returns the results in order. Three tickers, two files, two queries — one round trip instead of six.

The model structures its calls accordingly: independent work in parallel batches, dependent work in sequential turns. Runtimes keep it straight by feeding results back in call order, so the model always knows which answer belongs to which call.

Result←06Failure modes — where the contract breaks

Tool use fails in four characteristic ways, and recognizing them is most of debugging agents:

1. Malformed JSON. The model is a token predictor; occasionally it emits a call the parser cannot read — unclosed braces, truncated arguments, a stray markdown fence. Modern APIs mitigate with constrained decoding and structured outputs (the model can only emit valid JSON); runtimes retry or ask the model to fix itself. If you’re seeing parse errors, the model or the schema is the problem, not the parser.
2. Wrong arguments. The JSON is valid; the values are wrong — a hallucinated file path, a ticker that doesn’t exist, a required field omitted. Validation catches missing fields; nothing catches semantically wrong ones. read_file on a path the model invented is a wrong-arg failure, and the fix is usually “search for the file first” — more tool calls, not fewer.
3. Results too big. The worst failure, because it is silent. A terminal dump or a 10,000-line file read can blow the context budget and push the session toward compaction (101-02). Runtimes truncate — Hermes caps large reads at ~100K characters and returns a continuation offset; Anthropic’s programmatic tool calling keeps intermediate results out of context entirely. The lesson: tool output is context, and context is a budget.
4. Failing tools and loops. A tool can fail for reasons the model cannot see — network errors, permissions, timeouts. A well-built runtime feeds the error back (exit code, stderr) and lets the model adapt; a badly built one lets it retry the identical call forever. An agent thrashing on the same failing command is not the model being dumb — it is the loop missing a guardrail (retry caps, error feedback, denial rules) the runtime should provide.

Call→07Native function calling vs. “the model just writes code”

There are two fundamentally different ways to get a model to act, and knowing which one you’re looking at tells you how to trust it.

Native function calling is a trained capability: the model was fine-tuned on tool-call traces until emitting tool_calls is as natural as prose. The call is structured by construction — the API returns it as data, not text to parse — and validated against the schema before executing. Costs: you must declare every tool up front, schemas eat context, and the model can only do what you declared.

The model just writes code is the generalist path: give the model a shell (Bash in Claude Code, terminal in Hermes) and let it emit Python or shell as its “tool call.” Nothing to declare, nothing to validate — the model can do anything the sandbox can do. Costs: arbitrary code is arbitrary risk (sandboxing becomes mandatory, see 301-07), output is less predictable, and the model can burn tokens generating a loop you’d rather it had made in one structured call.

The pattern in real stacks is both, deliberately: structured calls for known, repeated, high-stakes operations (MCP tools, file edits, API calls — validated, auditable, cheap); code execution for novel, exploratory work (computing, transforming data, gluing things together).

Result←08Key takeaway

Call→09Go deeper

1. [1]

   Anthropic — “Tool use with Claude” (platform.claude.com)

   https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview

   The canonical definition (“Claude determines when to call a tool based on the user’s request and the tool’s description… returns a structured call that your application executes”), the full loop, and the tutorial to a production agentic loop.

2. [2]

   OpenAI — Function calling guide

   https://platform.openai.com/docs/guides/function-calling

   The tools parameter, JSON Schema definitions, parallel function calls, and structured outputs.

3. [3]

   MCP Specification — Tools (modelcontextprotocol.io)

   https://modelcontextprotocol.io/specification/2025-11-25/basic

   The name / description / inputSchema contract, JSON-RPC transport, and how tools are exposed and called across servers.

4. [4]

   Anthropic — “Introducing advanced tool use” (engineering post, free)

   https://www.anthropic.com/engineering/advanced-tool-use

   Tool Search (thousands of tools without consuming context) and programmatic tool calling (code-execution orchestration) — where this unit is heading.

• —

  DeepSeek API (api-docs.deepseek.com)

  https://api-docs.deepseek.com

  OpenAI/Anthropic-compatible API; tools/tool_calls in the OpenAI format on Mo’s own key, models deepseek-v4-flash / deepseek-v4-pro.

• —

  Hermes — developer guide

  https://hermes-agent.nousresearch.com/docs

  The tool system: native tools + MCP registration, approvals and deny rules, parallel calls, output truncation.

• —

  Claude Code docs (docs.claude.com)

  https://docs.claude.com/en/docs/claude-code

  Built-in tools (Bash, Read, Edit, Grep, Glob, WebFetch), MCP support, and permission modes.