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 to play (action='play'; ignored when context_uri is set)
    context_uri: Album/playlist/artist 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, spotify:track: URI or open.spotify.com URL
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: List of track URIs (up to 100)

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: List of track URIs to remove

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

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 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