{"paper":{"title":"Making OpenAPI Documentation Agent-Ready: Detecting Documentation and REST Smells with a Multi-Agent LLM System","license":"http://creativecommons.org/licenses/by-nc-nd/4.0/","headline":"OpenAPI documentation valid for microservices often lacks the semantic structure needed for AI agents.","cross_cats":[],"primary_cat":"cs.SE","authors_text":"Davi G. Assun\\c{c}\\~ao Pinheiro, Rayfran Rocha Lima, Thiago Medeiros de Menezes","submitted_at":"2026-05-14T03:23:51Z","abstract_excerpt":"The growing adoption of AI agents and the Model Context Protocol (MCP) has motivated organizations to expose existing REST APIs as agent-consumable tools. In our industrial context, this initiative targeted an ecosystem of 16 production APIs comprising approximately 600 endpoints. Although these APIs were stable and widely used within a microservice architecture, early proof-of-concept experiments revealed systematic failures in task planning, tool selection, and payload construction when accessed through MCP-based agents. Rather than attributing these failures to model limitations alone, we c"},"claims":{"count":4,"items":[{"kind":"strongest_claim","text":"structural validity within microservice environments does not guarantee semantic readiness for agent-based consumption","source":"verdict.strongest_claim","status":"machine_extracted","claim_id":"C1","attestation":"unclaimed"},{"kind":"weakest_assumption","text":"That the smells identified by the multi-agent LLM system are the main cause of observed agent failures and that practitioner agreement sufficiently validates their relevance without quantitative before-after agent performance data.","source":"verdict.weakest_assumption","status":"machine_extracted","claim_id":"C2","attestation":"unclaimed"},{"kind":"one_line_summary","text":"Hermes uses multi-agent LLMs to detect 2450 documentation and REST smells across 600 OpenAPI endpoints, demonstrating that structurally valid microservice APIs are often not semantically ready for agent consumption.","source":"verdict.one_line_summary","status":"machine_extracted","claim_id":"C3","attestation":"unclaimed"},{"kind":"headline","text":"OpenAPI documentation valid for microservices often lacks the semantic structure needed for AI agents.","source":"verdict.pith_extraction.headline","status":"machine_extracted","claim_id":"C4","attestation":"unclaimed"}],"snapshot_sha256":"eb6d1d94a764855c5f354bea3d1852425331cf4747ef026226a93e3bf4477b11"},"source":{"id":"2605.14312","kind":"arxiv","version":1},"verdict":{"id":"26777a92-8c9b-4eff-a1e1-4532102cb7cc","model_set":{"reader":"grok-4.3"},"created_at":"2026-05-15T02:41:59.087149Z","strongest_claim":"structural validity within microservice environments does not guarantee semantic readiness for agent-based consumption","one_line_summary":"Hermes uses multi-agent LLMs to detect 2450 documentation and REST smells across 600 OpenAPI endpoints, demonstrating that structurally valid microservice APIs are often not semantically ready for agent consumption.","pipeline_version":"pith-pipeline@v0.9.0","weakest_assumption":"That the smells identified by the multi-agent LLM system are the main cause of observed agent failures and that practitioner agreement sufficiently validates their relevance without quantitative before-after agent performance data.","pith_extraction_headline":"OpenAPI documentation valid for microservices often lacks the semantic structure needed for AI agents."},"references":{"count":26,"sample":[{"doi":"","year":2024,"title":"Abdullah AH Alzahrani. 2024. Software Systems Documentation: A Systematic Review.International Journal of Advanced Computer Science & Applications15, 8 (2024)","work_id":"bff96b08-6456-4d20-bad2-12cb5e21376e","ref_index":1,"cited_arxiv_id":"","is_internal_anchor":false},{"doi":"","year":2024,"title":"Anthropic. 2024. Model Context Protocol (MCP). https://modelcontextprotocol. io","work_id":"7ad6fe16-3b52-4036-a536-8093de804928","ref_index":2,"cited_arxiv_id":"","is_internal_anchor":false},{"doi":"","year":2025,"title":"Jayachandu Bandlamudi, Ritwik Chaudhuri, Neelamadhav Gantayat, Sambit Ghosh, Kushal Mukherjee, Prerna Agarwal, Renuka Sindhgatta, and Sameep Mehta. 2025. A framework for testing and adapting rest apis","work_id":"112b4480-d998-41ee-8a33-1807c5c8c0f7","ref_index":3,"cited_arxiv_id":"","is_internal_anchor":false},{"doi":"","year":2021,"title":"Sandra Casas, Diana Cruz, Graciela Vidal, and Marcela Constanzo. 2021. Uses and applications of the OpenAPI/Swagger specification: a systematic mapping of the literature. In2021 40th International Con","work_id":"aea476e5-9e19-4400-a260-4b0fe02a52f4","ref_index":4,"cited_arxiv_id":"","is_internal_anchor":false},{"doi":"","year":2023,"title":"Michael Coblenz, Wentao Guo, Kamatchi Voozhian, and Jeffrey S. Foster. 2023. A Qualitative Study of REST API Design and Specification Practices. In2023 IEEE Symposium on Visual Languages and Human-Cen","work_id":"98b64b9d-ce4c-4167-bb31-0fd727bb279c","ref_index":5,"cited_arxiv_id":"","is_internal_anchor":false}],"resolved_work":26,"snapshot_sha256":"aadeb5351e5be7cb7bc779a65751a420eecc02ce7f10dc064bf1181341ff5a6b","internal_anchors":2},"formal_canon":{"evidence_count":0,"snapshot_sha256":"258153158e38e3291e3d48162225fcdb2d5a3ed65a07baac614ab91432fd4f57"},"author_claims":{"count":0,"strong_count":0,"snapshot_sha256":"258153158e38e3291e3d48162225fcdb2d5a3ed65a07baac614ab91432fd4f57"},"builder_version":"pith-number-builder-2026-05-17-v1"}