Connect for Apple Music — Tool Reference

Add songs, albums, or playlists to the user's Apple Music library.

Adds catalog items to the user's library. Requires music-user-token scope.

Parameters:
    ids: List of catalog IDs to add. Required.
    type: Type of content (songs, albums, playlists). Required.

Returns:
    AddToLibraryResult with:
    - success: Whether the operation succeeded
    - items_added: Number of items added to library

Errors:
    ProviderError: Invalid IDs or missing permission

{
  "description": "Parameters for add_to_library",
  "properties": {
    "ids": {
      "description": "List of catalog IDs to add",
      "items": {
        "type": "string"
      },
      "title": "Ids",
      "type": "array"
    },
    "type": {
      "description": "Type of content to add",
      "enum": [
        "songs",
        "albums",
        "playlists"
      ],
      "title": "Type",
      "type": "string"
    }
  },
  "required": [
    "ids",
    "type"
  ],
  "title": "AddToLibraryParams",
  "type": "object",
  "additionalProperties": false
}

{
  "description": "Result from add_to_library",
  "properties": {
    "success": {
      "description": "Whether the operation succeeded",
      "title": "Success",
      "type": "boolean"
    },
    "items_added": {
      "description": "Number of items added to library",
      "title": "Items Added",
      "type": "integer"
    }
  },
  "required": [
    "success",
    "items_added"
  ],
  "title": "AddToLibraryResult",
  "type": "object"
}

Add tracks to an existing library playlist.

Appends songs to the end of the playlist. Requires music-user-token scope.

Parameters:
    playlist_id: Library playlist ID to add tracks to. Required.
    track_ids: List of catalog song IDs to add. Required.

Returns:
    AddToPlaylistResult with:
    - success: Whether the operation succeeded
    - tracks_added: Number of tracks added

Errors:
    ProviderError: Playlist not found or not editable
    ProviderError: Invalid track IDs

{
  "description": "Parameters for add_to_playlist",
  "properties": {
    "playlist_id": {
      "description": "Library playlist ID to add tracks to",
      "title": "Playlist Id",
      "type": "string"
    },
    "track_ids": {
      "description": "List of catalog song IDs to add",
      "items": {
        "type": "string"
      },
      "title": "Track Ids",
      "type": "array"
    }
  },
  "required": [
    "playlist_id",
    "track_ids"
  ],
  "title": "AddToPlaylistParams",
  "type": "object",
  "additionalProperties": false
}

{
  "description": "Result from add_to_playlist",
  "properties": {
    "success": {
      "description": "Whether the operation succeeded",
      "title": "Success",
      "type": "boolean"
    },
    "tracks_added": {
      "description": "Number of tracks added",
      "title": "Tracks Added",
      "type": "integer"
    }
  },
  "required": [
    "success",
    "tracks_added"
  ],
  "title": "AddToPlaylistResult",
  "type": "object"
}

Create a new playlist in the user's Apple Music library.

Optionally add initial tracks to the playlist. Requires music-user-token scope.

Parameters:
    name: Name for the new playlist. Required.
    description: Description for the playlist. Optional.
    track_ids: List of catalog song IDs to add. Optional.

Returns:
    CreatePlaylistResult with:
    - id: New library playlist ID
    - name: Playlist name
    - description: Playlist description
    - track_count: Number of tracks added

Errors:
    ProviderError: Missing music-user-token or invalid request
    ProviderError: Invalid track IDs

{
  "description": "Parameters for create_playlist",
  "properties": {
    "name": {
      "description": "Name for the new playlist",
      "title": "Name",
      "type": "string"
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Description for the playlist",
      "title": "Description"
    },
    "track_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional list of catalog song IDs to add to the playlist",
      "title": "Track Ids"
    }
  },
  "required": [
    "name"
  ],
  "title": "CreatePlaylistParams",
  "type": "object",
  "additionalProperties": false
}

{
  "description": "Result from create_playlist",
  "properties": {
    "id": {
      "description": "New library playlist ID",
      "title": "Id",
      "type": "string"
    },
    "name": {
      "description": "Playlist name",
      "title": "Name",
      "type": "string"
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Playlist description",
      "title": "Description"
    },
    "track_count": {
      "description": "Number of tracks added",
      "title": "Track Count",
      "type": "integer"
    }
  },
  "required": [
    "id",
    "name",
    "track_count"
  ],
  "title": "CreatePlaylistResult",
  "type": "object"
}

Get detailed information about an artist including top songs and albums.

Returns artist metadata, genres, and optionally their top albums and songs.

Parameters:
    artist_id: Apple Music artist catalog ID. Required.
    storefront: Storefront code (e.g., "us", "gb"). Default: "us"
    include: Related resources (albums, playlists, songs, music-videos). Optional.

Returns:
    GetArtistDetailsResult with:
    - artist: Detailed artist information including optional top songs/albums

Errors:
    ProviderError: Artist not found or invalid storefront

