Tool use and function calling

A language model on its own can only produce text. It cannot check today’s stock level, read a file or run a test. Tool use, often called function calling, is the mechanism that lets a model reach beyond its own weights: it asks for an action in a structured way, your software carries it out, and the result comes back for the model to use. It is the “act” step in every agent loop, so it is worth understanding precisely.

The shape of a tool

You describe each tool to the model with three things:

• a name, such as get_order_status;
• a description in plain language: what it does, when to use it, what it returns;
• an input schema, usually JSON Schema, listing parameters, types and which are required.

A definition looks roughly like this (exact field names vary between providers):

{
  "name": "get_order_status",
  "description": "Look up the current status of a customer order. Use when the user asks where an order is. Returns status, carrier and estimated delivery date.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "Order number as shown on the receipt, e.g. A-10442"
      }
    },
    "required": ["order_id"]
  }
}

These definitions are placed into the model’s context alongside your prompt. That means they cost tokens on every request, and it means the description is effectively a prompt: the model decides when and how to call a tool almost entirely from what you wrote there.

The round trip

A single tool call follows the same cycle every time:

1. You send the conversation plus the tool definitions.
2. The model responds with a tool call instead of, or as well as, text: the tool name, arguments matching the schema, and an id.
3. Your application executes the tool: calls the database, the API, the function.
4. You send the result back, tagged with the matching id.
5. The model continues: it may call another tool, or give its answer.

{ "type": "tool_call", "id": "call_1", "name": "get_order_status", "input": { "order_id": "A-10442" } }

The most important point is step 3.

The model never executes anything. It only asks. Your code decides whether, and how, the request is carried out.

This is both a design fact and a security boundary. Everything between the model’s request and the real world passes through code you control, so that is where you validate arguments, check permissions, enforce limits, sandbox risky operations and ask a human before anything irreversible. Treat the model’s arguments as untrusted input: a misleading document or a malicious prompt can steer the model into requesting something harmful.

Why structured calls rather than asking the model to write “CALL search” in its prose? Modern models are trained, and provider APIs are built, to emit tool calls as schema-shaped data in a dedicated part of the response. That is far more reliable to parse. Early research such as Toolformer (Schick et al., 2023) explored how models could learn when to insert API calls; today that capability is a standard API feature.

Parallel tool calls

Models can often request several independent calls in one response, for example checking three orders at once. Your code can run them concurrently and return all the results, each matched to its call id, before calling the model again. This cuts round trips and latency. Only independent calls belong together; if one call depends on another’s output, the model should make them in sequence.

Designing tools agents can use

A model can only act as well as its tools allow. The SWE-agent paper (Yang et al., 2024) named this idea the agent-computer interface (ACI): just as people work better with good user interfaces, agents work much better with tools designed for them. Tailored commands for viewing, searching and editing code made a large difference to its results on software tasks.

Anthropic’s guidance on writing tools for agents points the same way. The recurring advice:

Choose fewer, task-shaped tools

More tools are not automatically better. Wrapping every API endpoint gives the model many overlapping options and forces long call chains. A tool that matches a real task, such as schedule_meeting instead of separate list-availability and create-event calls, is easier to pick and use. Consistent prefixes such as crm_search_contacts help when you do have many.

Write descriptions like onboarding notes

Say what the tool does, when to use it and when not to, what each parameter means with an example, and what the output looks like. Make the implicit explicit: the model does not know your company’s jargon.

Make inputs forgiving

Use unambiguous parameter names (user_id, not user), enums for fixed choices, clear formats, and absolute rather than relative paths. Where cheap, normalise small variations instead of failing.

Return meaningful, compact results

Give the model what it needs for its next decision: readable names rather than opaque ids, relevant fields rather than raw dumps. Paginate, filter or truncate large outputs with sensible defaults so a single call does not flood the context.

Make errors actionable

Errors go back to the model as observations. Compare:

• “Error 400”
• “start_date must be YYYY-MM-DD; received 03/01/2026”

The second lets the model fix its call immediately; the first invites repeated failures.

Test with the model

Watch transcripts of the model using your tools. Where it hesitates, misuses a parameter or picks the wrong tool, that is usually a description or interface problem you can fix, and small wording changes can produce noticeable improvements.

Putting it together

Function calling is a simple contract: the model proposes, your code disposes. Definitions tell the model what is possible, structured calls make its intentions machine-readable, and results close the loop. Get the mechanics right, keep execution behind your own checks, and spend real design effort on the tools themselves: in practice, that is where much of an agent’s quality comes from.