Skip to main content
Glama
NovaLux12

SpotifyMCP

by NovaLux12
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

restore_library_snapshot

Add missing Spotify library items from a backup snapshot without deleting or overwriting: restore absent tracks, albums, shows, episodes, audiobooks, followed artists, and create new playlists.

Instructions

STRICTLY ADDITIVE restore of a library snapshot written by backup_library (see list_backups). Adds only what is missing: saves absent tracks/albums/shows/episodes/audiobooks, follows unfollowed artists, and creates NEW playlists named 'Restored · ()' — existing playlists are never touched and nothing is deleted, renamed, or overwritten. Truncated snapshots are previewable but refused before confirmation or writes; quota-hit, contentless or wrong-schema_version snapshots are refused outright. Prompt and result state where the stored data came from, the date the FILE declares (naming the reason when absent — never the mtime), the item count, and the single use made of it; dry_run defaults to TRUE (read-only preview); setting dry_run=false requires explicit confirmation before any write, fails closed when elicitation is unavailable or errors, and allows writes when SPOTIFY_MCP_CONFIRM=never.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
dry_runNoDEFAULT true: read-only preview of exactly what would be added. Set false to perform the (additive) writes after explicit confirmation.
categoriesNoWhich snapshot categories to restore. Default: all
backup_pathYesSnapshot JSON path from backup_library (see list_backups)
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 changedv2.1.2
    • changedInput schema / properties / backup_path / description
      Previous value: -"Path to the snapshot JSON file from backup_library_snapshot"New value: +"Snapshot JSON path from backup_library (see list_backups)"
  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

A4.6/5.0
Behavior5/5

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

Annotations only declare destructiveHint=false, so the description carries the real behavioral burden and does so richly: additive-only semantics, that existing playlists are never touched and nothing is deleted/renamed/overwritten, the 'Restored · <name>' naming rule, the refusal conditions, and the full dry_run/confirmation flow including the SPOTIFY_MCP_CONFIRM=never escape hatch and fail-closed elicitation. This far exceeds what the annotation conveys.

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?

The critical constraint ('STRICTLY ADDITIVE') is front-loaded and nearly every clause earns its place given the tool's complexity. It is, however, a single dense block with long run-on sentences, which slightly hurts scannability for an agent.

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 mutation tool with no output schema and a guarded confirmation flow, the description covers everything needed to invoke it correctly: provenance, refusal preconditions, default-preview behavior, confirmation requirements, and env-var overrides. Nothing material is missing.

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 description coverage is 100%, so the baseline is 3; dry_run, categories, max_results and response_format are already documented in the schema. The description adds meaning beyond it by explaining that dry_run=false triggers explicit confirmation and fails closed, tying the parameter to an operational contract rather than restating its default.

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?

Opens with a precise verb+resource ('STRICTLY ADDITIVE restore of a library snapshot') and immediately ties its provenance to backup_library (see list_backups), which no sibling can be confused with. The additive scope is stated unambiguously, setting it apart from copy_playlist, import_profile_state and other write siblings.

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?

Clearly establishes when to use it (restoring what a backup_library snapshot is missing) and states the alternatives for locating snapshots (list_backups). It also sets out when restore is refused (truncated, quota-hit, contentless, wrong schema_version). It stops short of explicitly contrasting with adjacent import tools like import_profile_state or library_snapshot_diff.

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