{
  "description": "Parameters for get_artist_details",
  "properties": {
    "artist_id": {
      "description": "Apple Music artist catalog ID",
      "title": "Artist Id",
      "type": "string"
    },
    "storefront": {
      "default": "us",
      "description": "Storefront code (e.g., 'us', 'gb'). Default: 'us'",
      "title": "Storefront",
      "type": "string"
    },
    "include": {
      "anyOf": [
        {
          "items": {
            "enum": [
              "songs",
              "albums",
              "playlists",
              "music-videos"
            ],
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Related resources to include. If not specified, returns basic info only.",
      "title": "Include"
    }
  },
  "required": [
    "artist_id"
  ],
  "title": "GetArtistDetailsParams",
  "type": "object",
  "additionalProperties": false
}

{
  "$defs": {
    "ArtistAlbum": {
      "description": "Brief album information for artist details",
      "properties": {
        "id": {
          "description": "Album catalog ID",
          "title": "Id",
          "type": "string"
        },
        "name": {
          "description": "Album name",
          "title": "Name",
          "type": "string"
        },
        "release_date": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Release date",
          "title": "Release Date"
        },
        "artwork_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Artwork URL template",
          "title": "Artwork Url"
        }
      },
      "required": [
        "id",
        "name"
      ],
      "title": "ArtistAlbum",
      "type": "object"
    },
    "ArtistDetails": {
      "description": "Detailed information about an artist",
      "properties": {
        "id": {
          "description": "Apple Music artist ID",
          "title": "Id",
          "type": "string"
        },
        "name": {
          "description": "Artist name",
          "title": "Name",
          "type": "string"
        },
        "genre_names": {
          "description": "Genre names",
          "items": {
            "type": "string"
          },
          "title": "Genre Names",
          "type": "array"
        },
        "artwork_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Artist artwork URL template",
          "title": "Artwork Url"
        },
        "url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Apple Music artist page URL",
          "title": "Url"
        },
        "albums": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/ArtistAlbum"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Top albums (if requested)",
          "title": "Albums"
        },
        "top_songs": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/ArtistSong"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Top songs (if requested)",
          "title": "Top Songs"
        }
      },
      "required": [
        "id",
        "name"
      ],
      "title": "ArtistDetails",
      "type": "object"
    },
    "ArtistSong": {
      "description": "Brief song information for artist details",
      "properties": {
        "id": {
          "description": "Song catalog ID",
          "title": "Id",
          "type": "string"
        },
        "name": {
          "description": "Song name",
          "title": "Name",
          "type": "string"
        },
        "album_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Album name",
          "title": "Album Name"
        }
      },
      "required": [
        "id",
        "name"
      ],
      "title": "ArtistSong",
      "type": "object"
    }
  },
  "description": "Result from get_artist_details",
  "properties": {
    "artist": {
      "$ref": "#/$defs/ArtistDetails",
      "description": "Detailed artist information"
    }
  },
  "required": [
    "artist"
  ],
  "title": "GetArtistDetailsResult",
  "type": "object"
}

Fetch current music charts (top songs, albums, playlists).

Provides context about trending music in a specific storefront/region.
Useful for discovering popular content or understanding current trends.

Parameters:
    types: Chart types to retrieve (songs, albums, playlists, music-videos). Required.
    storefront: Storefront code (e.g., "us", "gb"). Default: "us"
    genre: Genre ID to filter charts. Optional.
    limit: Items per chart type (1-50). Default: 20

Returns:
    GetChartsResult with:
    - charts: List of chart results by type with items and positions
    - storefront: Storefront used for the query

Errors:
    ProviderError: Invalid storefront or API error

{
  "description": "Parameters for get_charts",
  "properties": {
    "types": {
      "description": "Types of charts to retrieve (required)",
      "items": {
        "enum": [
          "songs",
          "albums",
          "playlists",
          "music-videos"
        ],
        "type": "string"
      },
      "title": "Types",
      "type": "array"
    },
    "storefront": {
      "default": "us",
      "description": "Storefront code (e.g., 'us', 'gb'). Default: 'us'",
      "title": "Storefront",
      "type": "string"
    },
    "genre": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Genre ID to filter charts (e.g., '14' for Pop). If not specified, returns overall charts.",
      "title": "Genre"
    },
    "limit": {
      "default": 20,
      "description": "Maximum items per chart type (1-50). Default: 20",
      "maximum": 50,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    }
  },
  "required": [
    "types"
  ],
  "title": "GetChartsParams",
  "type": "object",
  "additionalProperties": false
}

{
  "$defs": {
    "ChartItem": {
      "description": "A single item from a chart",
      "properties": {
        "id": {
          "description": "Apple Music catalog ID",
          "title": "Id",
          "type": "string"
        },
        "name": {
          "description": "Name of the song/album/playlist",
          "title": "Name",
          "type": "string"
        },
        "artist_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Artist name",
          "title": "Artist Name"
        },
        "artwork_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Artwork URL template",
          "title": "Artwork Url"
        },
        "position": {
          "description": "Chart position (1-based)",
          "title": "Position",
          "type": "integer"
        }
      },
      "required": [
        "id",
        "name",
        "position"
      ],
      "title": "ChartItem",
      "type": "object"
    },
    "ChartResult": {
      "description": "A single chart type result",
      "properties": {
        "chart_type": {
          "description": "Type of chart: songs, albums, playlists, music-videos",
          "title": "Chart Type",
          "type": "string"
        },
        "name": {
          "description": "Chart name (e.g., 'Top Songs')",
          "title": "Name",
          "type": "string"
        },
        "items": {
          "description": "Chart items in order",
          "items": {
            "$ref": "#/$defs/ChartItem"
          },
          "title": "Items",
          "type": "array"
        }
      },
      "required": [
        "chart_type",
        "name",
        "items"
      ],
      "title": "ChartResult",
      "type": "object"
    }
  },
  "description": "Result from get_charts",
  "properties": {
    "charts": {
      "description": "List of chart results by type",
      "items": {
        "$ref": "#/$defs/ChartResult"
      },
      "title": "Charts",
      "type": "array"
    },
    "storefront": {
      "description": "Storefront used for the query",
      "title": "Storefront",
      "type": "string"
    }
  },
  "required": [
    "charts",
    "storefront"
  ],
  "title": "GetChartsResult",
  "type": "object"
}

Fetch content the user listens to most frequently (heavy rotation).

Useful for understanding user's core music preferences and most-played content.
Returns albums, playlists, and stations the user plays repeatedly.

