Skip to main content
Glama
NovaLux12

SpotifyMCP

by NovaLux12
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

show_new_episodes

Read-onlyIdempotent

Find new episodes across your saved Spotify podcast shows, report those released within a lookback window, and flag which are already saved in your library.

Instructions

Find new episodes across your saved podcast shows: reports episodes released within the lookback window (default 7 days), marking which are already saved in your episode library. Fetches /me/shows then each show's latest episodes, overlapping episode lookups (width: SPOTIFY_MCP_MAX_CONCURRENCY, else SPOTIFY_MCP_FANOUT_CONCURRENCY, else 4) so a 25-show scan is not 25 serial round trips. WARNING: M saved shows → M+1 requests (1 show page + M episode lookups). Use max_shows to budget and cost_preview to see the cost without making any calls. This tool is read-only: nothing is ever changed.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
daysNoLookback window in days. Default 7.
marketNoISO 3166-1 alpha-2 country code for the per-show episode lookups, e.g. "US". Defaults to SPOTIFY_MCP_MARKET, then to the account country — these lookups are market-gated, so a wrong default silently drops episode rows.
max_showsNoPer-call budget for show episode lookups. Default: 25 (or SPOTIFY_MCP_FRESHNESS_BUDGET / SPOTIFY_MCP_SHOWRADAR_BUDGET). Scan caps at min(budget, SPOTIFY_MCP_FETCH_ALL_CAP) and reports truncation. WARNING: each lookup is an API request.
max_resultsNoMax items to return (default: SPOTIFY_MCP_MAX_ITEMS env or 50)
cost_previewNoCost preview only: make no API calls and return the request budget instead of the episode list. Use it to size a real call; it does not report any episodes. Default false.
per_show_limitNoHow many latest episodes to check per show for recency. Default 3.
response_formatNo'concise' = human prose, 'detailed' = more fields in prose, 'json' = raw API objectconcise

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv3.0.1
    • addedInput schema / properties / market
      Added value: +{
+  "description": "ISO 3166-1 alpha-2 country code for the per-show episode lookups, e.g. \"US\". Defaults to SPOTIFY_MCP_MARKET, then to the account country — these lookups are market-gated, so a wrong default silently drops episode rows.",
+  "pattern": "^[A-Za-z]{2}$",
+  "type": "string"
+}
  2. Changed2 schema fields changedv2.1.2
    • addedInput schema / properties / cost_preview
      Added value: +{
+  "description": "Cost preview only: make no API calls and return the request budget instead of the episode list. Use it to size a real call; it does not report any episodes. Default false.",
+  "type": "boolean"
+}
    • removedInput schema / properties / dry_run
      Removed value: -{
-  "description": "Preview only: validate inputs and describe exactly what would change without performing it",
-  "type": "boolean"
-}
  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.5/5.0
Behavior5/5

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

Annotations only mark readOnly/idempotent, but the description discloses substantial behavior beyond them: concurrency resolution via SPOTIFY_MCP_MAX_CONCURRENCY/FANOUT_CONCURRENCY, the M saved shows → M+1 requests cost model, truncation reporting, and the warning that a wrong market default silently drops episode rows. This is exactly the operational context an agent needs.

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

Conciseness4/5

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

Front-loads the purpose in the first clause, then layers cost model and warnings. Dense but every sentence carries information; the concurrency env-var detail is the only part bordering on excessive for a tool-selection description.

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 7-parameter read-only tool with no output schema, the description covers purpose, cost, concurrency, market gating, and the saved-vs-new marking. It does not describe the returned structure (e.g., what the concise/detailed/json formats contain), a minor gap given response_format is exposed as a parameter.

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 schema already documents each parameter and the baseline is 3. The description adds cross-parameter meaning the schema cannot: the max_shows → request-count relationship, cost_preview's 'no API calls, budget only' semantics, and the concurrency env fallback chain.

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: finds new episodes across saved shows within a lookback window, marking which are already saved. Distinguishes itself from siblings like get_saved_shows and search_saved_episodes by describing a recency-scan rather than a library listing.

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

Usage Guidelines4/5

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

Gives clear use conditions (find episodes released within the lookback window) and routes the agent to cost_preview and max_shows for budgeting before spending requests. It does not explicitly name a sibling alternative (e.g., whats_new) or state when not to use it, so it falls short of a 5.

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

Deploy Server

Other Tools