Skip to main content
Glama
NovaLux12

SpotifyMCP

by NovaLux12
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

search_deep

Read-onlyIdempotent

Search Spotify's catalog across multiple pages to get more than 10 results per type or continue from a later offset, deduping items and returning compact rows.

Instructions

Paged catalog search that walks past the API limit of 10 results per type. Fetches up to 5 pages of 10 results per requested type server-side from a caller-supplied offset, dedupes by id, and returns compact rows. Type walks overlap (width: SPOTIFY_MCP_MAX_CONCURRENCY, else SPOTIFY_MCP_FANOUT_CONCURRENCY, else 4); same request count. Decision guide: use search_deep when you need >10 results/type or a later window; otherwise use search (single page), search_fresh (new releases), search_by_isrc (ISRC-exact), whats_new (personal follows).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pagesNoPages of 10 results to walk per type, 1–5. Default: 1
queryYesSearch query
typesNoContent types to search. Default: ["track"]
marketNoISO 3166-1 alpha-2 country code, e.g. 'US'
offsetNoIndex of the first result to walk per type, 0–1000. The next_offset a call reports is the offset to pass here to continue. Default: 0
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
    • addedInput schema / properties / offset
      Added value: +{
+  "description": "Index of the first result to walk per type, 0–1000. The next_offset a call reports is the offset to pass here to continue. Default: 0",
+  "maximum": 1000,
+  "minimum": 0,
+  "type": "integer"
+}
  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. Changed2 schema fields changedv1.28.0
    • changedInput schema / properties / market / description
      Previous value: -"ISO 3166-1 alpha-2 country code"New value: +"ISO 3166-1 alpha-2 country code, e.g. 'US'"
    • addedInput schema / properties / market / pattern
      Added value: +"^[A-Za-z]{2}$"
  4. Addedv1.26.1

TDQS

A4.5/5.0
Behavior5/5

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

The annotations already mark it as read-only and idempotent, but the description goes further by disclosing server-side paging, deduplication by id, compact rows, overlap behavior, and continuation via offset. It adds substantial behavioral context beyond the structured annotations.

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 description is dense but front-loads the purpose and then moves into mechanics and the decision guide. It is longer than average, but nearly every clause conveys useful operational or routing 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 complex paged search tool with full parameter schema coverage and no output schema, it covers the critical missing pieces: pagination continuation, result-window behavior, and sibling routing. It does not detail return shape beyond compact rows, but the schema carries the parameter burden well.

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 the schema already documents each parameter, including offset continuation and page limits. The description reinforces paging and offset semantics but does not add much parameter-level meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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?

The description states a specific verb and resource: paged catalog search that walks past the API limit of 10 results per type. It also explicitly distinguishes itself from close siblings such as search, search_fresh, search_by_isrc, and whats_new in the decision guide.

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

Usage Guidelines5/5

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

It gives an explicit when-to-use rule: use search_deep when you need more than 10 results per type or a later window. It then names each alternative and its purpose, leaving no inference needed about tool selection.

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