Parameters:
    limit: Maximum items to return. Values above 10 are clamped to 10
        (Apple's API cap for this endpoint). Default: 10

Returns:
    GetHeavyRotationResult with:
    - items: List of frequently played content (albums, playlists, stations)
    - count: Number of items returned

Errors:
    ProviderError: Authentication failed or no subscription

{
  "description": "Parameters for get_heavy_rotation",
  "properties": {
    "limit": {
      "default": 10,
      "description": "Maximum number of items to return. Apple's API caps this endpoint at 10; values above 10 are clamped to 10. Default: 10",
      "maximum": 25,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    }
  },
  "title": "GetHeavyRotationParams",
  "type": "object",
  "additionalProperties": false
}

{
  "$defs": {
    "HeavyRotationItem": {
      "description": "A single item from heavy rotation (album, playlist, or station)",
      "properties": {
        "id": {
          "description": "Apple Music catalog ID",
          "title": "Id",
          "type": "string"
        },
        "type": {
          "description": "Type of content: 'albums', 'playlists', or 'stations'",
          "title": "Type",
          "type": "string"
        },
        "name": {
          "description": "Name of the album, playlist, or station",
          "title": "Name",
          "type": "string"
        },
        "artist_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Artist name (for albums)",
          "title": "Artist Name"
        },
        "artwork_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Artwork URL template (replace {w}x{h} with dimensions)",
          "title": "Artwork Url"
        }
      },
      "required": [
        "id",
        "type",
        "name"
      ],
      "title": "HeavyRotationItem",
      "type": "object"
    }
  },
  "description": "Result from get_heavy_rotation",
  "properties": {
    "items": {
      "description": "List of frequently played content",
      "items": {
        "$ref": "#/$defs/HeavyRotationItem"
      },
      "title": "Items",
      "type": "array"
    },
    "count": {
      "description": "Number of items returned",
      "title": "Count",
      "type": "integer"
    }
  },
  "required": [
    "items",
    "count"
  ],
  "title": "GetHeavyRotationResult",
  "type": "object"
}

Search or list songs in the user's Apple Music library.

Can filter by search term or return all library songs with pagination.
Useful for finding specific songs in the user's collection.

Parameters:
    search: Search term to filter songs. Optional.
    limit: Maximum songs to return (1-100). Default: 25
    offset: Pagination offset. Default: 0
    sort: Sort order (dateAdded, name, artistName, albumName). Optional.

Returns:
    GetLibrarySongsResult with:
    - songs: List of library songs
    - total: Number of songs returned
    - has_more: Whether more songs are available
    - next_offset: Offset for next page if has_more is True

Errors:
    ProviderError: Authentication failed or library access denied

{
  "description": "Parameters for get_library_songs",
  "properties": {
    "search": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Search term to filter songs. If not specified, returns all library songs.",
      "title": "Search"
    },
    "limit": {
      "default": 25,
      "description": "Maximum songs to return (1-100). Default: 25",
      "maximum": 100,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "description": "Offset for pagination. Default: 0",
      "minimum": 0,
      "title": "Offset",
      "type": "integer"
    },
    "sort": {
      "anyOf": [
        {
          "enum": [
            "dateAdded",
            "name",
            "artistName",
            "albumName"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Sort order. If not specified, uses default API ordering.",
      "title": "Sort"
    },
    "resolve_mbids": {
      "default": false,
      "description": "Resolve each song to a MusicBrainz recording_mbid via canonical → Typesense cascade. Default: false",
      "title": "Resolve Mbids",
      "type": "boolean"
    }
  },
  "title": "GetLibrarySongsParams",
  "type": "object",
  "additionalProperties": false
}

{
  "$defs": {
    "LibrarySong": {
      "description": "A song in the user's library",
      "properties": {
        "id": {
          "description": "Library song ID",
          "title": "Id",
          "type": "string"
        },
        "catalog_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Catalog ID if available",
          "title": "Catalog Id"
        },
        "isrc": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "ISRC code (from the linked catalog song, when available)",
          "title": "Isrc"
        },
        "name": {
          "description": "Song name",
          "title": "Name",
          "type": "string"
        },
        "artist_name": {
          "description": "Artist name",
          "title": "Artist Name",
          "type": "string"
        },
        "album_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Album name",
          "title": "Album Name"
        },
        "duration_ms": {
          "description": "Duration in milliseconds",
          "title": "Duration Ms",
          "type": "integer"
        },
        "artwork_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Artwork URL template",
          "title": "Artwork Url"
        },
        "date_added": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Date added to library (ISO8601)",
          "title": "Date Added"
        },
        "recording_mbid": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "MusicBrainz recording MBID (populated when resolve_mbids=true)",
          "title": "Recording Mbid"
        },
        "mbid_source": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Resolution tier that matched: 'isrc', 'canonical', or 'typesense'",
          "title": "Mbid Source"
        },
        "mbid_confidence": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Fuzzy match confidence (typesense tier only)",
          "title": "Mbid Confidence"
        }
      },
      "required": [
        "id",
        "name",
        "artist_name",
        "duration_ms"
      ],
      "title": "LibrarySong",
      "type": "object"
    }
  },
  "description": "Result from get_library_songs",
  "properties": {
    "songs": {
      "description": "List of library songs",
      "items": {
        "$ref": "#/$defs/LibrarySong"
      },
      "title": "Songs",
      "type": "array"
    },
    "total": {
      "description": "Number of songs returned",
      "title": "Total",
      "type": "integer"
    },
    "has_more": {
      "description": "Whether more songs are available",
      "title": "Has More",
      "type": "boolean"
    },
    "next_offset": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Offset for next page, if has_more is True",
      "title": "Next Offset"
    },
    "mbid_resolution_error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Set when resolve_mbids=true but the MBID resolution service failed (e.g. timeout) — null MBIDs then mean 'resolution unavailable', not 'no match'",
      "title": "Mbid Resolution Error"
    }
  },
  "required": [
    "songs",
    "total",
    "has_more"
  ],
  "title": "GetLibrarySongsResult",
  "type": "object"
}

Get tracks from a specific playlist (library or catalog).

Can retrieve tracks from user's library playlists or public catalog playlists.
Supports pagination for large playlists.

Parameters:
    playlist_id: Apple Music playlist ID. Required.
    is_library: Whether this is a library playlist (True) or catalog (False). Default: False
    storefront: Storefront code for catalog playlists. Default: "us"
    limit: Maximum tracks to return (1-100). Default: 50
    offset: Pagination offset. Default: 0

