Tool contract

A tool contract is the written specification of one tool that an agent can call. It states the inputs the tool accepts and their types, the output it returns, the errors it can raise, the permissions it needs and the side effects it causes. The harness uses the contract to check each call before it runs and each result before the agent sees it.

Without a contract, the agent is guessing the shape of the tool from its name. That works in a demonstration and fails in production, usually in ways that are hard to trace.

In practice

I write the contract before the tool is built, in the same format the harness reads. Each field has a type and a range. Each error has a code the agent can act on, such as "not found", "permission denied" or "rate limited", and each code has a documented next step. Any tool that writes data is marked as such, so the harness can apply a pause point before the call.

Contracts are versioned. A change to a tool is a change to the contract, and the regression evaluations run again.

Example

[Composite] A tool that looked up customer accounts returned a null where the agent expected an empty list. The agent treated the null as an error and retried six times. The contract was changed to define the empty case explicitly, and the harness rejected any result that did not match the contract.

Common mistakes

• Describing the tool in the prompt only. The prompt is not a checked contract.
• Returning free text where a structure is needed. The harness cannot validate prose.
• Failing silently. Every error case needs a code the agent and the logs can see.