MCP servers and clients in TypeScript · Chapter 5 of 16

Tools in depth

By the end of this chapter you can design tools a model uses well: arguments described and constrained in the zod schema, structured results with an output schema, descriptions that make the model pick the right tool, failures the model can act on, annotations that say what a tool may change, and a server that understands the names people actually use. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

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

The first 2 chapters of MCP servers and clients in TypeScript are free. This one comes with the all labs plan.

Why you need this

Chapter 4's server works when the caller already knows that Vaishali Nagar is BB02 and Masoor Dal is P017. A model does not. Offer the lab model a stock_level tool and ask the way a manager would:

Raja Park mein cheeni kitni bachi hai?       -> stock_level {"store_id":"Raja Park","product_id":"Sugar"}
How much mustard oil is left at Amer?        -> stock_level {"store_id":"Amer","product_id":"Mustard Oil"}

The model did its best: it filled the arguments with what the message said. A server that expects BB05 finds no such store, returns 0 units, and the assistant tells Rajat that Raja Park has run out of sugar. Nothing crashed, and the answer is wrong.

A tool is an interface for a reader that cannot ask you what you meant. Simran wants every tool in the catalogue server to say exactly what it takes, refuse what it cannot use, return data code can rely on, and fail in words the model can act on. Nisha adds one more: every tool must say whether it changes anything.

What you build: 4 tasks

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

  1. Task 1

    catalogue.ts: a search with a schema that says everything

    In catalogue.ts, export createServer(), an McpServer (any name) over /workspace/data/bazaar.db, served with serveStdio(createServer) only inside if (import.meta.main). Register search_products, with three arguments: query, a required string with a description; category, optional, one of the 16 categories of the products table as a z.enum; limit, an integer from 1 to 50, 10 by default.

    Its structured content is { products: [...] }, each product { id, name, price, mrp, gst_rate }: the products whose name contains query, ignoring case, and that are in category when one is given, sorted by id, at most limit of them. Give it an outputSchema for that object, and the same JSON as text in content.

  2. Task 2

    catalogue.ts: reorder advice, and failures a model can act on

    Add reorder_suggestion(store_id, product_id), whose structured content is { store_id, product_id, units, reorder_level, cases, order_units } (units on the shelf), with an outputSchema.

    Policy rule 5.3: a product below its reorder level is ordered in enough whole cases (products.case_size) to bring the store back to three times the reorder level; otherwise cases is 0. order_units is cases times the case size. For example, 3 units with a reorder level of 12 and cases of 12 need 33 more, so 3 cases, 36 units.

    For an unknown store, an unknown product, or a product the store does not stock, return a failed result (isError true) with a message that names the id; for an unknown id, show what a good one looks like (like BB07 or P013). A crash's message does not count.

  3. Task 3

    catalogue.ts: names the way people say them

    Add find_store(name_or_id), whose structured content is { id, name, area, manager }. It matches a store id (bb33) or an area (TONK ROAD), ignoring case.

    For anything else, return a failed result, and when some areas come close, name them in the message: at least the areas that share a word with what was asked (Bani Prk shares Bani with Bani Park).

    Then annotate all three tools read-only, with annotations: { readOnlyHint: true }.

  4. Task 4 · interview question

    Interview: steer.ts, descriptions that steer the model

    steer.ts has two working tools, item_lookup and store_lookup, with vague descriptions, and the lab model picks the wrong one, or none, for Gopal's questions in ask-gopal.ts:

    How many units of P031 are left at BB09?

    What is the MRP of P031?

    Is Lal Mirch Powder in stock at the Raja Park store?

    Rewrite only the two descriptions until lab-chat picks the right tool for all three: store_lookup gives a store's units of a product, item_lookup a product's price, MRP and GST. Do not change the names, schemas or handlers. Run node ask-gopal.ts to see the model's choice.

What you will learn

  • Arguments with descriptions, defaults, z.enum choices and constraints, all in the schema.
  • Structured results with an outputSchema.
  • Descriptions that steer the model to the right tool.
  • Failures: a result you return with isError, versus an exception whose message goes out as it is.
  • Annotations (readOnlyHint) and resolving names on the server.

More in The protocol

Build "Tools in depth" yourself

Bazaar Bhai, a chain of 40 kirana stores in Jaipur, exposes its stock and orders once, to every AI tool. 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 MCP servers and clients in TypeScript are free. This one comes with the all labs plan.