Lesson 20.220.2 A tool is a name, a description and a schema

Where this fits. Before step 1, call: before the loop can start, your program must tell the model which tools exist. This concept is about how a tool is described, so the model can ask for it correctly, and what that description can and cannot guarantee.

In everyday life. A bank's deposit slip has a box for the account number, eight digits, and a box for the amount, in dollars and cents. The teller's machine rejects a slip with seven digits. But a slip with eight digits can still name an account that does not exist, and the machine accepts it. The teller checks the account. In this concept, the slip is the tool's schema, the machine is the schema check, and the teller is your tool's handler, the code that actually runs the tool when the model asks for it.

What you will learn. How a tool is described to the model, what that description can promise about its inputs, and what it never can.

Why it matters. Inputs can have the right shape and still be wrong. Knowing which part checks the truth tells you where that check belongs.

One request, start to finish. Ana asks: "Does INV-8330 match its purchase order?" There is no invoice INV-8330.

1. The model reads the tool list and picks get_purchase_order, because its description says it finds the purchase order for one invoice.
2. It writes the inputs: {"po_number": null, "invoice_number": "INV-8330"}. With strict tool use on (a setting explained below), the API guarantees this matches the tool's schema, the description of its inputs: two fields, each a string or null, no others.
3. Your code runs the tool. The connector looks for INV-8330 and finds nothing.
4. The tool returns an error result: "No invoice INV-8330 in the AP data. Check the number, or call list_open_invoices to see open invoices."
5. The model reads the error and tells Ana it could not find that invoice.

The inputs were perfectly shaped. They were still wrong.

What does a tool definition hold?

Chapter 17 taught that a tool is its description: the model chooses a tool by reading what it says. A tool definition sent to a model API has three parts:

• A name, such as get_purchase_order, made of letters, digits, _ and -.
• A description, which the model reads to choose the tool and to fill it in. Your connector's descriptions, from Chapters 17 to 19, are reused word for word.
• An input schema, written in JSON Schema, the open standard for describing the shape of JSON data: which fields an object has, which are required, and what type each one is.

Here is get_purchase_order as the lab defines it once, in tools/ap-tools.json, for both APIs:

{
  "name": "get_purchase_order",
  "description": "Find the purchase order (PO) for an invoice, or look up a PO by number, and compare the amounts. ...",
  "input_schema": {
    "type": "object",
    "properties": {
      "po_number": { "type": ["string", "null"], "description": "A PO number such as PO-7003." },
      "invoice_number": { "type": ["string", "null"], "description": "An invoice number such as INV-8303." }
    },
    "required": ["po_number", "invoice_number"],
    "additionalProperties": false
  }
}

"required" lists the fields that must be there. Here that is every field, because the second API's strict tool use, which comes next, needs it. "additionalProperties": false says no other field is allowed. A field that may be left empty is written as "type": ["string", "null"] and still listed as required, so the model always says, explicitly, "no filter".

What does strict tool use guarantee?

Strict means the shape, never the truth. Both APIs offer strict tool use. With it on, the API constrains what the model can write, so its inputs always match the schema. Without it, a model can now and then send a missing field or an extra one. Strict is worth turning on, and the lab does, on both APIs. But a schema can only say "a string". It cannot say "an invoice that exists" or "an invoice this person may see". That check belongs to the handler, and in this book to the connector and the database (Chapters 18 and 19).

Figure 20.5. One definition, read three ways. Only the last reader knows whether the inputs are true.

How free is the model to choose a tool?

A request can also say how free the model is to use tools. Tool choice "auto", the default, lets the model decide whether to call a tool and which. Some APIs also let you force a tool, or force "use some tool". On most of the newest models of the first API, the lab's included, a request that forces a tool is rejected with a 400 error (the request itself was wrong, 20.9). Its documentation does not say why, and recommends "auto" with strict tool use instead. So this chapter always uses "auto", and Task 9 shows you that error once.

At work. In Lab 20, Task 2, your coding agent compares tools/ap-tools.json with the connector's own tool list, then shows you the two small functions that turn it into each API's shape, one per API, in src/loop/tools.ts and its Python twin. You predict which tool the model will ask for when Ana asks about this week's invoices.

The operating rule: define each tool once, in JSON Schema, with every field required and no extras, and turn strict on. Check every input's truth in the handler, never in the schema.