Most agent failures are not caused by "bad reasoning". They are caused by tool contracts that are ambiguous, unstable, or unsafe. A tool contract is the interface between an LLM and an action. If you want reliable agents, you need reliable tool contracts.
Define tool contracts as schemas, not prose
LLMs work best when tool arguments are strongly constrained. Prefer strict schemas over descriptive text:
- Clear required fields. No hidden defaults.
- Enums for options. Do not expect the model to invent magic strings.
- Consistent names. Keep field names stable and self-explanatory.
- Examples. Provide one or two valid examples in the tool description.
Where possible, validate requests and responses deterministically (see structured outputs and validation).
Return machine-readable errors
Agents need to know what went wrong. Use an error taxonomy that supports safe behaviour:
- Retryable. Timeouts and transient 5xx.
- Non-retryable. Validation errors and missing fields.
- AuthZ/AuthN. Missing permissions or expired tokens.
- Conflict. Concurrent updates and stale versions.
This taxonomy also improves dashboards and incident response (see error taxonomy).
Design for idempotency and safe retries
Agents often reattempt actions. If your tools are not idempotent, retries can create duplicate changes. Add:
- Idempotency keys. A stable request ID per user intent.
- Read-after-write checks. Confirm state before repeating actions.
- Dry-run mode. For high-risk actions, return a plan for approval.
These patterns pair well with approvals for sensitive actions (see agent approvals).
Make permissions explicit
Tool contracts are a security boundary. Controls should include:
- Least privilege. Tools should run with scoped credentials.
- Allowlists. Expose only approved tools and endpoints.
- Audit logs. Record actions with user, tenant and tool arguments.
Do not rely on the model to "be careful" about sensitive tools. Enforce via policy and runtime checks (see tool authorisation and safe tooling for agents).
Version tools like APIs
Tool contracts change over time. Treat them as APIs with compatibility rules:
- Additive changes. Add optional fields before removing old ones.
- Deprecation windows. Keep old fields supported for a defined period.
- Contract tests. Validate that a tool still accepts known-good requests.
For agentic systems, tool changes are high-risk. Use canary rollouts and change control (see canary rollouts and change management).
Reliable agents are built on boring engineering: strict schemas, clear errors, safe retries and stable contracts. If you fix tools, you often fix the agent.