The server provides 18 tools with consistent naming conventions (verb_noun pattern: getAlbums, playMusic, createPlaylist, etc.), clear descriptions, and well-structured input schemas. However, there are significant gaps in output schema documentation, limited error handling guidance, and missing tool annotations. Most tool descriptions are concise (30-100 chars) but lack context about when to use them vs. similar tools. Parameter schemas are properly typed with good constraints (enums, min/max, optional flags), but descriptions could be more detailed about expected formats and dependencies. No tool-level metadata about permissions, idempotency, or destructiveness.
Tools (18)
addToQueuewriteauthsource verified73/100
Adds a track, album, artist or playlist to the playback queue
Output schemas not documented. No visible documentation of what fields are returned by each tool, forcing LLMs to guess at response structure and complicating downstream tool chaining. Pattern baseline: 100% of A+ tools have documented return types.
Tool descriptions lack selection context. Descriptions state WHAT tools do but not WHEN to use them vs. similar tools (e.g., searchSpotify vs. getMyPlaylists, playMusic vs. addToQueue). LLMs cannot distinguish between tools without explicit context. Pattern baseline: average tool description length 194 chars; these are 30-100 chars and generic.
Document output schemas for all 18 tools. Add a schema section to each tool definition showing returned fields, types, and descriptions (e.g., getAlbums returns [{id, name, release_date, total_tracks, images, ...}, ...]). This is required for LLMs to plan chained calls.
Expand descriptions from 30-100 chars to 100-250 chars following pattern:tool-description. Include: (1) what it does, (2) when to use vs. similar tools, (3) what preconditions must hold, (4) example success response fields. E.g., 'playMusic: Start playback of a track, album, artist, or playlist on the user\'s active or specified Spotify device. Use this to initiate playback; use pausePlayback to pause without stopping. Requires active Spotify app or device. Returns: {is_playing, currently_playing_type, item}.'
Add tool annotations: mark WRITE tools with idempotentHint:false (playMusic, createPlaylist, skipToNext) to warn LLMs against retrying without verification. Mark createPlaylist, addTracksToPlaylist, updatePlaylistDetails with destructiveHint:true to trigger confirmation patterns. Mark all READ tools with readOnlyHint:true.
Clarify parameter relationships and defaults: For playMusic and addToQueue, document that uri overrides type+id if both provided. For all deviceId params, state 'If omitted, Spotify uses the user\'s currently active device. Returns error if no device is active.' For limit params in search/list tools, add 'Default: 20. Max: 50 for API compliance.'
Add error recovery hints to tool descriptions. E.g., playMusic: 'Common failures: (1) No active device, call getDevices() first or activate a Spotify app. (2) Invalid URI, verify format spotify:track:<id>. (3) Premium only, basic accounts cannot control playback. (4) Rate limited, retry after 30s.' This guides LLM error handling.
Score history
Overall score trend
↑ 53 points across a rubric change (v1 → v2)
53/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
D
53
2026-07-28+
v2
2026-03-09
F
0
-
v1
Get a list of the current user's playlists on Spotify
getNowPlayingread onlyauthsource verified75/100
Get information about the currently playing track on Spotify
No error handling guidance. Tools provide no recovery hints for common failures (device not found, network errors, permissions denied, invalid URI format). LLMs have no path forward on error. Pattern baseline: error responses must tell LLM what to do next.
Parameter descriptions incomplete for optional fields. Many optional parameters (e.g., deviceId in playMusic, position in addTracksToPlaylist) lack details about defaults, side effects, or when to omit. LLMs cannot reason about which parameters to include.
No pagination limit enforcement documented. searchSpotify, getMyPlaylists, getPlaylistTracks, getRecentlyPlayed accept limit parameters but no upper bound guidance (e.g., 'max 50'). Pattern baseline: cap results at 20-50 and state limit in description.
Ambiguous parameter semantics in playMusic and addToQueue. Both accept uri, type, and id simultaneously with unclear conflict resolution (uri overrides type/id?). No description clarifies which takes precedence or what happens if both are provided.
Missing device/playback context hints. Many WRITE tools (playMusic, pausePlayback, skipToNext, etc.) accept optional deviceId but do not explain what happens if omitted (uses active device? defaults to primary? errors?). LLM cannot predict behavior.
Implement idempotency keys or deduplication for playlist operations. createPlaylist should accept an optional idempotency_key to prevent duplicate playlists on retry. addTracksToPlaylist should validate duplicates and return which tracks were added/skipped. Document this in descriptions.
Split saveOrRemoveAlbumForUser into two separate tools (saveAlbumForUser, removeAlbumFromUser) to follow single-responsibility pattern:tool. This makes intent explicit and reduces parameter ambiguity.
Add pagination return metadata. List tools (getMyPlaylists, getPlaylistTracks, getRecentlyPlayed) should return {items: [...], total: N, offset: M, limit: L, has_more: bool} to let LLMs know when to fetch next page.
Document which tools accept human-friendly names vs. only Spotify IDs. For search-based tools (searchSpotify), clarify that results include both names and IDs. For direct lookups, clarify what format albumId/playlistId/trackId expect (raw ID or URI).
Add scope declarations to tool descriptions. E.g., playMusic requires 'streaming' scope, saveAlbumForUser requires 'library:modify' scope. This enables audit trails and least-privilege configuration.
Create a companion tool discovery/reference. Add a getAvailableDevices() or similar tool to help LLMs discover what devices and playback options are available before calling play/pause/skip. This reduces trial-and-error calls.