Returns:
    GetPlaylistTracksResult with:
    - playlist_name: Name of the playlist
    - tracks: List of tracks in the playlist
    - total: Total tracks in playlist
    - has_more: Whether more tracks are available
    - next_offset: Offset for next page if has_more is True

Errors:
    ProviderError: Playlist not found or access denied

{
  "description": "Parameters for get_playlist_tracks",
  "properties": {
    "playlist_id": {
      "description": "Apple Music playlist ID",
      "title": "Playlist Id",
      "type": "string"
    },
    "is_library": {
      "default": false,
      "description": "Whether this is a library playlist (True) or catalog playlist (False). Default: False",
      "title": "Is Library",
      "type": "boolean"
    },
    "storefront": {
      "default": "us",
      "description": "Storefront code for catalog playlists. Default: 'us'",
      "title": "Storefront",
      "type": "string"
    },
    "limit": {
      "default": 50,
      "description": "Maximum tracks to return (1-100). Default: 50",
      "maximum": 100,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "description": "Offset for pagination. Default: 0",
      "minimum": 0,
      "title": "Offset",
      "type": "integer"
    },
    "resolve_mbids": {
      "default": false,
      "description": "Resolve each track to a MusicBrainz recording_mbid via ISRC → canonical → Typesense cascade. Default: false",
      "title": "Resolve Mbids",
      "type": "boolean"
    }
  },
  "required": [
    "playlist_id"
  ],
  "title": "GetPlaylistTracksParams",
  "type": "object",
  "additionalProperties": false
}

{
  "$defs": {
    "PlaylistTrack": {
      "description": "A track in a playlist",
      "properties": {
        "id": {
          "description": "Track catalog ID",
          "title": "Id",
          "type": "string"
        },
        "name": {
          "description": "Track name",
          "title": "Name",
          "type": "string"
        },
        "artist_name": {
          "description": "Artist name",
          "title": "Artist Name",
          "type": "string"
        },
        "album_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Album name",
          "title": "Album Name"
        },
        "duration_ms": {
          "description": "Duration in milliseconds",
          "title": "Duration Ms",
          "type": "integer"
        },
        "artwork_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Artwork URL template",
          "title": "Artwork Url"
        },
        "isrc": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "ISRC code (when available from Apple Music)",
          "title": "Isrc"
        },
        "recording_mbid": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "MusicBrainz recording MBID (populated when resolve_mbids=true)",
          "title": "Recording Mbid"
        },
        "mbid_source": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Resolution tier that matched: 'isrc', 'canonical', or 'typesense'",
          "title": "Mbid Source"
        },
        "mbid_confidence": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Fuzzy match confidence (typesense tier only)",
          "title": "Mbid Confidence"
        }
      },
      "required": [
        "id",
        "name",
        "artist_name",
        "duration_ms"
      ],
      "title": "PlaylistTrack",
      "type": "object"
    }
  },
  "description": "Result from get_playlist_tracks",
  "properties": {
    "playlist_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Playlist name",
      "title": "Playlist Name"
    },
    "tracks": {
      "description": "List of tracks in the playlist",
      "items": {
        "$ref": "#/$defs/PlaylistTrack"
      },
      "title": "Tracks",
      "type": "array"
    },
    "total": {
      "description": "Total number of tracks in playlist",
      "title": "Total",
      "type": "integer"
    },
    "has_more": {
      "description": "Whether more tracks are available",
      "title": "Has More",
      "type": "boolean"
    },
    "next_offset": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Offset for next page, if has_more is True",
      "title": "Next Offset"
    },
    "mbid_resolution_error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Set when resolve_mbids=true but the MBID resolution service failed (e.g. timeout) — null MBIDs then mean 'resolution unavailable', not 'no match'",
      "title": "Mbid Resolution Error"
    }
  },
  "required": [
    "tracks",
    "total",
    "has_more"
  ],
  "title": "GetPlaylistTracksResult",
  "type": "object"
}

Fetch personalized music recommendations based on library and listening history.

Returns recommendation groups with titles explaining why content was recommended.
Great for discovering new music tailored to user preferences.

Parameters:
    limit: Maximum recommendation groups (1-30). Default: 10
    types: Filter by content types (albums, playlists, stations). Optional.

Returns:
    GetRecommendationsResult with:
    - groups: List of recommendation groups with title, reason, and contents
    - count: Number of groups returned

Errors:
    ProviderError: Authentication failed or no subscription

{
  "description": "Parameters for get_recommendations",
  "properties": {
    "limit": {
      "default": 10,
      "description": "Maximum number of recommendation groups to return (1-30). Default: 10",
      "maximum": 30,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "types": {
      "anyOf": [
        {
          "items": {
            "enum": [
              "albums",
              "playlists",
              "stations"
            ],
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Filter recommendation content types. If not specified, returns all types.",
      "title": "Types"
    }
  },
  "title": "GetRecommendationsParams",
  "type": "object",
  "additionalProperties": false
}

{
  "$defs": {
    "RecommendationContent": {
      "description": "A single recommended content item",
      "properties": {
        "id": {
          "description": "Apple Music catalog ID",
          "title": "Id",
          "type": "string"
        },
        "type": {
          "description": "Type of content",
          "title": "Type",
          "type": "string"
        },
        "name": {
          "description": "Name of the content",
          "title": "Name",
          "type": "string"
        },
        "artist_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Artist name (if applicable)",
          "title": "Artist Name"
        },
        "artwork_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Artwork URL template",
          "title": "Artwork Url"
        }
      },
      "required": [
        "id",
        "type",
        "name"
      ],
      "title": "RecommendationContent",
      "type": "object"
    },
    "RecommendationGroup": {
      "description": "A group of personalized recommendations",
      "properties": {
        "id": {
          "description": "Recommendation group ID",
          "title": "Id",
          "type": "string"
        },
        "title": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Title of the recommendation group",
          "title": "Title"
        },
        "reason": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Why these were recommended",
          "title": "Reason"
        },
        "contents": {
          "description": "Recommended content items",
          "items": {
            "$ref": "#/$defs/RecommendationContent"
          },
          "title": "Contents",
          "type": "array"
        }
      },
      "required": [
        "id",
        "contents"
      ],
      "title": "RecommendationGroup",
      "type": "object"
    }
  },
  "description": "Result from get_recommendations",
  "properties": {
    "groups": {
      "description": "List of recommendation groups",
      "items": {
        "$ref": "#/$defs/RecommendationGroup"
      },
      "title": "Groups",
      "type": "array"
    },
    "count": {
      "description": "Number of recommendation groups returned",
      "title": "Count",
      "type": "integer"
    }
  },
  "required": [
    "groups",
    "count"
  ],
  "title": "GetRecommendationsResult",
  "type": "object"
}

