spotify-mcp

by Stipe15

Overview Schema Related Servers Score Discussions

Python

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.0
Disambiguation4/5
Most tools target a distinct resource/action, and descriptions carefully separate near-misses like get_playlist vs get_playlist_items and get_top_artists vs top_local. A few analytics tools (dropped_artists, taste_drift, rediscover_tracks) share a similar 'what did I stop listening to' concept, but their time-window semantics are clearly differentiated.
Naming Consistency3/5
Reads consistently use get_* and playlist mutations use verb_* patterns, but the analytics block mixes noun phrases like listening_summary, skip_stats, top_local, taste_drift, and dropped_artists. The naming is readable and grouped by domain, but it is not a single predictable convention.
Tool Count2/5
35 tools is well past the heavy range and creates a large selection surface for agents, even though the set is organized into Spotify reads, playlist writes, and local analytics. Some tools also overlap or subsume others, e.g., build_playlist_from_candidates wraps resolve + create + add, and query_listening_history could replace several named analytics tools.
Completeness4/5
Core workflows are well covered: catalog lookup, library inspection, full playlist lifecycle, and a rich local analytics layer with an SQL escape hatch. The main gaps are playback control (play/pause/skip/seek) and library removal operations (unsave tracks/albums, unfollow artists), which are secondary to this server's data-and-playlist-management focus.
Average 4.1/5 across 35 of 35 tools scored. Lowest: 2.1/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 11 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is clear. However, the description adds no behavioral context about pagination, ordering, errors, or how the album is identified; it merely restates the output concept.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The fragment is short and contains no wasted words, but it is under-specified rather than effectively concise. It lacks a verb and provides almost no structural information that helps an agent invoke the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three parameters, pagination semantics, and many sibling tools for retrieving tracks and playlists, this description is too thin. The output schema may cover return shape, but the description still leaves critical selection and invocation context missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries full responsibility for parameter semantics, but it only implies that album_id refers to the album's tracklist. It does not explain limit and offset as pagination controls, nor does it clarify the expected format or scope of album_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'An album's tracklist' is a noun phrase that essentially restates the tool name get_album_tracks without an action verb. It identifies the resource but does not describe the operation, and it does not differentiate the tool from siblings like get_artist_albums or get_playlist_items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, what arguments are needed, or how it compares to alternative track-listing tools. The description simply names the output and leaves all usage decisions to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the selection criterion (owned or followed playlists) and is consistent with the read-only annotation. However, it says nothing about pagination behavior, ordering, or what fields a followed playlist entry includes. No contradiction with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Six words with no filler, and the 'owns or follows' qualifier earns its place. It is a model of brevity, though it borders on under-specification as a fragment rather than a complete sentence, so it does not quite reach a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is low in complexity (2 optional params), has an output schema so return values are documented elsewhere, and has read-only annotations. What is missing is pagination semantics for limit/offset and any sibling-routing context to help an agent choose among get_playlist, get_playlist_items, or get_saved_albums. Adequate but thin.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the limit and offset properties carry no descriptive text in the schema, and the tool description also fails to mention them. The conventional names and defaults partially mitigate the gap, but the rubric requires the description to compensate at low coverage, and it adds zero parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description is a noun phrase, not a sentence with a verb; the action is implied only by the tool name 'get'. It does identify the resource (playlists) and a meaningful scope ('owns or follows') that distinguishes it from singular get_playlist or track-level get_saved_tracks, but the missing verb and fragment form make the purpose less explicit than it could be.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool vs the 33 sibling tools. There is no mention of get_playlist for a specific playlist, get_playlist_items for contents, or get_saved_albums for saved items, and no exclusions or alternatives are stated. The 'owns or follows' scope is the only implicit hint, which is not enough for routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds useful behavioral detail about include_groups, including the comma-separated format and the 'omit for all' default, and it does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence with no filler, and the important filter semantics are front-loaded. It is slightly telegraphic, stating the resource as a noun phrase rather than a clear verb phrase, but it remains highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity, the readOnlyHint annotation, and the presence of an output schema, the description is largely sufficient for correct invocation. The main gap is the absence of any tool-selection or alternative guidance, which is already penalized under usage_guidelines.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 meaningfully documents include_groups with allowed values and default behavior, but artist_id, limit, and offset are left entirely to their names and schema defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource clearly ('An artist's albums') and the operation is inferable from the tool name. It does not explicitly use a verb like 'retrieve' or contrast with siblings such as get_saved_albums or get_album_tracks, so it is clear but lacks explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like get_saved_albums, search_catalog, or get_album_tracks. The only usage-related content is the include_groups filter, which is parameter behavior rather than tool-selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, and the description adds a useful behavioral trait: results are ordered most recently added first. It does not disclose pagination behavior beyond the schema's limit/offset defaults, but given the safety profile is already annotated, this is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler. It front-loads the resource and then adds ordering context, but it could be slightly more structured by including an explicit verb like 'Retrieves'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, read-only paginated list with an output schema, the description is mostly sufficient: it names the resource and the sort order. It lacks explicit usage guidance and pagination semantics, but the output schema and annotations cover the main operational safety and return expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 undocumented parameters, but it does not mention how limit or offset behave. The parameter names and defaults are somewhat self-explanatory, yet without any description of pagination semantics or bounds, the agent gets no added meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource ('albums saved to the user's library') and adds an ordering detail ('most recently added first'), which separates it from siblings like get_saved_tracks. However, it is a noun phrase rather than an explicit verb+resource statement, so it stops short of a fully explicit purpose declaration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as get_saved_tracks or get_artist_albums. The description implies a read-only saved-library context, but it never states exclusions, prerequisites, or which sibling tool to choose instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The `readOnlyHint` annotation establishes safety, and the description adds meaningful behavior beyond it: results depend on the ingest-timezone configuration (`SPOTIFY_MCP_TIMEZONE`) rather than the user's local clock. It also warns the agent to verify via `server_status` or `describe_listening_data` if results appear shifted, which is valuable non-obvious context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences carry the core purpose, the full valid `by` values, and an important timezone caveat. There is no filler, 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.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema covers return values and the readOnly annotation covers safety, so the description does not need to repeat those. However, with start/end parameters completely undocumented and no guidance on filtering behavior, an agent may not invoke range-filtered calls correctly. The core invocation still works because all parameters are optional, but the gaps keep it from being fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 does explain the `by` parameter with exact allowed values and day-of-week numbering, but it says nothing about `start` or `end` — their format, meaning, inclusivity, or defaults. An agent could incorrectly guess the date string format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that this tool returns play counts and hours broken down by local hour, day of week, or both, and it defines the `by` values. It does not explicitly distinguish itself from sibling listening-analytics tools like `listening_summary` or `skip_stats`, so it falls 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied: use this when you need hourly or day-of-week listening breakdowns. However, it does not explicitly say when to choose this over sibling tools, nor does it state any exclusions. The timezone caveat references `server_status` and `describe_listening_data`, which is helpful but is troubleshooting guidance rather than an alternative-selection rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'the existing items are discarded', which is a destructive side effect, while the annotations declare destructiveHint=false. This is a direct contradiction, so the description's otherwise useful behavioral detail cannot be credited.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: the core operation, the preview and clearing behavior, and the batch limit. The description is front-loaded and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Core behavior and edge cases are covered, and the output schema handles return values. However, the unexplained confirm_token parameter is a gap for a destructive operation, and the contradiction with destructiveHint=false undermines an agent's ability to assess risk.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds real meaning for the uris parameter: empty list clears, and over 100 URIs uses a two-step replacement. However, it says nothing about playlist_id or confirm_token, leaving the purpose of confirm_token in this destructive operation unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Replace a playlist's entire contents with a new list of URIs'. It clearly distinguishes this from incremental operations like add, remove, or reorder by emphasizing the entire contents are replaced and existing items are discarded.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear operational context: use it for full replacement or emptying a playlist, and it explains the 100-URI batching behavior. It does not explicitly name sibling alternatives or state when not to use it, so it stops short of full usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal readOnlyHint=true, so the description does not need to restate that. It adds useful behavioral context by noting that results are optionally filtered by a date range, that an overall skip rate is included, and importantly that is_skip is a heuristic rather than ground truth. This goes beyond the structured annotations, though it stops short of describing the full return shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tight sentence that front-loads the core purpose, then covers parameters, then adds an important caveat with a pointer to more detail. Every phrase earns its place and there is no redundant restating of the tool name or schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only aggregation tool with only two optional parameters, the description is nearly complete: it names the output areas, gives the date format, and references another tool for the key semantic caveat. The main gap is that there is no output schema and the description does not specify exactly which totals are returned (e.g., play count, time listened, or track count), leaving some interpretation open.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides no descriptions for start or end, so the description's explicit mention that they form a YYYY-MM-DD date range and are optional adds real value. However, it does not clarify whether the range is inclusive, what happens if only one bound is provided, or any timezone behavior, leaving some semantic gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as returning 'overall listening totals' with an optional date range, which is a specific, understandable purpose. It gives some implicit differentiation from siblings like listening_by_hour and skip_stats by emphasizing aggregate totals, but it does not explicitly distinguish itself from those tools by name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. The only cross-reference is to describe_listening_data, which is for explaining is_skip rather than for routing to a different summarization tool. Usage context must be inferred from the phrase 'Overall listening totals,' which is too implicit to count as real guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds useful behavioral context beyond the annotations: the precise eligibility filter, the silence window, and the ranking order. It does not describe the response shape, but an output schema exists, so that is not a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact sentence that front-loads the user-facing concept, then states the exact thresholds and ordering. There is no filler, no repetition of schema defaults, and every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only reporting tool with three simple parameters and an output schema, the description supplies the essential selection logic, threshold definitions, and sort order. The only minor omission is explicit treatment of limit, but its name and default make it largely self-explanatory.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description meaningfully defines min_plays and silent_since_months beyond the bare schema titles, and the ranking sentence clarifies output ordering. However, limit is not described at all, and schema description coverage is 0%, so the description carries most but not all of the parameter-explanation burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly identifies the returned set: artists with at least min_plays total plays and none in the last silent_since_months, ranked by historical play count. This is readily distinguishable from siblings like get_top_artists or reDiscover_tracks. It lacks an explicit verb such as 'returns' or 'gets' and does not name a sibling, 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies a discovery/reporting use case ('Artists you used to play a lot but have gone quiet on') and the threshold parameters give the agent control. However, it gives no explicit when-to-use/when-not-to-use guidance or alternative tool names, leaving the agent to infer which circumstance calls for this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only and non-destructive, so the safety profile is covered. The description adds valuable behavioral context beyond those annotations: the 403 failure mode, the ownership/collaboration restriction, and the fact that the item field contains the track/episode object. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, opening with the core purpose and following with the critical restriction. Each sentence earns its place; the 'no way around this restriction' clause is somewhat emphatic but not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description does not need to detail the return shape. It covers the essential invocation context: playlist items, pagination, and the auth-based 403 failure. The main gaps are explicit alternatives and deeper parameter semantics, but those are partially mitigated by the small, self-explanatory parameter set.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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, but it only hints at pagination without explaining playlist_id, limit, or offset. An agent can infer that limit/offset relate to pagination, but the description does not clarify how these parameters behave, what defaults matter, or what forms playlist_id should take.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource as tracks and episodes within a playlist and notes pagination, so an agent knows what the tool returns. It does not explicitly distinguish itself from sibling tools like get_playlist or get_saved_tracks, though the playlist-items scope is reasonably clear from the name and phrasing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives strong contextual guidance: only owned or collaborative playlists are supported, and Spotify returns 403 for others. This effectively tells the agent when not to call the tool, but it does not name alternative tools to use for playlist metadata or other playlist-related lookups.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavior beyond the annotations: it discloses the 256 KB payload cap and the fail-fast pre-confirmation check. This helps the agent avoid unnecessary round trips and sets expectations about validation behavior. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. The core purpose is front-loaded and the behavioral note earns its place by explaining an important limitation. Nothing extraneous is included.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for invoking the tool in a simple case, and an output schema exists so return values need not be described. However, the confirmation-token mechanism and the exact meaning of the pre-check are under-specified, leaving some ambiguity for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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, but it only partially does. It clarifies that image_path points to a local JPEG file, but does not explain the confirm_token flow or how confirmation is offered/obtained, and playlist_id semantics are left entirely to the schema's bare title.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Set'), a specific resource ('a playlist's cover image'), and the input source ('a local JPEG file'). This clearly differentiates the tool from sibling playlist operations like update_playlist_details or create_playlist.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case—setting a playlist cover from a local JPEG—but does not explicitly state when to prefer this over alternatives or mention any exclusions (e.g., remote URLs, non-JPEG formats). Usage context is inferable but not explicitly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so no safety warning is needed. The description adds meaningful behavioral context by clarifying that 'saved' means 'Liked Songs' and by specifying the sort order ('most recent first'), which helps the agent understand what to expect from the result list.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, tightly written sentence that front-loads the core purpose and then supplies the key ordering detail. Every word adds value and there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation, the description covers the resource, the user scope, the naming convention, and the ordering. Annotations cover safety, and an output schema exists, so return-value details are already structured. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate for limit and offset. It does not explain those parameters, but the added 'most recent first' ordering implicitly defines what offset means relative to the list. Since limit and offset are conventional pagination parameters with defaults, the description is adequate but not enriching.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource ('Tracks saved to the user's library') and adds the useful label 'Liked Songs' to resolve naming ambiguity. It is distinguishable from siblings like get_saved_albums and get_recently_played, but it does not explicitly call out any sibling or contrast, so it falls just 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: this is for listing a user's liked/saved tracks, sorted newest-first. There is no explicit guidance about when to prefer this over siblings such as get_recently_played or get_saved_albums, so usage guidance is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true; the description adds meaningful behavioral context by documenting the three time windows and clarifying that results are affinity-based history, not current popularity. Return-format details are covered by the output schema, so the lack of pagination prose is not a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core function, and each clause adds useful information. The negative clarification is compact and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity, read-only tool with an output schema and no required parameters, the description is nearly sufficient. It could be more complete by briefly noting pagination semantics for limit/offset, but nothing critical blocks correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 does explain the important time_range parameter with concrete windows, but leaves limit and offset entirely to inference from their names. Partial compensation only.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: retrieve the user's most-played tracks over a time window. It also adds a distinguishing qualifier ('Spotify's own affinity ranking... not a live popularity/trending signal') that sets it apart from recent-listening or trending-style sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for historical listening affinity rather than live trends, but does not name alternatives or give explicit when-to-use/when-not-to-use guidance. The 'not a live popularity/trending signal' clause is an implicit exclusion only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already indicates a safe read operation, and the description adds important behavioral context by disclosing the cursor-pagination mechanism and how to advance through pages. This goes beyond the annotation's generic safety signal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler. The core purpose is stated first, and the pagination instruction is compactly appended. Every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read-only tool with an output schema present, this description is complete enough. It names the resource, indicates the read-only nature through annotations, and explains the non-obvious cursor parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 carry parameter meaning. It explains that `after` is the last returned artist id used as a cursor, which is valuable. However, it does not clarify the `limit` parameter's role or valid range beyond what the schema's default of 20 implies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource ('Artists the user follows') and the operation (get/retrieve), distinguishing it from sibling tools like get_top_artists. It is specific and unambiguous, though it does not explicitly name a sibling alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to call this tool: to retrieve artists the user follows. It also provides concrete usage guidance for cursor pagination ('pass the last returned artist id as after'). However, it does not state exclusions or compare with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a non-read-only, idempotent, non-destructive operation. The description adds useful behavioral context by stating that only passed fields are changed and that a preview of an old-to-new diff is provided. It does not explain confirm_token or any confirmation flow, but the core mutation behavior is transparent enough given the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff, front-loaded with the primary purpose. Every sentence adds useful information: what changes, partial update semantics, and preview behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the common metadata fields and partial-update behavior, but it is incomplete for a tool with 5 parameters and 0% schema coverage, especially because confirm_token receives no explanation. The output schema likely covers return values, but the input semantics are not fully specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate. It does add meaning for name, description, and public/private visibility, and clarifies partial update behavior, but it leaves confirm_token entirely unexplained despite this being a likely important control parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates a playlist's name, description, and public/private visibility, using a specific verb and resource. It also distinguishes this from playlist item-management siblings by limiting scope to metadata fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Only the fields you pass are changed' line provides clear partial-update semantics and sets expectations for how to invoke the tool. While it does not explicitly name alternatives or exclusion cases, the scoped field list makes the intended use unambiguous among the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a critical non-obvious behavior: the first call returns a preview and a second call with confirm_token executes the creation. It also surfaces the collaborative/public conflict. Since annotations only carry false hints and give no safety detail, this description carries the behavioral burden effectively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense, front-loaded sentences: the action, the confirmation requirement, and the key constraint. Every sentence earns its place with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential invocation details: creation, emptiness, the confirmation flow, and mutually exclusive flags, while pointing to the response for exact confirm_token mechanics. An output schema exists, so return-value description is not needed. It could specify whose account the playlist is created under, but this is reasonably implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 explains confirm_token's role and the collaborative/public constraint, but it does not clarify the name, description, or default behavior of the other parameters. It partially compensates for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Create a new, empty Spotify playlist.' This clearly distinguishes it from the many read/list siblings and from item-mutation tools like add_playlist_items or replace_playlist_items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear operational context: the tool creates a new empty playlist, requires a two-step confirmation flow, and enforces the collaborative/public mutual exclusion. It does not explicitly name alternatives or when-not-to-use conditions, but the intended use case is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is covered; the description adds that the result is 'full metadata' but does not expand on error behavior, rate limits, or result shape. This is acceptable for a trivial get-by-id operation but does not go beyond baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no filler. The key information—what is returned and how the artist is identified—is front-loaded and complete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch-by-id tool with an output schema present and read-only annotations, the description is nearly sufficient. It could be stronger by noting that artist albums are handled by get_artist_albums, but the core usage is not ambiguous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must clarify the single parameter; it does so by specifying that artist_id is a Spotify id. This adds meaning beyond the schema's bare 'Artist Id' field, though it does not give format examples or validation constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('get'), a clear resource ('artist'), and the key qualifier ('by its Spotify id'). It is immediately recognizable as a single-artist metadata lookup and distinct from siblings like get_artist_albums or get_track.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use it: when you already have a Spotify artist id and need the full metadata for that one artist. It does not explicitly name alternatives or exclusion conditions, but the context is clear enough for a simple lookup tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already communicate read-only safety, so the bar is lower. The description adds behavioral value by explaining that the output is a set of track URIs intended for review and downstream playlist construction. It does not mention sorting or whether results are deduplicated, but those are minor gaps given the read-only annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one efficient sentence that front-loads the core concept, adds a helpful example, and names the exact downstream use. No words are wasted and it is easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core use case, required date parameters, the optional recency threshold, and the output format, and an output schema exists for further detail. The only real gaps are the undocumented semantics of limit and min_plays, which are minor because of their self-explanatory names and defaults.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 clearly explains played_start/played_end date format and the meaning of not_since_months. However, it does not describe limit or min_plays, which are only inferable from their names and defaults. This is meaningful partial compensation but not complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies a specific behavior: surfacing tracks heavily played in a past window but untouched for a period. The example and the phrase 'haven't touched since' distinguish it from currently popular or recently played tools, and the output format (track URIs) is stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a concrete use case and even includes a natural-language example ('40 tracks I played a lot in 2023 but haven't touched since'). It also suggests downstream tools for acting on the results. It does not explicitly name sibling tools as alternatives or state when not to use it, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses the exact derivation logic (reason_end='fwdbtn' AND played under the skip threshold), that the derived rate can disagree with the raw 'skipped' field, and that min_plays filters low-sampple noise. It does not describe the output columns or ordering, but the core behavioral traits are transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded. It names the tool's output, explains the key metric formula and caveat, and points to a related tool, all without fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a statistics tool with no output schema, the description explains the grouping options, the metrics reported, and the min_plays threshold purpose. The only meaningful omission is limit's behavior and the exact response shape, but enough context is provided for an agent to invoke the tool correctly with defaults.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only defaults and titles, so the description must carry parameter meaning. It does add meaning for group_by ('artist, track, or month') and min_plays ('filters out low-sample noise'), but limit is not described at all. This leaves a clear gap for a parameter that controls leaderboard size.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Skip-rate leaderboard grouped by artist, track, or month.' This fully captures what the tool computes and clearly differentiates it from sibling stats tools like listening_summary or listening_by_hour.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when this tool is relevant (skip-rate analysis) and mentions describe_listening_data as a reference for the skip definitions. It does not explicitly say when not to use it vs. siblings, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint=true and openWorldHint=false. The description adds meaningful behavioral context: data is local history, not live popularity, and date-range filtering is supported. It does not cover rate limits or authentication, but those are less critical given the read-only annotation and output schema presence.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, with the core functionality front-loaded and the key contextual caveat in the second sentence. No waste or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only ranking tool with an output schema, the description covers entities, metrics, date range, and local-vs-live scope. The main gap is exact parameter value formats, but the call shape is largely inferable and the output schema handles return documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 does map entity to artists/tracks/albums, metric to play count or listening time, and start/end to date range. However, it does not specify exact accepted values for entity or metric, date format, or the limit parameter, leaving some inference required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: it ranks artists, tracks, or albums by play count or total listening time with optional date range filtering. It also differentiates itself by specifying 'YOUR local listening history, not a live popularity signal,' which separates it from sibling tools like get_top_artists and get_top_tracks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: use for local listening history, not live popularity data. It explicitly notes that Spotify removed live popularity endpoints, which prevents the agent from expecting a live signal. It does not name alternative siblings, but the exclusion is strong enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds substantial behavior beyond that: a preview that always shows resolved and unresolved lists before any creation, a low_confidence marker at ~70% resolution, a hard-refusal mode when skip_unresolved=false, and an explicit limitation about chart freshness not being Spotify's own authority. This is exactly the kind of context annotations cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and each subsequent sentence carries real decision-relevant content: freshness limitation, preview/confidence behavior, and skip_unresolved semantics. The freshness caveat is slightly wordy ('say so to the user rather than implying otherwise' could be tighter), but nothing is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a composite 6-parameter tool with an output schema (so return values are covered), the description tells an agent nearly everything needed: the pipeline, the preview guarantee, the confidence threshold, the strict-mode behavior, and the freshness limitation. The only notable gap is the confirm_token flow — it is implied by 'before anything is created' but never explicitly tied to how confirmation is obtained or passed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 does meaningfully: 'candidates' are clarified as {artist, title} objects, and skip_unresolved=false is fully explained ('refuses to create anything unless every single candidate resolves'). But name, public, description, and especially confirm_token receive no semantic explanation — the preview-before-create hint implies a confirmation flow but never connects it to confirm_token explicitly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Resolve {artist, title} candidates and build a new playlist from whatever resolves.' It then names the exact pipeline ('resolve -> create playlist -> add tracks') and 'one two-phase call,' which clearly differentiates it from the standalone siblings resolve_tracks, create_playlist, and add_playlist_items. An agent immediately knows what this tool does and how it differs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The scope is clearly implied: this is for when you already have {artist, title} candidates and want the whole resolve-and-build pipeline in one call. The two-phase framing signals that separate sibling calls exist for piecemeal operation. However, there is no explicit when-not-to-use statement naming an alternative for already-resolved track IDs, so it stops at clear context without formal exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the useful behavioral detail that the result is 'Full metadata' rather than a subset. However, it does not disclose additional runtime concerns such as authentication requirements or possible error behavior, though these are partly mitigated by the output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short, front-loaded sentence with no filler. Every word contributes to the tool's purpose and usage, matching the simplicity of the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-ID lookup with an output schema and read-only annotations, the description is complete enough for an agent to select and call the tool correctly. The input semantics are clear, and the output schema covers the return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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. The only parameter, track_id, is explained as the 'Spotify id', adding platform-specific meaning beyond the schema's generic 'Track Id' title. This is sufficient for a single required parameter, though it does not specify the expected ID format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('get'), a specific resource ('one track'), and the key access mechanism ('by its Spotify id'). It also clearly disinguishes this from sibling tools like get_album_tracks or get_top_tracks by emphasizing single-track lookup by ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'one track by its Spotify id gives clear context for when to invoke this tool: when the agent already knows a specific Spotify track ID and needs metadata for that single track. It does not explicitly name alternatives or exclusions, but the target use case is evident from the wording.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover read-only, idempotent, and destructive hints, and the description adds meaningful behavior beyond them: the tool pins to the playlist's current snapshot if none is supplied, and stale playlists can cause issues. This is useful operational transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences: it states the core operation, defines the key parameters, and adds the snapshot caveat. Every sentence earns its place, 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter mutation tool with no schema parameter descriptions, the description is largely complete: core parameters, defaults, and stale-snapshot behavior are covered. The only gap is confirm_token, which is not explained anywhere, but the output schema and annotations reduce the burden elsewhere.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden. It clearly explains range_start, range_length, insert_before, and snapshot_id behavior. The only unaddressed parameter is confirm_token, but the core move parameters are well defined.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Move'), a precise resource ('a contiguous slice of a playlist's items'), and the destination ('a new position'). It clearly distinguishes this from sibling mutation tools like add_playlist_items, remove_playlist_items, and replace_playlist_items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear operational context: use this to move an item slice, and refresh with get_playlist_items first if the playlist may have changed since the last snapshot. It does not explicitly name alternatives or when-not-to-use, but the main decision context is covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though annotations already signal readOnlyHint and openWorldHint, the description adds valuable behavioral context: the hard cap of limit=10, offset=1000, the matching pitfalls of free_text, and the absence of popularity/relevance scores. This is exactly the kind of non-obvious behavior an agent needs to know before invoking.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: one sentence of purpose, one of usage constraints, and one of output caveat. Every sentence adds non-obvious information, and there is no repetition of schema or annotation content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 optional parameters, zero schema descriptions, and an output schema present, the description covers most of what matters: caps, pagination, filter strategy, and response limitations. The only notable gap is the unexplained 'types' parameter, which could affect whether an agent searches tracks, artists, albums, or other entity types.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden of explaining parameters. It clarifies limit, offset, free_text, and the field-filtered options, but it never mentions the 'types' parameter or explains how multiple filters combine. The parameter names are self-explanatory, yet the description adds useful semantics without fully covering all 9 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and resource ('Search the Spotify catalog') and immediately conveys what the tool does. It also differentiates the tool's role from siblings like get_track or get_artist by framing it as catalog-wide search rather than targeted retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit practical guidance: prefer field-filtered terms over free_text, and paginate with offset because of the limit cap. It stops short of naming sibling alternatives for specific use cases, but within the tool's own parameter space the guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already establishes safety, and the description adds meaningful non-obvious context: email, country, and product tier are never present due to a 2026 API change. This prevents an agent from expecting or depending on these fields, going beyond what the annotation or schema alone would communicate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler: the first states the purpose and primary fields, the second disposes of an important caveat. All content earn its place and the core message is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only profile lookup, the description is complete. The annotations handle the safety profile, an output schema exists for return types, and the description covers both what is present and what is notoriously absent. A caller has everything needed to invoke this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing the description needs to explain about inputs. The schema is trivially fully covered at 100%, and the baseline for zero-parameter tools is 4. The description focuses instead on output semantics, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return') and names the exact resource: the current user's Spotify profile. It lists the concrete fields returned (id, display name, uri, images, follower count), making its purpose unmistakable and clearly distinct from sibling tools that cover playback, playlists, or listening history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly establishes the context: use this when you need the current user's profile identity and follower information. It doesn't explicitly mention alternatives, but no sibling tool overlaps with this profile-retrieval purpose, so the appropriate use is obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this read-only and non-destructive. The description adds valuable behavioral context: the ranking is computed from listening history, and Spotify removed live popularity/trending signals in 2026, explaining why results may look stale or unexpected. This goes beyond what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences accomplish a lot: they define the resource, the time-window semantics, the ranking basis, and a critical exclusion. No filler, and the core purpose appears first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with an output schema, the description sufficiently covers what the tool returns, how the time window works, and what it is not. The output schema handles return-value details, and annotations cover safety, so nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema contains no parameter descriptions, but the description gives meaningful semantics for time_range (short_term=~4 weeks, medium_term=~6 months, long_term=~1 year). Limit and offset are left to inference, but they are conventional pagination parameters with defaults already in the schema, so the key decision-critical parameter is covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States clearly that this returns the user's most-played artists by listening affinity over a time window, which is a specific verb+resource and distinct from generic artist lookup or trending. Differentiates itself from live popularity signals, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear when-to-use context: for personalized affinity rankings over defined time windows. Also provides a when-not-to-use signal by explicitly saying it is not a live popularity/trending tool. It does not name alternative sibling tools, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the minimal annotations (readOnlyHint=false, destructiveHint=false). It discloses automatic chunking, the confirmation behavior across multiple API calls, append-only semantics, lack of deduplication, the position guarantee limitation beyond 100 URIs, and the preview showing raw URIs. This is exactly the kind of behavioral context an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence carries critical operational information. It is front-loaded with the core action, then covers limits, side effects, caveats, and preview behavior without wasted words. The structure makes the most important scoping and failure-mode information easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description reasonably focuses on behavior rather than return values. It covers chunking, deduplication, position limits, confirmation, and preview readability. The only notable omission is explicit guidance on confirm_token, though the mention of 'one confirmation' partially hints at it. Overall, an agent has most of what it needs to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 does explain important parameter-related semantics: URIs are passed by URI, position is 0-based and only reliable for the first 100 items, and chunking affects behavior. However, confirm_token is not explained and playlist_id is only implicitly obvious, so there is still a small gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource combination: 'Add tracks/episodes to a playlist by URI.' It clearly differentiates this from related mutation tools by calling out append-only behavior, no deduplication, and a position caveat, which helps an agent select it over reorder, replace, or remove tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides actionable usage guidance: it explicitly warns to check get_playlist_items first if duplicates matter, and explains how chunking affects API calls and confirmation. It does not explicitly name alternatives like replace_playlist_items or reorder_playlist_items, but the append-only and position limitations imply when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, and the description aligns with that by presenting this as a read-only comparison operation. It goes beyond annotations by detailing exact inclusion rules for each list, the ranking basis for held artists, and the data provenance ('by your own play counts — not an external trend signal'). No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences, zero filler. The core comparison is front-loaded, date format is given inline, and output semantics are enumerated without redundance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and 0% schema coverage, the description is largely complete: date format, list semantics, ranking rule, and data source are all covered. With an output schema present and readOnly annotations, the main omission is the undefined behavior of the optional limit parameter, which prevents full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden for parameter meaning. It explicitly explains the four date parameters with the YYYY-MM-DD format and defines periods A and B conceptually. However, it does not clarify how the optional limit parameter applies—whether it caps each returned list or the total result—leaving a minor but real gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific operation: comparing artist listening between two date periods by share of total plays, then defines the three output categories (gained, lost, held) precisely. The final sentence clarifies this is personal listening data, not an external trend signal, which helps distinguish it from other analytical tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear contextual guidance for when to use this tool: when you need to compare listening across two periods and understand gained, lost, or held artists. It does not explicitly name alternative tools or state when not to use it, but the purpose is obvious enough that an agent can select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag readOnlyHint=true. The description adds useful behavioral context by promising documentation of what is_skip actually means and its limitations, which is beyond the basic read-only indication. Still, it doesn't describe output format, but the output schema is available.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences carry exactly the needed information: what is described, when to use it, and what extra documentation is included. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, zero-parameter documentation tool with an output schema, the description fully covers purpose, usage timing, and content scope. The agent has all it needs to decide to call this tool and understand its value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has zero parameters, so there is nothing to document. The description adds value by describing the content the tool returns, which is the only relevant semantic context. Baseline 4 for zero-param tools is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb ('Describe') and resource ('local listening-history schema'), and enumerates concrete content: tables, views, columns, and example queries. It also explicitly ties itself to query_listening_history, which helps differentiate it from unrelated sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an explicit trigger: 'Read this before writing SQL for query_listening_history'. This tells the agent exactly when the tool should be invoked and orients it as a prerequisite for another tool, which is strong usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses the key edge case: when no device is active, the tool returns active=false with nothing else populated, and explicitly states this is normal, not an error. This prevents an agent from misinterpreting a successful response as failure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two focused sentences with no filler. The core purpose is front-loaded, and the important edge-case behavior is stated efficiently in the second sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters, a readOnlyHint annotation, an output schema, and a description that covers both the normal response contents and the no-active-device edge case, nothing needed for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing for the description to add beyond the schema. The baseline of 4 applies because no parameter documentation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Current Spotify playback state') and enumerates the exact fields returned (what's playing, device, progress, shuffle/repeat). This clearly distinguishes it from the sibling tools, none of which target live playback state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this is for the current playback state, implying use when live, real-time state is needed versus historical tools like get_recently_played. It does not explicitly name alternatives or exclusions, but the 'Current' qualifier is enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers safety, and the description adds useful behavioral context beyond that: it works for any playlist id, but item count is only meaningful for owned or collaborated playlists. It also clarifies that the tool returns metadata, not contents, which is valuable guidance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no wasted words. The core purpose is front-loaded, and the caveat and sibling routing are efficiently included.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and an output schema, the description fully covers what the tool does, when to use it, how it differs from the related sibling, and the key limitation of item counts. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage for parameters is 0%, but the description compensates by explaining that playlist_id can be any playlist id, not just one the user owns. This adds meaningful semantics beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns metadata for one playlist, explicitly listing the fields (name, description, owner, item count) and distinguishing it from the contents of the playlist. This makes the purpose unambiguous and differentiates it from the sibling get_playlist_items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides an explicit routing instruction: use get_playlist_items for tracks, and get_playlist for metadata. It also gives an important caveat about item count reliability, which helps an agent decide when results are meaningful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Explains substantial behavior beyond readOnlyHint/openWorldHint: no silent substitution/dropping, artist matching requirement, what strict/fuzzy modes do, and no chart-popularity bias. This tells an agent exactly what to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each earning its place; the guarantee and core behavior are front-loaded, and the strict/fuzzy explanation follows naturally. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a resolver with output schema and read-only annotations, the description covers the key matching policy, edge cases (sped-up edits, covers, live versions), and the strict toggle. Nothing essential for calling the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description is the only source. It explains the candidates' {artist, title} shape and the strict default/behavior, but could be more explicit about candidate object field requirements beyond the shorthand notation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Resolve') and resource ('{artist, title} candidates' to verified Spotify track URIs), with an explicit guarantee about the two possible outcomes. This distinguishes it from search/list tools in the sibling set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes clear context: resolving candidate track objects to verified URIs, with a strict/fuzzy matching toggle. It doesn't name alternative tools or explicitly state when not to use it, but the intended use case is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial context beyond the readOnlyHint annotation, detailing dry-run mode, OAuth scopes, destructive removal toggles, database build state, and cache stats. This gives an agent a realistic picture of what the read-only call exposes and what conditions may affect results, such as 'if built.'
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One well-organized sentence with a colon-delimited list packs a large amount of specific information without fluff. Every item in the list names a distinct piece of state an agent would want to check.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only diagnostic tool with an output schema present, the description is fully adequate. It enumerates all major status categories and provides conditional context about the listening-history database.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the empty schema already covers all argument semantics. The description appropriately does not invent param documentation and instead clarifies what the no-arg call returns.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb, 'Report,' and a specific resource, 'this server's own state,' then enumerates the exact kinds of state it covers. This sharply distinguishes server_status from all sibling tools, which target Spotify data and user listening history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes clear this is the diagnostic tool for server-level configuration and operational state. It doesn't explicitly name alternatives or when not to use it, but none of the siblings overlap with server status, so the context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral details beyond the readOnlyHint annotation: the 50-play Spotify cap, the ordering guarantee, the Unix ms timestamp format, and the mutual exclusivity of after_ms/before_ms. These are exactly the kind of constraints an agent needs to know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core behavior appears first, followed by the critical cap/alternative warning, then the parameter note. Every sentence contributes necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main behavior, the key limitation, the relevant alternative, ordering, and parameter constraints. The output schema exists to describe return values, so the description does not need to repeat them. This is complete for safe and correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the semantic load. It explains the meaning and units of after_ms and before_ms and their mutual exclusivity, but does not explicitly describe the limit parameter beyond the schema default. This is strong but not fully complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the user's last-played tracks ordered most recent first, which is a specific resource and result. It also explicitly distinguishes itself from a full listening history, preventing confusion with the local analytics sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells agents when not to use this tool: it is not a full listening history, and the local analytics tools should be used for that instead. It also documents the mutually exclusive timestamp parameters, giving clear guidance for invoking it correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description warns 'DESTRUCTIVE', explains that the tool is disabled by default, and describes the safety mechanism tied to snapshot_id. This gives the agent meaningful context about the destructive and state-mutating nature of the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place: destructive warning, enablement condition, snapshot safety prerequisite, and anti-pattern. The most important safety signal is front-loaded befor the technical detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a destructive, disabled-by-default operation with an output schema present. The description sufficiently covers safety, opt-in, prerequisite state, and call restrictions. The optional confirm_token is the only unaddressed param, and it is secondary to correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining the snapshot_id semantics clearly and by saying items are removed 'by URI', which maps to the uris parameter. Playlist_id is self-evident, but confirm_token is never mentioned, leaving a small gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Remove specific items from a playlist by URI.' This clearly distinguishes the tool from siblings such as add_playlist_items, replace_playlist_items, and reorder_playlist_items. There is no ambiguity about what action the tool performs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use and when-not-to-use guidance: only for a specific, user-approved removal request, never from a broad instruction. It also states the prerequisite of fetching a fresh snapshot_id via get_playlist immediately beforehand and mentions the opt-in environment variable needed to enable the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses that mutation statements and dangerous features (PRAGMA, ATTACH, file-reading functions) are rejected before execution, rows are capped, and a timeout applies. This gives the agent an accurate model of safety and limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense, front-loaded sentences with no filler. Every sentence contributes a distinct constraint or usage pointer, and the primary purpose is stated first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter and no output schema, the description covers schema discovery, statement restrictions, result truncation behavior, and timeout. Nothing critical is missing for an agent to invoke this escape-hatch tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Though the schema has no description for the single 'sql' parameter (0% coverage), the tool description compensates by specifying that the value must be a SELECT/WITH-only query, exactly one statement, and that unsupported statements are rejected. This is sufficient semantic guidance for the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names an explicit verb and resource ('Run a read-only SQL query... against the local listening database') and identifies itself as the escape hatch for questions the named analytics tools don't cover. This clearly differentiates it from sibling analytics tools and describes exactly what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit when-to-use rule ('questions the named analytics tools don't cover'), a prerequisite ('Call describe_listening_data first for the schema'), and hard constraints on how to invoke it (single statement, no writes). No alternative is named specifically, but the exclusion of other analytics tools is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![spotify-mcp MCP server](https://glama.ai/mcp/servers/Stipe15/spotify-mcp/badges/card.svg)](https://glama.ai/mcp/servers/Stipe15/spotify-mcp)

Score Badge

Copy to your README.md:

[![spotify-mcp MCP server](https://glama.ai/mcp/servers/Stipe15/spotify-mcp/badges/score.svg)](https://glama.ai/mcp/servers/Stipe15/spotify-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Stipe15/spotify-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server