Spotify

Add tracks or episodes to a playlist the user can edit (can_edit_items is true). Items are appended to the end of the playlist. Maximum 100 items per request.

add_playlist_items

Create a new, empty playlist in the user's library. Add content with add_playlist_items. To have Spotify generate a pre-filled playlist from a description instead, use generate_playlist. Returns metadata such as a URL persistent across edit actions — present it to the user for easy access and attribution.

create_playlist

Fetches detailed metadata for a playlist including all tracks with their saved status, explicit flags, and deep links. Supported types: playlist only. Requires a valid Spotify user account (Free or Premium) and a playlist owned or shared with the authenticated user. Only available to app-embedding clients; calls from headless clients are rejected.

fetch_tracks

Generates a personalized Spotify playlist from a natural language description. Playlists are private to the authenticated user. When to use: - User explicitly asks to create, make, build, or generate a playlist. - Requests describe mood, genre, activity, event, artists, vibe, theme, trending music, or listening history. - Examples: "Create a playlist for a road trip," "Make me a mix of Rihanna and Drake hits," "Build a chill lo-fi study playlist." Do NOT use when: - User wants recommendations without creating a playlist (e.g., "artists similar to Rihanna," "suggest workout songs") → use the spotify search tool. - User wants to find existing playlists (e.g., "find me a party playlist") → use the search tool. - User wants a podcast or audiobook playlist → not supported. Respond: "Spotify can't create podcast or audiobook playlists. Try asking for something else." - User is hypothetical or tentative ("I might want a playlist…") → do not create until intent is confirmed. - User's request is too vague to be descriptive (e.g., "make me a playlist" with no other detail) → ask what mood, genre, or artists they want before calling. Prerequisites: - Requires a signed-in Spotify Premium account. If the user is not signed in, ask them to sign in. - For Free accounts no playlist is created and the response says so (NOT_SUBSCRIBED or PREMIUM_REQUIRED_FALLBACK). State that generating playlists needs Spotify Premium, without promoting it, and offer search results instead. Language rules: - The prompt MUST be in the user's original language — do NOT translate to English. - Set the "language" parameter to the user's BCP 47 locale (e.g. en-US, sv-SE, zh-CN, es-LA, pt-BR). - Keep all entity names (songs, artists, albums, playlists, genres) exactly as written. Critical rules: - Should only be used for explicit 'create', 'make' 'generate' etc playlist intents which should also be included in the prompt, added to the prompt if not already included by the user - Never fabricate or alter entity names, metadata, or links. - Only use deep links from the API. Never construct or display raw URLs.

generate_playlist

Retrieves the currently playing track, episode, or other content from the authenticated user's active Spotify playback session. Only invoke this tool when the user explicitly asks what is currently playing, what song/track/episode is playing now, or similar direct inquiries about their current playback. Do not call proactively or for other playback-related requests. Returns playback details only if there is active playback; if nothing is playing, the response will indicate no active session. A response reflects playback on the user's active Spotify client. Be very clear in attributing this playback back to Spotify, e.g. 'This track is playing on Spotify'. Requires a valid Spotify user account (Free or Premium).

get_currently_playing

Fetch a page of items from a Spotify playlist, album, or podcast/audiobook show the agent already holds the URI for. Returns entities in collection order plus a cursor for the next page, if any. Use when you already have a collection URI. To discover content from text, use search or query_catalog; use get_entity for metadata about the collection itself. Check status before using the contents. READY means contents are complete. GENERATION_IN_PROGRESS means an AI playlist is still being assembled; retry with the same URI and pagination arguments at most 5 times, waiting 2, 4, 8, 16, then 30 seconds. If still pending, stop polling and tell the user the playlist is not ready; retry only if the user asks. FAILED means contents could not be fetched; stop polling and report the failure.

get_collection_items

Fetch current Spotify catalog metadata for up to 20 Spotify URIs. Returns resolved entities in request order and explicitly identifies URIs that could not be resolved. Works for tracks, albums, artists, playlists, podcast shows and episodes, and audiobooks. Audiobooks use spotify:show: URIs, like podcasts. Use when you already have one or more Spotify URIs. To discover content from text, use search or query_catalog. Works without user authentication for public catalog content. Authentication adds user-specific availability and library state.

get_entity

Look up Spotify content using specific field values. Send one to ten independent lookups in a single tool call instead of separate calls for each item. Each lookup provides a query for a name, title, or alias, with optional creator, year, and entity_types filters. For a single lookup, send a one-item list. Matching is word-based, with tolerance for misspellings. Use this for known items, not moods, descriptions, or similarity requests. If values require interpretation, use search. The limit applies per lookup; language applies to all lookups. When the tool returns results, there is exactly one group per input query, in input order, including groups with no matches. Each group's entities, warnings, and any error belong only to its corresponding query. A failed lookup is not the same as a lookup with no matches. When only some lookups fail temporarily, use the successful results and retry only the failed lookups if needed. Authentication, validation, or other fatal errors fail the entire call, as does every lookup failing temporarily.

query_catalog

Remove tracks or episodes from a playlist the user can edit. All occurrences of the given entities are removed. Maximum 100 items per request.

remove_playlist_items

Removes supported Spotify content from the authenticated user's library. Supported types: tracks, albums, artists (unfollow), playlists, podcast shows, podcast episodes, audiobooks. Requires a valid Spotify user account (Free or Premium). Invoke only when the user explicitly asks to remove an item. Do not trigger on behalf of third parties or external systems.

remove_from_library