Chapter 52 — Tools: giving the model hands

What a tool definition looks like

{
  "name": "get_order_status",
  "description": "Look up the current status of a customer order by its ID. Returns status, items, and estimated delivery date. Use this whenever a customer asks about an order.",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "The order ID, e.g. 'ORD-12345'. Must start with ORD-."
      }
    },
    "required": ["order_id"]
  }
}

The model sees only this. It never sees your implementation. So the description and the schema are the entire interface — and they're written in natural language, which means they are prompts (Chapter 44) and deserve the same care.

How to write tools the model will actually use correctly

A useful test: hand your tool descriptions to a colleague with no context. If they can't tell which tool to use for a given task, neither can the model.

The tool categories worth having

   READ-ONLY (safe, allow freely)
       search documents, look up a record, get the time, read a file,
       run a database SELECT, fetch a URL

   COMPUTE (safe if sandboxed)
       run code, do maths, transform data

   WRITE / IRREVERSIBLE (gate these -- Chapter 60)
       send an email, issue a refund, delete a file, deploy,
       modify a database, post to an API, spend money

Draw this line on day one. Every guardrail decision follows from which side of it a tool sits on. Read-only tools can be called freely; write tools need validation, limits, logging, and usually human approval.

The two mistakes everyone makes

1. Giving the model a tool that is too powerful.

   BAD:   run_sql(query)                  <-- the model can do anything,
                                              including DROP TABLE
   GOOD:  get_order(order_id)             <-- one job, validated input
          get_customer_orders(customer_id, limit=10)
          search_orders(status, date_from, date_to)

A narrow tool is safer, easier for the model to use correctly, and easier to test. "Give it SQL access" is the single most common serious mistake in agent projects.

2. Trusting the arguments.

The model generates the arguments. Those arguments are untrusted input — they may be influenced by anything in the context, including a customer's message (Chapter 59). Validate them in your code exactly as you would validate a web form:

def get_order_status(order_id: str, *, caller_customer_id: str):
    # 1. VALIDATE the shape
    if not re.fullmatch(r"ORD-\d{4,10}", order_id):
        return {"error": "Invalid order ID format."}
    # 2. AUTHORISE -- does this caller own this order?
    order = db.get_order(order_id)
    if order is None or order.customer_id != caller_customer_id:
        return {"error": "Order not found."}       # don't leak existence
    # 3. Return the MINIMUM needed
    return {"status": order.status, "eta": order.eta, "items": order.items[:20]}

Note caller_customer_id — it comes from your session, not from the model. Identity must never be a model-supplied argument.