The tool contract

Lesson 1 of 5 in Tools and Tool Use: The Contract Between Model and World.

You learned in the previous module that an agent is a model running in a loop with tools. Now look at a tool from the only vantage point that matters: the model’s side of the glass.

The model never sees your code. It cannot open your source files, read your API docs, browse your wiki, or ask a colleague what mode=3 means. Everything it will ever know about a tool arrives as three pieces of text in its context window: a name, a description, and a parameter schema. That trio is the tool contract — and the punchline of this entire module is that the contract is the only documentation the model ever reads.

A complete tool contract — everything the model will ever know about lookup_order

{
  "name": "lookup_order",
  "description": "Look up one existing customer order by its order ID. Use when the user asks about the status, contents, or delivery of a specific order they already placed. Not for placing, changing, or cancelling orders, and not for searching orders by customer name — use search_orders for that.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "The order identifier from the confirmation email, e.g. 'ORD-2026-114873'",
        "pattern": "^ORD-[0-9]{4}-[0-9]{6}quot;
      },
      "include_items": {
        "type": "boolean",
        "description": "Include the line items in the result. Set true only when the user asks what the order contains. Default: false.",
        "default": false
      }
    },
    "required": ["order_id"]
  }
}

Read that contract the way the model does, and each field turns out to have a job:

The name routes. lookup_order tells the model, in two words, what shelf this tool sits on. The description disambiguates. It says when to reach for this tool — and, just as deliberately, when not to. The schema constrains. The pattern stops the model from inventing free-form IDs; the typed parameters turn “write me some JSON” into “fill in this form”; the example value (ORD-2026-114873) shows the format instead of describing it.

The consequence cuts both ways. Write a great contract over a mediocre implementation and the model will use it correctly. Write a vague contract over a flawless implementation — query, “Queries the system”, one untyped input string — and the model will misuse it forever, because nothing outside the contract can reach the model to correct it.

Where the contract does its work — one tool-call round trip

User asks: where is my order?
Model reads the tool contracts in context
Names, descriptions, schemas — the only inputs to its choice. Your implementation is invisible from here.
Contract says which tool — and how
The name shortlists, the description decides, the schema shapes the arguments.
Model emits a tool call: name + JSON arguments
A structured request — the model proposes; it cannot execute anything itself.
Runtime validates the arguments and executes the code
This is where your actual implementation finally runs — and where validation and permissions belong.
Result text lands back in the context window
The result is a prompt too. Lesson 3 is about designing it.
Model continues: answer, or call again

Key terms: tool, tool contract, tool call, function calling, parameter schema

Interactive checkpoint quiz (2 questions) — open this page in a browser to take it.