Tools as an interface

Two ways into the same idea

Before You Start

The Core Idea

The model never sees your tool's code, only its name, description and parameter schema. In this lesson you build those three well, then write error messages the model understands.

1The description is the interface

The model picks a tool from its words alone. A name like tool1 and a description like "gets data" tell it nothing, so it picks almost at random.

In the example, a simple "model" picks the tool that shares the most words with the request. It is a simplification, but real models lean on the description in the same way.

def pick_tool(request, tools):
    """Stand-in for the model: picks the tool whose name and description share most words with the request."""
    words = set(request.lower().replace("?", "").split())
    def overlap(t):
        return len(words & set((t["name"].replace("_", " ") + " " + t["description"]).lower().split()))
    return max(tools, key=overlap)["name"]

vague = [
    {"name": "tool1", "description": "Gets data."},
    {"name": "tool2", "description": "Handles records from the system."},
]
clear = [
    {"name": "get_order_status", "description": "Look up the shipping status and delivery date of a customer order by its order number."},
    {"name": "search_help_articles", "description": "Search help centre articles for how-to questions, like resetting a password or changing an address."},
]
requests = ["what is the delivery date of my order?", "how do I reset my password?"]
for r in requests:
    print(f"{r}\n   vague tools -> {pick_tool(r, vague)}    clear tools -> {pick_tool(r, clear)}")

With vague tools the choice is effectively random: tool2 was picked for the delivery question only because its description contains "the". With clear names and descriptions every request went to its tool. A good description says what the tool does, when to use it, and gives an example of a request it fits.

2The schema and its defaults

A tool definition has three parts: a name with a verb and an object, a description saying what, when and when not, and a JSON schema of its parameters. The model fills the schema, and your code validates it before running.

get_order_status = {
    "name": "get_order_status",
    "description": (
        "Look up the shipping status and expected delivery date of one customer order. "
        "Use it when the user asks where an order is or when it will arrive. "
        "Do not use it for refunds; use get_refund_policy for that. "
        "Example: 'where is my order 48213?' -> order_id='48213'."
    ),
    "input_schema": {
        "type": "object",
        "properties": {
            "order_id": {"type": "string", "description": "The 5-digit number on the receipt, digits only."},
            "include_history": {"type": "boolean", "default": False,
                                "description": "Also return every tracking event. Rarely needed."},
        },
        "required": ["order_id"],
    },
}

The description says what, when and when not, points to the alternative tool, and gives an example. One parameter is required, the second optional with a default and a description saying it is rarely needed. Field names differ slightly between providers (input_schema or parameters); the content is the same.

Look at the picture: the description is the widest part, because it is the most important line you write for an agent. And every optional parameter with a sensible default reduces what the model must decide, and its errors.

3Error messages the model understands

The model reads the tool's result, errors included. A raw exception leaves it flailing, and an error that says what happened and what to do next lets it correct itself.

Look at the picture: the tool returns a clear error, so the model asks the user for the right number, then calls the tool again.

Two versions of the same tool. The first crashes on any unexpected input; the second cleans the input and explains the error.

import json

ORDERS = {"48213": "shipped"}

def get_order_status_bad(order_id):
    return ORDERS[order_id]                       # raises KeyError: the model sees a stack trace

def get_order_status(order_id, include_history=False):
    order_id = str(order_id).strip().lstrip("#")
    if not order_id.isdigit() or len(order_id) != 5:
        return {"error": f"order_id must be 5 digits, got {order_id!r}. Ask the user for the number on their receipt."}
    if order_id not in ORDERS:
        return {"error": f"No order {order_id}. Check the number with the user; do not guess another one."}
    return {"order_id": order_id, "status": ORDERS[order_id]}

for arg in ["#48213", "4821", "99999"]:
    try:
        print("bad: ", get_order_status_bad(arg))
    except Exception as e:
        print("bad:  crashed with", type(e).__name__, e)
    print("good:", json.dumps(get_order_status(arg)))

The bad version crashed even on #48213, a valid number with a # that people often type. The good version cleaned it and succeeded; when the number was short it told the model what to ask the user, and when it did not exist it said "do not guess another one". That last sentence prevents real behaviour: models trying nearby numbers until something turns up.

How It Works, Step by Step: how the model calls your tool

Going deeper

And return only what the model needs. A fifty-field reply straight from the database fills the context with internal numbers and meaningless identifiers, repeated in every later step. Pick the fields that answer, and add an optional detail parameter for whoever needs more.

Worked example

Let us see it directly. The "model" here picks the tool whose words overlap most with the request; a simplification, but real models rely on the description in essentially the same way.

Try it without code

Myth vs Reality

Try it yourself

Quick review cards

Check Your Understanding