Agent Tool Contract Design Template

Design one observable capability

Give each tool one clear operation and name it for the result, not the implementation. Describe when to use it, when not to use it, required authorization, side effects, cost, latency, and the meaning of success, pending, partial, and failure. Keep model-provided inputs separate from trusted runtime context such as identity and tenant.

Use constrained JSON Schema inputs and, where supported, structured output schemas. Require identifiers and confirmation data needed for safe execution instead of inventing defaults. Validate both input and output at the boundary. MCP annotations such as read-only, destructive, idempotent, and open-world are useful hints but are not trustworthy enforcement.

Record the complete tool contract

Authorize inside the tool using the actual runtime identity. Use idempotency keys or reconciliation for retryable mutations. Return a stable operation identifier and enough safe evidence to verify the postcondition without exposing credentials or restricted records.

Tool name and version: [STABLE_NAME, VERSION]
Purpose: [ONE OPERATION]
Use when / do not use when: [BOUNDARIES]
Runtime identity and authorization: [ENFORCED POLICY]
Input schema: [FIELDS, TYPES, REQUIRED, ENUMS, LIMITS]
Trusted context: [SERVER-INJECTED FIELDS]
Output schema: [STATUS, RESULT, OPERATION ID, SAFE EVIDENCE]
Side effects: [SYSTEM, OBJECT, SCOPE]
Risk hints: [READ-ONLY, DESTRUCTIVE, IDEMPOTENT, OPEN-WORLD]
Approval rule: [CONDITION -> APPROVER]
Timeout/cancellation: [BEHAVIOR]
Retry/idempotency: [KEY, DUPLICATE RESULT, RECONCILIATION]
Errors: [CODE -> MEANING -> SAFE NEXT ACTION]
Logging/redaction: [CAPTURE | EXCLUDE]
Rate/cost limits: [BOUND]
Precondition/postcondition: [CHECKS]
Rollback/compensation: [ACTION OR NOT POSSIBLE WITH REASON]
Contract tests: [POSITIVE, INVALID, UNAUTHORIZED, DUPLICATE, TIMEOUT]

Expected evidence and verification

The expected evidence is a versioned contract, boundary implementation, and tests proving accepted inputs, rejected inputs, authorization, output validation, failure semantics, duplicate handling, and postconditions.

Run contract tests without a model first, then exercise representative tool selection with redacted or synthetic data. Confirm descriptions do not cause over-broad selection, unauthorized calls fail closed, retries do not duplicate side effects, and rollback or compensation works. Review every contract change as an API and security change.