Problem
A global capability list says what is possible in general, but not what is possible right now. An agent looking at a shipped order cannot tell whether it can still be cancelled without trying.
Context
Use this pattern when:
- Resources move through states (draft, submitted, shipped) and the allowed actions change with each one.
- Agents are making decisions turn by turn and benefit from knowing their options at each point.
Recommended solution
Include an actions collection in each resource response listing the actions currently permitted, with references to their contracts. Omit actions that are not available, or include them with an explicit reason.
This is the agent equivalent of disabling a button and showing a tooltip explaining why.
- 01Model resource states and the transitions each permits.
- 02Return currently available actions with each resource.
- 03Include unavailable actions with a reason when the reason is useful.
- 04Reference the same action names used in the capability manifest.
Interaction diagram
Example implementation
Illustrative exampleExamples use a fictional store and illustrative field names. Adapt the shape to your stack; the qualities matter more than the exact format.
{
"id": "ORD-1042",
"status": "shipped",
"actions": [
{ "name": "track_shipment", "available": true },
{ "name": "start_return", "available": true, "until": "2026-11-05" },
{
"name": "cancel_order",
"available": false,
"reason": "Orders cannot be cancelled after shipping. Use start_return instead."
}
]
}Accessibility and security
Accessibility
- The same reasons used to explain unavailable actions to agents can be shown to people as helper text next to disabled controls.
Security
- Computing available actions per request can leak information about other users' resources if not authorization-checked. Scope it to what the caller may see.
Related patterns
Applies the principles Explicit Capabilities and Transparent State.