Returns:
    UserProfile. email/country/product are unavailable on newer Spotify apps
    and come back empty rather than erroring.

Returns:
    PlaybackState (is_playing is False when nothing is playing)

Args:
    action: 'play', 'pause', 'next', 'previous', 'seek', 'volume', 'shuffle' or 'repeat'
    track_ids: Tracks or episodes to play (action='play'; ignored when
        context_uri is set). Bare IDs are tracks; pass spotify:episode: URIs
        or episode share URLs for podcast episodes.
    context_uri: Album, playlist, artist or show URI to play (action='play')
    position_ms: Position in milliseconds (required for action='seek')
    volume_percent: Volume 0-100 (required for action='volume')
    state: 'on'/'off' for shuffle; 'track'/'context'/'off' for repeat
    device_id: Target device (default: the currently active one)

Returns:
    Last observed PlaybackState, possibly unconfirmed.

Confirmation is best effort: at most five post-action reads with brief waits.
Stale state or a later read failure returns the last observation. Checks do not
verify every requested track, context or device transition.

Returns:
    DeviceList; use transfer_playback with a device id to make one active

Args:
    device_id: Target device ID
    play: Start playing after the transfer (default True)

Args:
    query: Search query
    qtype: Type ('track', 'album', 'artist', 'playlist')
    limit: Max results per page (1-50, default 10). Spotify caps search at 10
        per page for restricted apps and rejects anything larger; a larger
        limit is retried at the cap rather than failing. Check the returned
        `limit` for what was actually served, and use `offset` to go deeper.
    offset: Number of results to skip for pagination (default 0)
    year: Filter by year (e.g., '2024')
    year_range: Filter by year range (e.g., '2020-2024')
    genre: Filter by genre (e.g., 'electronic', 'hip-hop')
    artist: Filter by artist name
    album: Filter by album name

Returns:
    SearchResults with 'items' (list of tracks) and pagination info ('total', 'limit', 'offset')

Note: Filters use Spotify's search syntax. For large result sets, use offset to paginate.
Example: query='love', year='2024', genre='pop' searches for 'love year:2024 genre:pop'

Args:
    track_id: Track ID, or a spotify:track:/spotify:episode: URI or
        open.spotify.com URL. A bare ID is taken as a track.
Returns:
    Status and message

Args:
    track_ids: Single track ID or list of track IDs (up to 50)

Returns:
    TrackList with 'tracks' containing track metadata including release_date.
    For single ID, returns {'tracks': [track]}.

Note: Batch lookup is much more efficient where it is available - 50 tracks
in 1 API call instead of 50. Spotify withholds the batch endpoint from some
apps, in which case this transparently falls back to one request per track,
so the result is the same either way.

Args:
    artist_ids: One artist ID/URI, or a list of up to 50. A list costs one
        Spotify request rather than one per artist.
Returns:
    ArtistInfo whose `artists` follows the order requested. `top_tracks` is
    filled only when a single artist was requested, and is empty rather than
    an error when Spotify withholds that endpoint.

Args:
    playlist_id: Spotify playlist ID

Returns:
    Playlist metadata (no tracks - use get_playlist_tracks for tracks)

Note: This returns playlist info only. For tracks, use get_playlist_tracks
which supports full pagination for large playlists.

Args:
    name: Playlist name
    description: Playlist description (default: empty)
    public: Whether playlist is public (default: False)

Returns:
    The created Playlist

Args:
    playlist_id: Playlist ID
    track_uris: Track or episode URIs/URLs (up to 100). Bare IDs are tracks;
        pass spotify:episode: URIs or episode URLs for episodes.

Args:
    limit: Max playlists to return per page (1-50, default 20)
    offset: Number of playlists to skip for pagination (default 0)

Returns:
    PlaylistList with 'items' (list of playlists) and pagination info ('total', 'limit', 'offset')

Note: For users with many playlists, use offset to paginate through results.
Example: offset=0 gets playlists 1-20, offset=20 gets playlists 21-40, etc.

Args:
    playlist_id: Playlist ID
    limit: Max tracks to return (None for all tracks, up to 10,000 safety limit)
    offset: Number of tracks to skip for pagination (default 0)

Returns:
    PlaylistTracks with 'items' (list of tracks), 'total', 'limit', 'offset'

Note: Large playlists require pagination. Use limit/offset to get specific ranges:
- Get first 100: limit=100, offset=0
- Get next 100: limit=100, offset=100
- Get all tracks: limit=None (use with caution on very large playlists)

Args:
    playlist_id: Playlist ID
    track_uris: Track or episode URIs/URLs to remove. Bare IDs are tracks.

Args:
    playlist_id: Playlist ID
    name: New playlist name (optional)
    description: New playlist description (optional)
    public: Whether playlist should be public (optional)