Get detailed information about a specific song.

Returns comprehensive song metadata including duration, release date,
genre, ISRC, composer, and whether lyrics are available.

Parameters:
    song_id: Apple Music song catalog ID. Required.
    storefront: Storefront code (e.g., "us", "gb"). Default: "us"
    include: Related resources to include (artists, albums, genres). Optional.

Returns:
    GetSongDetailsResult with:
    - song: Detailed song information

Errors:
    ProviderError: Song not found or invalid storefront

{
  "description": "Parameters for get_song_details",
  "properties": {
    "song_id": {
      "description": "Apple Music song catalog ID",
      "title": "Song Id",
      "type": "string"
    },
    "storefront": {
      "default": "us",
      "description": "Storefront code (e.g., 'us', 'gb'). Default: 'us'",
      "title": "Storefront",
      "type": "string"
    },
    "include": {
      "anyOf": [
        {
          "items": {
            "enum": [
              "artists",
              "albums",
              "genres"
            ],
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Related resources to include. If not specified, returns basic info only.",
      "title": "Include"
    },
    "resolve_mbids": {
      "default": false,
      "description": "Resolve track to a MusicBrainz recording_mbid via ISRC → canonical → Typesense cascade. Default: false",
      "title": "Resolve Mbids",
      "type": "boolean"
    }
  },
  "required": [
    "song_id"
  ],
  "title": "GetSongDetailsParams",
  "type": "object",
  "additionalProperties": false
}

{
  "$defs": {
    "SongDetails": {
      "description": "Detailed information about a song",
      "properties": {
        "id": {
          "description": "Apple Music catalog ID",
          "title": "Id",
          "type": "string"
        },
        "name": {
          "description": "Song name",
          "title": "Name",
          "type": "string"
        },
        "artist_name": {
          "description": "Artist name",
          "title": "Artist Name",
          "type": "string"
        },
        "album_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Album name",
          "title": "Album Name"
        },
        "duration_ms": {
          "description": "Duration in milliseconds",
          "title": "Duration Ms",
          "type": "integer"
        },
        "release_date": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Release date (YYYY-MM-DD)",
          "title": "Release Date"
        },
        "track_number": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Track number on album",
          "title": "Track Number"
        },
        "disc_number": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Disc number",
          "title": "Disc Number"
        },
        "genre_names": {
          "description": "Genre names",
          "items": {
            "type": "string"
          },
          "title": "Genre Names",
          "type": "array"
        },
        "isrc": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "ISRC code",
          "title": "Isrc"
        },
        "composer_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Composer name",
          "title": "Composer Name"
        },
        "artwork_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Artwork URL template",
          "title": "Artwork Url"
        },
        "preview_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Audio preview URL",
          "title": "Preview Url"
        },
        "has_lyrics": {
          "default": false,
          "description": "Whether lyrics are available",
          "title": "Has Lyrics",
          "type": "boolean"
        },
        "recording_mbid": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "MusicBrainz recording MBID (populated when resolve_mbids=true)",
          "title": "Recording Mbid"
        },
        "mbid_source": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Resolution tier that matched: 'isrc', 'canonical', or 'typesense'",
          "title": "Mbid Source"
        },
        "mbid_confidence": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Fuzzy match confidence (typesense tier only)",
          "title": "Mbid Confidence"
        }
      },
      "required": [
        "id",
        "name",
        "artist_name",
        "duration_ms"
      ],
      "title": "SongDetails",
      "type": "object"
    }
  },
  "description": "Result from get_song_details",
  "properties": {
    "song": {
      "$ref": "#/$defs/SongDetails",
      "description": "Detailed song information"
    },
    "mbid_resolution_error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Set when resolve_mbids=true but the MBID resolution service failed (e.g. timeout) — a null MBID then means 'resolution unavailable', not 'no match'",
      "title": "Mbid Resolution Error"
    }
  },
  "required": [
    "song"
  ],
  "title": "GetSongDetailsResult",
  "type": "object"
}

Get the user's Apple Music storefront (country/region).

The storefront determines which catalog content is available and is required
for many catalog queries. Call this first if you need to query the catalog
for the user's specific region.

Parameters:
    None - This tool takes no parameters.

Returns:
    GetStorefrontResult with:
    - id: Storefront code (e.g., "us", "gb", "jp")
    - name: Full country/region name (e.g., "United States")
    - default_language_tag: Default language (e.g., "en-US")

Errors:
    ProviderError: Authentication failed or no subscription

{
  "description": "Parameters for get_storefront (none required)",
  "properties": {},
  "title": "GetStorefrontParams",
  "type": "object",
  "additionalProperties": false
}

{
  "description": "Result from get_storefront",
  "properties": {
    "id": {
      "description": "Storefront code (e.g., 'us', 'gb', 'jp')",
      "title": "Id",
      "type": "string"
    },
    "name": {
      "description": "Full country/region name (e.g., 'United States')",
      "title": "Name",
      "type": "string"
    },
    "default_language_tag": {
      "description": "Default language tag (e.g., 'en-US')",
      "title": "Default Language Tag",
      "type": "string"
    }
  },
  "required": [
    "id",
    "name",
    "default_language_tag"
  ],
  "title": "GetStorefrontResult",
  "type": "object"
}

