Methodology
OpenAPI actionability quality
ia.openapi-quality · 4.17
Act
SHOULD
Recommendation
AR-ACT-02
Why it matters
An OpenAPI document helps agents only when each operation is concrete. Agents need operationId, descriptions, typed parameters and response schemas to make a correct call.
How to fix it
Give each operation an operationId, a description, typed parameters and response schemas.
-
Add a unique operationId and a description to each operation.
-
Add a schema with a type to each parameter and each response.
"parameters": [{"name": "q", "in": "query", "required": true, "schema": {"type": "string"}}]
Verify
curl -sf https://{domain}/openapi.json | jq -e '[.paths[][] | objects | has("operationId")] | all'
Expected: exit code 0
Run a new scan for this checkpoint:
isagentready results {domain} --checkpoint ia.openapi-quality
Details Mapping, lifecycle and references
- AR mapping
- Full match
- Evidence source
- agentready.org AR-ACT-02
- Score role
- Core
- Introduced
- 2026-08-24
- Revised
- 2026-08-29
- Methodology version
- 2026-10-22