osu-mcp has 11 well-named, read-only tools with consistent verb_noun naming (get_*, search_*). All tools have descriptions (avg ~80 chars, within baseline 34-392). Input schemas are present and use Zod with type constraints and enums. However, output schemas are NOT documented, responses are JSON-stringified without field-level documentation. Error handling is minimal (generic 'Error: {error}' messages with no recovery guidance). Parameter descriptions are adequate but lack format/constraint details (e.g., 'user' accepts username OR user ID but this is not stated). No tool annotations (readOnlyHint, etc.). Composition is sound, each tool has one responsibility, and tools chain naturally (e.g., get_user → get_user_scores). Baseline: avg tool description 194 chars; this server ~80 chars (below median but acceptable for domain-specific APIs).

• Document output schemas for each tool. Example: 'Returns {user: {id, username, pp, rank, country}, mode: string}'. This enables LLMs to extract and chain data.
• Replace generic error handling with actionable messages. Example: 'User not found. Try search_beatmapsets() with a partial name, or verify the user ID is numeric.'
• Clarify dual-mode parameters in descriptions. For get_user, state: 'user: Username (string) or user ID (numeric). If unsure, use username.'
• Add readOnlyHint annotations to all tools via MCP SDK. This declares intent and enables client-side safety checks.
• Add limit/offset parameters to search_beatmapsets and get_rankings, with defaults (e.g., limit=20, offset=0). Document in descriptions: 'Returns up to 20 results; use offset for pagination.'