Return the OAuth scopes/permissions currently granted for the user's Apple Music connection.

Retrieves scopes from token exchange and calls the Apple Music API to verify
the user's storefront and subscription status.

Parameters:
    None - This tool takes no parameters.

Returns:
    GetUserPermissionsResult with:
    - scopes: List of granted OAuth scope codes (e.g., ["music-user-token"])
    - storefront: User's Apple Music storefront/region (e.g., "us")
    - subscription_active: Whether user has an active Apple Music subscription

Common scopes:
    - music-user-token: Full user authentication for API access, including read
      and write access to the user's library (unlike Spotify, Apple Music uses
      a single scope that grants full access)

Errors:
    ProviderError: User has not connected Apple Music or token is invalid/expired
    ProviderError: No active Apple Music subscription

{
  "description": "Parameters for get_user_permissions (none required)",
  "properties": {},
  "title": "GetUserPermissionsParams",
  "type": "object",
  "additionalProperties": false
}

{
  "description": "Result from get_user_permissions",
  "properties": {
    "scopes": {
      "description": "List of granted OAuth scope codes (e.g., 'music-user-token')",
      "items": {
        "type": "string"
      },
      "title": "Scopes",
      "type": "array"
    },
    "storefront": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "User's Apple Music storefront (ISO country code, e.g., 'us', 'gb')",
      "title": "Storefront"
    },
    "subscription_active": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Whether user has an active Apple Music subscription (if determinable from token)",
      "title": "Subscription Active"
    }
  },
  "required": [
    "scopes"
  ],
  "title": "GetUserPermissionsResult",
  "type": "object"
}

List playlists in the user's Apple Music library.

Returns all playlists saved to the user's library, including both
user-created playlists and playlists added from the catalog.
Supports pagination for large libraries.

Parameters:
    limit: Maximum playlists to return (1-100). Default: 25
    offset: Pagination offset. Default: 0

Returns:
    ListLibraryPlaylistsResult with:
    - playlists: List of library playlists with id, name, description, artwork, etc.
    - total: Number of playlists returned
    - has_more: Whether more playlists are available
    - next_offset: Offset for next page if has_more is True

Errors:
    ProviderError: Authentication failed or library access denied

{
  "description": "Parameters for list_library_playlists",
  "properties": {
    "limit": {
      "default": 25,
      "description": "Maximum playlists to return (1-100). Default: 25",
      "maximum": 100,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "description": "Offset for pagination. Default: 0",
      "minimum": 0,
      "title": "Offset",
      "type": "integer"
    }
  },
  "title": "ListLibraryPlaylistsParams",
  "type": "object",
  "additionalProperties": false
}

{
  "$defs": {
    "LibraryPlaylist": {
      "description": "A playlist in the user's library",
      "properties": {
        "id": {
          "description": "Library playlist ID",
          "title": "Id",
          "type": "string"
        },
        "name": {
          "description": "Playlist name",
          "title": "Name",
          "type": "string"
        },
        "description": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Playlist description",
          "title": "Description"
        },
        "artwork_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Artwork URL template",
          "title": "Artwork Url"
        },
        "can_edit": {
          "default": false,
          "description": "Whether the user can edit this playlist",
          "title": "Can Edit",
          "type": "boolean"
        },
        "date_added": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Date added to library (ISO8601)",
          "title": "Date Added"
        },
        "track_count": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Number of tracks in the playlist",
          "title": "Track Count"
        }
      },
      "required": [
        "id",
        "name"
      ],
      "title": "LibraryPlaylist",
      "type": "object"
    }
  },
  "description": "Result from list_library_playlists",
  "properties": {
    "playlists": {
      "description": "List of library playlists",
      "items": {
        "$ref": "#/$defs/LibraryPlaylist"
      },
      "title": "Playlists",
      "type": "array"
    },
    "total": {
      "description": "Number of playlists returned",
      "title": "Total",
      "type": "integer"
    },
    "has_more": {
      "description": "Whether more playlists are available",
      "title": "Has More",
      "type": "boolean"
    },
    "next_offset": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Offset for next page, if has_more is True",
      "title": "Next Offset"
    }
  },
  "required": [
    "playlists",
    "total",
    "has_more"
  ],
  "title": "ListLibraryPlaylistsResult",
  "type": "object"
}

Resolve MusicBrainz recording MBIDs or ISRCs to Apple Music catalog IDs.

Designed as the reverse direction of resolve_mbids: given MB-native
track identifiers, find the corresponding Apple Music catalog songs
so they can be added to an Apple Music playlist. The primary use case
is mirroring a LB or MB playlist into Apple Music.

Resolution path:
    recording_mbids → brainz enrichment (ISRCs + artist/title)
                   → Apple catalog filter[isrc]=          [tier 1: exact]
                   → (optional) Apple catalog search by (artist, title)
                                                          [tier 2: fuzzy]
    isrcs          → Apple catalog filter[isrc]=          [tier 1: exact]
                   → (optional) brainz ISRC-enrichment + search by
                     (artist, title)                      [tier 2: fuzzy]

Tier 1 is the default and precise path. Tier 2 only fires when
enable_fuzzy_fallback=true (default) AND tier 1 returns no match.
Each resulting match carries a `match_source` field: 'isrc' means
exact-recording guarantee; 'fuzzy' means the top (artist, title)
text-search hit (likely but not guaranteed the same recording).

Apple's catalog endpoint caps ISRC filter lists at 25; we chunk and
parallelize. One ISRC can match multiple catalog songs (remasters,
regional variants) — we pick the lowest catalog ID per ISRC as the
canonical match.

Parameters:
    recording_mbids: List of MBIDs (mutually exclusive with isrcs). Max 50.
    isrcs: List of ISRCs (mutually exclusive with recording_mbids). Max 100.
    storefront: Storefront code (e.g. 'us', 'gb'). Default: 'us'.
    enable_fuzzy_fallback: When the ISRC cascade misses, try
        (artist, title) search. Default: true.

