{"record_type":"pith_number_record","schema_url":"https://pith.science/schemas/pith-number/v1.json","pith_number":"pith:2026:FVP4O2IBWQZGDWGK5EXL4JO3HQ","short_pith_number":"pith:FVP4O2IB","schema_version":"1.0","canonical_sha256":"2d5fc76901b43261d8cae92ebe25db3c07920a78d049ea27c7f84180005bd253","source":{"kind":"arxiv","id":"2605.14312","version":1},"attestation_state":"computed","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"},"verification_status":{"content_addressed":true,"pith_receipt":true,"author_attested":false,"weak_author_claims":0,"strong_author_claims":0,"externally_anchored":false,"storage_verified":false,"citation_signatures":0,"replication_records":0,"graph_snapshot":true,"references_resolved":true,"formal_links_present":false},"canonical_record":{"source":{"id":"2605.14312","kind":"arxiv","version":1},"metadata":{"license":"http://creativecommons.org/licenses/by-nc-nd/4.0/","primary_cat":"cs.SE","submitted_at":"2026-05-14T03:23:51Z","cross_cats_sorted":[],"title_canon_sha256":"8d91f7ba1dac19331e8e03876ab4f2521f2ea5b10ddbfd80060feec849dd81d7","abstract_canon_sha256":"9c069f8ff2066f2f5340401d1e7175511bead030aa02bf56b9dbd75f9a6959d6"},"schema_version":"1.0"},"receipt":{"kind":"pith_receipt","key_id":"pith-v1-2026-05","algorithm":"ed25519","signed_at":"2026-05-17T23:39:09.982620Z","signature_b64":"V9fUC01k1ZAmXf6+BXiNl5wk0Dp6DjwtohN3Oq/9SMF40F/pyjDpn4GKzEePAx2+m7kNcrvQg9OoDAh0DiNkDQ==","signed_message":"canonical_sha256_bytes","builder_version":"pith-number-builder-2026-05-17-v1","receipt_version":"0.3","canonical_sha256":"2d5fc76901b43261d8cae92ebe25db3c07920a78d049ea27c7f84180005bd253","last_reissued_at":"2026-05-17T23:39:09.982150Z","signature_status":"signed_v1","first_computed_at":"2026-05-17T23:39:09.982150Z","public_key_fingerprint":"8d4b5ee74e4693bcd1df2446408b0d54"},"graph_snapshot":{"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"},"aliases":[{"alias_kind":"arxiv","alias_value":"2605.14312","created_at":"2026-05-17T23:39:09.982226+00:00"},{"alias_kind":"arxiv_version","alias_value":"2605.14312v1","created_at":"2026-05-17T23:39:09.982226+00:00"},{"alias_kind":"doi","alias_value":"10.48550/arxiv.2605.14312","created_at":"2026-05-17T23:39:09.982226+00:00"},{"alias_kind":"pith_short_12","alias_value":"FVP4O2IBWQZG","created_at":"2026-05-18T12:33:37.589309+00:00"},{"alias_kind":"pith_short_16","alias_value":"FVP4O2IBWQZGDWGK","created_at":"2026-05-18T12:33:37.589309+00:00"},{"alias_kind":"pith_short_8","alias_value":"FVP4O2IB","created_at":"2026-05-18T12:33:37.589309+00:00"}],"events":[],"event_summary":{},"paper_claims":[],"inbound_citations":{"count":0,"internal_anchor_count":0,"sample":[]},"formal_canon":{"evidence_count":0,"sample":[],"anchors":[]},"links":{"html":"https://pith.science/pith/FVP4O2IBWQZGDWGK5EXL4JO3HQ","json":"https://pith.science/pith/FVP4O2IBWQZGDWGK5EXL4JO3HQ.json","graph_json":"https://pith.science/api/pith-number/FVP4O2IBWQZGDWGK5EXL4JO3HQ/graph.json","events_json":"https://pith.science/api/pith-number/FVP4O2IBWQZGDWGK5EXL4JO3HQ/events.json","paper":"https://pith.science/paper/FVP4O2IB"},"agent_actions":{"view_html":"https://pith.science/pith/FVP4O2IBWQZGDWGK5EXL4JO3HQ","download_json":"https://pith.science/pith/FVP4O2IBWQZGDWGK5EXL4JO3HQ.json","view_paper":"https://pith.science/paper/FVP4O2IB","resolve_alias":"https://pith.science/api/pith-number/resolve?arxiv=2605.14312&json=true","fetch_graph":"https://pith.science/api/pith-number/FVP4O2IBWQZGDWGK5EXL4JO3HQ/graph.json","fetch_events":"https://pith.science/api/pith-number/FVP4O2IBWQZGDWGK5EXL4JO3HQ/events.json","actions":{"anchor_timestamp":"https://pith.science/pith/FVP4O2IBWQZGDWGK5EXL4JO3HQ/action/timestamp_anchor","attest_storage":"https://pith.science/pith/FVP4O2IBWQZGDWGK5EXL4JO3HQ/action/storage_attestation","attest_author":"https://pith.science/pith/FVP4O2IBWQZGDWGK5EXL4JO3HQ/action/author_attestation","sign_citation":"https://pith.science/pith/FVP4O2IBWQZGDWGK5EXL4JO3HQ/action/citation_signature","submit_replication":"https://pith.science/pith/FVP4O2IBWQZGDWGK5EXL4JO3HQ/action/replication_record"}},"created_at":"2026-05-17T23:39:09.982226+00:00","updated_at":"2026-05-17T23:39:09.982226+00:00"}