Apple Music MCP shows competent tool coverage (42 tools) with consistent naming patterns (verb_noun structure: get_, create_, add_, remove_, delete_, set_, play, pause, etc.). Most tools have descriptions and parameter types visible in schema declarations. However, significant gaps exist: (1) Output schemas are not documented, we cannot see what these tools return, only what they accept; (2) Parameter descriptions are present but many are generic or lack detail about format/constraints; (3) No evidence of error handling patterns or recovery guidance; (4) Some tools lack clear composition, duplicate functionality (search_library vs search_library_applescript, get_playlists_applescript vs get_library_playlists) without clear distinction; (5) Many AppleScript-dependent tools (26+ tools) are platform-gated but lack clear documentation of platform requirements in descriptions; (6) Security concern: no visible evidence of secret injection for API tokens, auth appears to be handled at server init, but tool descriptions don't clarify. Baseline: production A+ tools average 194 chars for descriptions; many here are 50-100 chars, providing minimal context. Schema completeness: input schemas are present for all tools, but output schemas (critical for LLM planning) are completely absent from visible code.

• Document ALL output schemas. For every tool, publish: what fields it returns, their types, which fields are guaranteed, which are optional. Use a structured format (JSON Schema or markdown table). This is critical for LLM reasoning and downstream tool chaining.
• Rename duplicate tools to eliminate confusion. Consolidate 'search_library' + 'search_library_applescript' into one 'search_library' with a parameter '--applescript' or internal platform detection. Same for get_playlists, get_playlist_tracks. LLMs shouldn't have to reason about which to pick.
• Add platform constraints to descriptions upfront. Every macOS-only tool should begin: '(macOS only; uses AppleScript)'. Every API-only tool should note '(cross-platform; requires MusicKit authorization)'. This prevents wasted calls on incompatible platforms.
• Expand descriptions to 150-250 chars minimum, following baseline production standards. For each tool, answer: What does it do? When/why should the agent call it? What important fields does it return? What should the agent do next? E.g., 'Get the currently playing track (cross-platform). Returns track name, artist, album, current time. Use before seeking/rating to confirm what's playing.'
• Add error handling guidance to each tool description. Specify: what errors can occur (auth failure, network error, not found, permission denied, invalid parameter), are they retryable, what should the agent do? E.g., '(Network errors are transient; retry after 2s. If auth fails, call check_auth_status first.)'