Returns:
    LookupSongsResult with `results`: one item per input, in the
    input order. Each item carries the original mbid/isrc and a
    `match` field (None if no Apple song was found via ANY enabled tier).

Errors:
    ValidationError: Neither recording_mbids nor isrcs provided,
                     or both provided, or either exceeds its max length.

{
  "description": "Parameters for lookup_songs",
  "properties": {
    "recording_mbids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "maxItems": 50,
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "MusicBrainz recording MBIDs to resolve. Each MBID is looked up against the MB replica to find its ISRC(s), which are then queried against Apple's catalog. Mutually exclusive with isrcs; one of the two must be provided. Max 50 per call.",
      "title": "Recording Mbids"
    },
    "isrcs": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "maxItems": 100,
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "ISRCs to look up directly against Apple's catalog. Skips the MBID→ISRC resolution step. Mutually exclusive with recording_mbids; one of the two must be provided. Max 100 per call.",
      "title": "Isrcs"
    },
    "storefront": {
      "default": "us",
      "description": "Storefront code (e.g. 'us', 'gb'). Default: 'us'",
      "title": "Storefront",
      "type": "string"
    },
    "enable_fuzzy_fallback": {
      "default": true,
      "description": "When the ISRC cascade doesn't resolve (no ISRC in MB, or ISRC not in Apple's catalog for this storefront), fall back to (artist, title) text search against Apple's catalog. Trades exact-recording precision for broader coverage. The returned match's `match_source` field tells the caller which path produced it. Default: true — playlist-mirror workflows usually prefer 'find the closest thing' over 'return null'.",
      "title": "Enable Fuzzy Fallback",
      "type": "boolean"
    }
  },
  "title": "LookupSongsParams",
  "type": "object",
  "additionalProperties": false
}

{
  "$defs": {
    "LookupSongsMatch": {
      "description": "Best-matching Apple Music catalog song for a lookup input.",
      "properties": {
        "id": {
          "description": "Apple Music catalog ID",
          "title": "Id",
          "type": "string"
        },
        "name": {
          "description": "Song name",
          "title": "Name",
          "type": "string"
        },
        "artist_name": {
          "description": "Artist name",
          "title": "Artist Name",
          "type": "string"
        },
        "album_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Album name",
          "title": "Album Name"
        },
        "duration_ms": {
          "description": "Duration in milliseconds",
          "title": "Duration Ms",
          "type": "integer"
        },
        "isrc": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "ISRC of the matched song",
          "title": "Isrc"
        },
        "artwork_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Artwork URL template",
          "title": "Artwork Url"
        },
        "match_source": {
          "default": "isrc",
          "description": "How the match was produced. 'isrc' means exact ISRC match against Apple's catalog (same recording as MB). 'fuzzy' means an (artist, title) text search picked the top hit — likely but not guaranteed to be the same recording as MB.",
          "enum": [
            "isrc",
            "fuzzy"
          ],
          "title": "Match Source",
          "type": "string"
        }
      },
      "required": [
        "id",
        "name",
        "artist_name",
        "duration_ms"
      ],
      "title": "LookupSongsMatch",
      "type": "object"
    },
    "LookupSongsResultItem": {
      "description": "One result row per input MBID or ISRC.",
      "properties": {
        "recording_mbid": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The input MBID (populated when recording_mbids was used).",
          "title": "Recording Mbid"
        },
        "isrc": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The ISRC used for the lookup — either the input ISRC, or the ISRC resolved from the MBID. None when the MBID had no ISRC in MB.",
          "title": "Isrc"
        },
        "match": {
          "anyOf": [
            {
              "$ref": "#/$defs/LookupSongsMatch"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Best Apple catalog match (lowest catalog ID, which typically corresponds to the canonical/earliest Apple release). None when no song was found for the ISRC in this storefront."
        }
      },
      "title": "LookupSongsResultItem",
      "type": "object"
    }
  },
  "description": "Result from lookup_songs",
  "properties": {
    "results": {
      "description": "One entry per input, in the same order as the input list.",
      "items": {
        "$ref": "#/$defs/LookupSongsResultItem"
      },
      "title": "Results",
      "type": "array"
    }
  },
  "required": [
    "results"
  ],
  "title": "LookupSongsResult",
  "type": "object"
}

Search the Apple Music catalog for songs, artists, albums, and playlists.

Enables playlist building and library management workflows that require
finding content by name. Essential for workflows like "build me a playlist
with songs by X, Y, Z" without requiring the user to provide catalog IDs.

Parameters:
    term: Search query (e.g., "Red Hot Chili Peppers Give It Away"). Required.
    types: Filter by type (songs, albums, artists, playlists). Optional - returns all if not specified.
    storefront: Storefront code (e.g., "us", "gb"). Default: "us"
    limit: Results per type (1-25). Default: 10

Returns:
    SearchCatalogResult with:
    - results: Container with songs, albums, artists, and playlists arrays
    - storefront: Storefront used for the query

Use Cases:
    1. Playlist building: "Create a running playlist with songs by Rush"
    2. Adding to library: "Add the album 'Blood Sugar Sex Magik' to my library"
    3. Artist exploration: "Find artists similar to Foo Fighters"

Errors:
    ProviderError: Invalid storefront or rate limit exceeded

