NaviGravity presents a moderately well-structured MCP server for Navidrome music curation with 17 tools. Strengths: all tools have descriptions (most 50-150 chars), most input parameters are typed and include descriptions, and tool names follow verb_noun conventions appropriately. Schema definitions are visible for all tools and include enums, minimums, maximums where applicable. Weaknesses: output schemas are not documented anywhere in the source, LLMs cannot predict what fields each tool returns, forcing them to guess downstream field names and types for chaining. Error handling is absent, no indication of how failures are communicated, what's retryable, or how to recover. Parameter descriptions lack constraint details (e.g., 'limit' fields say 'default 20, max 500' but no explanation of why or consequences). No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear READ_ONLY vs WRITE distinctions. Some tools accept ambiguous or overloaded parameters (e.g., 'playlist_id' and 'playlist_name' in get_playlist should clarify precedence). Logging infrastructure is present and JSON-formatted, but no audit trail tie-back to tool invocations per the pattern:audit-trail baseline.

• Add output schema documentation for ALL tools. For each tool, explicitly document the structure of the returned JSON, including field names, types, and any nested objects. E.g., get_song_details returns {id, title, artist, album, year, genre, duration, bpm, play_count, last_played, starred, rating, comment, path}, types and whether fields can be null.
• Implement error handling with actionable recovery guidance. Define error categories: NOT_FOUND (suggest available alternatives), INVALID_INPUT (show valid options), PERMISSION_DENIED (suggest an authorization tool if available), TIMEOUT (suggest retry with backoff), BACKEND_ERROR (generic, not retryable, suggest contacting admin). Return errors as structured JSON: {error: {code, message, recovery_hint}}.
• Add tool annotations to all tool definitions. For each WRITE tool (create_playlist, star_song, rate_song, etc.), add destructiveHint=true. For each READ_ONLY tool, add readOnlyHint=true. Mark idempotent tools (e.g., star_song is idempotent, calling twice has same effect as once) with idempotentHint=true.
• Document parameter precedence and mutual exclusivity. For get_playlist, explicitly state: 'If both playlist_id and playlist_name are provided, playlist_id takes precedence. If neither is provided, returns an error requesting one.' For any other multi-param tools, apply the same discipline.
• Enrich limit/page parameters with explanations. Instead of 'Maximum number of songs to return (default 20, max 500)', write: 'Maximum number of songs to return. Default 20 for fast responses; increase up to 500 for comprehensive results. Note: very large results may slow down agent reasoning and increase token usage. Recommended: 20-50.'

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

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