Initiate TIDAL authentication. Returns an auth URL for the user to open manually.
After opening the URL and completing login, call tidal_login_complete() to finish.
If already authenticated, returns success immediately.

Returns:
    A dictionary containing auth URL and instructions, or success if already authenticated

Complete a pending TIDAL authentication. Call this after the user has opened
the auth URL from tidal_login() and completed the browser login.

Args:
    timeout: Maximum seconds to wait for authentication completion (default: 300)

Returns:
    A dictionary containing authentication status and user information if successful

Retrieves tracks from the user's TIDAL account favorites.

USE THIS TOOL WHENEVER A USER ASKS FOR:
- "What are my favorite tracks?"
- "Show me my TIDAL favorites"
- "What music do I have saved?"
- "Get my favorite songs"
- Any request to view their saved/favorite tracks

This function retrieves the user's favorite tracks from TIDAL.

Args:
    limit: Maximum number of tracks to retrieve (default: 20, note it should be large enough by default unless specified otherwise).

Returns:
    A dictionary containing track information including track ID, title, artist, album, and duration.
    Returns an error message if not authenticated or if retrieval fails.

Search TIDAL's catalog for tracks, albums, artists, and playlists.

USE THIS TOOL WHENEVER A USER ASKS FOR:
- "Search for [song/album/artist name]"
- "Find [song name] on TIDAL"
- "Look up [artist name]"
- "Search TIDAL for [query]"
- "Find albums by [artist]"
- Any request to search or find music in TIDAL's catalog

When processing the results of this tool:
1. Present the top_hit first if available - this is TIDAL's most relevant result
2. Group results by type (tracks, albums, artists, playlists)
3. Include the TIDAL URL for each result so users can easily access them
4. For tracks, include artist and album information
5. For albums, include artist and track count
6. Format results in a clear, readable manner

Args:
    query: Search query (e.g., "Bohemian Rhapsody", "Radiohead", "Dark Side of the Moon")
    search_type: Type of content to search for:
                - "track" - Search only for tracks/songs
                - "album" - Search only for albums
                - "artist" - Search only for artists
                - "playlist" - Search only for playlists
                - "all" (default) - Search all content types
    limit: Maximum number of results per type (default: 50, max: 300)

Returns:
    Dictionary with search results organized by type (tracks, albums, artists, playlists)
    and an optional top_hit for the most relevant result

Search TIDAL for multiple tracks/albums/artists in a single request.
This is MUCH MORE EFFICIENT than calling search_tidal multiple times.

USE THIS TOOL WHEN:
- You need to search for multiple songs to create a playlist
- You have a list of song names to look up
- You're building a collection of tracks based on a user's description
- The user provides a list of songs they want to find

This tool processes all searches concurrently, making it 10-50x faster than
calling search_tidal repeatedly for each song.

When processing the results:
1. Check each result for the 'tracks' array with matching songs
2. Use the first track in each result as the best match
3. Some queries may have 'error' instead of results - handle gracefully
4. Collect track IDs for playlist creation

Args:
    queries: List of search queries. Each item can be:
             - A string: "Bohemian Rhapsody Queen" (searches for tracks)
             - A dict with 'query' and optional 'type':
               {"query": "Bohemian Rhapsody", "type": "track"}
             Valid types: "track", "album", "artist", "playlist", "all"
             Default type is "track" if not specified.
             Maximum 100 queries per request.
    limit_per_query: Maximum results per query (default: 5, max: 20)
                    Keep this low (1-5) for faster responses when you only need the best match.

Returns:
    Dictionary with 'results' array containing search results for each query.
    Each result includes the original query and matching tracks/albums/etc.

Example:
    batch_search_tidal([
        {"query": "Bohemian Rhapsody Queen", "type": "track"},
        {"query": "Yesterday Beatles", "type": "track"},
        "Stairway to Heaven"  # String queries default to track type
    ], limit_per_query=1)

Creates a TIDAL playlist by searching for songs and adding the best matches.
This is the RECOMMENDED way to create a playlist when you have song names/descriptions.

USE THIS TOOL WHEN:
- A user provides a list of song names to add to a playlist
- You need to create a playlist from song descriptions (not track IDs)
- You want to build a playlist based on user-provided song names

This tool handles the entire workflow efficiently:
1. Batch search for all songs concurrently
2. Collect the best matching track IDs
3. Create the playlist with all found tracks

