TOOLS.md
Tool and MCP contracts
Inventory model-callable capabilities and make schemas, descriptions, authentication, authorization, side effects, idempotency, errors, timeouts, output limits, and approval requirements explicit.
Fillable structure
Replace prompts with project evidence.
Remove any field that does not apply. A smaller maintained file is more useful than generic documentation that agents and reviewers cannot trust.
- 01
Tool inventory and contract
Make tool selection and consequences understandable to both models and reviewers.
Capability: Name the user outcome and why a model needs this tool
Schema: Define narrow typed inputs, outputs, defaults, and validation
Side effects: Classify read-only, reversible, external write, financial, destructive, or privileged behavior
- 02
Identity and authority
Keep authentication separate from the permission to perform a specific action.
Authentication: Define caller, user, service, tenant, and credential lifecycle
Authorization: Define resource- and action-level policy checked at execution time
Approval: List arguments and actions requiring preview, confirmation, or a second reviewer
- 03
Reliability and observability
Specify predictable behavior under repetition, delay, partial failure, and large outputs.
Failure contract: Define typed errors, retryability, timeout, cancellation, and partial results
Idempotency: Define duplicate detection, keys, replay, and exactly-once assumptions
Telemetry: Record tool name, sanitized arguments, authorization, latency, result, and correlation identifiers
- 04
Verification
Test the contract as adversarially as the model and external systems will use it.
Contract tests: Cover valid, malformed, boundary, oversized, and unsupported inputs
Safety tests: Cover prompt injection, confused deputy, cross-tenant, approval bypass, and revocation
Operational tests: Cover timeout, retry, duplicate execution, dependency failure, and recovery
Related field guides
Next template
DELEGATION.md · Multi-agent delegation