F
licenseA
qualityD
maintenanceEnables AI assistants to control Spotify playback, search for music, manage playlists, and access library information through the Spotify API. Requires Spotify Premium for playback control features.
4
-
SpotifyScraper MCP Server
by AliAkhtari78
Provides tools for extracting public Spotify data including tracks, albums, artists, playlists, podcasts, lyrics, and transcripts without requiring an API key. Supports search, downloading covers and previews, and accessing related artists and recommendations.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@SpotifyScraper MCP Serverget the lyrics for 'Bohemian Rhapsody'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
SpotifyScraper
Extract public Spotify data — tracks, albums, artists, playlists, and podcasts — without the official API or an API key.
🎧 Try it live in your browser → — paste any Spotify link and watch SpotifyScraper pull typed data, cover art, and a preview, with the exact Python that does it. (How it was built.)
SpotifyScraper bootstraps an anonymous token from Spotify's own public embed
pages and reads the same JSON endpoints the web player uses, returning typed,
immutable models. v3 is a ground-up rewrite focused on reliability and a clean,
modern API. Public data needs no login; the opt-in logged-in features
(lyrics, podcast transcripts, and account info) add your own Spotify sp_dc
cookie — never a password or an API key.
Upgrading from v2? See the migration guide. The previous line lives on the
v2.xbranch.
SpotifyScraper vs. the official API (spotipy)
spotipy wraps Spotify's official Web API — the right choice when you need to
write to a user's account or read private/library data. SpotifyScraper reads the
public data the web player already exposes, so it skips the setup entirely.
SpotifyScraper | spotipy (official API) | |
API key / app registration | ❌ not needed | ✅ required |
OAuth flow | ❌ not needed | ✅ required for most data |
Rate-limit quota / billing | none | Spotify quota |
Sync and async | ✅ | sync only |
Fully typed, immutable models | ✅ | partial |
Lyrics & podcast transcripts | ✅ (cookie) | ❌ |
MCP server for Claude / LLM agents | ✅ | ❌ |
Write / playback / private data | ❌ (read-only public) | ✅ |
Use spotipy for authenticated writes and private, market-accurate data; use SpotifyScraper for fast, key-free access to public metadata, lyrics, and previews — plus a drop-in MCP server for AI agents.
Hit by the official-API deprecations? Spotify's
audio-features,recommendations, andrelated-artistsendpoints have returned403for new apps since Nov 2024. SpotifyScraper still returns related artists and recommendations with no API key. (It can't bring backaudio-features— Spotify removed that data entirely, from every tool.)
Related MCP server: Spotify MCP Node Server
Install
pip install spotifyscraper # core (only depends on httpx)
pip install "spotifyscraper[media]" # + cover/preview embedding (mutagen)
pip install "spotifyscraper[browser]" # + Playwright browser fallback & login
pip install "spotifyscraper[cli]" # + the spotifyscraper command-line tool
pip install "spotifyscraper[keyring]" # + store the login cookie in the OS keyring
pip install "spotifyscraper[mcp]" # + the spotifyscraper-mcp MCP server for LLM hosts
pip install "spotifyscraper[all]" # everythingPython 3.10+.
Quickstart
from spotify_scraper import SpotifyClient
with SpotifyClient() as client:
track = client.get_track("https://open.spotify.com/track/4uLU6hMCjMI75M1A2tKUQC")
print(track.name, "—", track.artists[0].name)
print(track.duration_ms, "ms |", track.preview_url)
print(track.to_dict()) # JSON-safe dict, if you prefer dictsEvery entity has its own method — get_track, get_album, get_artist,
get_playlist, get_episode, get_show — each accepting a URL, URI, or bare
ID.
Async
import asyncio
from spotify_scraper import AsyncSpotifyClient
async def main():
async with AsyncSpotifyClient() as client:
track, album = await asyncio.gather(
client.get_track("4uLU6hMCjMI75M1A2tKUQC"),
client.get_album("6N9PS4QXF1D0OWPk0Sxtb4"),
)
print(track.name, "|", album.name)
asyncio.run(main())Download a cover and preview
from spotify_scraper import SpotifyClient
with SpotifyClient() as client:
track = client.get_track("4uLU6hMCjMI75M1A2tKUQC")
client.download_cover(track, dest="covers/")
client.download_preview(track, dest="previews/", embed_cover=True) # needs [media]Localized display names
Pass locale — a BCP-47 language tag: a bare language subtag ("de",
"ja") or a language-region tag ("ja-JP") — to localize the language of
display names. Set it per client or override it per call:
with SpotifyClient(locale="ja-JP") as client: # default for every call
track = client.get_track("4uLU6hMCjMI75M1A2tKUQC")
other = client.get_track("4uLU6hMCjMI75M1A2tKUQC", locale="de-DE") # per-call winsIt is sent as the Accept-Language header and changes only how names are
spelled. It is not a country/market code — a bare "US" is meaningless as
a language and is ignored — and it does not filter regional availability
or vary preview URLs: anonymous Spotify resolves country from the request IP,
and its pathfinder silently ignores a market variable. True market/availability
filtering requires the authenticated Web API, which this library does not
implement; for region-specific results, point the client's proxy at the target
region. See the
localization guide.
Features
All core entities + podcasts — tracks, albums, artists, playlists, shows, episodes.
Search across every entity type, returning one typed
SearchResults.Charts & discovery — editorial charts, related artists, full paginated discography, and album recommendations.
Cover colors & Canvas — extract an artwork's theming palette and download a track's looping Canvas video.
Credits & concerts — performers/writers/producers and an artist's upcoming live events.
Public user profiles —
get_user()(name, follower counts, public playlists).MCP server — expose everything to Claude/LLMs via
spotifyscraper-mcp(batch tools + a one-callget_track_visuals); also ships as a container on ghcr.io.Localized display names — pass a BCP-47 language tag (
locale) to set the language of names.Lyrics & podcast transcripts — cookie-authenticated, time-synced, one token for both.
Browser-assisted login + session persistence — log in once, then run headless (no stored passwords).
Account-aware —
get_account()/is_premium(), plus cookie-freesession_info().Batch helpers — plural
get_*s([...])with partial-failure-safe results and managed concurrency.Sync & async clients sharing one sans-io core.
Typed, frozen models with JSON-safe
to_dict()/from_dict().Two-tier resilience — Spotify's GraphQL API with automatic fallback to the embed page.
One core dependency (
httpx); media and browser support are optional extras.Optional response cache — opt-in, persistent, token-safe (only token-free pathfinder GETs).
Anti-ban built in — per-host rate limiting, retries with backoff, UA rotation, proxies.
Browser fallback via Playwright when you need a real browser.
Command line
With the cli extra installed, a spotifyscraper command is available:
spotifyscraper track 4uLU6hMCjMI75M1A2tKUQC # entity metadata as JSON
spotifyscraper playlist <id> --max-tracks 50 --pretty
spotifyscraper download preview <id> -o ./previews --embed-coverEvery command emits JSON, so it composes with tools like jq. See the
CLI guide.
Batch helpers
Each getter has a plural sibling (get_tracks, get_albums, …) that fetches
many inputs and returns one BatchItem per input — index-aligned, and a dead
input never aborts the rest:
items = client.get_tracks(["4uLU6hMCjMI75M1A2tKUQC", "bad-id"])
ok = [i.result for i in items if i.ok]
failed = {i.value: i.error for i in items if not i.ok}The async client runs them concurrently, bounded by max_concurrency (default
5). See the batch guide.
Response caching
For repeated lookups, enable an opt-in persistent cache. It only stores token-free pathfinder responses — never the embed pages that carry the anonymous token — so no credential is ever written to disk:
from spotify_scraper import SpotifyClient, CacheConfig, FileCache
with SpotifyClient(cache=CacheConfig(store=FileCache())) as client:
client.get_track("4uLU6hMCjMI75M1A2tKUQC") # first call hits the network
client.get_track("4uLU6hMCjMI75M1A2tKUQC") # served from the cacheDefault TTL is 24h; the FileCache is stdlib-only and the backend is pluggable.
See the caching guide.
Search
search() runs one anonymous, aggregate query across every entity type and
returns a typed SearchResults:
from spotify_scraper import SpotifyClient
with SpotifyClient() as client:
results = client.search("daft punk", types=("track", "artist"), limit=5)
print(results.total, "track matches")
for track in results.tracks:
print(track.name, "—", track.artists[0].name)Hits are sparse (pass an id to get_album()/get_show() for the full entity);
total is the track-match count. See the
search guide.
Lyrics & transcripts
Lyrics and podcast transcripts need a Spotify account cookie (sp_dc); the
library handles the token handshake for you, and one cookie powers both:
from spotify_scraper import SpotifyClient
with SpotifyClient(cookies="cookies.txt") as client: # or cookies={"sp_dc": "..."}
lyrics = client.get_lyrics("4uLU6hMCjMI75M1A2tKUQC")
for line in lyrics.lines:
print(line.start_ms, line.text)
transcript = client.get_transcript("07gKzPFkbvGF0cHoeG7ARS") # a podcast episode
for line in transcript.lines:
print(line.start_ms, line.text)Your cookie is sent only to Spotify and never logged. An episode with no
transcript raises NotFoundError. See the
lyrics & cookies guide.
Browser-assisted login
Don't want to copy a cookie by hand? login() opens a real browser, you sign in
once, and the captured sp_dc is persisted (no password is ever collected or
stored). Later runs reconnect headlessly — ideal for servers:
from spotify_scraper import SpotifyClient
with SpotifyClient() as client:
client.login() # reuse a valid session, else open a browser
print(client.get_lyrics("4uLU6hMCjMI75M1A2tKUQC").sync_type)
# A later, headless run — no browser needed:
with SpotifyClient.from_saved_session() as client:
account = client.get_account() # who am I?
print(account.product, account.country, client.is_premium())
transcript = client.get_transcript("07gKzPFkbvGF0cHoeG7ARS")login() reuses a valid saved session by default (browser only the first time);
from_saved_session() never needs the browser extra. The cookie is stored in
an owner-only file, or the OS keyring with store="keyring" (the keyring
extra). get_account()/is_premium() report the logged-in account, and
SpotifyClient.session_info() checks a saved session without exposing the
cookie. See the
authenticated sessions guide.
Roadmap
Shipped
Version | Scope |
3.0 | The library: all entities, pagination, media downloads, browser fallback, docs |
3.1 | Command-line interface |
3.2 | Cookie-authenticated lyrics |
3.3 | Cookie-authenticated podcast transcripts ( |
3.4 | Search across every entity type ( |
3.5 | Optional response cache ( |
3.6 | Visual & discovery: cover colors, Canvas videos, charts, related artists, paginated discography, recommendations, public profiles, track credits, concerts · a best-in-class MCP server + container image |
3.7 | MCP batch tools ( |
3.8 | Maintenance: dependency, toolchain & CI modernization (all Actions on current majors, SHA-pinned) · docs & PyPI backlinks |
3.9 | Official MCP registry publishing (+ Glama/mcp.so/PulseMCP/Smithery discovery) · "vs spotipy" comparison · one-time, opt-out CLI star hint |
What's next — future ideas are tracked in the GitHub milestones and issues — 👍 or weigh in on the ones that matter most to you. Scope is subject to change.
Reliability & maintenance
This library rides Spotify's own public endpoints, so it can break when Spotify changes them. To keep it dependable:
A daily canary runs the live test suite against Spotify. When an endpoint shifts, it automatically opens a
spotify-breakageissue (and closes it on recovery), so regressions surface before they reach you.Breakages are triaged and fixed promptly with the help of Claude Code (Anthropic's coding agent), under the maintainer's review — the same agent-assisted workflow that keeps this project moving. Persisted-query hashes live in a single file (
api/pathfinder.py), so a Spotify rotation is a one-line update.Every change runs through
ruff+mypy --strict+ a hermetic test suite (85% coverage floor) across Python 3.10–3.13 on Linux, macOS, and Windows.
If something is broken for you, please open an issue — the monitoring has often caught it already.
Documentation
Full docs, guides, and the API reference: https://spotifyscraper.readthedocs.io
The MCP server also ships as a container:
docker run -p 8000:8000 ghcr.io/aliakhtari78/spotifyscraper (set SPOTIFY_SP_DC
to enable the authenticated tools).
Legal
SpotifyScraper is an unofficial, independent project, not affiliated with Spotify. It reads publicly available data and the ~30-second previews Spotify publishes; it does not download full tracks or circumvent DRM. Use it for educational and personal purposes, and in line with Spotify's Terms of Service. See the legal notice.
Contributing
Contributions are welcome — see CONTRIBUTING.md. The project
is developed spec-first with OpenSpec;
specs live in openspec/.
Star history
If SpotifyScraper saved you the official-API OAuth dance, a ⭐ helps other developers find it — and tells me which features to keep building.
License
MIT © Ali Akhtari — full-stack AI engineer (aliakhtari.com).
Available Tools
28 toolsget_accountA
Fetch the logged-in account's product state (needs SPOTIFY_SP_DC).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It reveals the authentication requirement (SPOTIFY_SP_DC) but does not disclose other behavioral traits such as read-only nature, rate limits, or error responses. The disclosure is partial but helpful.
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, front-loaded sentence. Every word is essential, no filler. It efficiently conveys purpose and a key requirement.
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?
An output schema exists, so return value details are covered. The description provides core purpose and auth info but could improve by noting what 'product state' means or typical use cases. Still, it's largely complete for a simple parameterless tool.
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?
There are zero parameters, and schema coverage is 100%, so the baseline of 3 applies. No additional parameter semantics are needed as the tool requires no input.
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 fetches the 'logged-in account's product state', specifying a unique resource distinct from siblings like get_track or get_playlist. The verb 'Fetch' and resource 'account product state' are specific and 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?
The description includes a crucial prerequisite: 'needs SPOTIFY_SP_DC', guiding the agent on required credentials. While it doesn't explicitly list when to use alternatives, the context implies this is for account-level data, distinct from other get tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_albumC
Fetch an album (with its tracks) by URL, URI, or ID.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It mentions fetching with tracks, which is helpful, but lacks information on read-only nature, authentication, rate limits, or potential side effects. The description is minimal and does not go beyond the basic function.
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, straightforward sentence that efficiently conveys the core functionality. It is well-structured and lacks any redundant information.
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 has a simple interface (one parameter) and an output schema is present, which reduces the burden on the description. However, the description omits important context such as authentication requirements, rate limits, or any edge cases. It is adequate for a basic fetch but not fully complete.
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 coverage is 0%, but the description adds meaning by stating that the 'value' parameter accepts 'URL, URI, or ID', which clarifies the type of input expected. This 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'fetch', resource 'album', and adds detail that it includes tracks. This distinguishes it from siblings like 'get_track' or 'get_artist'. The mention of 'by URL, URI, or ID' further specifies the input. However, it could be slightly more explicit about the output format.
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 on when to use this tool vs alternatives (e.g., 'get_albums' for multiple albums). The description implies usage for single album lookup but does not provide context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_albumsA
Fetch many albums at once; one ordered result per input, failures captured per item.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| values | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description mentions ordered result and failure capture, but does not disclose read-only nature, authentication needs, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is front-loaded with purpose and efficiently conveys key behaviors (ordered results, failure handling). No unnecessary words.
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?
With output schema present, return value explanation is not needed. Lacks details on pagination or input size limits, but sufficient for a straightforward list fetch tool.
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?
0% schema description coverage. 'Many albums at once' implies 'values' parameter is list of identifiers, but does not specify what values represent (e.g., album IDs) or format requirements.
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 clearly states the action 'Fetch many albums at once' with specific verb and resource. It distinguishes from sibling 'get_album' by indicating batch processing.
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?
Implies use for multiple albums via 'many at once', but lacks explicit when-not-to-use or alternatives. Siblings include single-fetch tools, so context helps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_artistB
Fetch an artist by URL, URI, or ID.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
B3.4/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It only implies a read operation ('Fetch') but discloses no side effects, auth needs, rate limits, or return behavior. Minimal transparency.
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?
Single sentence of 9 words, front-loaded and concise. Every word earns its place, though slightly more detail could be added without harming conciseness.
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?
Given a simple single-parameter tool and the presence of an output schema, the description is minimally adequate. However, it does not explain how the three identifier types differ or what the response contains, and lacks guidance among many siblings.
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% with no parameter description. The description adds 'by URL, URI, or ID' which gives semantic meaning to the 'value' parameter beyond what the schema provides (just a string title). However, it lacks specific format details.
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 'Fetch an artist by URL, URI, or ID' with a specific verb and resource, and distinguishes it from sibling tools like get_track or get_album which fetch different resources.
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 on when to use this tool versus alternatives. With many sibling get_* tools, there is no differentiation or exclusion criteria, leaving the agent to guess context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_artist_eventsC
Fetch an artist's upcoming concerts/events.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
C2.4/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that events are 'upcoming', but lacks details on timeframe, pagination, authentication, rate limits, or behavior when no events exist. This is minimal transparency for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, but it is under-specified. It lacks essential information, making it less a model of conciseness and more a placeholder.
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?
Despite the presence of an output schema, the description fails to explain the input parameter, provide usage context, or disclose behavioral traits. For a tool with one parameter and no annotations, this is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'value' has no schema description (0% coverage) and the tool description adds no explanation of what 'value' represents (e.g., artist ID or name). This leaves the agent unable to correctly populate the parameter.
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?
Description clearly states the verb 'Fetch' and resource 'artist's upcoming concerts/events', distinguishing it from sibling tools like 'get_artist' which return artist metadata. However, it could be more precise about what 'upcoming' means and whether it returns a list or single event.
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 usage guidelines provided. The description does not specify when to use this tool vs alternatives, nor does it mention any prerequisites or context for using it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_artistsA
Fetch many artists at once; one ordered result per input, failures captured per item.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| values | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description adds value by revealing ordered results and per-item error handling, though it could mention read-only nature.
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?
Single sentence conveying all key points with no fluff, front-loaded with main purpose.
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?
Essential behavior is covered (batch, ordering, errors), but lacks input specification and constraint details; output schema exists so return values need not be explained.
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 coverage is 0%, but description does not clarify what 'values' contains (IDs? names? URIs?), leaving the agent to guess.
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 'Fetch' and resource 'many artists', and it distinguishes from siblings like 'get_artist' by emphasizing batch 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?
It implies usage for multiple artists (vs singular calls) and mentions failure handling, but does not explicitly state when to prefer this over alternatives like 'get_artist'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_canvasC
Fetch a track's Canvas looping video (needs SPOTIFY_SP_DC).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
C2.9/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses authentication requirement (needs SPOTIFY_SP_DC), which is a behavioral trait. However, no annotations exist, and description does not state read-only nature, rate limits, or other behavioral details.
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?
One sentence, very concise. But lacks necessary details, making it under-informative rather than efficiently complete.
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?
Despite having an output schema, description is minimal. Lacks explanation of what Canvas is, return format, or error conditions, leaving the agent underinformed for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter 'value' has no description in schema (0% coverage) and description adds no meaning. Does not clarify that 'value' is likely a track ID.
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 states verb 'Fetch' and resource 'track's Canvas looping video', distinguishing it from sibling tools like get_track. Adds prerequisite 'needs SPOTIFY_SP_DC'. Could be more specific about what 'Canvas' is.
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?
Mentions authentication requirement ('needs SPOTIFY_SP_DC'), implying usage context. No explicit guidance on when to use this tool vs alternatives like get_track or get_track_visuals.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_chartB
Fetch an editorial chart (e.g. 'top-50-global') as a playlist.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | ||
| max_tracks | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
B3/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only says 'fetch,' implying a read operation, but does not mention auth requirements, rate limits, or any side effects. The lack of detail on return format (despite output schema) or safe usage lowers the score.
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 sentence that conveys the core purpose efficiently. No unnecessary words or redundancy.
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?
For a simple fetch tool with only two parameters and an output schema, the description is minimally adequate. However, it does not explain what an 'editorial chart' is, how to find valid keys, or describe the output structure. More context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for parameters, and the description does not explain the meaning of 'key' (beyond an example) or 'max_tracks' (e.g., its purpose, bounds, or effect). This fails to add value 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 identifies the action (fetch) and resource (editorial chart) with an example ('top-50-global'), and the phrase 'as a playlist' adds specificity. It distinguishes from siblings like list_charts (lists charts) and get_playlist (gets user playlists).
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 provided on when to use this tool versus alternatives (e.g., list_charts, get_playlist), nor any prerequisites or exclusions. The description only states what it does, not the context for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_colorsA
Extract a cover image's theming colors (image URL/uri, or any entity URL/URI/ID).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A3.7/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states that the tool extracts colors, without detailing error handling, output format, or side effects. This is minimal 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 a single, efficient sentence with parenthetical qualifiers. It is front-loaded with the action and avoids any redundant or irrelevant information.
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 has one parameter and an output schema, so the description need not detail return values. However, it lacks explanation of what 'theming colors' means or how many colors are returned, which is minor but leaves some ambiguity.
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 has 0% description coverage, but the description compensates by explaining that the single 'value' parameter accepts image URLs/URIs or any entity URL/URI/ID, adding meaningful context beyond the raw type.
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 a specific verb ('Extract') and resource ('theming colors from a cover image'). It distinguishes this tool from siblings like get_cover_image or get_track by focusing on color extraction rather than retrieval of the image or entity data.
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 usage by specifying acceptable inputs (image URL/URI or entity URL/URI/ID), but it does not explicitly state when to use this tool versus alternatives like get_cover_image, nor does it mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_cover_imageC
Return an entity's cover art as an inline image.
kind is one of track/album/artist/playlist/episode/show.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | track | |
| value | Yes |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states what the tool does but does not disclose behavioral traits like authentication requirements, rate limits, error handling (e.g., if no cover art exists), or whether the image is cached. The description is minimal on behavior.
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?
Two sentences with no fluff: the first states the core purpose, the second explains the 'kind' values. Very concise, but could benefit from a brief note on the 'value' parameter or output format. Still, every sentence earns its place.
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 two parameters and no output schema, the description is incomplete. It explains only one parameter partially ('kind'), and omits details on the required 'value' parameter and the return format (e.g., data URL, base64, binary). No output schema exists. This is inadequate for reliable tool 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?
The description clarifies the 'kind' parameter by listing valid values, which adds value beyond the schema's default-only definition. However, the 'value' parameter (required) is not described at all, leaving its semantics (e.g., entity ID vs name) unclear. Schema coverage is 0%, so the description partially compensates but is incomplete.
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 the verb 'Return' and the resource 'entity's cover art as an inline image', and specifies the valid entity kinds. This distinguishes it from sibling get_* tools which return metadata, not images. However, 'inline image' is somewhat ambiguous (e.g., URL vs base64).
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 provided on when to use this tool versus alternatives (e.g., other get_* tools). There is no mention of prerequisites, such as needing a valid entity ID, or when not to use it. The purpose is implied but not explicitly contextualized.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_creditsA
Fetch a track's credits — performers, writers, producers (needs SPOTIFY_SP_DC).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It discloses the authentication requirement (SPOTIFY_SP_DC), which adds behavioral context beyond the schema. However, it does not mention error handling, rate limits, or what happens without the credential.
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 concise sentence that front-loads the purpose and appends the key requirement. No wasted words.
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?
Has an output schema but doesn't need to describe returns. However, the parameter is undocumented, and the tool's complexity (1 param, no annotations) is not fully addressed. The description omits what 'value' should be, making it incomplete for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and description does not explain the single required parameter 'value' (likely a track ID or URL). Despite low coverage, description adds no parameter meaning, which severely impacts agent ability to invoke correctly.
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?
Clearly states the verb 'Fetch' and the resource 'a track's credits', listing examples (performers, writers, producers). This distinguishes it from sibling tools like get_track or get_lyrics.
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?
Explicitly notes the prerequisite '(needs SPOTIFY_SP_DC)', indicating a required credential. While it doesn't mention when-not-to-use or alternatives, the context of sibling tools implies it's for specific credit data needing special auth.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_discographyB
Fetch an artist's full discography (albums, singles, compilations).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes | ||
| max_releases | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
B3/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations and a generic description, the tool does not disclose behavioral traits such as authentication requirements, rate limits, pagination, error behavior, or data freshness. The description only states the action without any side-effect or safety context.
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, clear sentence that is appropriately short. However, it sacrifices crucial details for brevity, which slightly reduces its effectiveness. Still, it is well-structured and front-loaded.
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 the presence of an output schema and multiple sibling tools, the description fails to provide complete context. It does not specify input parameter purposes, output structure, or appropriate usage scenarios, leaving significant gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the meaning of 'value' (likely artist ID/name) or 'max_releases' limit. The parameter names provide minimal intuition, but the description adds no additional semantic value beyond the schema itself.
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 specifies the verb 'Fetch', the resource 'artist's full discography', and enumerates contents like albums, singles, and compilations. This clearly distinguishes it from sibling tools such as get_album, get_track, and others that focus on individual items.
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 using this tool when needing an artist's entire discography, but it lacks explicit guidance on when not to use it or alternatives. There is no mention of preferring other tools for specific albums or tracks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_episodeB
Fetch a podcast episode by URL, URI, or ID.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
B3.3/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; the description does not disclose behavioral traits such as authentication requirements, error handling (e.g., if episode not found), rate limits, or side effects. With no annotations, the description should cover these, but it does not.
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 sentence that is front-loaded with the key action and resource. It is concise and to the point, though additional context could be added without becoming verbose.
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 the tool has only one parameter and an output schema exists, the description is minimal. However, it lacks usage guidelines and behavioral transparency, making it incomplete for an agent to reliably decide when and how to invoke it.
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?
Although the schema has 0% description coverage, the description adds value by explaining that the 'value' parameter can be a URL, URI, or ID. This clarifies the acceptable input format, which is not evident from the schema alone.
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 action 'Fetch' and the resource 'podcast episode', specifying three identifier types (URL, URI, or ID). It distinguishes from siblings like get_episodes (plural) and get_show by focusing on a single episode retrieval.
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 on when to use this tool versus alternatives like get_episodes (for multiple episodes) or get_show (for the whole show). The description only states what it does, not context-specific usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_episodesB
Fetch many episodes at once; one ordered result per input, failures captured per item.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| values | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
B3.3/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description reveals that failures are captured per item, a non-obvious behavioral trait. However, with no annotations, it does not disclose read-only status, rate limits, or other safety aspects. Adequate but not comprehensive.
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 wasted words, front-loaded with action. Efficient and easy to digest.
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?
Lacks essential information for a batch operation: input format (what the strings should be), authentication requirements, output schema details, and any limits on the number of inputs. Incomplete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and description fails to explain the single parameter 'values'. It does not specify what the strings represent (e.g., episode IDs, URLs), leaving the agent to guess.
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 clearly states 'Fetch many episodes at once', specifying verb and resource. The phrase 'one ordered result per input, failures captured per item' distinguishes this batch operation from the single-episode sibling tool 'get_episode'.
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 batch usage, but no explicit guidance on when to use this tool versus the singular 'get_episode'. No mention of when not to use or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_lyricsB
Fetch a track's lyrics (needs SPOTIFY_SP_DC).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
B3/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description discloses an authentication requirement (SPOTIFY_SP_DC), adding behavioral context beyond the schema. However, it does not mention rate limits, side effects, or output behavior, leaving gaps that annotations would normally fill.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but it is under-specified. The brevity comes at the cost of missing essential parameter documentation, making it less useful overall.
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?
The tool has one simple parameter and an output schema, but the description fails to explain the input or output. Given the low schema coverage (0%) and lack of annotation support, the description is incomplete for reliable tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one required parameter 'value' with 0% description coverage. The description provides no explanation of what 'value' represents (track ID, URL, etc.), leaving the agent without critical information to invoke the tool correctly.
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 action ('Fetch a track's lyrics') and the specific resource. It is distinct from sibling tools like get_track or get_album, and the verb+resource combination is precise.
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 mentions a prerequisite ('needs SPOTIFY_SP_DC'), which hints at when the tool is usable, but it does not elaborate on when to choose this tool over alternatives like search or get_track. No explicit when-not or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_playlistB
Fetch a playlist by URL, URI, or ID (up to max_tracks tracks).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes | ||
| max_tracks | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
B3.2/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must fully disclose behavior. It states 'Fetch' (read-only) and hints at a track limit, but does not mention authentication, rate limits, error handling, or what happens if the identifier is invalid. The behavior is minimally conveyed.
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?
A single, front-loaded sentence conveys the core purpose efficiently. No redundant words, though the backtick formatting around max_tracks is slightly informal.
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?
Given the presence of an output schema, the description does not need to detail return values. However, it lacks mention of pagination, track object details, or constraints (e.g., max tracks for non-owner playlists). For two parameters, it provides sufficient but not complete context.
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 coverage is 0%, so the description must compensate. It explains max_tracks as an upper limit and indicates value accepts URL, URI, or ID, but does not specify the expected format (e.g., full URL vs. Spotify ID). This adds some meaning but leaves ambiguity.
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 action ('Fetch'), the resource ('a playlist'), and identifies multiple identifier types (URL, URI, or ID) and a parameter constraint (up to max_tracks tracks). This specificity distinguishes it from sibling tools like get_track or get_album.
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 provided on when to use this tool versus alternatives like search or get_playlists. The description implies usage for fetching a single playlist but lacks when-not-to-use or context about prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_playlistsA
Fetch many playlists at once (up to max_tracks each); failures captured per item.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| values | Yes | ||
| max_tracks | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A3.8/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility. It discloses batch fetching behavior, a cap on tracks per playlist via max_tracks, and per-item failure capture, which are crucial behavioral traits beyond the input 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?
A single sentence that front-loads the main action and efficiently conveys key behavior (batch, track limit, failure capture) without any redundant words.
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?
For a 2-param tool with an output schema, the description adequately covers batching and error behavior. However, the required 'values' parameter is not defined, and the output schema's presence does not excuse the omission of the input parameter's purpose.
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 explain parameters. It adds meaning for 'max_tracks' (limits tracks per playlist) but completely omits the required 'values' parameter, leaving it undefined.
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 'Fetch many playlists at once' using a specific verb and resource, and distinguishes itself from singular siblings like 'get_playlist' by emphasizing batch retrieval with per-item failure capture.
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 usage for fetching multiple playlists and mentions failure handling, but does not explicitly state when not to use it or provide alternatives like 'get_playlist' for single playlist retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_showB
Fetch a podcast show (with episodes) by URL, URI, or ID.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes | ||
| max_episodes | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
B3.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description adds the behavioral detail that the tool fetches a show 'with episodes', but does not disclose more (e.g., pagination, error handling, rate limits). Some context is given, but not comprehensive.
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 10-word sentence that is front-loaded and efficient. Every word earns its place.
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 has 2 parameters with no descriptions, no annotations, but includes an output schema. The description mentions 'with episodes', which helps a bit, but lacks parameter details and usage context. Given the sibling tools, it is minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not clarify what the 'value' parameter expects (URL, URI, or ID?) or the purpose of 'max_episodes'. The description adds no meaning beyond the 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 uses a specific verb ('Fetch') and resource ('podcast show with episodes') and clearly states the lookup keys (URL, URI, or ID). It distinguishes from sibling tools like get_episode (which fetches a single episode) and get_shows (which fetches multiple shows).
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 explicit guidance on when to use this tool versus alternatives like get_shows or search. The description implies usage for fetching a single show by identifier, but does not mention exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_showsB
Fetch many shows at once (up to max_episodes each); failures captured per item.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| values | Yes | ||
| max_episodes | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
B3.4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses partial failure handling ('failures captured per item') and a limit on episodes per show. However, with no annotations, it does not state whether the operation is read-only, destructive, or any authentication requirements.
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?
Single sentence that conveys core purpose and key details without extraneous words. Front-loaded with the main action.
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?
Output schema exists, so return values are covered. However, the description does not clarify what 'values' expects (e.g., show IDs, URLs), nor does it reference siblings to help the agent distinguish use cases. Adequate but not comprehensive.
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 coverage is 0%, so description must compensate but only mentions 'max_episodes' in passing. The 'values' parameter (likely show IDs) is not explained, nor is the format or source of valid values.
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?
Clearly states it fetches multiple shows, specifies the 'max_episodes' limit per show, and mentions failure capture per item. Distinguishes itself from singular 'get_show' and 'get_episode' as a batch operation.
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 explicit guidance on when to use this tool versus alternatives such as 'get_show' for a single show or other batch tools like 'get_tracks'. Usage is implied but not detailed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_similar_albumsC
Recommend albums similar to a track.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| value | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
C2.7/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only says 'recommend' but does not disclose how recommendations are generated, whether authentication is needed, or what output format is expected (though output schema exists). Minimal behavioral insight.
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?
A single sentence, concise and to the point. No unnecessary fluff. However, it could be structured to include parameter hints without sacrificing conciseness.
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 the tool's simplicity (2 params, output schema exists), the description is incomplete. It lacks parameter explanations and usage context. For a recommendation tool, more detail on input format and expected behavior is needed.
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 hints that 'value' is a track identifier but does not specify format (e.g., Spotify ID, name). 'limit' is not explained. The added meaning is vague.
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 'Recommend albums similar to a track' clearly states the action (recommend) and resource (albums), with the input (a track). It distinguishes from siblings like get_album (get a specific album) and search (general search). However, it could be more explicit about the recommendation basis.
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 on when to use this tool over alternatives like search, get_discography, or get_related_artists. The description does not specify prerequisites or exclusions, leaving the agent without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_trackA
Fetch a track by URL, URI, or 22-character ID.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A3.7/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states the operation (fetch) without disclosing side effects, permissions, rate limits, or read-only status. The return format is covered by output schema, but behavioral aspects are missing.
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?
Single sentence, front-loaded with the core action and resource, no wasted words. Perfectly concise.
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?
For a simple fetch tool with one parameter and an output schema, the description is adequate but lacks any additional context about use cases, common scenarios, or constraints. It is minimally viable.
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 input schema has 0% parameter description coverage, so the description compensates by clarifying that 'value' can be a URL, URI, or 22-character ID, which adds essential semantics beyond the bare schema definition.
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 verb 'Fetch a track' and specifies the resource and identification methods (URL, URI, or 22-character ID). Clearly distinguishes from sibling tools that operate on different entities (albums, artists, etc.).
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?
Implicitly suggests use when you need a single track by identifier, but provides no explicit guidance on when to use this tool versus alternatives like get_tracks or search. No exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_tracksB
Fetch many tracks at once; one ordered result per input, failures captured per item.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| values | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
B3.1/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions ordering and failure capture but omits details on rate limits, batch size constraints, or authentication requirements, which are critical for a batch fetch tool.
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 description is very concise but sacrifices necessary detail. It front-loads the purpose but omits parameter explanation, making it insufficiently informative despite its brevity.
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 the existence of an output schema, the return values are covered elsewhere, but the description fails to detail input format, error handling specifics, or limits (e.g., maximum array size), leaving significant gaps for a batch tool.
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?
The sole parameter 'values' has zero schema description coverage, and the description does not explain what the array elements represent (e.g., track IDs, URLs). The phrase 'one ordered result per input' hints at mapping but lacks explicit semantics.
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 verb 'Fetch' and the resource 'many tracks', and distinguishes from the single-item sibling 'get_track' by specifying batch behavior.
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 batch usage but does not explicitly state when to use this tool over alternatives like 'search' or individual fetchers, nor does it provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_track_visualsA
Fetch a track plus its cover colors and canvas in one call, for visual UIs.
track and colors are always present (anonymous). canvas is
best-effort: the looping cover video when the server has a SPOTIFY_SP_DC
cookie and the track has one, else null — a missing cookie or Canvas never
fails the call.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A3.9/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description explains that track and colors are always present, canvas is best-effort, and missing conditions never fail the call. This discloses key behavioral traits 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?
Two efficient sentences with clear structure, using formatting for fields. No unnecessary information.
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?
Covers the response contents and conditional behavior well. However, the lack of parameter explanation is a gap, somewhat mitigated by the presence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% coverage and the description does not explain what the 'value' parameter represents (likely a track ID). This is a critical omission as the parameter is 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?
Clearly states the tool fetches a track plus cover colors and canvas in one call for visual UIs. This distinguishes it from siblings like get_track, get_colors, and get_canvas which handle these separately.
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?
Indicates intended use for 'visual UIs' and explains that canvas is best-effort conditional on a cookie. While it doesn't explicitly state when not to use it or name alternatives, the context and sibling list provide good guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_transcriptB
Fetch a podcast episode's transcript (needs SPOTIFY_SP_DC).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
B3.1/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only mentions a credential requirement and fails to describe what the transcript fetching entails (e.g., format, size, or side effects).
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 description is a single short sentence, which is concise but lacks essential details about parameter meaning and behavior, making it less effective than a slightly longer description.
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 0% schema coverage and no parameter explanation, the description is too sparse. Although an output schema exists, the description does not clarify what the tool returns beyond the basic action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description provides no explanation for the required 'value' parameter (presumably the episode ID). The agent cannot infer its meaning.
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 action ('Fetch') and resource ('podcast episode's transcript'), distinguishing it from sibling tools that deal with tracks, albums, artists, etc.
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 mentions a prerequisite ('needs SPOTIFY_SP_DC'), providing necessary context. However, it does not specify when to use or not use this tool relative to alternatives, though no sibling directly handles transcripts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_userC
Fetch a public user profile (needs SPOTIFY_SP_DC).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
C2.6/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It only states it fetches a public user profile and notes a prerequisite. It does not disclose behavioral traits such as rate limits, error behavior, or data freshness. The public nature is implied but not elaborated.
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 that front-loads the key action and resource. It is appropriately sized for a simple tool, though it could include more detail without becoming verbose.
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?
Despite having an output schema, the description lacks contextual completeness. It does not explain what constitutes a 'public user profile' or how to obtain the SPOTIFY_SP_DC cookie. For a tool with one required parameter, it is minimal but leaves gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter (user_id) with 0% description coverage. The description does not explain what user_id represents or any constraints. It adds no semantic value beyond the schema, which only provides the parameter name and type.
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?
Description clearly states verb 'Fetch' and resource 'public user profile', distinguishing it from sibling tools like get_track, get_album, etc. However, it does not explicitly contrast with siblings. The note about needing SPOTIFY_SP_DC adds specificity.
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?
The description mentions a prerequisite (needs SPOTIFY_SP_DC) but provides no guidance on when to use this tool versus alternatives, such as when to use get_account instead. No when/when-not or context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_chartsA
List the built-in editorial charts (key, name, backing playlist id).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A3.8/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the full burden. It only states what is listed, not behavioral traits such as whether the operation is read-only, if there are rate limits, ordering, or completeness (e.g., 'returns all charts without pagination').
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 concise sentence (12 words), front-loaded with the action 'List'. No extraneous information.
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 parameterless tool with an output schema (not shown), the description adequately states purpose and return fields. It could be improved by confirming it returns all charts and no pagination, but it is sufficiently complete for its simplicity.
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 no parameters (0 params), so the description does not need to add meaning to parameters. The mention of returned fields provides useful context beyond the empty schema. Baseline 4 for zero parameters 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 'List' and clearly identifies the resource as 'built-in editorial charts'. It also specifies the returned fields (key, name, backing playlist id). This distinguishes it from siblings like 'get_chart' which likely retrieves a single chart.
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 tool is for listing all built-in charts, but it does not explicitly state when to use it vs. alternatives (e.g., 'get_chart' for a specific chart). No exclusion or context is provided beyond the basic action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
searchC
Search across tracks, albums, artists, playlists, shows, and episodes.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| types | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
C2.7/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It does not mention that the tool is read-only, results are paginated (implied by limit parameter), or any rate limiting or ordering. The description is too brief to fully inform an agent.
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 one sentence and achieves its purpose without extraneous words. It is front-loaded with the verb 'Search' and resource list. However, it could include a brief note on behavior without becoming verbose.
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 the presence of an output schema, return values are covered. However, the description lacks information on parameter constraints (e.g., required fields, default values) and usage context, making it incomplete for an agent to use effectively.
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 explain parameter meanings. It mentions allowable types (e.g., tracks, albums) but does not describe the 'query', 'limit', or 'types' parameters in detail, leaving the agent to infer their purpose from names alone.
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 the tool searches across multiple content types (tracks, albums, artists, etc.), distinguishing it from sibling get_* tools that retrieve single items. However, it does not specify that the tool returns a list of results.
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 on when to use this tool versus alternatives (e.g., when to use search vs. get_track). The context signals and sibling list indicate many lookup tools, but the description provides no selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
28 tool updates
v0.1.0- First observed
get_account - First observed
get_album - First observed
get_albums - First observed
get_artist - First observed
get_artist_events - First observed
get_artists - First observed
get_canvas - First observed
get_chart - First observed
get_colors - First observed
get_cover_image - First observed
get_credits - First observed
get_discography - First observed
get_episode - First observed
get_episodes - First observed
get_lyrics - First observed
get_playlist - First observed
get_playlists - First observed
get_related_artists - First observed
get_show - First observed
get_shows - First observed
get_similar_albums - First observed
get_track - First observed
get_track_visuals - First observed
get_tracks - First observed
get_transcript - First observed
get_user - First observed
list_charts - First observed
search
TDQS
B3.3/5.0
Disambiguation5/5
Each tool has a clearly distinct purpose: single-entity fetchers, batch fetchers, search, charts, related data, visuals, lyrics, etc. No two tools overlap in functionality; even the composite get_track_visuals is unique.
Naming Consistency4/5
The predominant pattern is 'get_<entity>' (singular or plural), with a few exceptions like 'list_charts' and 'search'. This is mostly consistent, but the mix of 'get_' and 'list_' and the absence of a prefix for 'search' are minor deviations.
Tool Count4/5
28 tools is on the high side, but each tool serves a specific data retrieval need for Spotify, including batch versions for efficiency. The count is justified given the breadth of Spotify's API, though it could be slightly trimmed.
Completeness4/5
The tool set covers nearly all read operations for Spotify entities, including batch fetches, charts, visuals, lyrics, and events. Missing are recommendation endpoints and playlist creation/modification, but for a scraper this is acceptable.
Maintenance
ActivityStale
ResponsivenessSyncing
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Spotify: Spotify Data API for Millions of songs & podcasts, artists, albums, playlists and more.
The media memory layer for AI agents and their humans. Your AI client gets 29 tools to search your collection, add items, update ratings, preview music, and find patterns across everything you've read, watched, and listened to.
YouTube transcripts, search, channel/playlist listings and upload tracking for AI agents. No signup.
Podcast search, metadata, chapters, and transcripts for AI agents — from $15/mo
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to control Spotify playback, manage playlists, search music, and access listening history. Requires Spotify Premium and uses secure OAuth 2.0 with PKCE authentication.13109MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to create, manage, and populate Spotify playlists using the Spotify Web API.3MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to control Spotify playback, search music, manage playlists and library, and access user listening insights via the Spotify Web API.-
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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/AliAkhtari78/SpotifyScraper'
If you have feedback or need assistance with the MCP directory API, please join our Discord server