Skip to content

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


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.