01 · NARROW
One bounded capability
Prefer propose_recovery_option over a generic execute_sql or unrestricted HTTP tool.
LESSON 05 · ACTION SURFACE
Tool Design
Tools are where model intent becomes real-world effect. Make each capability narrow, typed, permissioned, idempotent where needed, and verifiable.
An API is not automatically a safe agent tool.
A conventional API can expose a large action surface, weak validation, implicit authority, and ambiguous failure behavior. An agent-facing tool should expose only the capability the agent actually needs.
D→V RULE
Make dangerous actions harder to express. The tool schema should encode policy, not merely transport parameters.
02 · TYPED
Constrained inputs
Use enums, required identifiers, ranges, and structured payloads.
03 · AUTHORIZED
Policy before execution
Require the right actor, approval token, tenant, scope, or capability before side effects occur.
04 · IDEMPOTENT
Safe retry behavior
Side-effecting actions should use request IDs or business keys so retries do not duplicate consequences.
05 · EXPLICIT FAILURE
Machine-readable errors
Return policy denial, stale state, validation failure, conflict, and transient failure distinctly.
06 · VERIFIABLE
Readable result state
After execution, provide a way to re-read authoritative state and confirm the intended effect.
tool: change_booking
input:
shipment_id: string
option_id: string
approval_id: string
idempotency_key: string
preconditions:
- approval belongs to named human owner
- option is still valid
- shipment state matches expected version
failure_codes:
- POLICY_DENIED
- STALE_STATE
- VALIDATION_ERROR
- TRANSIENT_FAILURE
verification:
- read_booking(shipment_id)
INTERACTIVE LAB · TOOL CONTRACT TESTS
Would you ship this tool?
Evaluate tool designs against the agent boundary and authority matrix from the prior lessons.
LESSON ARTIFACT
Write the Tool Contract.
Define one production-facing capability clearly enough that engineering, security, and operations could review the same artifact.