mcp-open-library demonstrates solid tool design with consistent naming conventions, complete input schemas, and clear descriptions. All 7 tools follow verb_noun naming (get_*, search_*) and include proper JSON Schema validation with type constraints. Descriptions are concise and actionable (avg ~150 chars). However, output schemas are not explicitly documented in the source code, and there is minimal error recovery guidance. Parameter descriptions are adequate but could be more explicit about constraints and expected formats. No tool annotations (readOnlyHint, etc.) are present despite all tools being read-only operations.

• Document output schemas explicitly in tool definitions. Include TypeScript interfaces or JSON Schema showing what fields each tool returns (e.g., author_info returns {key, name, birth_date, ...}, get_authors_by_name returns {num_found, offset, results: [{key, name, ...}]}). This enables agents to plan downstream calls and extract correct fields.
• Add readOnlyHint: true to all tool definitions. Mark all 7 tools as read-only in their annotations since they only query Open Library and do not modify any state. This signals to agents the calls are safe to make speculatively.
• Enhance error recovery guidance in descriptions. Add phrases like 'If no results found, try broadening the search terms' for search_books, and 'Pass the edition_key from search results to get_book_by_id for detailed edition info' for navigation hints.
• Clarify limit/offset edge cases in parameter descriptions. Specify: 'Passing offset beyond total results returns empty list', 'limit capped at 100 regardless of input', 'default limit is 10 if omitted'.
• Add constraint hints to ID parameters using pattern examples. Instead of bare 'OL\d+A' pattern, include in description: 'Must match pattern OL<digits>A (e.g., OL23919A for author IDs)' so LLMs understand valid formats.
• Document when to use get_authors_by_name vs search_books. Clarify that search_books is more flexible (searches across titles, subjects, places) while get_authors_by_name specifically searches author names only.