Agents from scratch (TypeScript) · Chapter 5 of 18

Tool errors

By the end of this chapter you can run any tool call without letting it crash your agent: a tool that does not exist, arguments that are not JSON, a function that throws, a booking system that says no. Each problem goes back to the model as a result it can read, and the model tells the customer or tries again. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: The loop
  • 4 tasks
  • TypeScript
  • In the all labs plan

The first 2 chapters of Agents from scratch (TypeScript) are free. This one comes with the all labs plan.

Why you need this

On Monday morning Meenakshi's test bot went quiet. A customer had asked to move a booking that starts this afternoon. GharFix said no, as its policy says, and the bot's loop turned that refusal into an exception:

Error: the slot starts within 4 hours: it cannot be rescheduled, only cancelled (policy 3.3)
    at unwrap (file:///workspace/chapters/05-tool-errors/fix-crash.ts:41:30)
    at runAgent (file:///workspace/chapters/05-tool-errors/fix-crash.ts:58:22)

The customer got nothing: no answer, no apology, not even the rule. And a refusal is the gentle case. A model writes tool calls the way it writes everything, by prediction, so a wrong key, a tool name that does not exist or arguments that are not quite JSON will happen in production, a few times in every thousand runs. Vikram's rule for the agent is the same as for any server: a bad request is answered, never allowed to crash the process. And the answer goes to the one reader who can do something with it: the model.

What you build: 4 tasks

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

  1. Task 1

    run-tool.ts: a tool runner that never throws

    Write and export runTool(name, argumentsJson) in run-tool.ts: name is the tool the model asked for, argumentsJson the JSON text it wrote. It runs GharFix's function of that name (FUNCTIONS from ../../shared/gharfix.ts) with the parsed arguments and returns the result as JSON text. The file does nothing else when imported.

    It must never throw. Each of these returns JSON text of an object with an error key holding a sentence: a name that is not a tool (the sentence names it; toString is not a tool either, though every object has one); arguments that are not valid JSON; JSON that is not an object (null, an array, a string); and anything thrown inside the function (include the error's message, or the thrown value itself when it is not an Error).

    A function's own error result, like get_quote's for a job that is not on the rate card, is a result like any other: return it unchanged. A wrong key such as service_name throws nothing in TypeScript: GharFix answers it with its own error, which goes back unchanged too.

    The check calls runTool with good calls, each of those problems, and with GharFix's get_booking replaced by one that throws.

  2. Task 2

    too-late.ts: an error the customer hears about

    Run this request through the loop with a system message (GharFix's booking assistant; it must say today is 2026-10-22), GharFix's TOOLS, and your runTool from ./run-tool.ts for every call, exactly:

    Please move my booking GF712358 to 2026-10-26 evening.

    GharFix refuses, because the slot starts within 4 hours. Send that error back like any other result and print the model's final answer. Then look the booking up with getBooking and print one line: its booking_id, date, slot and status, separated by spaces.

  3. Task 3

    confused.ts: wrong, then right

    Run Meenakshi's job J11 through the loop with the model lab-chat-confused, a system message like task 2's, GharFix's TOOLS and your runTool for every call, exactly:

    Book a carpenter in RT Nagar 27 Oct evening: a cupboard hinge came off. I am Deepa Shetty, phone 9992578190.

    The model's first call has a wrong key. Send the error back as that call's result; the model reads it and asks again. When it answers, print the answer, then Requests: and the number of requests the run took. Never send more than 10.

  4. Task 4 · interview question

    Interview: fix-crash.ts, find the crash

    fix-crash.ts's runAgent(question, model) books Meenakshi's plumber request, then crashes on a reschedule GharFix refuses. Fix it so that nothing a tool or the model does can crash it: every problem goes back to the model as a tool result with an error key.

    The check calls it with lab-chat and the plumber request, with lab-chat-confused and the same request (its first call has a wrong key), and with lab-chat and the reschedule GharFix refuses. Each time it must return the model's final answer.

    Keep the function's name and parameters, and the system message.

What you will learn

  • Every way a tool call can fail, and which ones are your loop's problem.
  • What TypeScript does with a wrong key (nothing), and why.
  • Errors as results: { error: '...' } in the tool message.
  • The model reads the error: it tells the customer, or retries.
  • Helpful errors: what to put in one so the next step can succeed.

More in The loop

Build "Tool errors" yourself

GharFix, a Bengaluru home-services company, needs an assistant that books, reschedules and refunds safely. You build it in TypeScript. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of Agents from scratch (TypeScript) are free. This one comes with the all labs plan.