Skip to content
AI Engineer Guide.

concept · concepts · intermediate · concept 1 of 16

Tool contracts

0 of 16 complete

Why it matters

A function signature written for humans assumes the caller has read the documentation. A model has only the schema and description in its context, and it will invent plausible arguments when the contract is ambiguous. Ambiguity shows up as wrong units, missing optional fields treated as null, and retries that duplicate a write. A tool contract is the work of making the call unambiguous to a caller that cannot ask a clarifying question and will not read the source.

Mental model

A tool contract is a form at a government office: the fields, the accepted formats and what happens after submission. The metaphor breaks because a clerk rejects a bad form, while a model will fill an ambiguous field with a guess and the tool may accept it.

How it works

Schema-valid, contract-incompleteInteractive

The schema constrains shape. Side effects, retry safety, error meaning and version are the rest of the contract, and the dispatcher cannot infer them from types.

Model

proposes

Runtime

dispatches

Tool

mailer

Step 1/5 · propose
1 · propose · send_invoicein-process · Model → Runtime
{ "name": "send_invoice",
  "arguments": {
    "invoiceId": "inv_221",
    "to": "ada@example.com" } }

The description says "sends the invoice".
The side effect is declared; retry safety
is not.

Step 1: propose. Hover, tap or tab to any message to inspect its payload.

Figure. The call passes every JSON Schema check and still sends the invoice twice: the contract declares the side effect but no retry-safety clause. A timeout is not proof of failure, and without a caller-supplied idempotency key the retry is a second send.

What to notice. The failure is a retry that duplicates a write. The missing contract term — an idempotency key the tool enforces with a unique constraint — is described here but not drawn; the unit-ambiguity case, where a schema accepts both seconds and milliseconds, is omitted. Invoice, address and message ids are illustrative.

Text version

Sequence across Model, Runtime (the dispatcher) and Tool (the mail provider). Step 1, propose: an in-process Model to Runtime row proposing send_invoice with invoiceId inv_221 and recipient ada@example.com; the description declares a send side effect but says nothing about retry safety. Step 2, call: Runtime to Tool send_invoice with the same arguments and no idempotency key; every field satisfies the schema. Step 3, timeout: Tool to Runtime an error after 2000 ms, noting that the mail provider accepted message msg_1, so the timeout does not prove failure. Step 4, retry: Runtime to Tool the identical call again, still with no key. Step 5, duplicate: Tool to Runtime a successful result with messageId msg_2; the first attempt produced msg_1, so two emails were sent. Step 6, observe: an in-process Runtime to Model row carrying the successful result; the model sees success and never learns that the retry duplicated the side effect.

  1. Name the tool as a verb and an object, and write a description that states when to use it and when not to.
  2. Define the input schema with types, enums, formats, units and required fields, and forbid additional properties.
  3. Declare the output shape, including the fields the model needs to decide the next step, and avoid returning an opaque blob.
  4. Classify the side effect as read, write, send or destructive, and state whether a retry is safe.
  5. Define an error taxonomy the model can act on, separating invalid input, permission denied, not found, rate limited and internal failure.
  6. Version the contract and keep old versions callable until every client has migrated.

Trade-offs

ChoiceGood forCostFails when
Rich schema with many enumsFewer invalid argumentsLong description consumes context and constrains legitimate inputThe domain is open-ended
Free-form string argumentFlexibleThe model guesses format and unitsThe argument is a date, currency or identifier
Structured error codesModel can retry or escalate correctlyMore design and mapping workThe upstream API returns prose errors
Few broad toolsShort promptAmbiguous intent and wide authorityOperations have different risk levels
Trade-off mapInteractive

Good for

Fewer invalid arguments

Cost

Long description consumes context and constrains legitimate input

Fails when

The domain is open-ended

  1. The domain is open-ended
  2. The argument is a date, currency or identifier
  3. The upstream API returns prose errors
  4. Operations have different risk levels

Figure. Each choice with what it buys, what it costs, and the case where it loses.

What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.

Text version

Four trade-offs: Rich schema with many enums is good for Fewer invalid arguments, costs Long description consumes context and constrains legitimate input, and fails when The domain is open-ended. Free-form string argument is good for Flexible, costs The model guesses format and units, and fails when The argument is a date, currency or identifier. Structured error codes is good for Model can retry or escalate correctly, costs More design and mapping work, and fails when The upstream API returns prose errors. Few broad tools is good for Short prompt, costs Ambiguous intent and wide authority, and fails when Operations have different risk levels

Failure modes

  • Unit ambiguity. The model passes seconds where milliseconds are expected and the tool accepts it. Debug: log argument values with their distribution and compare against the documented range.
  • Silent coercion. A string is coerced to a number and a malformed value becomes zero. Debug: validate with strict types and test a payload with the wrong type.
  • Retry duplicates a write. A timeout triggers a retry and the action happens twice. Debug: check for an idempotency key in the request log and confirm the tool rejects a repeated key.

In production

Track invalid-argument rates per tool and per field, because a spike usually means the description is ambiguous. Keep contract tests that call the tool with the exact examples in its description.

Common misconceptions

People think: A JSON schema is a complete contract.

Actually: It constrains shape and type; meaning, units, side effects and retry safety live outside the schema.

People think: Better descriptions are enough to fix tool misuse.

Actually: Descriptions help selection; enforcement of arguments and permissions belongs in the dispatcher.

Interview angle

A strong answer treats the description and schema as the model-facing API, then covers errors, side effects and versioning. It gives an example of an ambiguity that a schema cannot catch. Weak answers describe a function signature and assume the model will read the documentation.

Sources