swagger-mcp has critical definition gaps. Tool descriptions are minimal (10-50 chars, well below the 194-char baseline). The makeRequest tool lacks parameter descriptions entirely, 'path', 'method', 'parameters', and 'body' have no guidance on format, constraints, or valid values. Input schemas exist but are incomplete: 'body' is typed as 'unknown' with no structure; 'parameters' uses additionalProperties:true without field guidance. No output schema is documented. Error handling returns raw error text without recovery guidance. The loadSwaggerDoc tool is redundant with the resource endpoint. No tool annotations (readOnlyHint, destructiveHint) despite makeRequest being a WRITE operation.

• Add 150-250 char descriptions to both tools. For makeRequest: 'Make an HTTP request to a Swagger-documented API endpoint. Validates path and method against the spec. Supports query/path parameters and JSON request bodies. Requires SWAGGER_URL to be configured. Modifies state if method is POST/PUT/DELETE/PATCH.'
• Document all makeRequest parameters: path='API endpoint path from Swagger spec (e.g. /users/{id})'; method='HTTP verb: GET, POST, PUT, DELETE, PATCH (case-insensitive)'; parameters='Object mapping path/query param names to values (e.g. {id: "123", limit: 10})'; body='JSON request body for POST/PUT/PATCH (optional, omit for GET/DELETE)'.
• Add tool annotations: makeRequest with destructiveHint=true (for POST/PUT/DELETE/PATCH); loadSwaggerDoc with readOnlyHint=true.
• Document output schema: makeRequest returns {status: number, headers: object, body: unknown, error?: string}. loadSwaggerDoc returns {spec: object, version: string, paths: string[]}.
• Add error recovery guidance: 'Path not found' → 'Call loadSwaggerDoc to see available paths'; 'Method not supported' → 'Check Swagger spec for allowed methods on this path'; 'Request failed' → 'Verify parameters match spec schema and auth token is valid'.