Executive summary
A production tool contract combines interface schema with business authority and recovery semantics. It preserves the originating principal, authenticates the workload, identifies the protected resource, restricts operation and scope, classifies the external effect, validates input, defines idempotency and reconciliation, distinguishes accepted requests from verified effects, provides typed errors, enforces budgets, records minimum audit evidence, and states which changes reopen the release decision. The contract belongs at the tool gateway—not inside the agent's natural-language prompt.
Decision relevance: Define what each tool can do, under whose authority, with which limits, and how its external effect is verified before an agent can use it.
Tool contract field register
| Field | Purpose | Minimum evidence |
|---|---|---|
tool_id | Stable identifier for the capability, independent of a display label. | Versioned registry entry and owning team. |
purpose_and_prohibited_use | States the business capability and explicitly disallowed uses. | Approved use boundary and reviewer roles. |
principal_and_workload_identity | Preserves the originating person or service and the executing workload identity. | Authenticated identity chain and revocation path. |
authorization | Defines resource, operation, scope, tenant, amount, time, and environment constraints. | External policy decision and least-privilege token or capability. |
input_schema | Constrains accepted arguments and rejects ambiguous or extra fields. | Machine-validatable schema and adverse test cases. |
effect_class | Classifies the operation as observe, propose, mutate, communicate, execute code, or transfer value. | Consequence rating and required approval mode. |
idempotency_and_reconciliation | Prevents duplicate effects and defines how unknown completion is resolved. | Idempotency key, status lookup, and reconciliation test. |
success_and_verification | Separates an accepted request from a verified business effect. | Independent verification query or returned durable identifier. |
error_model | Defines rejected, retriable, terminal, partial, and unknown-result states. | Typed errors, retry budget, and stop conditions. |
budgets | Bounds calls, elapsed time, data volume, value, messages, and monetary cost. | Enforced limits and limit-exceeded tests. |
audit_and_retention | Records the minimum evidence needed for accountability without defaulting to sensitive payload capture. | Trace identifiers, policy result, effect identifier, and retention rule. |
version_and_change_policy | Prevents silent contract drift and states which changes reopen evaluation. | Semantic version, compatibility policy, and change record. |
Machine-readable template
Agent tool contract template
{
"schema": "longtermcapabilities-agent-tool-contract/v1",
"tool_id": "example.customer-record.read",
"version": "1.0.0",
"owner_role": "Customer Data Service Owner",
"purpose": "Read one authorized customer record for a named case.",
"prohibited_uses": [
"bulk export",
"cross-tenant lookup",
"use without a case identifier"
],
"effect_class": "observe",
"identity": {
"preserve_originating_principal": true,
"workload_identity_required": true,
"delegation_chain_required": true
},
"authorization": {
"resource": "customer_record",
"operations": [
"read"
],
"constraints": [
"tenant",
"case_id",
"record_id",
"purpose",
"expiry"
],
"approval": "policy-gateway"
},
"input_schema": {
"type": "object",
"additionalProperties": false,
"required": [
"tenant_id",
"case_id",
"record_id"
],
"properties": {
"tenant_id": {
"type": "string",
"minLength": 1
},
"case_id": {
"type": "string",
"minLength": 1
},
"record_id": {
"type": "string",
"minLength": 1
}
}
},
"result": {
"accepted_is_not_verified_effect": true,
"verification": "returned record identifier and source version"
},
"idempotency": {
"required": false,
"reconciliation": "not applicable for read-only operation"
},
"budgets": {
"max_calls_per_task": 3,
"timeout_ms": 3000,
"max_result_bytes": 65536
},
"errors": [
"rejected",
"not_found",
"not_authorized",
"timeout",
"unknown"
],
"audit": {
"required_fields": [
"trace_id",
"task_id",
"principal_id",
"workload_id",
"policy_decision_id",
"tool_version",
"record_id_hash",
"outcome"
],
"capture_payload_by_default": false
},
"change_policy": {
"reopen_release_on": [
"new operation",
"broader scope",
"new effect class",
"authorization change",
"schema breaking change"
]
}
}A tool is an effect boundary
Tools can observe, retrieve, draft, communicate, mutate records, execute code, change configuration, or transfer value. The effect class determines approval, logging, verification, retry, and recovery requirements. A read-only tool and a payment tool should not share the same default policy.
Preserve principal and workload identity
Record who or what initiated the task, which workload executes the call, and every delegation hop. Issue a resource-specific, short-lived capability rather than passing a broad upstream token through the tool server.
MCP security guidance explicitly identifies token passthrough and missing audience validation as trust-boundary failures, and it recommends progressive least-privilege scopes. [S3] [S2]
Accepted is not the same as completed
An API may accept a request and fail later, complete after a timeout, or partially apply a change. The contract should define an idempotency key, durable effect identifier, status lookup, reconciliation rule, and the exact point at which workflow state may advance.
Errors are part of the contract
Distinguish rejected, not authorized, invalid, retriable, terminal, partial, and unknown-result states. A generic exception encourages unsafe retries. Retry policies should have attempt, elapsed-time, cost, and effect budgets and should stop when progress cannot be demonstrated.
Version the behavior, not only the schema
A non-breaking JSON change can still materially alter side effects, authorization, provider behavior, or verification. The change policy should name which modifications require regression testing, threat review, human approval, and a new release decision.
Research boundary
The included template is an engineering starting point. It is not a protocol extension, security certification, or replacement for the actual API, identity, domain, and legal contract.
Sources
Sources support the linked statements and terminology. They do not certify a system, establish buyer intent, or convert this research into a formal assurance.
- Model Context Protocol server toolsModel Context Protocol · Accessed 2026-08-01
Technical specification
- Model Context Protocol AuthorizationModel Context Protocol · Accessed 2026-08-01
Technical specification
- Model Context Protocol Security Best PracticesModel Context Protocol · Accessed 2026-08-01
Draft technical security guidance
- Accelerating the Adoption of Software and Artificial Intelligence Agent Identity and AuthorizationNIST NCCoE · Accessed 2026-08-01
Government concept paper
- Summary Analysis of Responses to the Request for Information Regarding Security Considerations for AI AgentsNIST · Accessed 2026-08-01
Government technical report
- OWASP Top 10 for Agentic Applications for 2026OWASP GenAI Security Project · Accessed 2026-08-01
Open security guidance
- Securing Agentic Applications Guide 1.0OWASP GenAI Security Project · Accessed 2026-08-01
Open security guidance