Skip to main content
Glama
NovaLux12

SpotifyMCP

by NovaLux12
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

whats_new

Scan followed artists and saved shows to surface new albums, singles, and podcast episodes; cap lookups with max_artists and preview request cost using dry_run.

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: the follow list is paged 50 artists per request, so on a COLD read cache the album leg costs ceil(max_artists/50) follow pages PLUS up to max_artists album lookups (#679); a repeat scan inside the cache window re-probes the same canonical request and spends no request (#900). A large library can still exhaust small dev-account quotas in one call. Use max_artists to budget and dry_run to preview the cost before running; dry_run labels its figure a budget bound (it is arithmetic over the budget, not a measurement) and a real call reports the request count it actually issued in cost. 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 per-kind watermark file (default path ~/.spotify-mcp/freshness.json). Tracked per kind, so a call scoped to one kind never moves the other kind's mark. An explicit date never writes this file; 'last-check' and a days_back window do.
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 costs a request unless the read cache already holds that artist's canonical release probe (#900).
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. Changed2 schema fields changedv3.0.1
    • changedInput schema / properties / max_artists / description
      Previous value: -"Per-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."New value: +"Per-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 costs a request unless the read cache already holds that artist's canonical release probe (#900)."
    • changedInput schema / properties / since / description
      Previous value: -"Only 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)"New value: +"Only include releases on/after this date (YYYY-MM-DD), or 'last-check' to resume from the stored per-kind watermark file (default path ~/.spotify-mcp/freshness.json). Tracked per kind, so a call scoped to one kind never moves the other kind's mark. An explicit date never writes this file; 'last-check' and a days_back window do."
  2. Changed1 schema field changedv2.1.2
    • changedInput schema / properties / since / anyOf
      Previous value: -[
-  {
-    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
-    "type": "string"
-  },
-  {
-    "const": "last-check",
-    "type": "string"
-  }
-]New value: +[
+  {
+    "const": "last-check",
+    "type": "string"
+  },
+  {
+    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+    "type": "string"
+  }
+]
  3. Changed2 schema fields changedv1.31.0
    • removedInput schema / $schema
      Removed value: -"http://json-schema.org/draft-07/schema#"
    • addedInput schema / additionalProperties
      Added value: +false
  4. Addedv1.26.1

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only carry destructiveHint=false, so the description carries the real burden and does so richly: paging cost (ceil(max_artists/50) pages plus album lookups), cache-window behavior, quota exhaustion risk on small dev accounts, dry_run semantics (budget bound vs measured cost), and the cost field returned by a real call.

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?

Front-loaded with purpose, then warnings, then a decision guide. Dense and long but each block earns its place for a quota-sensitive tool; minor redundancy around the cost/cache message and issue-number parentheticals.

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, zero-required-param tool with no output schema, the description covers budgeting, dry_run vs real-run cost reporting, watermark persistence, and sibling routing - everything an agent needs to call it correctly.

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

Parameters4/5

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

Schema coverage is 100% so the baseline is 3, but the description adds genuine interpretive context beyond the schema: how max_artists interacts with fetch caps and cache, that dry_run's figure is arithmetic not measurement, and how since/'last-check' watermarks are tracked per kind.

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

Purpose5/5

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

States a specific verb and resource: 'derive what's new from followed artists (new albums/singles) and saved shows (new podcast episodes)'. It also names the surface it replaces and explicitly differentiates itself from four named siblings in the decision guide.

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

Usage Guidelines5/5

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

Provides an explicit decision guide routing between whats_new, search_fresh, search/search_deep, and search_by_isrc by scenario. Adds concrete advice on when to use max_artists to budget and dry_run to preview cost.

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