{
  "description": "Parameters for search_catalog",
  "properties": {
    "term": {
      "description": "Search query (e.g., 'Red Hot Chili Peppers Give It Away')",
      "title": "Term",
      "type": "string"
    },
    "types": {
      "anyOf": [
        {
          "items": {
            "enum": [
              "songs",
              "albums",
              "artists",
              "playlists"
            ],
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Filter by type. If not specified, returns all types.",
      "title": "Types"
    },
    "storefront": {
      "default": "us",
      "description": "Storefront code (e.g., 'us', 'gb'). Default: 'us'",
      "title": "Storefront",
      "type": "string"
    },
    "limit": {
      "default": 10,
      "description": "Results per type (1-25). Default: 10",
      "maximum": 25,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    }
  },
  "required": [
    "term"
  ],
  "title": "SearchCatalogParams",
  "type": "object",
  "additionalProperties": false
}

{
  "$defs": {
    "SearchCatalogResults": {
      "description": "Container for all search result types.\n\nWhen serialized, None values are automatically excluded to reduce response size\nand improve token efficiency in LLM workflows.",
      "properties": {
        "songs": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/SearchResultSong"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Matching songs (if 'songs' type requested or no filter)",
          "title": "Songs"
        },
        "albums": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/SearchResultAlbum"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Matching albums (if 'albums' type requested or no filter)",
          "title": "Albums"
        },
        "artists": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/SearchResultArtist"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Matching artists (if 'artists' type requested or no filter)",
          "title": "Artists"
        },
        "playlists": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/SearchResultPlaylist"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Matching playlists (if 'playlists' type requested or no filter)",
          "title": "Playlists"
        }
      },
      "title": "SearchCatalogResults",
      "type": "object"
    },
    "SearchResultAlbum": {
      "description": "An album in search results",
      "properties": {
        "id": {
          "description": "Apple Music catalog ID",
          "title": "Id",
          "type": "string"
        },
        "name": {
          "description": "Album name",
          "title": "Name",
          "type": "string"
        },
        "artist_name": {
          "description": "Artist name",
          "title": "Artist Name",
          "type": "string"
        },
        "track_count": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Number of tracks",
          "title": "Track Count"
        },
        "release_date": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Release date (YYYY-MM-DD)",
          "title": "Release Date"
        },
        "artwork_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Artwork URL template",
          "title": "Artwork Url"
        }
      },
      "required": [
        "id",
        "name",
        "artist_name"
      ],
      "title": "SearchResultAlbum",
      "type": "object"
    },
    "SearchResultArtist": {
      "description": "An artist in search results",
      "properties": {
        "id": {
          "description": "Apple Music artist ID",
          "title": "Id",
          "type": "string"
        },
        "name": {
          "description": "Artist name",
          "title": "Name",
          "type": "string"
        },
        "genre_names": {
          "description": "Genre names",
          "items": {
            "type": "string"
          },
          "title": "Genre Names",
          "type": "array"
        },
        "artwork_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Artist artwork URL template",
          "title": "Artwork Url"
        }
      },
      "required": [
        "id",
        "name"
      ],
      "title": "SearchResultArtist",
      "type": "object"
    },
    "SearchResultPlaylist": {
      "description": "A playlist in search results",
      "properties": {
        "id": {
          "description": "Apple Music playlist ID",
          "title": "Id",
          "type": "string"
        },
        "name": {
          "description": "Playlist name",
          "title": "Name",
          "type": "string"
        },
        "curator_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Curator/creator name",
          "title": "Curator Name"
        },
        "description": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Playlist description",
          "title": "Description"
        },
        "artwork_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Artwork URL template",
          "title": "Artwork Url"
        }
      },
      "required": [
        "id",
        "name"
      ],
      "title": "SearchResultPlaylist",
      "type": "object"
    },
    "SearchResultSong": {
      "description": "A song in search results",
      "properties": {
        "id": {
          "description": "Apple Music catalog ID",
          "title": "Id",
          "type": "string"
        },
        "name": {
          "description": "Song name",
          "title": "Name",
          "type": "string"
        },
        "artist_name": {
          "description": "Artist name",
          "title": "Artist Name",
          "type": "string"
        },
        "album_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Album name",
          "title": "Album Name"
        },
        "duration_ms": {
          "description": "Duration in milliseconds",
          "title": "Duration Ms",
          "type": "integer"
        },
        "artwork_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Artwork URL template",
          "title": "Artwork Url"
        }
      },
      "required": [
        "id",
        "name",
        "artist_name",
        "duration_ms"
      ],
      "title": "SearchResultSong",
      "type": "object"
    }
  },
  "description": "Result from search_catalog",
  "properties": {
    "results": {
      "$ref": "#/$defs/SearchCatalogResults",
      "description": "Search results by type"
    },
    "storefront": {
      "description": "Storefront used for the query",
      "title": "Storefront",
      "type": "string"
    }
  },
  "required": [
    "results",
    "storefront"
  ],
  "title": "SearchCatalogResult",
  "type": "object"
}

Rate a song, album, playlist, or music video (like/dislike).

Sets or removes a rating on catalog content. Ratings influence recommendations.

Parameters:
    id: Catalog ID of the item to rate. Required.
    type: Type of content (songs, albums, playlists, music-videos). Required.
    rating: Rating value: 1 (like/love), -1 (dislike), 0 (remove rating). Required.

Returns:
    SetRatingResult with:
    - success: Whether the operation succeeded
    - id: ID of the rated item
    - rating: Rating that was set

Errors:
    ProviderError: Item not found or rating failed

{
  "description": "Parameters for set_rating",
  "properties": {
    "id": {
      "description": "Catalog ID of the item to rate",
      "title": "Id",
      "type": "string"
    },
    "type": {
      "description": "Type of content to rate",
      "enum": [
        "songs",
        "albums",
        "playlists",
        "music-videos"
      ],
      "title": "Type",
      "type": "string"
    },
    "rating": {
      "description": "Rating value: 1 (like/love), -1 (dislike), 0 (remove rating)",
      "enum": [
        1,
        -1,
        0
      ],
      "title": "Rating",
      "type": "integer"
    }
  },
  "required": [
    "id",
    "type",
    "rating"
  ],
  "title": "SetRatingParams",
  "type": "object",
  "additionalProperties": false
}

{
  "description": "Result from set_rating",
  "properties": {
    "success": {
      "description": "Whether the operation succeeded",
      "title": "Success",
      "type": "boolean"
    },
    "id": {
      "description": "ID of the rated item",
      "title": "Id",
      "type": "string"
    },
    "rating": {
      "description": "Rating that was set",
      "title": "Rating",
      "type": "integer"
    }
  },
  "required": [
    "success",
    "id",
    "rating"
  ],
  "title": "SetRatingResult",
  "type": "object"
}