How to Design Tools an AI Agent Can Actually Use

What makes a tool usable by an agent

This gets neglected because tool descriptions look like documentation, so they get written last and reviewed by nobody. They are not documentation. They are the part of the prompt that decides what the agent does, and the only instruction it has at the moment it chooses an action.

The Five P Tool Contract

Every tool description should carry the same five parts in the same order. Consistency matters as much as content: twelve tools written to one template compare cleanly, and twelve written in twelve styles force the model to guess what the differences mean.

Read it back with one question in mind: could someone who has never seen your system call this correctly first time. If they would need to ask you anything, the model will guess instead, and the guess will be confident.

One tool per outcome, not one per endpoint

Wrapping your REST API one to one is the fastest way to build a tool set and the most reliable way to make an agent slow and error prone. Endpoints are shaped for programmers who read documentation and hold state across calls. Tools should be shaped for the outcome someone wants.

The pattern that carries most of the benefit is search then act. Provide one lookup tool that takes a human-shaped query and returns the records with the fields the next action needs, including their identifiers. Then provide action tools that require those identifiers. The agent never has to invent an ID because there is always a tool that hands it one, and your validator can reject any identifier that did not appear in an earlier result. That check is covered further in controlling what an agent is allowed to do.

Error messages are prompts

Whatever a tool returns lands in the model's context and shapes the next decision. That makes error text prompt engineering with a different job title, and it is the most valuable writing in the whole system, because the agent reads it at the exact moment it is stuck.

Schema rules that remove whole bug classes

The schema is a contract the model cannot argue with, so put as much of the constraint there as possible and leave the description for what a schema cannot express. Each rule below corresponds to a bug that stops occurring once the rule is applied.

• Enumerate anything enumerable. An enum of five reason codes is checkable. A free-text reason field produces sixty variants in a month and no reporting.
• Stay one level deep. Models fill flat objects far more reliably than nested ones. If you need nesting, you probably need a second tool.
• Make almost nothing optional. Every optional field is an invitation to invent a value that seems helpful. Required and validated beats optional and hopeful.
• Ban negative booleans. A field called exclude_inactive gets set wrong roughly half the time. Use status with values active, inactive and all.
• Absolute dates only, and say what day it is. Put the current date in the system prompt and reject relative strings at the boundary with an error naming the expected format.
• Put units in the field name. Fields called amount_minor_units and timeout_seconds prevent an argument nobody notices until a refund is a hundred times too large.
• Pattern-match identifier fields. A regex on order_id catches an invented ID at the schema layer, before it reaches your database.
• Cap and paginate returns. A four thousand token result is charged again on every remaining turn of the run. Return the fields the next action needs plus a cursor, not the whole record.

The last rule is the one with a running cost attached. Return size is not a one-off charge, it is a subscription paid for the rest of the run, which is why trimming tool output is usually a bigger saving than changing model. The mechanism is set out in what an AI agent actually is.

# tools/refund_order_line.yaml
# Authored in YAML, serialised to the provider's JSON tool schema at build time.
# Every section below maps to one part of the Five P contract.

name: refund_order_line

description: |
  PURPOSE
  Issues a refund for ONE line on ONE order and returns the refund record.
  It does not cancel the order, does not refund shipping, and does not email
  the customer. Use cancel_order and send_customer_email for those.

  PROVENANCE
  order_id            must come from a search_orders or get_order result in
                      this run. Never construct or infer it.
  line_id             must come from the lines array of that same order.
  amount_minor_units  integer, order currency, minor units. Must be less than
                      or equal to line.refundable_minor_units from get_order.
  reason_code         one of the enum values. Free text belongs in note.
  idempotency_key     one stable string per intended refund. Reusing it returns
                      the original refund instead of creating a second one.

  PRECONDITION
  Order status must be delivered or shipped. Call get_order and read status
  before calling this tool.

  POSTCONDITION
  Creates a refund in state pending. Money moves later. The return value proves
  the refund was created, not that it settled. Confirm with get_refund.

  ON ERROR
  amount_exceeds_refundable  read refundable_minor_units from get_order and
                             retry once with a valid amount.
  order_not_refundable       stop and escalate. Do not try another tool.
  upstream_unavailable       wait 2 seconds, retry once, then escalate.

