Three tools with basic schemas and descriptions, but significant gaps in parameter documentation and output schema clarity. Tool names follow verb_noun pattern (ReadOpenAPIDocument, ListAllAPIFromDocument, GetSingleAPIDetail), which is good. However, descriptions lack depth on WHEN to use each tool and what the output structure is. Parameter descriptions are minimal or missing. No error handling guidance. No tool annotations (readOnlyHint, etc.). Output schemas are not documented, LLMs cannot plan downstream calls or extract structured data reliably.

• Document the output schema for each tool. E.g., ListAllAPIFromDocument should return {apis: [{url: string, methods: [{method: string, description: string, ...}]}], totalCount: number}. This enables LLMs to plan multi-step workflows.
• Add readOnlyHint: true to all three tool definitions (via mark3labs/mcp-go server.Tool struct or equivalent) to signal safety and enable aggressive caching.
• Expand tool descriptions to 100 - 200 characters with explicit prerequisites and output hints. E.g., 'Lists all API endpoints and HTTP methods from the currently loaded OpenAPI document. Returns an array of {url, methods} objects. Call ReadOpenAPIDocument first.'
• Add format guidance to parameters. E.g., 'urlPath: The exact route path from the OpenAPI document (e.g., /users/{id}, /api/v1/posts). Use ListAllAPIFromDocument to discover valid paths.'
• Implement error recovery hints. E.g., if ReadOpenAPIDocument fails with 'file not found', return 'OpenAPI file not found at {path}. Verify the path is absolute or relative to the working directory. Common locations: ./openapi.yaml, /etc/api/openapi.json'.