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-operation-ids

    OpenAPI has operationIds

    What it checks

    AI agents use operationIds as stable function names when calling your API. Without unique operationIds, agents must guess endpoint names from paths, leading to ambiguity and errors. An operationId that is not a legal function name — spaces, punctuation, or more than 64 characters — cannot be registered as a tool at all.

    Why it matters

    A tool-calling runtime uses operationId as the function name it exposes to the model, so duplicate ids collide into one name and ids that violate the runtime’s function-name pattern (^[a-zA-Z0-9_-]{1,64}$) are rejected at tool-registration time.

    Evidence

    • Microsoft 365 Copilot states: “Operation IDs are unique identifiers for an operation in the API and are used by Copilot to create functions that are executed when responding to a user’s prompt”. It adds that “Operation IDs are shown during debugging as functions to indicate which operations Copilot is attempting to execute” — learn.microsoft.com/…/openapi-document-guidance (verified 2026-08-21)
    • Anthropic tool definitions: name “Must match the regex ^[a-zA-Z0-9_-]{1,64}$” — an operationId carrying spaces, punctuation, or more than 64 characters cannot be registered verbatim as a tool name — platform.claude.com/…/define-tools (verified 2026-08-21)
    • Gemini function calling consumes only “a subset of the OpenAPI schema” and instructs “Use descriptive names without spaces or special characters” for function names — ai.google.dev/…/function-calling (verified 2026-08-21)
    • OpenAPI 3.1 on operationId: “Unique string used to identify the operation. The id MUST be unique among all operations described in the API”, and “Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions” — spec.openapis.org/…/v3.1.0.html (verified 2026-08-21)

    Limits

    operationId is optional in OpenAPI, and spec-to-tool converters routinely synthesize a name from the method and path when it is absent. A spec without operationIds is therefore degraded rather than unusable. That weakens the audit’s warn on missing ids. Conversely the constraint that genuinely breaks registration (character legality and length) is documented at grade A yet is not measured by this audit at all, so the check is graded on a mechanism it only partially exercises. (That last sentence is no longer true as of 2026-08-22 — see the fold below.)

    How it scores

    A named agent is documented to turn operationIds into the functions it calls, and the function-name constraint is published API contract. But the specification makes operationId optional, and generators synthesize one from the method and path. Absence therefore degrades naming rather than breaking the call.

    Example failure

    A site publishes /openapi.json whose operations carry operationId: "Get user's profile (v2)". The spaces, apostrophe and parentheses put it outside ^[a-zA-Z0-9_-]{1,64}$, so a tool-calling runtime cannot register the name and the operation is unreachable.

    A site that publishes no OpenAPI document — or one that declares no operations — is not a failure here. There are no operationIds to judge, so the audit returns “not applicable” and takes no weight off the score.

    A document whose paths is present and yields nothing readable is a different case. That document exists and is broken — "paths": ["get","post"] puts a string where a path item belongs, {"/x": {"get": "yes"}} puts one where an operation belongs — so it still fails, and the report names the defect. Absent means absent; present-and-broken is a finding.

    One broken entry does not erase the operations beside it. The ids that can be read are checked, and any entry that could not be read is named in the report rather than counted as a missing id.

    Sources