input_schema:
  type: object
  additionalProperties: false
  required: [order_id, line_id, amount_minor_units, reason_code, idempotency_key]
  properties:
    order_id:           { type: string, pattern: "^ORD-[0-9]{8}$" }
    line_id:            { type: string, pattern: "^LN-[0-9]{4}$" }
    amount_minor_units: { type: integer, minimum: 1 }
    reason_code:
      type: string
      enum: [damaged, not_as_described, late_delivery, goodwill, duplicate_charge]
    note:               { type: string, maxLength: 280 }
    idempotency_key:    { type: string, minLength: 8 }

returns: |
  { "refund_id": "RF-00012345", "state": "pending",
    "amount_minor_units": 1299, "currency": "GBP",
    "expected_settlement": "3 working days",
    "verify_with": "get_refund(refund_id)" }

Writes need idempotency and two phases

Read tools can be retried freely. Write tools cannot, and an agent will retry, because retrying is what a model does when a response looks ambiguous. Design every write assuming it will be called twice with the same intent, once because of a timeout and once because the model was not sure the first one worked.

1. Make the idempotency key an argumentNot a header your code adds

   The key belongs in the schema so the model generates one per intent rather than per call. If your code generates it, a retry produces a fresh key and a second refund.

2. Store the key and replay the original resultServer side

   A repeated key returns the first result, including the same identifier and the same state. The agent then sees a consistent world instead of two conflicting truths.

3. Split irreversible actions into prepare and commitThe pattern worth the extra turn

   Prepare returns a preview with a short-lived token: the amount, the record, what will change. Commit takes only that token. A human can approve between the two without anybody building an approval system.

4. Return the resulting state, never OKOne line, large effect

   The response should say what the record now is, and name the tool that verifies it. An agent given a verification path uses it. An agent given OK reports success.

5. Tag every write with the run identifierFor the bad day

   When a run fails between two writes, you need to find the first one to compensate for it. Without a run tag, that search is manual and slow at exactly the wrong moment.

The tool schema tax

Every tool description is sent to the model on every turn, whether or not the agent uses that tool. A large tool set is therefore a fixed tax on every run, and it also lowers accuracy, because more similar-sounding options make the choice harder. Both costs point the same way.

Run it with your real tool count before you argue about model pricing. The number that usually surprises people is the share output: on an endpoint-shaped tool set, a large fraction of every prompt is spent describing tools the agent will never call on this task. Grouping by outcome cuts the tax and the error rate together.

Testing a tool description

Tool descriptions are prose that controls behaviour, so they need tests like any other behaviour. The test is cheap: give a model nothing but your tool list and a phrased request, and check which tool it picks and which arguments it fills. No agent loop, no database, no waiting.

Terms used precisely here

Tool schema

The machine-readable declaration of a tool's name, arguments, types and constraints, sent to the model alongside its description on every turn so it can produce a valid call.

Provenance rule

An instruction stating where an argument's value must come from, usually that an identifier must appear in an earlier tool result in the same run and may never be constructed by the model.

Idempotency key

A stable string supplied with a write so that repeating the same call returns the original result instead of performing the action twice. Generated once per intent, not once per attempt.

Two-phase write

A write split into a prepare call that returns a preview and a short-lived token, and a commit call that takes only that token, so an irreversible action can be reviewed before it happens.

Tool surface

The complete set of tools exposed to an agent in one run. It defines both the token cost of every turn and the outer limit of the damage a bad run can do.

That last item is the one people resist. A tool nobody calls is not free: it is a permanent tax on every prompt and one more option to choose wrongly. The tool set is usually the part of a build that gets postponed, and it is the first thing we rewrite in AI agent development.