Skip to main content
Glama
NovaLux12

SpotifyMCP

by NovaLux12
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

plan_podcast_session

Read-onlyIdempotent

Plan a listening session by packing saved podcast episodes or recent episodes from saved shows into a chosen time, skipping played items and stopping when the next episode won't fit.

Instructions

Greedy-pack your saved podcast episodes into a listening session of a given length. Episodes play their remaining time (duration minus resume position); fully played ones are skipped. Scanning stops at the first unplayed episode that doesn't fit.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
kindNoRestrict the source: 'episodes' = your saved episodes only, 'shows' = recent episodes of your saved shows only. Omit to use saved episodes (plus saved shows when saved_only is false)
marketNoISO 3166-1 alpha-2 country code for the saved-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. Ignored for a saved-episodes-only plan.
minutesYesSession length in minutes (1–480)
saved_onlyNoWhen no kind is set, include recent episodes of saved shows too. Default: true (saved episodes only)
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. Changed1 schema field changedv3.0.1
    • addedInput schema / properties / market
      Added value: +{
+  "description": "ISO 3166-1 alpha-2 country code for the saved-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. Ignored for a saved-episodes-only plan.",
+  "pattern": "^[A-Za-z]{2}$",
+  "type": "string"
+}
  2. Changed2 schema fields changedv1.31.0
    • removedInput schema / $schema
      Removed value: -"http://json-schema.org/draft-07/schema#"
    • addedInput schema / additionalProperties
      Added value: +false
  3. Addedv1.26.1

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds genuine behavioral detail beyond that: episodes use remaining time (duration minus resume position), fully played episodes are skipped, and scanning aborts at the first non-fitting unplayed episode. Return format is not described, but the algorithm disclosure is substantive.

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

Conciseness5/5

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

Three tight sentences with zero waste, front-loaded with the core action and followed by the algorithm rules that determine the output. Every sentence earns its place.

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

Completeness4/5

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

For a read-only planning tool with full schema coverage and no output schema, the description is essentially complete. The one meaningful gap is that it does not state it performs no playback, which matters given the start_podcast_session sibling.

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

Parameters3/5

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

Schema description coverage is 100%, so all six parameters (kind, market, minutes, saved_only, max_results, response_format) are already fully documented in the schema. The description's mention of resume position is algorithm context, not parameter semantics, so it adds little. Baseline 3 applies.

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?

States a specific verb and resource: 'Greedy-pack your saved podcast episodes into a listening session of a given length.' The packing algorithm is clearly described. However, it never names its adjacent sibling start_podcast_session, so an agent must infer that this plans rather than plays.

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?

Usage is only implied: the word 'plan' and 'greedy-pack' signal a non-playing computation, but there is no explicit when-to-use statement, no exclusion, and no routing to start_podcast_session, which is the most likely confusion point.

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