Args:
    playlist_id: Playlist ID
    range_start: Zero-based position of the first track to move
    insert_before: Zero-based position to insert the moved block before.
        Pass the playlist's total track count to move the block to the end.
    range_length: Number of consecutive tracks to move (default 1)
    snapshot_id: Optional playlist snapshot ID to guard against concurrent edits

Returns:
    ActionResult with the new snapshot_id

Note: Positions are zero-based. Example: move the first 3 tracks to just
before position 10 with range_start=0, range_length=3, insert_before=10.

Args:
    album_ids: One album ID/URI, or a list of up to 20 — Spotify's own cap
        for album batches, which is lower than the 50 for tracks and artists.

Returns:
    AlbumInfo whose `albums` follows the order requested. `tracks` holds the
    album's track list only when a single album was requested.

Args:
    limit: Max tracks to return per page (1-50, default 20)
    offset: Number of tracks to skip for pagination (default 0)

Returns:
    SavedTracks with 'items' (tracks with added_at timestamp) and pagination info

Args:
    track_ids: Track IDs or URIs (up to 50)

Args:
    track_ids: Track IDs or URIs (up to 50)

Up to 50 tracks per tool call, split into upstream chunks of at most 40.
Use this before save_tracks rather than paging through get_saved_tracks.

Args:
    track_ids: Track IDs or URIs (up to 50)
Returns:
    MembershipStatus.results maps each Spotify track id to true if liked

Up to 20 albums per tool call, preserving this tool's existing album cap.

Args:
    album_ids: Album IDs or URIs (up to 20)
Returns:
    MembershipStatus.results maps each Spotify album id to true if saved

Uses artist URIs on the consolidated library route, with a legacy fallback.
Requires user-follow-read; reauthorize if your existing grant lacks it.

Args:
    artist_ids: Artist IDs or URIs (up to 50)
Returns:
    MembershipStatus.results maps each Spotify artist id to true if followed

Args:
    limit: Max albums to return per page (1-50, default 20)
    offset: Number of albums to skip for pagination (default 0)

Returns:
    SavedAlbums with 'items' (albums with added_at) and pagination info

Args:
    album_ids: Album IDs or URIs (up to 20)

Args:
    album_ids: Album IDs or URIs (up to 20)

Args:
    limit: Max artists to return per page (1-50, default 20)
    after: The `after` cursor from the previous page (omit for the first page)

Returns:
    FollowedArtists; pass its `after` back for the next page (None on the last)

Args:
    artist_ids: Artist IDs or URIs (up to 50)

Args:
    artist_ids: Artist IDs or URIs (up to 50)

Args:
    playlist_id: Playlist ID, URI or open.spotify.com URL

For playlists the user owns this is how Spotify deletes them — there is no
separate delete endpoint.

Args:
    playlist_id: Playlist ID or URI

Args:
    limit: Max shows to return per page (1-50, default 20)
    offset: Number of shows to skip for pagination (default 0)

Returns:
    SavedShows with 'items' (shows with added_at) and pagination info

Args:
    show_ids: Show IDs or URIs (up to 50)

Args:
    show_ids: Show IDs or URIs (up to 50)

Args:
    show_ids: Show IDs or URIs (up to 50)
Returns:
    MembershipStatus.results maps each Spotify show id to true if saved

Args:
    episode_ids: Episode IDs or URIs (up to 50)
Returns:
    MembershipStatus.results maps each Spotify episode id to true if saved

Args:
    show_id: Show ID, URI or open.spotify.com URL
    limit: Max episodes to return per page (1-50, default 20)
    offset: Number of episodes to skip for pagination (default 0)

Returns:
    EpisodeList with 'items' and pagination info

Args:
    limit: Max episodes to return per page (1-50, default 20)
    offset: Number of episodes to skip for pagination (default 0)

Returns:
    EpisodeList with 'items' (episodes with show and added_at) and pagination info

Args:
    episode_ids: Episode IDs or URIs (up to 50)

Args:
    episode_ids: Episode IDs or URIs (up to 50)

Args:
    limit: Max audiobooks to return per page (1-50, default 20)
    offset: Number of audiobooks to skip for pagination (default 0)

Returns:
    SavedAudiobooks with 'items' and pagination info

Args:
    audiobook_ids: Audiobook IDs or URIs (up to 50)
Returns:
    MembershipStatus.results maps each Spotify audiobook id to true if saved

Args:
    audiobook_ids: Audiobook IDs or URIs (up to 50)

Args:
    audiobook_ids: Audiobook IDs or URIs (up to 50)

Args:
    limit: Max tracks to return (1-50, default 20)

Returns:
    RecentlyPlayed with each track's played_at timestamp

This remains useful when recommendations or related artists are unavailable
to the app. Spotify's policy also restricts analysis and AI ingestion.

Args:
    item_type: 'tracks' or 'artists' (default 'tracks')
    time_range: 'short_term' (~4 weeks), 'medium_term' (~6 months) or 'long_term'
    limit: Max items to return (1-50, default 20)

Returns:
    TopItems with either 'tracks' or 'artists' populated