The server exposes two READ_ONLY tools with complete input schemas and type definitions. Both tools have descriptions and properly constrained numeric parameters (limit 1-100, max_chars 200-8000). However, descriptions are minimal (under 100 chars each), lack context on when to use each tool and how they differ, and do not explain dependency relationships or recovery strategies. Output schemas are documented in code (ExcerptOutput, FulltextSearchOutput) but descriptions lack guidance on field meanings and chaining behavior. Error handling exists but is generic ('Excerpt retrieval failed: {type}') without actionable recovery hints. No tool annotations (readOnlyHint, idempotentHint) are visible, though the tools are clearly read-only. The naming is verb-forward (calibre_get_excerpt, calibre_fulltext_search) and unambiguous. Composition is sound, each tool has one clear responsibility, and both accept human-friendly inputs (ISBN, query string). Overall, the tools are functional and schema-complete, but descriptions and error messaging fall short of production-grade LLM-optimized tooling.

• Expand tool descriptions to 150-200 chars. Example: 'calibre_fulltext_search: Search the Calibre library using full-text query syntax. Returns snippets of matching books with ISBN and title. Use this to discover relevant books; use calibre_get_excerpt to fetch longer passages from a specific ISBN.'
• Document output fields. Add to ExcerptOutput docstring: 'source_hint (str|null): Name or type of the document source (e.g., "Chapter 5", "PDF page 42"). snippet/text (str): The actual excerpt text, up to max_chars length.'
• Implement actionable error messages. Replace 'Excerpt retrieval failed: FileNotFoundError' with 'Calibre library not found at {library_path}. Verify MCP_CALIBRE_ROOT environment variable is set correctly.'
• Add tool annotations via FastMCP decorator or schema. Mark both tools with readOnlyHint=True and idempotentHint=True to guide client caching and retry logic.
• Add pagination to calibre_fulltext_search. Return {hits: [...], total_matches: <int>, next_offset: <int|null>} to enable agents to fetch additional results. Update description: 'Returns up to limit results; use offset parameter to fetch subsequent batches.'
• Clarify the 'around' parameter. Description should read: 'Optional text fragment to locate in the book. If provided, the returned excerpt will be positioned around the first occurrence of this text. If the fragment is not found, a default excerpt from the start of the book is returned.'
• Add dependency hints to descriptions. E.g., 'To fetch a longer excerpt, first use calibre_fulltext_search to find the book's ISBN, then call this tool.'

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry