{"id":"ia.openapi-quality","name":"OpenAPI actionability quality","verify":{"command":"curl -sf https://{domain}/openapi.json | jq -e '[.paths[][] | objects | has(\"operationId\")] | all'","rescan":"isagentready results {domain} --checkpoint ia.openapi-quality","expect":"exit code 0"},"fix":{"steps":[{"action":"Add a unique operationId and a description to each operation.","order":1,"language":null,"code_example":null},{"action":"Add a schema with a type to each parameter and each response.","order":2,"language":"json","code_example":"\"parameters\": [{\"name\": \"q\", \"in\": \"query\", \"required\": true, \"schema\": {\"type\": \"string\"}}]"}],"summary":"Give each operation an operationId, a description, typed parameters and response schemas.","skill":{"name":"agent-protocols","anchor":"ia.openapi-quality"}},"category":"agent_protocols","aggregate":null,"references":[{"title":"OpenAPI Specification","kind":"spec","url":"https://spec.openapis.org/oas/latest.html"}],"stage":"act","lifecycle":{"introduced":"2026-08-24","revised":["2026-08-29"],"retired":null,"replaced_by":null},"methodology_version":"2026-10-22","evidence_tier":"standard","evidence_source":{"title":"agentready.org AR-ACT-02","url":"https://www.agentready.org/#act"},"why":"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.","profiles":["api_tool_readiness","agentic_commerce"],"score_role":"core","legacy_id":"4.17","i18n":{"nl":{"name":"Bruikbaarheid van OpenAPI","steps":["Voeg een unieke operationId en een beschrijving toe aan elke operatie.","Voeg aan elke parameter en elke response een schema met type toe."],"why":"Een OpenAPI-document helpt agents alleen als elke operatie concreet is. Agents hebben operationId, beschrijvingen, getypeerde parameters en responseschema's nodig voor een correcte call.","fix_summary":"Geef elke operatie een operationId, een beschrijving, getypeerde parameters en responseschema's.","verify_expect":"exitcode 0"}},"ar_practice_ids":["AR-ACT-02"],"strength":"SHOULD","ar_mapping":"full","evidence_type":"recommendation","detail_url":"https://isagentready.com/en/methodology/checkpoints/ia.openapi-quality","maturity":"recommended","applicability":{"mode":"detected_surface","condition":null,"surfaces":["api","commerce"]}}