Provides tools for searching Spotify and reading playlists, saved tracks, artist catalogs, recommendations, and recently played tracks, as well as creating playlists and adding tracks to them.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@spotify-mcp recommend songs similar to 'Blinding Lights'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that wraps spotipy so Claude (or any MCP client) can search Spotify and read playlists, saved tracks, artist catalogs, and discovery signals.
Built specifically as re-com's Spotify backend — read-heavy by design, not a playback-control server. It does support creating playlists and adding tracks to them (so a re-com recommendation list can become a real playlist), but there's no play/pause/queue control; look at one of the several playback-focused Spotify MCP servers already out there for that.
Tool | Description |
| Search Spotify. |
| List the current user's playlists. Omit |
| Get the tracks in a playlist. Local files/episodes are skipped. |
| Get the user's saved ("Liked Songs") tracks. |
| Get a single track's metadata. |
| Spotify's algorithmic recommendations from one seed track — the closest analog to YouTube Music's radio. |
| Get an artist's profile. |
| An artist's top tracks (Spotify caps this at ~10 — there's no full-catalog endpoint). |
| Artists related to the given one. |
| The user's recently played tracks. |
| Create a new playlist owned by the current user. |
| Add tracks (by ID or URI) to a playlist, chunked in batches of 100. |
| Delete the cached OAuth token. |
A real limitation, stated plainly: Spotify restricts /recommendations and artist_related_artists for API apps created after November 2024 that don't have "Extended Quota Mode" (a manual approval Spotify grants sparingly). If your app doesn't have it, get_recommendations and get_related_artists will 403 — handle_errors turns that into a clear message rather than a raw traceback, and re-com's spotify_client.py treats it as one signal being unavailable, not a fatal error. search_music, playlists, saved tracks, and artist top tracks are unaffected.
Other Claude Code projects on this machine (e.g. re-com) call these tools by spawning this server over MCP rather than talking to spotipy/Spotify themselves — this is the only place Spotify credentials live.
Related MCP server: spotify-mcp
Go to the Spotify Developer Dashboard, create an app.
Add a redirect URI matching SPOTIFY_REDIRECT_URI (default http://127.0.0.1:8888/callback — you don't need anything actually listening on that port; see step 3).
Note the app's Client ID and Client Secret.
python3 -m venv .venv
source .venv/bin/activate
pip install -e .export SPOTIFY_CLIENT_ID="..."
export SPOTIFY_CLIENT_SECRET="..."
python scripts/setup_auth_spotify.pyThis prints an authorization URL, waits for you to log in and paste back the URL you're redirected to (works fine over SSH/headless — nothing needs to bind the redirect port), and writes the resulting token to .spotify_cache (path configurable via SPOTIFY_CACHE_PATH).
.spotify_cache is equivalent to your logged-in session — never commit it or share it. It's already gitignored. Tokens refresh automatically once cached; re-run this script only if refresh itself starts failing (e.g. the app's client secret was rotated, or you revoked access from your Spotify account settings), or if SCOPE in server.py gains new permissions (delete .spotify_cache first so the auth flow re-prompts for consent — a stale cached token won't pick up new scopes on its own).
claude mcp add spotify -s user \
-e SPOTIFY_CLIENT_ID="..." \
-e SPOTIFY_CLIENT_SECRET="..." \
-e SPOTIFY_CACHE_PATH="$(pwd)/.spotify_cache" \
-- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"-s user makes it available in any Claude Code session, not just this directory. Use absolute paths for the python interpreter, server.py, and SPOTIFY_CACHE_PATH since the server can be launched from any working directory.
For other MCP clients (Claude Desktop, etc.), point them at the same command and env vars using their respective config format.
The unit test suite (tests/) runs against a hand-rolled fake spotipy.Spotify client — no network access or Spotify credentials needed:
pip install -e ".[dev]"
pytestTool calls translate common failure modes into clear messages instead of raw tracebacks:
Missing/expired auth (401) → tells you to redo authenticate step.
Restricted/forbidden (403) → tells you it's likely a Spotify API access restriction (see the recommendations/related-artists caveat above) or a missing OAuth scope.
Rate limiting (429) → tells you to wait, including the Retry-After hint if Spotify sent one.
Any other API or OAuth error is reported directly rather than as a raw traceback.
MIT — see LICENSE.
Add tracks to a playlist by Spotify track ID (or URI). Chunks in batches of 100, Spotify's per-request limit.
| Name | Required | Description | Default |
|---|---|---|---|
| track_ids | Yes | ||
| playlist_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It adds useful transparency by noting that batches are chunked to Spotify's 100-item per-request limit, which is beyond the schema. However, it does not disclose other side effects or prerequisites such as playlist ownership, duplicate handling, or whether tracks are appended.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The action is front-loaded, and the second sentence adds the key batching detail. Every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simple two-parameter contract, the description covers the core operation and the main API limit, and an output schema exists to handle return details. It is not exhaustive (no mention of error cases or ownership), but it is sufficient for correct invocation in the common case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It does clarify that track_ids accepts Spotify track IDs or URIs, which is meaningful. It does not add detail for playlist_id or explicitly state the 100-item batch behavior as a parameter constraint, so compensation is partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Add tracks to a playlist', with the method (by Spotify track ID or URI). This clearly distinguishes it from siblings like get_playlist_tracks, create_playlist, and search_music without needing to inspect schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied: use this tool when you need to add tracks to an existing playlist. It does not explicitly contrast with alternatives like create_playlist or get_playlist_tracks, nor does it state when not to use it, but the name and description make the primary scenario clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new playlist owned by the current user and return it (id, name, ...).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| public | No | ||
| description | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the behavioral disclosure burden. It does state that the playlist is owned by the current user and that the created playlist is returned, which is useful. But it does not disclose authorization requirements, side effects beyond creation, or any limitations such as playlist name uniqueness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that leads with the action and includes the key ownership and return behavior. There is no filler or redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The input schema and presence of an output schema help, but the description alone leaves gaps around parameter meaning and when to select this tool over siblings. It is minimally adequate for a straightforward create call but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description needed to explain the parameters (name, public, description), but it does not. The only mention of 'name' refers to the return value, not the input parameter. The schema provides types and defaults but no semantic explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Create' with a clear resource, 'a new playlist owned by the current user', and even notes the return value. This distinguishes it from sibling tools like get_playlists or add_tracks_to_playlist without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose strongly implies when to use it: when a new playlist should be created for the current user. However, it does not explicitly mention alternatives or conditions like 'do not use this for adding tracks' or 'use get_playlists to list existing playlists'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get an album's tracks. Omit limit to fetch all of them.
Album track objects are the "simplified" shape and carry no album key of
their own, so callers that need one should attach it from the album they
asked for.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| album_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses a non-obvious output trait: track objects are simplified and lack an `album` key, and it tells callers how to handle that. This goes well beyond a generic 'get' description, though it doesn't mention errors, auth, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: the main action is front-loaded, and the important behavioral caveat about the simplified shape is separated into its own short paragraph. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple read tool with an output schema available, so the description doesn't need to explain return values. It covers the key non-obvious details: default behavior for `limit` and the missing `album` key in result objects. Minor gaps like explicit routing versus sibling tools prevent a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaningful semantics for `limit` by explaining that omitting it fetches all tracks, but it doesn't describe valid limit values or elaborate on `album_id` beyond its name and type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the resource and action: retrieving an album's tracks. It also differentiates the result shape from other track-returning tools by noting the simplified track objects, so an agent can distinguish it from siblings like get_playlist_tracks or get_artist_top_tracks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear context for when to call this tool: when you need an album's tracks. The instruction to omit `limit` to fetch all tracks provides a concrete usage rule, though it doesn't explicitly name alternatives or exclusions relative to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get an artist's profile (name, genres, popularity, images).
| Name | Required | Description | Default |
|---|---|---|---|
| artist_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool is a read operation ('Get') but doesn't disclose any behavioral traits such as authentication requirements, rate limits, or what happens if the artist_id is invalid. The output schema exists but the description adds no behavioral context beyond the verb.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the action and resource, then lists the key return fields. Every word earns its place; no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema exists, so return values are covered. However, with no annotations and no parameter explanation, the description is incomplete for an agent that needs to know how to construct a valid call (e.g., what artist_id format is expected). It's adequate for a simple lookup but leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the artist_id parameter beyond its name. The description mentions the profile fields but doesn't clarify the format or source of artist_id (e.g., Spotify ID vs. URL). With only one parameter, the description should have compensated but didn't.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and resource ('artist's profile'), and lists the fields returned (name, genres, popularity, images). This clearly distinguishes it from siblings like get_artist_top_tracks and get_artist_albums, though it doesn't explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: call this when you need an artist's profile details. It doesn't explicitly state when to use it versus alternatives like get_artist_top_tracks or get_related_artists, but the field list (name, genres, popularity, images) provides enough context for an agent to infer the right scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get an artist's albums and singles. Omit limit to fetch all of them.
This plus get_album_tracks is the only route to an artist's real catalog
that survives Spotify's post-Nov-2024 restrictions: get_artist_top_tracks
403s for apps without Extended Quota Mode and caps at ~10 even when it
works. Appears-on and compilation albums are excluded -- they would credit
the artist for other people's records.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| artist_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral burden. It discloses the limit-omission behavior (fetch all), the exclusion of appears-on/compilation albums with reasoning, and the Spotify restriction context. This goes well beyond the schema and gives the agent a clear picture of what the tool does and does not return.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two paragraphs with no wasted words. The core action and limit behavior are front-loaded, followed by the sibling distinction and exclusions. It's slightly longer than minimal but every sentence adds value, so a 4 is appropriate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential usage, exclusions, and limitations. An output schema exists, so return-value details are presumably structured there. It doesn't mention pagination or rate limits, but these are secondary given the output schema and the clear scope. Overall, the description is complete enough for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It explains the `limit` parameter's semantics ('Omit limit to fetch all of them') which adds meaning beyond the schema's type/default. The `artist_id` parameter is self-evident from its name. This is sufficient compensation for a two-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'an artist's albums and singles.' It explicitly distinguishes itself from get_artist_top_tracks and positions itself as one of two viable routes to the real catalog, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use guidance by naming the alternative get_artist_top_tracks and explaining its failure modes (403 without Extended Quota Mode, caps at ~10). It also states what is excluded (appears-on and compilation albums) and why, so an agent knows exactly when to choose this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get an artist's top tracks (Spotify caps this at ~10 -- there's no "full catalog" endpoint the way YouTube Music's channel Songs tab has).
| Name | Required | Description | Default |
|---|---|---|---|
| artist_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It usefully reveals the ~10 track cap and the absence of a full-catalog endpoint, which are meaningful constraints. It does not mention auth, error behavior, or other side effects, but the tool is a simple read operation and output schema exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one tight, front-loaded sentence with the core action stated first. The parenthetical is useful context about the tool's limits, not filler, so every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter lookup with an output schema, the description is mostly adequate and the cap note is valuable. However, it omits usage context such as how top tracks relate to the other track/album endpoints and provides no parameter guidance, leaving some gaps for the agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no information about the artist_id parameter beyond the name already present in the schema. It does not specify whether this is a Spotify ID, URI, or URL, so it fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the operation: 'Get an artist's top tracks,' naming a specific resource and action. It does not explicitly distinguish this from sibling tools like get_artist_albums or get_album_tracks, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to choose this tool over the many sibling track/album tools, nor any when-not-to-use note. The parenthetical explains a platform limitation but does not route the agent to an alternative or state selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the authenticated user's own profile (id, display_name, ...).
The id is the only way to tell a playlist the user owns from one they
merely follow: get_playlists returns both, indistinguishable except by
owner.id. That distinction is load-bearing rather than cosmetic --
Spotify 403s playlist_items on another user's playlist, so a caller that
treats followed playlists as its own gets an error it cannot act on.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It makes the read-only nature evident through 'Get,' clarifies that the result is the authenticated user's own profile, and adds a load-bearing consequence about playlist ownership. It doesn't discuss rate limits or errors, but for a zero-parameter getter with an output schema, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in the first sentence, and the second paragraph is compact but substantive: it explains why the returned id matters and prevents a common authorization failure. Every sentence earns its place; there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, a low-complexity read operation, and an existing output schema, the description provides everything an agent needs: what the tool returns, that it is the authenticated user's profile, and why the id is critical for playlist ownership decisions. No essential guidance is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema already represents that with 100% coverage, so there is nothing for the description to add. Per the baseline for 0 parameters, a 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get the authenticated user's own profile (id, display_name, ...).' This clearly identifies what the tool does and is distinct from sibling tools like get_playlists or get_saved_tracks, so an agent can differentiate it without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives strong contextual guidance: get_playlists returns both owned and followed playlists, and owner.id is the only way to distinguish them. It doesn't explicitly say 'use this tool when you need the current user's id,' but the implication is clear and reinforced by the Spotify 403 consequence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the current user's playlists. Omit limit to fetch all of them.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It usefully discloses the default behavior ('Omit limit to fetch all of them') and implies a read-only operation with 'List'. However, it does not mention auth requirements, pagination behavior, or what happens when limit is explicitly provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler. The core purpose is front-loaded and the second sentence adds necessary parameter nuance without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity read-only list tool with an output schema and a single optional parameter, the description is nearly complete. It covers the key behavior and default, though it omits minor details like permission requirements and limit edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description adds real value by explaining that omitting limit fetches all playlists. This conveys the parameter's purpose and default semantics beyond the bare schema type and default value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and a clear resource ('the current user's playlists'), which distinguishes it from siblings like get_playlist_tracks or create_playlist. The scope is unambiguous even without naming alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives such as get_playlist_tracks or create_playlist. The phrase 'current user's playlists' gives context, but no exclusions, prerequisites, or route-to-sibling instructions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the tracks in a playlist. Omit limit to fetch the entire playlist.
Local files and episodes (no track id) are skipped. See _track_of for
the two payload shapes this has to read.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| playlist_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden and does meaningful work: it discloses that local files and episodes without a track id are skipped and warns that two payload shapes need to be handled via `_track_of`. It stops short of explaining auth, error, or return details, but the output schema covers return shape and no side-effect hazards remain hidden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences with no filler: purpose first, limit behavior second, edge-case handling third. Every sentence contributes information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter fetch with an output schema present, the description covers the main invocation choice, the edge cases, and the payload complexity. It is not exhaustive about failure modes or authentication, but those are not necessary for a simple playlist-track lookup.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the parameters. It adds real meaning for `limit` ('omit to fetch the entire playlist'), but `playlist_id` is only implied by the tool name and sentence rather than explicitly documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and object: 'Get the tracks in a playlist,' which clearly identifies both the action and the target resource. The tool name and sibling set make its scope obvious, and it is distinct from album, saved-track, and individual-track lookups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a concrete behavioral instruction: omit `limit` to fetch the entire playlist, implying limit should be supplied when a partial fetch is desired. It does not explicitly state when a sibling tool should be preferred, but the playlist-scoped context is clear enough for an agent to route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the user's recently played tracks (each item wraps a "track" key).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries more responsibility. It does disclose the read-only nature through 'Get' and adds a useful response-shape detail with 'each item wraps a track key.' However, it says nothing about authentication, pagination, rate limits, or error behavior, so the behavioral disclosure is only partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence that states the verb and resource immediately. The parenthetical about the 'track' key is brief and adds meaningful return-shape information without padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and an output schema, the description is nearly sufficient. However, it lacks usage guidance against similar siblings and provides minimal parameter context, while the absence of annotations leaves some safety/behavioral expectations unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description never mentions the limit parameter. The parameter name 'limit' and default 50 give a reasonable hint, but the description adds no semantic value beyond the schema, so it fails to compensate for missing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource and action: 'Get the user's recently played tracks.' The phrase 'recently played' distinguishes this from sibling tools like get_saved_tracks and get_playlist_tracks, so an agent can tell them apart without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance about when to use this tool versus alternatives such as get_saved_tracks or get_playlist_tracks. The description implies the use case by naming 'recently played,' but it never states exclusions, prerequisites, or why an agent should choose this over a sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get Spotify's algorithmic recommendations seeded from one track.
May 403 if this app doesn't have access to /recommendations -- Spotify restricts it for apps created after Nov 2024 without Extended Quota Mode.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| seed_track_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the behavioral disclosure burden. It proactively discloses the potential 403 error and why it can occur (Spotify's Extended Quota Mode restriction), which is valuable. However, it does not explicitly state that the operation is read-only or mention rate limits, though 'Get' implies a read.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: one clear purpose sentence followed by a focused caveat. No filler or redundant explanations, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with an output schema, the description is nearly complete: it explains the key input semantics and the important failure mode. The only gaps are the optional limit behavior and the null allowance, but these are visible in the schema, so the description is still adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning to seed_track_id ('seeded from one track') but leaves limit unexplained and does not address the schema's allowance for null in seed_track_id or the expected track ID format. This is insufficient for a low-coverage schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('Spotify's algorithmic recommendations') and clarifies the seeding basis ('from one track'). This distinguishes it from sibling tools like search_music or get_artist_top_tracks without needing to inspect schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the usage context (recommendations seeded from a single track) but does not explicitly state when to choose this over alternatives such as get_related_artists or get_artist_top_tracks. There are no exclusion conditions or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current user's saved ("Liked Songs") tracks. Omit limit for all of them.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It does disclose one useful behavioral trait: omitting limit returns all tracks rather than a default page. But it does not mention read-only behavior, authentication expectations, ordering, or pagination details, so the burden is only partially met.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The main purpose is front-loaded, and the limit instruction earns its place because it changes the default behavior of the only parameter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only tool with an output schema, the description is reasonably complete: it states what is returned and how to request all items. The main gaps are the lack of explicit sibling differentiation and broader behavioral context, but these are already reflected in other dimensions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning beyond the schema by explaining that omitting limit returns all tracks, which the schema's bare 'default: null' does not convey. It does not spell out valid integer bounds, but for a single optional limit parameter this is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Get the current user's saved (
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The resource is clear enough that an agent can infer when to use this tool: whenever the current user's saved tracks are needed. However, there is no explicit mention of alternatives or any when-not-to-use guidance relative to siblings like get_playlist_tracks or get_album_tracks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single track's metadata (title, artists, album, ...).
| Name | Required | Description | Default |
|---|---|---|---|
| track_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral disclosure burden; 'Get' and 'metadata' imply a read-only retrieval and signal no mutation, which is adequate for a simple lookup. However, it does not mention error responses, authentication requirements, or the absence of side effects beyond what the verb implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler; every word contributes to defining the operation and the metadata examples add useful detail without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, has only one parameter, and an output schema exists, so the description is minimally viable. It lacks guidance on obtaining track_id, error scenarios, and interaction with sibling tools, leaving some context gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain the track_id parameter beyond its name. It does not specify ID format, where to obtain it, or any constraints, so the description adds little to the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and names a precise resource ('a single track's metadata') with examples of included fields, which distinguishes it from sibling tools like get_album_tracks, get_playlist_tracks, and get_saved_tracks that operate on different collections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives such as search_music or get_album_tracks, no prerequisites, and no indication of how to obtain a valid track_id. Usage context must be inferred entirely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete the cached Spotify OAuth token.
Subsequent tool calls will fail until you re-authenticate via scripts/setup_auth_spotify.py.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently states that it deletes the cached token and that calls will fail until re-authentication, which is a key behavioral consequence. It does not cover every edge case (e.g., server-side effects), but for a local token deletion this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two sentences that state the action and its consequence. No filler or redundant information, and the key fact is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, has no parameters, and has an output schema, so the description does not need to explain return values. It covers purpose, effect, and recovery steps, making it complete for an agent to decide and call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters (schema coverage 100% with empty properties), so the baseline of 4 applies. The description adds no parameter-specific meaning because there are none to describe.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete the cached Spotify OAuth token') with a specific verb and resource. It is easily distinguished from sibling tools that deal with music and playlists, as this is the only auth-related tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool, but it implies usage by describing the consequence (subsequent calls fail until re-auth). It also suggests the re-authentication path, which gives some context, but no explicit when-to-use or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Spotify. filter is "track" or "artist".
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| filter | No | track |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description bears the full disclosure burden. It implies a read-only search operation, but it does not mention behavior such as pagination, limit effects, result ordering, or the fact that search is restricted to tracks/artists beyond the filter parameter itself. This is minimal behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with no filler; both sentences earn their place and the key parameter hint is front-loaded. It borders on under-specification, but that issue is more relevant to contextual completeness than to conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and only a one-sentence description, the tool is under-specified for confident use among 15 siblings. The output schema helps with return values, but the description still lacks usage context, query expectations, and behavioral details needed for a 3-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It usefully explains the filter parameter's allowed values ('track' or 'artist'), which is the least obvious parameter. Query is reasonably inferable from its name, but limit receives no semantic explanation, so compensation is only partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear operation ('Search') and resource ('Spotify'), and the filter line narrows the target to tracks or artists. It is understandable on its own, though it does not explicitly differentiate itself from sibling get_track or get_artist tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus alternatives such as get_track, get_artist, or get_recommendations. No conditions, exclusions, or preferred use cases are given, so the agent must infer when search is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0add_tracks_to_playlistcreate_playlistget_album_tracksget_artistget_artist_albumsget_artist_top_tracksget_current_userget_playlist_tracksget_playlistsget_recently_playedget_recommendationsget_related_artistsget_saved_tracksget_tracklogoutsearch_musicScored across 16 tools
Most tools are clearly distinct by resource (tracks, playlists, artists, albums, user). Minor overlap: get_playlist_tracks vs get_saved_tracks vs get_recently_played all return track lists, but their source contexts are clear. get_artist_top_tracks and get_artist_albums both provide artist catalog access, though descriptions clarify the distinction.
The set predominantly follows a verb_noun pattern (get_*, create_playlist, add_tracks_to_playlist, search_music, logout). The two exceptions are search_music and logout, which are still readable and not jarring. Overall consistent and predictable.
16 tools is slightly above the ideal 3-15 range but appropriate for Spotify's broad domain (search, user library, playlists, artists, albums, recommendations). Each tool covers a distinct need; no obvious redundancy.
The surface covers search, playlist CRUD (create, read, add tracks), saved tracks, artist/album browsing, and user info. Notable gaps: no update/delete playlist, no remove tracks from playlist, no play/control playback, no track/album search filtering beyond track/artist, and no user's top items. Core browsing is solid but lifecycle coverage is incomplete.
MCP server for Russian books search, details, and recommendation candidates.
An MCP server that provides tools to discover and retrieve podcast episodes transcripts.
MCP server for Suno AI music generation, lyrics, and covers
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
