Tool Use & Function Calling

A model cannot query your database, send an email or check today's price. It generates text.

Tool calling bridges that: you describe functions the model may use, and instead of answering it can emit a structured request to call one. Your code executes it and returns the result, which the model then reasons over.

This is the mechanism behind every agent, and most of its reliability comes from decisions you make about the tool interface — not from the model.

The mechanics

You supply tool definitions with the request:

{
  "name": "get_order_status",
  "description": "Look up the current status of a customer order by its ID.",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string", "description": "Order ID, e.g. ord_8842" }
    },
    "required": ["order_id"]
  }
}

The model responds either with text, or with a call: get_order_status({ order_id: "ord_8842" }). Your code executes it — the model never runs anything — and you send the result back for the model to continue.

The critical point: a tool call is a request, not an instruction you must obey. It arrives as untrusted input and deserves the same treatment as a request from a browser.

The description is the interface

The single highest-leverage thing in this lesson.

The model chooses tools based almost entirely on their names and descriptions. A vague description produces wrong tool choices, and no amount of system-prompt instruction compensates.

// Poor — when would a model use this?
{ "name": "process", "description": "Processes data" }

// Good — states purpose, scope and boundaries
{
  "name": "search_orders",
  "description": "Search a customer's past orders by date range or status. Returns at most 20 orders, newest first. Use for questions about order history. Does NOT modify orders — use update_order for that."
}

Three things good descriptions do: say when to use it, state what it returns, and name what it does not do. That last one prevents a large share of misuse.

Parameter descriptions matter equally. "date" invites a dozen formats; "Start date in ISO 8601 format, e.g. 2026-07-27" gets one.

Designing the tool set

Few, well-chosen tools beat many. Selection accuracy degrades as the set grows, and every definition consumes context on every request. Six good tools outperform thirty overlapping ones.

Avoid overlap. If two tools could plausibly serve the same request, the model will sometimes pick the wrong one. Merge them or sharpen the boundary.

Match the task, not your API surface. Do not expose twelve CRUD endpoints and hope the model composes them. Expose reschedule_appointment, which internally does the reads and writes. Coarse, task-shaped tools produce far more reliable behaviour than fine-grained ones — fewer steps, fewer chances to compound errors.

Return what the model needs, and no more. A tool returning a 200-field object floods the context. Return the handful of fields relevant to the decision.

Validation is not optional

The model produces arguments by generating text. They can be malformed, out of range, or entirely invented — a plausible-looking order_id for an order that never existed.

Validate every call as untrusted input, exactly as in the DTO lesson:

const schema = z.object({
  order_id: z.string().regex(/^ord_[a-z0-9]{4,}$/),
  limit: z.number().int().min(1).max(20).default(10),
});

const parsed = schema.safeParse(args);
if (!parsed.success) {
  return { error: "invalid_arguments", detail: parsed.error.issues };
}

Authorisation belongs here too. The tool must check that this user may access this order — the object-level authorisation from the security lesson. A model asked to only fetch the current user's orders is not an access control.

Errors are messages, not exceptions

When a tool fails, the model reads the result and decides what to do. So error text is a prompt, and its wording changes behaviour.

// Unhelpful — the model cannot act on this
{ "error": "Error 500" }

// Actionable — the model can correct itself
{ "error": "order_not_found",
  "message": "No order with ID ord_9999. Order IDs start with 'ord_' followed by digits. Use search_orders to find a valid ID." }

The second recovers; the first loops or hallucinates.

Distinguish the two kinds of failure. Retryable — a timeout or rate limit — should say so, and your code should apply backoff rather than letting the model retry in a tight loop. Terminal — invalid input, not found, forbidden — should say clearly that retrying will not help, or the model will try the same call repeatedly.

Side effects and idempotency

The dangerous category. A tool that only reads is recoverable; a tool that acts is not.

Every write tool needs an idempotency key, generated per logical action and passed through. Models retry, frameworks retry, and users resubmit — the reasoning from the API design lesson applies directly, and here the caller is less predictable than any client you have designed for.

Confirm before consequential actions. Return a proposed action for approval rather than performing it, for anything irreversible or externally visible.

Enforce limits in the tool. Refund caps, rate limits and permission checks live in code. Nothing in a prompt is a control.

Parallel calls and ordering

Models can request several tools at once. Where the calls are independent, executing them in parallel is a substantial latency win — three sequential lookups become one round.

But only parallelise reads, or writes you have proven independent. Two writes touching the same record concurrently is the race from the concurrency lesson, now initiated by a model that has no concept of transactions.

Testing

Tools are ordinary code and should be tested as such — but you also need to test selection: given a realistic request, does the model choose the right tool with the right arguments?

Build a small labelled set of requests mapped to expected tool calls, and run it whenever you change a description, add a tool, or change model. Tool selection is remarkably sensitive to all three, and this suite catches regressions that end-to-end testing hides.

Check your understanding

Common mistakes

Vague descriptions. The most common cause of wrong tool choice, and the cheapest to fix.

Exposing raw CRUD. Task-shaped tools produce far more reliable behaviour than primitives the model must compose.

Trusting arguments. They are generated text. Validate and authorise.

Returning entire objects. Floods context and buries the useful field.

Opaque errors. The model reads them; they should tell it what to do.

No idempotency on writes. Retries duplicate side effects.

Parallelising writes. Concurrent conflicting actions with no coordination.

Not testing tool selection. Small description changes silently alter behaviour.

Practice

Key takeaways

• The model requests a call; your code executes it. Treat every call as untrusted input.
• Descriptions are the interface — state when to use the tool, what it returns, and what it does not do.
• Few, task-shaped tools beat many fine-grained ones: better selection, fewer steps, less compounding error.
• Validate and authorise inside the tool, including object-level permission checks.
• Error messages are prompts — make them actionable, and distinguish retryable from terminal.
• Write tools need idempotency keys, confirmation for consequential actions, and limits enforced in code.
• Parallelise reads only; concurrent writes reintroduce races with no coordination.
• Test tool selection with a labelled set — it is sensitive to descriptions, tool count and model version.

Further reading

• Timo Schick et al., "Toolformer: Language Models Can Teach Themselves to Use Tools" (NeurIPS 2023).
• Shunyu Yao et al., "ReAct: Synergizing Reasoning and Acting in Language Models" (ICLR 2023).
• Anthropic, "Building effective agents" (2024) — tool design as the main lever.
• Pat Helland, "Idempotence Is Not a Medical Condition" (ACM Queue, 2012) — why retried tool calls need keys.
• OWASP, Top 10 for Large Language Model Applications (2023) — excessive agency and insecure output handling.