ao3-mcp has well-structured tool definitions with detailed parameter descriptions and clear naming. All 5 tools follow verb_noun convention (search_works, find_tags, get_work, read_works, get_work_text). Parameter descriptions are comprehensive, especially for search_works which documents AO3 query syntax extensively. However, output schemas are not formally documented, responses are returned as strings rather than structured objects. Error handling is minimal; no recovery guidance or error classification. The server lacks tool annotations (readOnlyHint, destructiveHint) despite all tools being read-only. Descriptions are strong (100-300+ chars) but output structure documentation is absent.

• Document output schemas for all tools. Define the structure of search_works results (array of work objects with fields: work_id, title, authors, fandoms, rating, words, kudos, hits, summary, etc.). Use JSON Schema format in tool definitions.
• Add readOnlyHint annotation to all 5 tools in FastMCP registration: @mcp.tool(readOnlyHint=True). This signals to agents that these tools are safe to call without side effects.
• Implement structured error responses with recovery guidance. E.g., 'API throttled. Retry after 60 seconds.' or 'No results found. Try broader wildcards or fewer filters.' Return error objects with code, message, and retry_after fields.
• Add parameter constraints to read_works: document max query length, expected format (question/prompt), and warn that GEMINI_API_KEY must be set at runtime. Add a note: 'If reader returns no text, the fic may contain explicit content, retry or use get_work_text.'
• Enhance search_works pagination: return total_results and has_more fields so LLM knows if additional pages exist. Document that max 5 pages = max 100 results per call, and suggest batching searches across multiple calls if broader discovery needed.