The mcp-openapi-server defines 3 tools for OpenAPI endpoint discovery and invocation. Naming follows verb_noun patterns (list-, get-, invoke-), which is appropriate. However, critical gaps exist across descriptions, parameter documentation, and schema completeness. Tool descriptions are present but generic. Most critically, the invoke-api-endpoint tool has severely incomplete schema definition: its 'params' parameter is defined as type 'object' with empty properties {}, providing no guidance on what fields are valid or required. Parameter descriptions are minimal or missing. No output schemas are documented. Error handling and recovery guidance are absent. The tools lack the structured, LLM-optimized documentation needed for confident agent selection and execution.

• Document the output schema for each tool. E.g. list-api-endpoints should return: {endpoints: [{path: string, method: string, summary?: string}, ...], total: number}. This enables LLMs to chain tools and extract the right data.
• Expand the description of invoke-api-endpoint to explain that it dynamically invokes OpenAPI-spec endpoints, include what typical responses look like, and warn that destructive operations are allowed (e.g. DELETE, PUT).
• Replace the empty 'params' schema in invoke-api-endpoint with a properly structured definition. Fetch the OpenAPI spec's parameter definitions for the requested endpoint and pass them as the schema, or document that params must match the endpoint's schema from get-api-endpoint-schema.
• Add detailed parameter descriptions to get-api-endpoint-schema and invoke-api-endpoint clarifying that 'endpoint' is a path matching OpenAPI spec paths (e.g. '/users/{id}'), and optionally accept HTTP method if the spec defines multiple methods per path.
• Implement pagination for list-api-endpoints with limit and offset parameters, returning a total count. Document the default limit (e.g. 50) and max limit (e.g. 500).
• Add error handling that returns actionable messages. E.g. 'Endpoint /invalid/path not found in OpenAPI spec. Available paths: /users, /users/{id}, /posts. Try get-api-endpoint-schema for details on any path.'
• Add a dry_run boolean parameter to invoke-api-endpoint so agents can preview the call before executing. This prevents accidental data loss on destructive operations.

Inferred effective spec: <=2025-11-25.

• Relies on Stateful initialize / Mcp-Session-Id (removed; protocol is stateless) - make each request self-contained