This is MUCH faster than searching for songs one-by-one and then creating a playlist.

Args:
    title: Name for the new playlist
    song_descriptions: List of song descriptions to search for.
                      Include artist name for better matching.
                      Examples: ["Bohemian Rhapsody by Queen", "Yesterday Beatles",
                                "Stairway to Heaven Led Zeppelin"]
                      Maximum 100 songs per request.
    description: Optional playlist description

Returns:
    Dictionary with:
    - playlist: Created playlist details including URL
    - matched_songs: List of songs that were found with their track info
    - unmatched_songs: List of songs that couldn't be found
    - match_rate: e.g., "45/50" showing how many songs were matched

Example:
    create_playlist_from_songs(
        title="My 80s Favorites",
        song_descriptions=[
            "Take On Me a-ha",
            "Livin' on a Prayer Bon Jovi",
            "Sweet Child O' Mine Guns N' Roses"
        ],
        description="Classic 80s hits"
    )

Recommends music tracks based on specified track IDs or can use the user's TIDAL favorites if no IDs are provided.

USE THIS TOOL WHENEVER A USER ASKS FOR:
- Music recommendations
- Track suggestions
- Music similar to their TIDAL favorites or specific tracks
- "What should I listen to?"
- Any request to recommend songs/tracks/music based on their TIDAL history or specific tracks

This function gets recommendations based on provided track IDs or retrieves the user's
favorite tracks as seeds if no IDs are specified.

When processing the results of this tool:
1. Analyze the seed tracks to understand the music taste or direction
2. Review the recommended tracks from TIDAL
3. IMPORTANT: Do NOT include any tracks from the seed tracks in your recommendations
4. Ensure there are NO DUPLICATES in your recommended tracks list
5. Select and rank the most appropriate tracks based on the seed tracks and filter criteria
6. Group recommendations by similar styles, artists, or moods with descriptive headings
7. For each recommended track, provide:
   - The track name, artist, album
   - Always include the track's URL to make it easy for users to listen to the track
   - A brief explanation of why this track might appeal to the user based on the seed tracks
   - If applicable, how this track matches their specific filter criteria
