SpotifyMCP

move_items_between_playlists

Bulk transfer tracks between Spotify playlists with copy or move modes. Copy leaves the source intact; move removes transferred items, with dedupe, filters, and dry-run previews.

Instructions

Bulk rehome items between playlists. Mode copy keeps the source intact; mode move removes from source after copying — by playlist position, removing exactly the transferred occurrences and leaving any other copy in the source. Supports dedupe against target and optional name/artist filter. Either side may be named by lane.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`mode`	No	copy = leave source intact; move = remove from source after copy	copy
`limit`	No	Source page size, 1–100. Default: 100
`dedupe`	No	Skip tracks already in target. Default: true
`filter`	No	Optional substring filter: only transfer tracks whose name or artist name contains this string (case-insensitive)
`dry_run`	No	Preview only: validate inputs and describe exactly what would change without performing it
`scan_cap`	No	Maximum source rows to scan; bounded by SPOTIFY_MCP_FETCH_ALL_CAP
`max_results`	No	Max items to return (default: SPOTIFY_MCP_MAX_ITEMS env or 50)
`source_lane`	No	Lane name resolving to the source playlist; provide exactly one of source_playlist_id or source_lane
`target_lane`	No	Lane name resolving to the target playlist; provide exactly one of target_playlist_id or target_lane
`response_format`	No	'concise' = human prose, 'detailed' = more fields in prose, 'json' = raw API object	concise
`source_playlist_id`	No	Source playlist ID, spotify:playlist: URI, or URL; provide exactly one of source_playlist_id or source_lane
`target_playlist_id`	No	Target playlist ID, spotify:playlist: URI, or URL; provide exactly one of target_playlist_id or target_lane

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv3.0.1Oct 1, 2026

addedInput schema / properties / source_lane

Added value: +{
+  "description": "Lane name resolving to the source playlist; provide exactly one of source_playlist_id or source_lane",
+  "minLength": 1,
+  "type": "string"
+}

changedInput schema / properties / source_playlist_id / description

Previous value: -"Source playlist ID, spotify:playlist: URI, or URL"New value: +"Source playlist ID, spotify:playlist: URI, or URL; provide exactly one of source_playlist_id or source_lane"

addedInput schema / properties / target_lane

Added value: +{
+  "description": "Lane name resolving to the target playlist; provide exactly one of target_playlist_id or target_lane",
+  "minLength": 1,
+  "type": "string"
+}

changedInput schema / properties / target_playlist_id / description

Previous value: -"Target playlist ID, spotify:playlist: URI, or URL"New value: +"Target playlist ID, spotify:playlist: URI, or URL; provide exactly one of target_playlist_id or target_lane"

removedInput schema / required

Removed value: -[
-  "source_playlist_id",
-  "target_playlist_id"
-]

Changed8 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
```

addedInput schema / properties / limit

Added value: +{
+  "description": "Source page size, 1–100. Default: 100",
+  "maximum": 100,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / scan_cap

Added value: +{
+  "description": "Maximum source rows to scan; bounded by SPOTIFY_MCP_FETCH_ALL_CAP",
+  "maximum": 10000,
+  "minimum": 1,
+  "type": "integer"
+}

changedInput schema / properties / source_playlist_id / description

Previous value: -"Source playlist ID or spotify:playlist: URI"New value: +"Source playlist ID, spotify:playlist: URI, or URL"

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

changedInput schema / properties / target_playlist_id / description

Previous value: -"Target playlist ID or spotify:playlist: URI"New value: +"Target playlist ID, spotify:playlist: URI, or URL"

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

Addedv1.26.1Aug 29, 2026

TDQS

A3.8/5.0

Behavior4/5

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

This description adds substantial behavioral detail beyond the single destructiveHint annotation: move removes by playlist position, removing exactly the transferred occurrences while leaving other copies in the source, dedupe against the target, and an optional filter. There is mild tension with destructiveHint=false given that move deletes items from the source, but since the copy lands in the target first and the removal semantics are fully disclosed (not hidden), the agent is not misled. It does not cover pagination/scan behavior or error handling.

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?

Two tightly packed sentences, front-loaded with the core operation and its mode distinction, then the removal nuance, then supporting options. No filler or repeated name/title text; every clause carries information.

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 12-parameter mutating tool with no output schema and only a destructiveHint annotation, the description covers the critical semantics: what copy vs move does, how removal is scoped, dedupe and filtering. What is missing is minor for correct invocation: the response_format/dry_run usage implications, paging via limit/scan_cap, and any failure conditions, though the schema documents those parameters.

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 12 parameters are already documented in the schema (mode enum, dedupe default, filter substring semantics, lane-vs-id exclusivity). The description restates the mode and dedupe/filter ideas and adds the only novel note, that 'either side may be named by a lane,' but contributes little beyond the schema. Baseline 3 for full coverage.

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?

The opening line states a specific verb and resource ('Bulk rehome items between playlists') and immediately disambiguates the two modes (copy keeps source intact, move removes after copying). It does not name or contrast itself with near-siblings like merge_playlists, copy_playlist, or playlist_union, so an agent must infer the boundary. Clear purpose, but not sibling-differentiating.

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 gives real decision-relevant context: copy vs move semantics, dedupe-against-target, name/artist filtering, and lane-based naming of either side. However it never states when to prefer this tool over copy_playlist, merge_playlists, or batch_add_to_playlist, nor any exclusions or prerequisites. Usage is implied by capability rather than stated.

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

Deploy Server

move_items_between_playlists

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools