Express.js backend web application for Spotify OAuth authentication and API integration. Provides session management, token refresh, and REST endpoints for searching tracks, retrieving top tracks, and creating/managing playlists.
Server has 4 tools with complete input schemas and descriptions. Naming follows verb_noun convention (get_, create_, add_, search_). Descriptions are present and adequate (68-174 chars), though some lack actionable guidance. Parameters are properly typed with enums and constraints. No output schema documentation. Error handling is minimal, API errors are passed through without recovery guidance. Most tools follow the tool pattern but lack composition hints and idempotency guarantees. Averages to a C+/B- because definitions are present but incomplete for production use.
Adds specified tracks (by URI) to an existing Spotify playlist
Creates a new Spotify playlist for the authenticated user with specified name, description, and public/private setting
Retrieves the user's top tracks from Spotify based on time range and limit
Searches for tracks on Spotify matching a query string with configurable result limit
No output schema documentation. Tools return unstructured text responses without documenting field structure, making it impossible for agents to plan downstream calls or extract data reliably.
Minimal error handling. Errors are raw API responses without recovery guidance. E.g., 'Spotify API error: 401' tells the agent nothing actionable, should be 'Access token expired. Re-authenticate via Spotify OAuth.'
No pagination or result limits enforced in spotify_search_tracks and spotify_get_top_tracks. While limits are capped by Spotify API (50 max), responses could be high-token and lack next_cursor/total_count for composition.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | F | 0 | 2026-07-28+ | v2 |
| 2026-03-09 | D | 54 | - | v1 |
spotify_create_playlist returns a resource_link but no playlist_id in structured form. Agents need the ID to chain spotify_add_to_playlist. Forcing extraction from unstructured text is error-prone.
Descriptions lack dependency hints. E.g., spotify_add_to_playlist expects 'spotify:track:...' URIs but does not guide agents to call spotify_search_tracks first to get URIs. Multi-step workflows are underdocumented.
No idempotency guarantees documented. spotify_create_playlist and spotify_add_to_playlist modify state, but no mention of retry safety or duplicate-prevention (e.g., can I safely retry if network fails?).
Position parameter in spotify_add_to_playlist is undocumented and optional without clarification. What happens if omitted? (Appends? Inserts at top?) Description should state the default behavior.