Knowshelf provides two read-only tools with complete JSON schemas and detailed descriptions in Chinese. Both tools have proper input schemas with type definitions, required fields, and constraints (e.g., minLength, maxItems). Descriptions are substantive (150-250 chars) and explain WHEN to use each tool and dependencies between them. However, output schemas are not documented, LLMs cannot predict response structure. Parameter descriptions are present but could be more explicit about format/constraints. No error handling guidance, no tool annotations (readOnlyHint), and no pagination support despite query potentially returning many results.

• Document output schema for query: specify fields (id, summary, metadata, score, recallExplanation), types, and nesting. Example: {results: [{id: int, summary: string, metadata: object, score: float, recallExplanation: string}], total: int}
• Add pagination to query: include limit parameter with default (e.g., 20) and max (e.g., 100), and return total count or next_cursor in response. State in description: 'Results are paginated; default limit=20, max=100.'
• Add error handling guidance: document what happens if question is empty after trim, if bookID is invalid, if no results match. Example: 'If no results found, try rewrittenQueries or remove bookID filter to search all books.'
• Add tool annotations: set readOnlyHint=true on both tools in the MCP server registration to signal safety and enable client optimizations.
• Enhance parameter descriptions with explicit constraints: 'question (string, 1-1000 chars after trim): the user's original question. Server trims whitespace; empty after trim returns error.' Similarly for rewrittenQueries and hypotheticalAnswer.

Inferred effective spec: 2026-07-28+.

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