kakuyomu-mcp exhibits significant definition quality gaps across multiple dimensions. All 5 tools have proper verb-starting names (get_, search_) and schema definitions with typed parameters. However, tool descriptions are brief but present (ranging 20-60 chars), and parameter descriptions are minimal or missing. The schema quality is variable: most tools have type-annotated parameters with basic descriptions, but lack depth in explaining semantics, constraints, and error conditions. Output is returned as plain text strings rather than structured JSON, limiting LLM composability. No tool annotations (readOnlyHint, idempotentHint, destructiveHint) are present. Error handling is minimal, catch-all exception handlers return generic error messages without actionable recovery guidance. The server targets a Japanese content aggregation domain (kakuyomu.jp) with domain-specific parameters (serial_status, genre_name, review_point_range), but constraint documentation is sparse. Parameter validation is implicit; no explicit enum enforcement or range validation is visible in the code.

• Refactor all tool return values from plain-text strings to structured JSON objects. Example: Instead of 'ID: 12345\nタイトル: Example Work', return {"id": "12345", "title": "Example Work", "catchphrase": "...", "introduction": "..."}. This enables LLMs to extract and chain results naturally.
• Add formal enum constraints for categorical parameters. Define serial_status with values like ["連載中", "完結", "一時休止"], genre_name with ["恋愛", "ファンタジー", "SF"], and include these in both the parameter descriptions and schema. Use JSON Schema 'enum' constraint.
• Expand parameter descriptions to 50-100 characters with format hints. Example for ex_q: 'Search exclusion query; e.g., "ロボット" to exclude robot-themed works. Pass as UTF-8 string.'
• Return pagination metadata in all list results. Add fields: {"total_count": 1000, "returned_count": 10, "next_page": 2, "has_more": true}. This lets LLMs know when to request the next batch.
• Improve error handling to be actionable. Instead of 'エラーが発生しました: Connection timeout', return '{"error": "timeout", "message": "Request to kakuyomu.jp timed out after 5s. Try again in 10s or reduce the limit parameter.", "retryable": true}'. Include error classification (retryable vs user-fixable vs fatal) and specific guidance.
• Add tool annotations to the @mcp.tool() decorators. Since all tools are read-only, mark each with readOnlyHint=True. Example: @mcp.tool(readOnlyHint=True). This signals to agents that calls are safe to retry or batch.
• Document output schema for each tool in a separate docstring or schema registry. Specify return type as JSON object with field types. Example for get_rankings: Returns a list of objects with fields {"rank": int, "id": str, "title": str, "author": str, "catchphrase": str, "tags": [str], "introduction": str}.

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

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