SpotifyMCP

get_playlist

Read-onlyIdempotent

Retrieve a Spotify playlist's metadata, cover image, and items, with optional market relinking, unavailable-track flags, pagination, and field filtering.

Instructions

Get a playlist's metadata (including cover image) and items. Use market to relink tracks and flag unavailable ones, and fields/additional_types to trim the payload — both are forwarded to the metadata read and the item pages.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`id`	No	Alias for playlist_id, resolved the same way
`limit`	No	Items per page, 1–100. Default: 50
`fields`	No	Comma-separated list of response fields to keep, e.g. 'total,items(track(name,uri))'
`market`	No	ISO 3166-1 alpha-2 country code, e.g. 'GB'; relinks tracks to that market and flags unavailable ones
`offset`	No	Pagination offset for items. Default: 0
`fetch_all`	No	Fetch all items across pages (up to 500), continuing FROM offset. limit is the page size. Note: library tools' fetch_all ignores offset — contracts differ between modules (#110).
`max_results`	No	Max items to return (default: SPOTIFY_MCP_MAX_ITEMS env or 50)
`playlist_id`	No	Playlist ID, spotify:playlist: URI, or open.spotify.com/playlist URL
`response_format`	No	'concise' = human prose, 'detailed' = more fields in prose, 'json' = raw API object	concise
`additional_types`	No	Item types to include beyond the default 'track', e.g. ['track', 'episode']

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedv3.0.1Oct 1, 2026

addedInput schema / properties / additional_types

Added value: +{
+  "description": "Item types to include beyond the default 'track', e.g. ['track', 'episode']",
+  "items": {
+    "enum": [
+      "track",
+      "episode"
+    ],
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / fields

Added value: +{
+  "description": "Comma-separated list of response fields to keep, e.g. 'total,items(track(name,uri))'",
+  "type": "string"
+}

changedInput schema / properties / id / description

Previous value: -"Alias for playlist_id"New value: +"Alias for playlist_id, resolved the same way"

addedInput schema / properties / id / minLength
```
Added value: +1
```

addedInput schema / properties / market

Added value: +{
+  "description": "ISO 3166-1 alpha-2 country code, e.g. 'GB'; relinks tracks to that market and flags unavailable ones",
+  "pattern": "^[A-Za-z]{2}$",
+  "type": "string"
+}

changedInput schema / properties / playlist_id / description

Previous value: -"Playlist ID"New value: +"Playlist ID, spotify:playlist: URI, or open.spotify.com/playlist URL"

addedInput schema / properties / playlist_id / minLength
```
Added value: +1
```

Changed2 schema fields changedv1.31.0Sep 25, 2026
- removedInput schema / $schema
```
Removed value: -"http://json-schema.org/draft-07/schema#"
```
- addedInput schema / additionalProperties
```
Added value: +false
```

Changed8 schema fields changedv1.26.1Aug 29, 2026

removedInput schema / additionalProperties
```
Removed value: -false
```

changedInput schema / properties / fetch_all / description

Previous value: -"Fetch all items across pages (up to 500) instead of a single page"New value: +"Fetch all items across pages (up to 500), continuing FROM offset. limit is the page size. Note: library tools' fetch_all ignores offset — contracts differ between modules (#110)."

changedInput schema / properties / id / description

Previous value: -"Playlist ID"New value: +"Alias for playlist_id"

addedInput schema / properties / max_results

Added value: +{
+  "description": "Max items to return (default: SPOTIFY_MCP_MAX_ITEMS env or 50)",
+  "exclusiveMinimum": 0,
+  "maximum": 2000,
+  "type": "integer"
+}

addedInput schema / properties / offset / maximum
```
Added value: +9007199254740991
```

addedInput schema / properties / playlist_id

Added value: +{
+  "description": "Playlist ID",
+  "type": "string"
+}

addedInput schema / properties / response_format

Added value: +{
+  "default": "concise",
+  "description": "'concise' = human prose, 'detailed' = more fields in prose, 'json' = raw API object",
+  "enum": [
+    "concise",
+    "detailed",
+    "json"
+  ],
+  "type": "string"
+}

removedInput schema / required
```
Removed value: -[
-  "id"
-]
```

First observedv1.0.1Aug 24, 2026

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds real behavioral context beyond that: market relinks tracks to a country and flags unavailable ones, and fields/additional_types trim the payload across both the metadata read and the item pages.

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, purpose front-loaded, then parameter behavior. Dense but every clause carries information. The second sentence crams several parameters together, but no sentence is wasted.

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 10-parameter tool with no output schema, the description covers identity, market and field-trimming but omits response_format (concise/detailed/json — a major output-shape decision), pagination (limit/offset/fetch_all/max_results), and the id/playlist_id alias. It is adequate but leaves notable gaps for an agent to fill from the schema alone.

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 baseline is 3, but the description adds value beyond the schema by clarifying that fields/additional_types are forwarded to both the metadata read and the item pages, and that market affects linkage/unavailability rather than simple filtering. It says nothing about response_format, limit/offset, or fetch_all semantics.

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: retrieves a playlist's metadata (including cover image) and items. This implicitly separates it from siblings like get_playlist_items and get_playlist_cover, which return only one half, though no sibling is named explicitly.

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 explains what market, fields and additional_types do and notes they are forwarded to both the metadata read and item pages, which implies when to reach for them. It never states when to prefer this tool over get_playlist_items, get_playlist_cover, or search_within_playlist, so usage remains inferred rather than guided.

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

Deploy Server

get_playlist

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools