The server provides 6 READ_ONLY tools for querying the Shahnameh Persian epic. While all tools have descriptions and basic input schemas, there are significant quality gaps: (1) Parameter descriptions are minimal and lack detail about format/constraints; (2) Output schemas are completely undocumented, the code returns `Any` type with no schema specification; (3) Error handling is generic (returns plain text strings like 'Unable to fetch chapters or no chapters found' with no recovery guidance); (4) No pagination support despite tools that could return large result sets (get_chapters, list_verses_by_substrings); (5) Tool descriptions lack WHEN/WHY context for LLM selection; (6) No optional parameter validation or format constraints; (7) Descriptions present but below production baseline of 194 chars average. Tool naming is reasonable (get_*, list_*, search_*) but descriptions fail to meet the 'what, when, why' pattern expected for production tools.

• Document return type and schema for each tool. Example for get_chapters: Return type should be {chapters: [{id: string, title: string, parent_id?: string, sub_chapters?: array}], total: number}. Use explicit JSON Schema in tool registration.
• Expand parameter descriptions with format and constraints. Example: 'title (string, 1-100 chars, matched case-insensitively), filters chapters by title. Leave empty to retrieve all chapters.' for get_chapters.
• Add limit and offset/page_size parameters to list_chapter_verses, list_verses_by_substrings, and get_chapters. Document default limit (suggest 20-50) and max limit (suggest 100).
• Enhance error handling: Distinguish HTTP status codes (404 → 'Chapter not found. Try searching chapters by title.'; 500 → 'Service temporarily unavailable, retry in a few seconds'; timeout → 'Request timed out after 30s, server may be overloaded'). Return structured error objects with 'type', 'message', and 'recovery_suggestion' fields.
• Add WHEN/WHY context to tool descriptions. Example for search_explanations: 'Use this when you want semantic/conceptual explanations of events or characters (supports partial matching and context). Use get_chapter_by_id for exact chapter lookup by ID.'
• Implement input validation in each tool function. Example: validate id parameter is non-empty before calling HTTP endpoint. Return 'Invalid chapter_id: must be non-empty string' rather than silently failing.
• Add per-result metadata to list operations. Include 'total_count' and 'has_more' in responses to guide pagination. Example: {verses: [...], total_count: 512, has_more: true, next_offset: 20}.