ytm-mcp has 12 tools with basic schemas and descriptions, but significant gaps prevent production use. All tools have descriptions (10-80 chars, mostly short), and input schemas are present with type definitions. However, parameter descriptions are sparse or missing entirely. Most parameters lack guidance on valid ranges, formats, or dependencies. Output schemas are undocumented, LLMs cannot predict what fields to expect. Error handling is absent; no recovery guidance or actionable error messages. Tool naming is reasonable (verb_noun pattern), but composition issues exist: playback_control conflates 8 distinct actions into one tool, and download_history + download_song could be unified. No security annotations, no idempotency hints, no permission gates. Baseline: 549 production tools average 194 chars for descriptions and 72 chars per param; ytm-mcp averages ~40 chars for descriptions and most params lack any description text.

• Split playback_control into 8 separate tools (play_song, pause_playback, next_track, previous_track, toggle_shuffle, toggle_repeat, like_song, dislike_song) so each has one clear responsibility and LLMs can compose them independently.
• Document output schemas for all tools. For search_song, specify: returns array of {id, title, artist, url, duration}. For list_playlists, specify: returns array of {playlist_id, name, visibility, song_count}. For get_current_song, specify: returns {id, title, artist, album, duration_ms, is_playing}.
• Add descriptions to all parameters. For 'query' in search_song: 'Song name, artist, or album (e.g. "Bohemian Rhapsody" or "Queen")'. For 'format' in download_song: 'Audio format: opus (smaller, better quality) or mp3 (wider compatibility). Default: opus.'
• Add error handling with recovery guidance. Wrap tool implementations in try-catch; return structured errors like {status: 'error', code: 'NOT_FOUND', message: 'Song not found. Try search_song() with a different query.', retryable: false}.
• Add tool annotations to the MCP tool registration. Mark download_song, download_history, create_playlist, add_to_playlist with destructiveHint=true. Mark get_history, search_song, list_playlists, get_current_song with readOnlyHint=true. Mark idempotent operations (e.g. add_to_playlist with same song twice) with idempotentHint=true.