Tools

Overview

A model that can only produce text is limited to what it memorised during training. It cannot read your database, check today's price, or send anything.

Tool calling is the fix, and it works in a way people usually get backwards: the model never executes anything. It emits a name and some arguments, your code validates and runs them, and the result goes back into the conversation. This lesson is that round trip — plus why validating those arguments is a security boundary and not a formality.

Theory

The round trip. The model emits a tool name and JSON arguments. It cannot execute anything. Your code validates the arguments, runs the function, and returns the result as a tool message the model reads on its next turn. The model is asking, not doing — that distinction is the whole security model.

Tool definitions are JSON Schema. Name, description, and typed parameters. The description is read by the model, so it is a prompt: "the user's account id, a UUID" gets used correctly far more often than "id".

Validating arguments is a security boundary, not a formality. The model is an untrusted input source — it can hallucinate an id, a path, or a row that belongs to someone else. Parse against a schema and check the caller is allowed to touch that resource. A tool that trusts its arguments is an API with authentication removed.

Make tools idempotent where you can. Models retry, chain, and sometimes call the same thing twice from slightly different reasoning. If a repeat call is harmless, that is a non-event instead of a duplicate charge.

Return errors as results, not exceptions. A tool that throws ends the loop. A tool that returns { error: "no user with that id" } lets the model read it and try something sensible — which is usually what you wanted.

Visual Diagram

Draw it as a loop between two boxes. The left box is the model: it receives tool definitions plus conversation history, and emits either a text response or a tool-call request (name + arguments as text). The right box is your application: it receives that request, runs the arguments through schema validation, then through business-rule validation, then — only if both pass — executes the actual side effect. The result (success data, or a structured error) flows back into the left box's next input as a new message. The loop repeats until the model produces a final text response with no further tool call.

Code

A refund tool with schema validation, a re-check of business rules the schema can't express, an idempotency key to survive retries safely, and structured errors returned to the model instead of thrown.

import { generateText, tool, stepCountIs } from "ai";
import { z } from "zod";
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";

const provider = createOpenAICompatible({
  name: "example-gateway",
  baseURL: "https://ai.gateway.lovable.dev/v1",
  headers: { "Lovable-API-Key": process.env.LOVABLE_API_KEY ?? "" },
});

// Stand-in for a real idempotency-key store (Redis, a database unique index).
const processedRefunds = new Set<string>();

const issueRefund = tool({
  description: "Issue a refund for a previously drafted, human-approved order.",
  // The schema is the contract the model must satisfy to be accepted at all —
  // it is NOT the security boundary. A schema-valid amountCents can still be
  // ten times the refund policy allows; that check has to happen below.
  inputSchema: z.object({
    orderId: z.string().min(1),
    amountCents: z.number().int().positive(),
    idempotencyKey: z.string().uuid(),
  }),
  execute: async ({ orderId, amountCents, idempotencyKey }) => {
    // Re-check business invariants the JSON Schema can't express. Every
    // field here already passed Zod — that only proves it's the right
    // *shape*, not that it's the right *value*.
    if (amountCents > 50_000) {
      return { error: `amountCents ${amountCents} exceeds the $500 refund cap` };
    }

    // Idempotency: a retried tool call (network blip, the model re-issuing
    // the same call) must not double-refund the customer.
    if (processedRefunds.has(idempotencyKey)) {
      return { status: "already_processed", idempotencyKey };
    }

    // Stand-in for a real payment-provider call. A failure here becomes
    // structured data returned to the model, not a thrown exception — the
    // model can then decide whether to retry, ask a clarifying question, or
    // hand off to a human, instead of the whole request just dying.
    if (!orderId.startsWith("ord_")) {
      return { error: `unknown order ID format: ${orderId}` };
    }

    processedRefunds.add(idempotencyKey);
    return { status: "refunded", orderId, amountCents };
  },
});

export async function handleRefundRequest(userMessage: string) {
  const { text } = await generateText({
    model: provider("gpt-4o-mini"),
    system: "Issue refunds only for orders a human reviewer has already approved.",
    prompt: userMessage,
    tools: { issueRefund },
    stopWhen: stepCountIs(4),
  });
  return text;
}

Notice the two separate validation passes: Zod's inputSchema runs automatically before execute is even called, rejecting anything the wrong shape — but the amountCents > 50_000 check inside execute runs after that, because "positive integer" and "within refund policy" are different questions. The idempotencyKey check runs before the side effect, not after, so a retried call is safe. And every failure path returns a plain object the model can read, instead of throwing.

Real Product Example

Claude Code — the coding agent this lesson's content was itself built with tooling from — is a concrete, observable example of tool-call validation as a security boundary. It exposes tools like file read/write and shell execution to the model as JSON-schema functions, the same mechanism described in this lesson. Before a potentially destructive tool call executes — a shell command, a file write outside the working directory — it runs through a permission layer that checks the specific arguments the model produced against configured rules, and can require explicit human confirmation before proceeding. A shell command the model requests isn't trusted because it came from a well-behaved model; it's checked against an allow/deny policy the same way this lesson's refund example re-checks amountCents against a policy the schema can't express. When a tool fails — a file doesn't exist, a command exits non-zero — the error text is returned to the model as a tool result, not thrown as an exception that would kill the whole turn, letting the model see what happened and adjust its next action, exactly the error-surfacing pattern described above.

Common Mistakes

Senior Tips

Exercises

Mini Project

Validation boundary review. Take one tool from any project you've built earlier in this path — or write a new small one if you don't have one handy — and retrofit it with the two-layer validation from this lesson.

1. Write down every argument the tool accepts and, for each, one business rule that a type-level schema cannot express (a range, an ownership check, a rate limit).
2. Add those checks inside execute, after schema validation, each returning a structured error object rather than throwing.
3. Add an idempotency key parameter if the tool has any side effect, and a check that rejects a repeated key without repeating the side effect.
4. Write a short test (or a manual trace, if you don't have a test harness yet) that calls the tool twice with the same idempotency key and confirms the side effect only happened once.

Resources

• Vercel AI SDK — Tool Calling: the tool() API, input schemas, multi-step tool-calling loops, and error handling used throughout this lesson's code.
• Anthropic — Tool Use Overview: the full round trip for defining tools, handling tool calls, and the pricing implications of tool definitions taking up input tokens on every call.