A tool contract defines what a runtime may call, with which authority, under what failure and side-effect semantics, and with what evidence.
Status and scope
Read-only, reversible write, irreversible, financial or high-impact, external communication, code execution, and administrative tools.
Fields
| Field | Type | Required | Contract meaning |
|---|---|---|---|
contractVersion | constant | Yes | See the schema constraints and examples for this versioned field. Required value: aruntime.tool-contract.v1. |
toolId | string | Yes | See the schema constraints and examples for this versioned field. |
version | string | Yes | See the schema constraints and examples for this versioned field. |
description | string | Yes | See the schema constraints and examples for this versioned field. |
inputSchema | object | Yes | See the schema constraints and examples for this versioned field. |
outputSchema | object | Yes | See the schema constraints and examples for this versioned field. |
authenticationRef | string | Yes | See the schema constraints and examples for this versioned field. |
permissionClass | enum | Yes | See the schema constraints and examples for this versioned field. Allowed values: read, reversible-write, irreversible, financial-high-impact, external-communication, code-execution, administrative. |
sideEffectClass | enum | Yes | See the schema constraints and examples for this versioned field. Allowed values: none, reversible, compensatable, irreversible. |
dataClassification | enum | Yes | See the schema constraints and examples for this versioned field. Allowed values: public, internal, confidential, restricted. |
egressPolicy | object | Yes | See the schema constraints and examples for this versioned field. |
timeoutMs | integer | Yes | See the schema constraints and examples for this versioned field. |
retryPolicy | object | Yes | See the schema constraints and examples for this versioned field. |
idempotency | object | Yes | See the schema constraints and examples for this versioned field. |
concurrency | object | Yes | See the schema constraints and examples for this versioned field. |
approvalTriggers | array | Yes | See the schema constraints and examples for this versioned field. |
compensation | object | Yes | See the schema constraints and examples for this versioned field. |
errorTaxonomy | array | Yes | See the schema constraints and examples for this versioned field. |
rateLimits | object | Yes | See the schema constraints and examples for this versioned field. |
observability | object | Yes | See the schema constraints and examples for this versioned field. |
auditFields | array | Yes | See the schema constraints and examples for this versioned field. |
deprecation | object | Yes | See the schema constraints and examples for this versioned field. |
Versioning and compatibility rules
- Tool identifiers are stable; incompatible input, output, authorization, or side-effect changes require a new version.
- Retry policy must align with idempotency. An irreversible tool without deduplication must not be automatically retried after an ambiguous timeout.
- Permission class and side-effect class are separate: a tool can be authorized for a role while still requiring approval for a specific invocation.
- Compensation is a new governed action, not proof that the original side effect never occurred.
Validation and error behavior
Validate the complete envelope before model execution or credential resolution. Return a stable machine code, a safe human explanation, the failing JSON Pointer, and the supported contract versions. Never “repair” missing authority or risk fields with model-generated values.
{
"error": {
"code": "contract-validation-failed",
"contractVersion": "aruntime.tool-contract.v1",
"path": "/idempotencyKey",
"message": "A stable idempotency key is required.",
"retryable": false
}
}Security, redaction, and minimization
- Authentication references point to a secret manager or workload identity; contracts never contain secret values.
- Egress destinations are explicit and default-deny. Tool adapters validate input after planning and before credential resolution.
- Code-execution tools require a bounded environment, resource limits, network policy, secret isolation, artifact capture, and termination controls.
Validated examples
Read-only customer projection tool
{
"contractVersion": "aruntime.tool-contract.v1",
"toolId": "customer.read.v3",
"version": "3.2.0",
"description": "Reads a bounded customer account projection without modifying the account.",
"inputSchema": {
"type": "object",
"required": [
"customerRef"
],
"properties": {
"customerRef": {
"type": "string"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"customerRef",
"status"
],
"properties": {
"customerRef": {
"type": "string"
},
"status": {
"type": "string"
}
},
"additionalProperties": true
},
"authenticationRef": "secretref://customer-api/runtime-reader",
"permissionClass": "read",
"sideEffectClass": "none",
"dataClassification": "confidential",
"egressPolicy": {
"allowed": true,
"destinations": [
"customer-api.internal"
]
},
"timeoutMs": 3000,
"retryPolicy": {
"maxAttempts": 3,
"backoff": "exponential-jitter",
"retryableErrors": [
"timeout",
"upstream-unavailable"
]
},
"idempotency": {
"supported": true,
"keyLocation": "header:Idempotency-Key",
"deduplicationWindowSeconds": 86400
},
"concurrency": {
"mode": "parallel",
"maxConcurrent": 100
},
"approvalTriggers": [],
"compensation": {
"supported": false,
"toolRef": null,
"deadlineSeconds": null
},
"errorTaxonomy": [
{
"code": "not-found",
"retryable": false,
"meaning": "The customer reference does not exist."
},
{
"code": "upstream-unavailable",
"retryable": true,
"meaning": "The authoritative customer service is unavailable."
}
],
"rateLimits": {
"requests": 100,
"perSeconds": 60,
"scope": "tenant"
},
"observability": {
"requiredSpans": [
"tool.validate",
"tool.invoke"
],
"requiredMetrics": [
"tool.duration",
"tool.errors"
],
"logPayloads": false
},
"auditFields": [
"requestId",
"actorRef",
"tenantRef",
"toolVersion",
"outcome"
],
"deprecation": {
"status": "active",
"replacementRef": null,
"sunsetUtc": null
}
}Reference implementation
The bundled PHP 8.1 example validates admission fields, selects a constrained model route, checks tool permission and approval requirements, performs an idempotent synthetic operation, creates minimized evidence, handles errors, and prints expected JSON output.
Download the runnable PHP example
php examples/php/runtime_pipeline.php