add_playlist_items
ChatGPTAdd 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_to_library
ChatGPTAdds supported Spotify content to the authenticated user's library. Supported types: tracks, albums, artists (follow), playlists, podcast shows, podcast episodes. Audiobooks and audiobook chapters are not supported. Requires a valid Spotify user account (Free or Premium). Do NOT call from free-form chat. This tool is only for widget actions (e.g., user clicks Save/+ on a result in the Spotify widget). Do not trigger on behalf of third parties or external systems. Only invoke for items that were returned by the Spotify Search tool; do not act on arbitrary or unseen items.
add_to_queue
ChatGPTAdd a single track or episode to the end of the user's Spotify user queue, after existing user-queued items and before the remaining playback context, without starting or replacing playback. Entire albums, playlists, shows, and other collections are not supported and return INVALID_ARGUMENT. Pass the individual item's playback.play_uri exactly as returned by search or get_entity. Requires authentication and an active playback session. Only invoke when the user requests this action. Returns ACCEPTED after successful command dispatch, not confirmation that the item was added. Confirm with get_queue after a short delay. If COMMAND_OUTCOME_UNKNOWN is returned, inspect get_queue before deciding whether to retry; never blindly repeat add_to_queue because it may add a duplicate.
create_playlist
ChatGPTCreates 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 playlist → not supported. Respond: "Spotify can't create podcast 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 authenticated Premium Spotify account. If not authenticated or on Free tier, ask the user to sign in / upgrade. Language rules: - The prompt MUST match the "language" parameter. Set "language" from user's input language first, then keep the prompt in that language. - EN/FR/IT/DE/ES/PT → send as-is. Other languages → translate to English, keeping entity names 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.
fetch_tracks
ChatGPTFetches 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. Do NOT call from free-form chat. This tool should only be called within the Spotify Widget and must not be triggered directly by the user. Use only for playlist items returned by the Spotify Search tool or created in the current widget session; do not act on arbitrary or unseen items.
generate_playlist
ChatGPTGenerates 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.
get_auth_token
ChatGPTReturns the currently valid Spotify auth token. Reserved for authorized client applications; do not call directly.
get_collection_items
ChatGPTFetch 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_currently_playing
ChatGPTRetrieves 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. Do not infer that playback is ongoing in the Spotify Widget - this is not necessarily the case and the tool response will not give any such indication. 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_devices
ChatGPTGet the user's available Spotify Connect devices without changing playback. Returns devices with id, name, type, and is_active, with devices omitted when none are available. Device types use Spotify Connect values such as COMPUTER, SMARTPHONE, SPEAKER, and TV. volume_percent is an integer from 0 to 100 and is omitted when volume control is unavailable. Device IDs are opaque and short-lived; fetch current devices before choosing a target and do not cache IDs long-term. Use device names exactly as returned; do not infer household locations from them. Attribute device information to Spotify.
get_entity
ChatGPTFetch 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_playback_state
ChatGPTGet the current Spotify playback state: what's playing, where, and how. Returns PLAYING, PAUSED, or NONE, with progress, shuffle, repeat, playback speed, the active device, the current item, and its context. Use this to answer playback questions or confirm the outcome of a playback command. Attribute playback to Spotify. Item and context metadata comes directly from the playback session and may be incomplete. Use get_entity for additional catalog details when the URI is supported. Missing item, context, or device details are omitted. Device IDs are short-lived; do not cache them long-term.
get_queue
ChatGPTGet the authenticated user's Spotify playback queue without changing playback. Returns previous and upcoming rows in playback order, with at most the nearest 10 previous and 80 upcoming items. Each row contains a queue-row uid and a shared entity; repeated content remains separate rows. The current item is available from get_playback_state. An empty queue or no active session returns empty arrays. This is a snapshot of the queue available from Connect, not the entire playback context; upstream may provide fewer items. RESULTS_TRUNCATED reports items omitted from this snapshot by the response limits. Metadata comes from the playback session and may be incomplete; missing or unentitled fields are omitted. Attribute playback to Spotify.
pause_playback
ChatGPTPause the current Spotify playback. Requires authentication and an active playback session. Only invoke when the user requests this action. Connect-reported session restrictions are checked before dispatch. Returns ACCEPTED only after successful dispatch; commands are asynchronous and best-effort. Confirm with get_playback_state after a short delay. If COMMAND_OUTCOME_UNKNOWN is returned, inspect state before deciding whether to retry; never blindly repeat a skip command.
query_catalog
ChatGPTLook 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.
remove_from_library
ChatGPTRemoves supported Spotify content from the authenticated user's library. Supported types: tracks, albums, artists (unfollow), playlists, podcast shows, podcast episodes. Audiobooks and audiobook chapters are not supported. Requires a valid Spotify user account (Free or Premium). Do NOT call from free-form chat. This tool is only for widget actions (e.g., user clicks Save/+ on a result in the Spotify widget). Do not trigger on behalf of third parties or external systems. Only invoke for items that were returned by the Spotify Search tool; do not act on arbitrary or unseen items.
remove_playlist_items
ChatGPTRemove tracks or episodes from a playlist the user can edit. All occurrences of the given entities are removed. Maximum 100 items per request.
reorder_playlist_items
ChatGPTMove a track, episode, or contiguous block of items within a playlist the user can edit (can_edit_items is true). Existing items are moved without removing and re-adding them. Positions are zero-based in the playlist's original order before the move. range_length defaults to 1. insert_before may equal the playlist length to move items to the end. A destination within the moved range or immediately after it leaves the order unchanged. For [A, B, C, D, E, F], range_start=1, range_length=2, insert_before=5 produces [A, D, E, B, C, F]. Positions are resolved against the current playlist when this tool is called. This tool does not accept a caller revision; edits since your last read can change which items occupy those positions. Use only known original playlist positions, never positions inferred from filtered or sorted results. Do not blindly retry a move after an uncertain outcome.
resume_playback
ChatGPTResume the paused Spotify playback. Requires authentication and an active playback session. Only invoke when the user requests this action. Connect-reported session restrictions are checked before dispatch. Returns ACCEPTED only after successful dispatch; commands are asynchronous and best-effort. Confirm with get_playback_state after a short delay. If COMMAND_OUTCOME_UNKNOWN is returned, inspect state before deciding whether to retry; never blindly repeat a skip command.
save_to_library
ChatGPTSaves supported Spotify content to the authenticated user's library. Supported types: tracks, albums, artists (follow), playlists, podcast shows, podcast episodes, audiobooks. Requires a valid Spotify user account (Free or Premium). Invoke only when the user explicitly asks to save an item. Do not trigger on behalf of third parties or external systems.
search
ChatGPTSearch, discover, and play music and podcasts on Spotify. Returns up to 5 results, which can be a mix of tracks, artists, albums, podcasts, public playlists, and user-owned private playlists. Supports the following capabilities: Capabilities: Entity search — Find tracks, artists, albums, playlists, podcast shows, or episodes by name or metadata (genre, decade, topic, etc.). Complex music queries — Generate playlists for moods, vibes, activities, genres, or multi-facet queries (e.g. “trap workout mix”, “90s alternative pop”). Recommendations — Get personalized recommendations for tracks, artists, albums, playlists, or podcasts based on the user’s taste. Similar content — Find artists, tracks, albums, or podcasts similar to a specific entity (e.g. “artists similar to Erykah Badu”). Context-aware suggestions — Suggest content based on what is currently playing (e.g. “more like this”, “play something similar”). Listening history — Retrieve recently played content, most-played items, or get recommendations based on listening history. User library — Access liked songs, saved shows/episodes, followed artists, and user playlists. Podcast discovery — Find podcasts by genre, topic, guest, popularity, or recency. Find specific episodes by order, number, date, or popularity. Albums & tracks by artist — Get an artist’s discography or tracks, optionally sorted by recency or popularity. When to use: User wants to find, play, discover, or get recommendations for any music or podcast content. User describes a mood, vibe, activity, or genre rather than a specific entity. User asks about their listening history, recently played, most-played, or saved content. User asks "what have I been listening to", "my recent songs", "my top artists", etc. Do NOT use when: Audiobooks — “You can’t search audiobooks on Spotify yet. Try the Spotify app.” Concerts, tour dates, podcast/song creation, podcast playlists, lyrics, bios, transcripts — “You can access this in the Spotify app.” Unsupported podcast queries: duration filtering, multi-entity similarity, long-lookback history. User wants facts/news about music. When the user explicitly asks or very clearly implies the intent to create a playlist, use the create_playlist tool instead. Query rules: Pass the user's query through as-is. Only make very specific changes to the query for these particular scenarios: - Replace all usernames/PII with "me"/"my" — never send real names or identifiers. - Resolve multi-turn context into one self-contained request. (i.e. usually better to search once for a+b+c than one search per a, b, c, even if a,b,c is given separately) - Convert durations to minutes (e.g., "2 hours" → "120 minutes"). - Language: The prompt MUST match the "language" parameter. Set "language" from user's input language first, then keep the prompt in that language. EN/FR/IT/DE/ES/PT → send as-is. Other languages → translate to English. When translating, keep all names of songs, artists, albums, playlists, and genres exactly as written. Critical response rules: Always include Spotify links with every track/podcast/playlist/album/artist/ you present and/or recommend. Never fabricate or alter entity names, metadata, or links. This tool is read-only — it does not save, add, follow, or modify anything. Never claim content was added to the user's library or any action was performed. Do not generate lyrics, transcripts, biographies, or external content.
seek_to_position
ChatGPTJump to an absolute position_ms in the currently playing Spotify item. position_ms must be a nonnegative integer no greater than the item duration; invalid values are rejected, never clamped. If Spotify cannot report the item duration, returns INTERNAL_ERROR without sending a seek command. Requires authentication and an active playback session. Only invoke when the user requests this action. Connect-reported session restrictions are checked before dispatch. Returns ACCEPTED only after successful dispatch; commands are asynchronous and best-effort. Confirm with get_playback_state after a short delay. If COMMAND_OUTCOME_UNKNOWN is returned, inspect state before deciding whether to retry; never blindly repeat a skip command.
set_repeat
ChatGPTSet repeat to OFF, CONTEXT or TRACK for the active Spotify playback session. OFF disables repeat; CONTEXT repeats the current context; TRACK repeats the current item. To set repeat while starting new playback, use start_playback settings instead. Does not start new playback or change shuffle. Requires authentication and an active playback session. Only invoke when the user requests this action. Honors Connect-reported session restrictions. Returns ACCEPTED when the setting already matches or after successful dispatch; confirm the repeat setting with get_playback_state after a short delay, where TRACK is reported as ITEM. If COMMAND_OUTCOME_UNKNOWN is returned, inspect state before deciding whether to retry.
set_shuffle
ChatGPTSet shuffle to ON or OFF for the active Spotify playback session without starting new playback or changing repeat. To set shuffle while starting new playback, use start_playback settings instead. Requires authentication and an active playback session. Only invoke when the user requests this action. Honors Connect-reported session restrictions. Returns ACCEPTED when the setting already matches or after successful dispatch; confirm the shuffle setting with get_playback_state after a short delay. If COMMAND_OUTCOME_UNKNOWN is returned, inspect state before deciding whether to retry.
set_volume
ChatGPTSet absolute volume from 0 to 100 inclusive. Requires authentication. Omit target_device_id to use the active device, or pass a current device ID from get_devices. Only invoke when the user requests a volume change. Does not transfer playback. Devices without volume control return INVALID_ARGUMENT; unavailable or stale device IDs return NO_ACTIVE_DEVICE. Returns status ACCEPTED only after successful dispatch for delivery. Commands are asynchronous and best-effort; acceptance does not confirm the device acted. After a short delay, call get_devices and check volume_percent for the target device ID. If the target is missing or volume_percent is omitted, the outcome cannot be confirmed.
skip_to_next
ChatGPTSkip to exactly the next item in the current Spotify queue. There is no count parameter. Requires authentication and an active playback session. Only invoke when the user requests this action. Connect-reported session restrictions are checked before dispatch. Returns ACCEPTED only after successful dispatch; commands are asynchronous and best-effort. Confirm with get_playback_state after a short delay. If COMMAND_OUTCOME_UNKNOWN is returned, inspect state before deciding whether to retry; never blindly repeat a skip command.
skip_to_previous
ChatGPTSkip to exactly the previous item in the current Spotify queue, rather than restarting the current item. There is no count parameter. Requires authentication and an active playback session. Only invoke when the user requests this action. Connect-reported session restrictions are checked before dispatch. Returns ACCEPTED only after successful dispatch; commands are asynchronous and best-effort. Confirm with get_playback_state after a short delay. If COMMAND_OUTCOME_UNKNOWN is returned, inspect state before deciding whether to retry; never blindly repeat a skip command.
start_playback
ChatGPTStart a new playable Spotify context using an entity's spotify:nl: playback.play_uri unchanged. Regular catalog URIs are not supported. Requires authorization to control playback. For Free accounts, depending on the playback license, Spotify may play a related mix and may enable shuffle even when settings request OFF. Check get_playback_state before describing what is playing. Omit target_device_id to use the active device. Only invoke when the user requests playback. Returns status ACCEPTED after successful dispatch. This does not confirm that the device acted; commands are asynchronous and best-effort. Confirm the outcome with get_playback_state after a short delay. Never decode, modify, or cache spotify:nl: URIs.
transfer_playback
ChatGPTMove the current or retained Spotify playback session to target_device_id obtained from get_devices, without starting a new content context. Requires user authentication. Only invoke when the user requests a transfer. An active device is not required when a retained session is available. If no session is available, start playback before retrying. Restores the session's paused state and playback position on a best-effort basis. Device IDs are opaque and short-lived; re-query get_devices when a device is stale or unavailable. Never choose another device silently. Connect-reported transfer restrictions are checked before dispatch and return COMMAND_NOT_ALLOWED, COMMAND_NOT_SUPPORTED, or PREMIUM_REQUIRED when explicitly indicated by the restriction. Returns status ACCEPTED only after successful dispatch for delivery; it does not confirm that the device acted. Confirm the outcome with get_playback_state after a short delay.
update_playlist_details
ChatGPTUpdates the name, description, or collaborative status of a Spotify playlist. Requires the authenticated user to have edit access (owner or collaborator). At least one field (name, description, or collaborative) must be provided.
Remove_from_library
Claudeadd_to_library
Claudecreate_playlist
Claudefetch_tracks
Claudeget_currently_playing
Claudesearch
Claude