Tool Contracts for AI Agents
A tool is an authority boundary disguised as a function call. A good contract makes the intended action easy and an accidental action difficult.
Contract Surface
Each tool should state:
| Field | Question |
|---|---|
| Name and description | When should the model call this instead of another tool? |
| Input schema | Which values are valid, required, bounded, and mutually exclusive? |
| Preconditions | What must already exist or be authorized? |
| Effects | Is the call read-only, reversible, externally visible, or destructive? |
| Output schema | What stable facts will return without flooding context? |
| Errors | Can the caller distinguish invalid input, denial, timeout, and partial completion? |
| Idempotency | Is retry safe, or does it duplicate an external action? |
| Approval | Which arguments or effects require a human gate? |
Schema validation prevents malformed calls; it does not establish intent, authorization, or truth.
Design Rules
- Prefer a few orthogonal tools over many overlapping aliases.
- Use enums, limits, and explicit paths instead of free-form command strings where possible.
- Separate reads from writes and reversible writes from destructive actions.
- Return stable identifiers, counts, and concise evidence; place large artifacts in files or resources.
- Make partial success explicit. Never report a batch as successful because one item succeeded.
- Include dry-run or preview only when it reflects the real authorization and validation path.
- Treat tool output as untrusted content, especially when it comes from web pages, issues, or documents.
- Log redacted arguments, result state, latency, and correlation IDs without storing secrets.
Retry Policy Belongs to the Effect
Automatic retry is reasonable for a read that timed out before returning. It is dangerous for “send message,” “charge card,” or “create deployment” unless the operation has an idempotency key and confirmed outcome semantics. The harness should classify errors rather than asking the model to guess whether repetition is safe.
Small-Model Tooling
Compact local models usually perform better with fewer tools, short descriptions, shallow JSON schemas, and one obvious action per tool. Test exact tool-call parsing with the selected chat template and quantization. A model that writes good code in plain text may still fail structured arguments or invent tool names.
MCP can standardize tool discovery and invocation, but the server and host still own authorization, output filtering, approvals, and auditability.