MCP servers and clients · Chapter 5 of 16

Tools in depth

By the end of this chapter you can design tools a model uses well: parameters described and constrained in the schema, structured results with Pydantic models, descriptions that make the model pick the right tool, errors 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
  • Python
  • In the all labs plan

The first 2 chapters of MCP servers and clients 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. Ask the lab model, with a stock_level tool offered, 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.py: a search with a schema that says everything

    In catalogue.py, an MCPServer (any name) from /workspace/data/bazaar.db, write the tool search_products(query, category=None, limit=10). It returns a list of Product, a Pydantic model with the fields id, name, price, mrp and 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.

    In its schema, query is required and has a description; category is one of the 16 categories of the products table, or None by default; limit is an integer from 1 to 50, 10 by default.

    End the file with mcp.run() under the main guard.

  2. Task 2

    catalogue.py: reorder advice, and errors a model can act on

    Add reorder_suggestion(store_id, product_id), returning a Reorder model with store_id, product_id, units (on the shelf), reorder_level, cases and order_units.

    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, raise ToolError with a message that names the id; for an unknown id, show what a good one looks like (like BB07 or P013).

  3. Task 3

    catalogue.py: names the way people say them

    Add find_store(name_or_id), returning a Store model with id, name, area and manager. It matches a store id (bb33) or an area (TONK ROAD), ignoring case.

    For anything else, raise ToolError, and when some areas come close (Bani Prk), name them in the message.

    Then annotate all three tools read-only, with ToolAnnotations(read_only_hint=True).

  4. Task 4 · interview question

    Interview: steer.py, descriptions that steer the model

    steer.py 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.py:

    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, parameters or code. Run python3 ask_gopal.py to see the model's choice.

What you will learn

  • Parameters with descriptions, defaults, Literal choices and constraints, all in the schema.
  • Structured results with Pydantic models.
  • Descriptions that steer the model to the right tool.
  • ToolError: a failure with a message, versus a crash.
  • Annotations (read_only_hint) 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. 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 are free. This one comes with the all labs plan.