The Vercel AI SDK · Chapter 3 of 21

Tools: Mali looks things up

By the end of this chapter you can give a model tools: functions of yours that it can ask to run when it needs real data. You will make tools with tool(), a description and a zod schema, see the JSON the SDK sends for them, read the calls the model asks for and the results your code sends back, and see why a tool's name and description decide whether it is ever used. You will build two tools, look things up with them, fix a search tool the model never picks, and put guesses and tool calls side by side. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: The SDK on the server
  • 4 tasks
  • TypeScript
  • In the all labs plan

The first 2 chapters of The Vercel AI SDK are free. This one comes with the all labs plan.

Why you need this

Deepa tried Mali on three questions her team gets every hour:

Is the Snake Plant in stock?   => Yes, the Snake Plant is in stock, at ₹299.
Where is my order HB-1043?     => Your order HB-1043 is on its way and should reach you today.
Do you deliver to 562157?      => Yes, we deliver to 562157, and your plants can reach you tomorrow.

All three are wrong. The Snake Plant is out of stock and costs ₹449. HB-1043 is delayed until Thursday. HariBhari does not deliver to Devanahalli (562157). And Mali said each one warmly, with full confidence, even though its instructions say "look them up with your tools, never guess".

That is what models do with a question about live data they cannot see: they write the answer that sounds most likely. Stock, orders and delivery areas change every day; they are in HariBhari's database, not in the model's training, and not in its instructions. Mali needs a way to ask for them. That way is tools.

What you build: 4 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    tools.ts: two tools for Mali

    Export const tools = { getOrder, checkDelivery } from tools.ts, each made with tool() (from 'ai') with a description, an inputSchema (a zod object) and an execute function:

    getOrder takes orderId (a string) and returns getOrder(orderId) from ../../shared/haribhari.ts.

    checkDelivery takes pincode (a string) and returns checkDelivery(pincode) from the same file.

    Give each tool a description of a sentence or more, and each input a .describe(). The Check runs each execute, and offers your tools to the lab model with an order question and a delivery question: the model must pick the right tool and fill its input.

  2. Task 2

    lookup.ts: Mali looks things up

    Export an async function lookUp(question) from lookup.ts. It calls generateText with lab('lab-chat'), instructions MALI_INSTRUCTIONS, tools (from ./tools.ts) and the question as the prompt, with the default one step, and returns:

    { calls: each of result.toolCalls as { tool: toolName, input }, results: the output of each of result.toolResults, text: result.text, finishReason: result.finishReason }

    Under if (import.meta.main), look up Where is my order HB-1044? and print each call as call: NAME INPUT_JSON, each result as result: JSON, then text: JSON and finish: REASON.

  3. Task 3

    search-tool.ts: a tool the model can find and fill

    search-tool.ts gives a tool named lookup, with no description and only one input, q. The model never picks it. Rewrite it so that tools is { searchPlants }: a description saying it searches HariBhari's catalogue for plants by light, pets and budget, and inputs query (a string), light (optional 'low', 'medium' or 'bright'), petSafe (optional boolean) and maxPrice (optional number, rupees), each with a .describe(). Its execute passes the inputs to searchPlants from ../../shared/haribhari.ts.

    The Check asks for pet-safe plants for low light under a budget: the model must pick searchPlants and fill light, petSafe and maxPrice.

  4. Task 4 · interview question

    Interview: guesses.ts, guesses or tools?

    Ask three questions twice each, with lab('lab-chat') and MALI_INSTRUCTIONS: first with no tools, then with tools from ./tools.ts (the default one step). The questions, in order: Where is my order HB-1042? then Do you deliver to 560100? then Where is my order HB-1046?

    For each, print:

    Q: QUESTION

    without tools: TEXT

    with tools: "TEXT", FINISH, called NAME INPUT_JSON

    where "TEXT" is JSON.stringify of the text, FINISH the finishReason, and several calls are joined with ", ".

    Deepa will ask: which of these two answers can she send to a customer?

What you will learn

  • What a tool is: a function the model can ask you to run, and how that round trip works.
  • tool(): a description, an inputSchema (zod) and an execute function.
  • What the model sees: the JSON schema the SDK makes from your zod schema.
  • toolCalls and toolResults: what the model asked for, and what your function returned.
  • Choosing a tool: why the name and description decide whether it is picked.
  • One step: why the text comes back empty, a cliffhanger for chapter 4.

More in The SDK on the server

Build "Tools: Mali looks things up" yourself

HariBhari, a Bengaluru plant shop, wants Mali, a plant helper on its website. You build it end to end, from the first call to a chat that streams cards, asks before it adds to the cart and stays within budget. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of The Vercel AI SDK are free. This one comes with the all labs plan.