Opens in a new tabSkip to content
Agent LighthouseAgent Lighthouse

    Searches the text of every published page. The evidence sources themselves are not in this index — search all of them on the trusted sources page.

    GitHub ↗
    Browse checks and page contents
    agent-interfaces/openapi-description-quality

    OpenAPI description quality for tool-calling

    What it checks

    When an AI agent converts your OpenAPI spec into callable tools, the description fields become the prompt the LLM uses to decide when and how to call each function. A one-word description like “search” tells the model nothing about what the endpoint does, what the parameter means, or what values are valid — so the agent guesses, calls the wrong tool, or fills parameters with hallucinated values. Every operation and every parameter needs a verbose description (more than 15 characters) that explains purpose, expected input, and behavior.

    Why it matters

    When an OpenAPI document is converted into LLM-callable tools, the description text on the operation and its parameters becomes the tool and argument descriptions the model reads. It reads them when deciding which endpoint to call and what to pass. An operation with no human-readable text leaves the model with only the operationId to reason from.

    Evidence

    • FastMCP’s OpenAPI integration “creates MCP components using a variety of metadata from the OpenAPI spec, such as incorporating the OpenAPI description into the MCP component description”, and derives the tool name from the operationId — gofastmcp.com/…/openapi (verified 2026-08-21)
    • OpenAI GPT Actions consume an OpenAPI schema and “decide which API call is relevant to the user’s question and generate the json input necessary for the API call” — developers.openai.com/…/introduction (verified 2026-08-21)
    • Anthropic states the consuming behavior plainly: “Claude determines when to call a tool based on the user’s request and the tool’s description” — platform.claude.com/…/overview (verified 2026-08-21)
    • MCP’s tool shape confirms where that text lands: description is the “Human-readable description of functionality”, and per-property descriptions live in the inputSchema — modelcontextprotocol.io/…/tools (verified 2026-08-21)

    Limits

    The mechanism is proven for the described text, not for the description key specifically. OpenAPI 3.1 defines summary as “A short summary of what the operation does”, alongside description, “A verbose explanation of the operation behavior”; many specs carry only the former. The same document confirms that path-level parameters are inherited by operations — they “can be overridden at the operation level, but cannot be removed there” — and that parameters may be $ref-ed into components/parameters — spec.openapis.org/…/v3.1.0.html (verified 2026-08-21). A spec that is perfectly legible to a converter can therefore score 0% here. Nothing in any source supports the specific 15-character threshold, which measures length rather than informativeness.

    How it scores

    Every link in the chain is documented by a vendor: named converters map OpenAPI descriptions onto tool descriptions, and both OpenAI and Anthropic state that the model picks the call from those descriptions.

    Sources