8. Format your response as a nicely presented list of recommendations with helpful context (remember to include the track's URL!)
9. Begin with a brief introduction explaining your selection strategy
10. Lastly, unless specified otherwise, you should recommend MINIMUM 20 tracks (or more if possible) to give the user a good variety to choose from.

[IMPORTANT NOTE] If you're not familiar with any artists or tracks mentioned, you should use internet search capabilities if available to provide more accurate information.

Args:
    track_ids: Optional list of TIDAL track IDs to use as seeds for recommendations.
              If not provided, will use the user's favorite tracks.
    filter_criteria: Specific preferences for filtering recommendations (e.g., "relaxing music,"
                     "recent releases," "upbeat," "jazz influences")
    limit_per_track: Maximum number of recommendations to get per track (NOTE: default: 20, unless specified otherwise, we'd like to keep the default large enough to have enough candidates to work with)
    limit_from_favorite: Maximum number of favorite tracks to use as seeds (NOTE: default: 20, unless specified otherwise, we'd like to keep the default large enough to have enough candidates to work with)

Returns:
    A dictionary containing both the seed tracks and recommended tracks

Creates a new TIDAL playlist with the specified tracks.

USE THIS TOOL WHENEVER A USER ASKS FOR:
- "Create a playlist with these songs"
- "Make a TIDAL playlist"
- "Save these tracks to a playlist"
- "Create a collection of songs"
- Any request to create a new playlist in their TIDAL account

This function creates a new playlist in the user's TIDAL account and adds the specified tracks to it.
The user must be authenticated with TIDAL first.

NAMING CONVENTION GUIDANCE:
When suggesting or creating a playlist, first check the user's existing playlists using get_user_playlists()
to understand their naming preferences. Some patterns to look for:
- Do they use emoji in playlist names?
- Do they use all caps, title case, or lowercase?
- Do they include dates or seasons in names?
- Do they name by mood, genre, activity, or artist?
- Do they use specific prefixes or formatting (e.g., "Mix: Summer Vibes" or "[Workout] High Energy")

Try to match their style when suggesting new playlist names. If they have no playlists yet or you
can't determine a pattern, use a clear, descriptive name based on the tracks' common themes.

When processing the results of this tool:
1. Confirm the playlist was created successfully
2. Provide the playlist title, number of tracks added, and URL
3. Always include the direct TIDAL URL (https://tidal.com/playlist/{playlist_id})
4. Suggest that the user can now access this playlist in their TIDAL account

Args:
    title: The name of the playlist to create
    track_ids: List of TIDAL track IDs to add to the playlist
    description: Optional description for the playlist (default: "")

Returns:
    A dictionary containing the status of the playlist creation and details about the created playlist

Adds tracks to an existing TIDAL playlist.

USE THIS TOOL WHENEVER A USER ASKS FOR:
- "Add this song to my playlist"
- "Put these tracks in my [playlist name] playlist"
- "Add this to my favorites playlist"
- "Include this track in my workout playlist"
- Any request to add songs/tracks to an existing playlist

This function adds one or more tracks to a playlist that already exists in the user's TIDAL account.
The playlist_id must be provided, which can be obtained from the get_user_playlists() function.

When processing the results of this tool:
1. Confirm how many tracks were successfully added
2. If allow_duplicates is False and some tracks were already in the playlist, they won't be added again
3. Mention the playlist name and provide a link to it

Args:
    playlist_id: The TIDAL ID of the playlist to add tracks to (required)
    track_ids: List of TIDAL track IDs to add to the playlist (required)
    allow_duplicates: If False (default), tracks already in the playlist won't be added again

Returns:
    A dictionary containing the status and number of tracks added

Fetches the user's playlists from their TIDAL account.

USE THIS TOOL WHENEVER A USER ASKS FOR:
- "Show me my playlists"
- "List my TIDAL playlists"
- "What playlists do I have?"
- "Get my music collections"
- Any request to view or list their TIDAL playlists

This function retrieves the user's playlists from TIDAL and returns them sorted
by last updated date (most recent first).

When processing the results of this tool:
1. Present the playlists in a clear, organized format
2. Include key information like title, track count, and the TIDAL URL for each playlist
3. Mention when each playlist was last updated if available
4. If the user has many playlists, focus on the most recently updated ones unless specified otherwise

Returns:
    A dictionary containing the user's playlists sorted by last updated date

Retrieves tracks from a specified TIDAL playlist with pagination support.

USE THIS TOOL WHENEVER A USER ASKS FOR:
- "Show me the songs in my playlist"
- "What tracks are in my [playlist name] playlist?"
- "List the songs from my playlist"
- "Get tracks from my playlist"
- "View contents of my TIDAL playlist"
- Any request to see what songs/tracks are in a specific playlist

This function retrieves tracks from a specific playlist in the user's TIDAL account.
The playlist_id must be provided, which can be obtained from the get_user_playlists() function.

PAGINATION: For large playlists, use the offset parameter to get additional tracks.
The response includes 'total_available' showing the total tracks in the playlist.
If total_available > track_count, call again with offset incremented by the limit
to get the next batch (e.g., first call offset=0, second call offset=100, etc.)

When processing the results of this tool:
1. Present the playlist information (title, description, track count) as context
2. List the tracks in a clear, organized format with track name, artist, and album
3. Include track durations where available
4. Check total_available vs track_count to know if there are more tracks
5. If there are many tracks, focus on highlighting interesting patterns or variety

Args:
    playlist_id: The TIDAL ID of the playlist to retrieve (required)
    limit: Maximum number of tracks to retrieve per request (default: 100, max: 500)
    offset: Starting index for pagination (default: 0). Use to get additional tracks.

Returns:
    A dictionary containing tracks, track_count (returned), total_available (in playlist), offset, and limit

Deletes a TIDAL playlist by its ID.

USE THIS TOOL WHENEVER A USER ASKS FOR:
- "Delete my playlist"
- "Remove a playlist from my TIDAL account"
- "Get rid of this playlist"
- "Delete the playlist with ID X"
- Any request to delete or remove a TIDAL playlist

This function deletes a specific playlist from the user's TIDAL account.
The user must be authenticated with TIDAL first.

When processing the results of this tool:
1. Confirm the playlist was deleted successfully
2. Provide a clear message about the deletion

Args:
    playlist_id: The TIDAL ID of the playlist to delete (required)

Returns:
    A dictionary containing the status of the playlist deletion

Downloads a TIDAL track to local storage using tidal-dl-ng.

USE THIS TOOL WHENEVER A USER ASKS FOR:
- "Download this track"
- "Save this song to my computer"
- "Download track ID X"
- "I want to download [song name]" (after identifying the track ID)
- Any request to download a single track from TIDAL

IMPORTANT PREREQUISITES:
1. tidal-dl-ng must be installed: pip install tidal-dl-ng
2. User must have authenticated tidal-dl-ng: run 'tdn login' in terminal
3. tidal-dl-ng authentication is SEPARATE from TIDAL MCP authentication

When processing the results of this tool:
1. Confirm the download was successful or explain any errors
2. If tidal-dl-ng is not installed, guide user to install it
3. If authentication failed, guide user to run 'tdn login' in terminal
4. The file will be saved to tidal-dl-ng's configured download location

Args:
    track_id: The TIDAL track ID to download (numeric string)

Returns:
    A dictionary containing download status and any output messages

Downloads a TIDAL album to local storage using tidal-dl-ng.

USE THIS TOOL WHENEVER A USER ASKS FOR:
- "Download this album"
- "Save this album to my computer"
- "Download album ID X"
- "I want to download [album name]" (after identifying the album ID)
- Any request to download a complete album from TIDAL

IMPORTANT PREREQUISITES:
1. tidal-dl-ng must be installed: pip install tidal-dl-ng
2. User must have authenticated tidal-dl-ng: run 'tdn login' in terminal
3. tidal-dl-ng authentication is SEPARATE from TIDAL MCP authentication

When processing the results of this tool:
1. Confirm the download was successful or explain any errors
2. Note that albums may take several minutes to download
3. If tidal-dl-ng is not installed, guide user to install it
4. If authentication failed, guide user to run 'tdn login' in terminal
5. The files will be saved to tidal-dl-ng's configured download location

Args:
    album_id: The TIDAL album ID to download (numeric string)

Returns:
    A dictionary containing download status and any output messages

Downloads a TIDAL playlist to local storage using tidal-dl-ng.

USE THIS TOOL WHENEVER A USER ASKS FOR:
- "Download this playlist"
- "Save this playlist to my computer"
- "Download playlist ID X"
- "I want to download [playlist name]" (after identifying the playlist ID)
- Any request to download a complete playlist from TIDAL

IMPORTANT PREREQUISITES:
1. tidal-dl-ng must be installed: pip install tidal-dl-ng
2. User must have authenticated tidal-dl-ng: run 'tdn login' in terminal
3. tidal-dl-ng authentication is SEPARATE from TIDAL MCP authentication

When processing the results of this tool:
1. Confirm the download was successful or explain any errors
2. Note that playlists may take a long time to download depending on size
3. If tidal-dl-ng is not installed, guide user to install it
4. If authentication failed, guide user to run 'tdn login' in terminal
5. The files will be saved to tidal-dl-ng's configured download location

You can get playlist IDs from the get_user_playlists() function.

Args:
    playlist_id: The TIDAL playlist ID/UUID to download

Returns:
    A dictionary containing download status and any output messages

Downloads all favorites of a specific type from TIDAL using tidal-dl-ng.

USE THIS TOOL WHENEVER A USER ASKS FOR:
- "Download all my favorite tracks"
- "Download my saved albums"
- "Save all my favorites to my computer"
- "Download my favorite artists' music"
- Any request to download their saved/favorite content from TIDAL

IMPORTANT PREREQUISITES:
1. tidal-dl-ng must be installed: pip install tidal-dl-ng
2. User must have authenticated tidal-dl-ng: run 'tdn login' in terminal
3. tidal-dl-ng authentication is SEPARATE from TIDAL MCP authentication

When processing the results of this tool:
1. Confirm the download was started/completed or explain any errors
2. Warn user that downloading all favorites can take a VERY long time
3. If tidal-dl-ng is not installed, guide user to install it
4. If authentication failed, guide user to run 'tdn login' in terminal
5. The files will be saved to tidal-dl-ng's configured download location

Args:
    favorite_type: Type of favorites to download. One of:
                  - "tracks" (default) - Download all favorite tracks
                  - "albums" - Download all favorite albums
                  - "artists" - Download all content from favorite artists
                  - "videos" - Download all favorite videos

Returns:
    A dictionary containing download status and any output messages