Skip to main content
Glama
NovaLux12

SpotifyMCP

by NovaLux12
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

whats_new

Find new albums, singles, and podcast episodes from your followed artists and saved shows. Budget API calls with max_artists and preview with dry_run to avoid quota exhaustion.

Instructions

Personal new-releases radar: derive what's new from followed artists (new albums/singles) and saved shows (new podcast episodes), replacing the removed browse/new-releases surface. WARNING: N followed artists = N+1 API requests (1 follow page + N album lookups); a large library can exhaust small dev-account quotas in one call. Use max_artists to budget and dry_run to preview the cost before running. Decision guide: whats_new for personal follows radar; search_fresh for query-scoped tag:new, search/search_deep for general catalog, search_by_isrc for ISRC-exact.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
kindsNoWhich sources to scan. Default: ['albums','podcasts']
sinceNoOnly include releases on/after this date (YYYY-MM-DD), or 'last-check' to resume from the stored watermark file (default path ~/.spotify-mcp/freshness.json)
dry_runNoPreview only: validate inputs and describe exactly what would change without performing it
days_backNoLook this many days back when `since` is omitted. Default: 30
max_artistsNoPer-call budget for artist album lookups (and show episode lookups). Default: 25 (or SPOTIFY_MCP_FRESHNESS_BUDGET). Walk caps at this budget and reports truncation. Independent of SPOTIFY_MCP_FETCH_ALL_CAP. WARNING: each lookup is an API request.
max_resultsNoMax items to return (default: SPOTIFY_MCP_MAX_ITEMS env or 50)
response_formatNo'concise' = human prose, 'detailed' = more fields in prose, 'json' = raw API objectconcise

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.26.1

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full behavioral burden. It discloses the N+1 API request cost model ('N followed artists = N+1 API requests'), warns about quota exhaustion, and recommends safe usage through max_artists and dry_run. This is substantial non-obvious behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, each earning its place: purpose first, then cost warning, then mitigation, then decision guide. It is front-loaded and free of filler, packing maximum useful information into minimal space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex, high-cost tool with 7 parameters and no annotations or output schema, the description is remarkably complete. It covers purpose, usage boundaries, API cost, mitigation, alternatives, and key parameter semantics. Nothing essential for correct invocation seems missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by linking max_artists and dry_run to the API-cost model, which helps an agent choose parameter values intelligently. It does not repeat all parameter descriptions, but the schema already covers them fully.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'derive what's new from followed artists (new albums/singles) and saved shows (new podcast episodes)'. It also distinguishes the tool from siblings in the decision guide, naming search_fresh, search/search_deep, and search_by_isrc as alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'Decision guide' explicitly states when to use this tool vs alternatives. It also provides concrete operational guidance: 'Use max_artists to budget and dry_run to preview the cost before running', which goes beyond generic when-to-use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools