AAK-MCP-OPENAPI-LAZY-DESCRIPTION-001: OpenAPI operation with missing or sub-40-char description (Hermes LAZY)
- Severity
- MEDIUM
- Category
- Tool Poisoning (
tool-poisoning) - Scanner
agent_audit_kit/scanners/openapi_smells.py- Auto-fixable
- No.
- SARIF name
OpenApiLazyDescription
What it detects
An OpenAPI 3.x operation has a missing or sub-40-character description field. Per Hermes (arXiv:2605.14312, EASE 2026), this is the most common smell in MCP-on-REST migrations — agents over-rely on operation descriptions to disambiguate tool choice, and sparse descriptions cause silent mis-routing. Hermes' large-scale evaluation found this smell across essentially every analyzed operation in the 600-endpoint corpus, with 2,450 smells total across the 3 classes (LAZY / BLOATED / TANGLED).
How to fix
Author a >=40-character description that names the operation's purpose, expected input shape, and side-effecting class. Agent tool-selection accuracy improves materially when descriptions disambiguate similar-looking operations.
To confirm the finding is gone, report only this rule:
agent-audit-kit scan . --rules AAK-MCP-OPENAPI-LAZY-DESCRIPTION-001
Limitations
Looks for the spec only at the project root (openapi.*, swagger.*, *.openapi.*) or under a top-level api/, openapi/, spec/ or docs/api/ folder; backend/openapi.yaml and docs/openapi.yaml are not found. A summary of 40 or more characters counts as the description. A spec over 1 MB is not read.
References
- Incidents and advisories: ARXIV-2605.14312
- CSA AI Controls Matrix (AICM): AIS-07
All rules. This page is generated from the rule registry when the documentation is built; to change it, change the rule in agent_audit_kit/rules/builtin.py. To give the rule a hand-written write-up, add docs/rules/AAK-MCP-OPENAPI-LAZY-DESCRIPTION-001.md: the page then shows that text, with the registry reference appended under it.