Minimal spec
{
"openapi": "3.1.0",
"info": { "title": "Order Tools", "version": "1.0.0" },
"paths": {
"/orders/{id}": {
"get": {
"operationId": "order.get",
"summary": "Get order details",
"x-agent-capability": {
"version": 1,
"enabled": true,
"scope": "order.read",
"risk": { "level": "low" },
"subject": { "required": true }
}
}
}
}
}Who may read the catalog
Every URL-backed provider declares one of exactly two configurable spec_access_policy values below. This policy governs access to the OpenAPI or tools.json catalog only. It never weakens tool-call signature verification or the business system's on-behalf-of authorization.
| Policy | Use it when | Hub behavior |
|---|---|---|
signed_required | Default and recommended. Only a hub that holds the tool-provider secret may read the catalog. | Fetch with a valid signature, then run unsigned and invalid-signature negative probes. All three observations must match before the cache is updated. |
public_allowed | The operator explicitly accepts exposing paths, parameters, scopes, and risk declarations to anyone who can reach the URL. | Fetch unsigned only. The hub never silently falls back to a signed request. |
Inline specs are unaffected. The console shows configured expectation separately from observed evidence; selecting signed protection is not itself proof that the endpoint is protected.
Probe results and failure handling
| Observation | Status | Result |
|---|---|---|
| Valid signature returns 2xx with a valid spec; unsigned and invalid-signature requests both return 401, 403, or 404 | protected | Apply the new catalog. |
Either negative probe returns 2xx while signed_required is configured | public | Policy mismatch; reject the refresh. |
| The signed primary request is not 2xx, or a negative probe returns 3xx, 429, 5xx, times out, or fails at the network layer | inconclusive | No safe conclusion; reject the refresh. |
An unsigned public_allowed request returns 2xx with a valid spec | public | Apply the catalog as explicitly configured. |
The correctly signed primary request must return 2xx. A 404 counts as rejection only for an unsigned or invalid-signature negative probe. Any failed refresh preserves the previous valid cache.
Use the final URL
signed_required and public_allowed do not follow redirects. Configure spec_url to point directly to the final response; 3xx is inconclusive.
Keep responses bounded
Each request has a 10-second deadline and the positive spec body is limited to 5 MiB. Timeout, oversize, or parse failure preserves the old cache.
Disable protected-response caching
A signed-only response must send Cache-Control: private, no-store so a proxy or CDN cannot turn one valid fetch into a public copy.
Probe evidence has limits
protected proves the direct probes behaved correctly. It does not prove that every intermediary honors your cache configuration; review the origin, gateway, and CDN separately.
SDK path
Official SDKs
PHP, Node, Python, Java, Go, and .NET all produce the same tool spec contract and provide helpers for signatures, visitor tickets, callbacks, authz probes, and Hub API calls.
Plain HTTP
Teams using other languages can publish OpenAPI with x-agent-capability ACC metadata and implement the documented HMAC contract directly.
How to choose risk levels
Low
Read-only queries or deterministic previews: get order, search staff, calculate refund preview.
Medium
Creates drafts or submits requests to your existing business workflow: create refund request, create approval request.
High
Immediate irreversible or sensitive side effects: execute refund, delete staff, change permissions, batch send messages.
Conditional
Use parameter-level confirmation when risk depends on amount, tenant, data scope, or affected count.
Business authority stays in your system
X-Bailing-Signature: sha256=<hmac> X-Bailing-Timestamp: 1782912000 X-Bailing-Tool: order.get X-Bailing-Job-Id: job_... X-Bailing-On-Behalf-Of: u_42
The hub decides whether the AI agent can reach a tool. Your backend decides whether u_42 can operate this specific business object right now.
Recommended tool shapes
| Shape | Examples | Recommended handling |
|---|---|---|
| Query | order.get, staff.search | low, read-only |
| Preview | refund.preview, delete.impact | Return impact summary before write |
| Request | refund.request.create | medium, business workflow handles approval |
| Execute | refund.execute, staff.delete | high or confirmation required |