The server exposes 6 tools derived from Swagger/OpenAPI specs with reasonable naming (verb_noun pattern) and basic input schemas. However, descriptions are minimal (10-50 chars), parameter descriptions lack depth, and output schemas are not documented. Tools follow a consistent pattern but fall short of production-grade clarity. Parameter validation rules, format constraints, and recovery guidance are absent. The implementation generates tool definitions from Swagger but does not enrich them with LLM-optimized language.

• Expand tool descriptions to 80 - 200 characters. Example: 'listPets' → 'List all pets in the store, filtered by tags or limited to N results. Returns an array of pet objects with id, name, tag, and age. Call this first to discover available pets before getting details.'
• Add field-level descriptions to nested objects. For 'body' in createPet: { name: 'string (required, 1-255 chars)', tag: 'string (optional, e.g. "dog", "cat")', age: 'integer (optional, 0-50)' }.
• Document return schemas. E.g., 'Returns: { id: integer, name: string, tag: string, age: integer, createdAt: ISO8601 timestamp }'. Include all fields agents might need downstream.
• Add parameter bounds and format constraints in descriptions. E.g., 'limit' → 'Maximum number of results to return (1 - 100, default 20).'
• For listPets and searchPets, document pagination. E.g., 'Results are limited to 50 items per call. If more exist, use offset/limit or check the returned count to fetch additional pages.'
• For destructive tools (deletePet), add a dry-run parameter or confirm-before-execute pattern. Error message should guide recovery: 'Pet with ID 123 not found. Call listPets to verify the pet exists before retrying.'
• Register tools with explicit tool annotations during tool creation. Mark read-only tools with readOnlyHint=true, destructive operations with destructiveHint=true.
• In code (mcp/server.go RegisterTools method), enrich the Swagger-to-MCP converter to add LLM-friendly descriptions, parameter annotations, and output schema documentation before registering with the MCP server.