A tool contract defines how a runtime may invoke an external capability and how the capability reports effects. It is the security, reliability, and audit boundary between model-generated intent and the external world.
Key takeaways
- Schema validation is necessary but not sufficient; authorization depends on actor, resource, action, state, and risk.
- Retry policy follows side-effect and idempotency semantics.
- Credentials are references resolved at execution time, not values shown to the model.
[ar_diagram id=”tool-authorization-sequence”]
Purpose
The contract gives a runtime enough information to validate, authorize, execute, observe, recover, and deprecate a tool without relying on natural-language description alone. It also gives the tool owner an explicit responsibility for schemas, errors, side effects, and compensation.
Contract fields
| Area | Fields |
|---|---|
| Identity | toolId, version, description, owner through registry metadata |
| Data | inputSchema, outputSchema, dataClassification, egressPolicy |
| Access | authenticationRef, permissionClass, approvalTriggers |
| Effects | sideEffectClass, idempotency, compensation |
| Execution | timeoutSeconds, retryPolicy, concurrency, rateLimits |
| Operations | errors, observability, auditFields, deprecation |
Tool classes
- Read-only
- Retrieves data without changing source state; still subject to authorization and data classification.
- Reversible write
- Changes state with a documented inverse or compensation.
- Irreversible
- Cannot be reliably undone; requires stronger controls.
- Financial or high-impact
- Moves value or affects rights, eligibility, safety, or material outcomes.
- External communication
- Sends messages or publishes information outside the task boundary.
- Code execution
- Runs commands or code in an isolated, constrained environment.
- Administrative
- Changes identity, policy, access, infrastructure, or security configuration.
Retry and idempotency
Read-only tools may be retryable when the result can change safely. Writes require an idempotency key bound to actor, tenant, resource, operation, and intended payload. If a timeout occurs after submission, query operation status before retrying. Compensation is explicit and may itself require approval.
Error taxonomy
Use stable codes such as input.invalid, permission.denied, approval.required, rate.exceeded, dependency.unavailable, timeout.before-submit, timeout.unknown-commit, conflict, partial-effect, compensation.failed, and output.invalid. Include retry eligibility and safe diagnostic detail without leaking secrets.
Versioning and deprecation
Version schemas and semantics together. A breaking change receives a new major version and can coexist during migration. The registry records introduced, deprecated, and removal dates in UTC, replacement tool, compatibility, and affected policies. Do not silently repoint an existing tool ID to a materially different side effect.
Examples and schema
[ar_downloads file=”tool-contract-read-only.json”][ar_downloads file=”tool-contract-reversible-write.json”][ar_downloads file=”aruntime-tool-contract.schema.json”]