CORE GUIDE
Tool contracts for agents
A tool contract defines what an agent may request, what the runtime guarantees, what can fail and which side effects require stronger controls.
Mental model
A tool is an application boundary, not a magic capability. Its contract should make input schema, permissions, side effects, result states, idempotency and error semantics explicit enough for runtime enforcement.
Why it matters
Models choose tool calls probabilistically, so ambiguous tool descriptions and permissive APIs become safety and reliability problems. A well-designed contract narrows the action space and lets deterministic code reject invalid requests before they reach a consequential system. It also gives the model structured observations it can reason about after execution.
01
Design tools around business actions and invariants
Expose narrow operations with typed inputs instead of generic shell-like power when the domain allows it. Specify required permissions, validation rules, reversible versus irreversible effects, idempotency behavior, timeout semantics and structured result states. The runtime checks these rules independently of the model and returns only the evidence needed for the next decision.
02
Example: issue a customer credit
Instead of a generic `execute_payment` tool, the agent receives `issue_support_credit` with customer ID, bounded amount, reason code and operation ID. The runtime enforces account scope and amount limits, requires approval above a threshold, and returns `COMPLETED`, `PENDING` or `REJECTED` with an authoritative transaction reference.
Common failure modes
- Giving the model a broad generic tool when a narrow domain action would suffice.
- Encoding permissions only in the tool description instead of runtime enforcement.
- Returning free-form success text without structured status and identifiers.
Engineering heuristics
- Name tools after bounded business actions with explicit side effects.
- Validate permissions and invariants in runtime code, never only in prompt text.
- Design result states for recovery, including UNKNOWN or PENDING when necessary.
Takeaways
- 01Tool design shapes the agent's safe action space.
- 02Runtime enforcement is stronger than persuasive instructions.
- 03Good contracts make both execution and recovery explicit.
Related concepts from the Knowledge Graph
These relationships come from the canonical graph, not a separate Guide taxonomy.