osu-mcp demonstrates solid tool design with consistent naming (verb_noun pattern), comprehensive parameter schemas, and clear descriptions. All 12 tools follow the get_/search_ convention. Schemas are well-structured with proper types, enums, and constraints (e.g., difficulty_range, bpm_range as tuples; mode as enum). Descriptions average ~120 chars, meeting the 10-1024 baseline. However, output schemas are not documented, LLMs cannot predict response structure. Error handling exists but lacks recovery guidance. No tool annotations (readOnlyHint, idempotentHint) despite all tools being read-only. Parameter descriptions are present but could be more prescriptive about constraints (e.g., 'ISO 3166-1 alpha-2' is stated but not validated in description).

• Document output schemas for all 12 tools. Include field names, types, and nested structure. Example: 'Returns {beatmaps: [{id, title, difficulty, status, bpm, length}], total_count: int}'.
• Add tool annotations to server.py _bind_tool(). Set readOnlyHint=true and idempotentHint=true for all tools. This signals to LLMs that tools are safe to retry and do not modify state.
• Enhance error messages with recovery guidance. In client.py, catch NotFoundError and return: 'User not found. Try search_users() with a partial name.' instead of bare 404.
• Expand parameter descriptions with explicit validation rules. E.g., 'country_code: ISO 3166-1 alpha-2 code (exactly 2 uppercase letters, e.g., JP, US, EC). Invalid codes return 404.'
• Increase get_seasonal_backgrounds description to ~100 chars. Add context: 'Get the currently active seasonal backgrounds (rotates quarterly). Useful for UI theming or tracking seasonal events.'

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

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