Minimal spec
GET/.well-known/bailing/tools.json
{
"openapi": "3.1.0",
"info": { "title": "Order Tools", "version": "1.0.0" },
"paths": {
"/orders/{id}": {
"get": {
"operationId": "order.get",
"summary": "Get order details",
"x-ai-enabled": true,
"x-ai-scope": "order.read",
"x-ai-risk-level": "low",
"x-ai-requires-subject": true
}
}
}
}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
POSTBusiness tool endpoint
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 |