A
licenseA
qualityD
maintenanceEnables AI agents to search, license, and pay for rights-clean music per use, returning a verifiable license certificate.
5
MIT
rootvine-mcp
RootVine resolves where to stream, buy, or collect music — ranked neutrally by trust, price and availability, never by commission.
resolve_music— Live streaming (Spotify, Apple Music, Tidal, YouTube Music, Deezer), digital purchase (iTunes, Amazon Music, Bandcamp) and physical links (vinyl, CD, Discogs) for a song or album, with prices in GBP, direct links, and click-through URLs. Misses returndid_you_mean; typos are corrected and flagged inresolved_as.corrected.resolve_artist— An artist's profile, genres, and full discography; each release carries aqueryforresolve_music, the route to album-level vinyl/CD/collector editions.discography_complete: falsemeans unknown, not none.discover_music— Browse curated charts, genre corridors, mood walls, artist spotlights, and historic chart snapshots back to 1946 (foyer/chamber/wall/archives modes).resolve: truewith awallfetches number one's links in the same call.find_product— Category router: reads music vs. game from the user's words (or an explicitcategory) and answers in that tool's shape.resolve_game— Registered but not live: returns an explicit "coming soon" with no links, prices, or store calls.
Caveats baked into every answer:
Music only today; games, books, films, podcasts, and live events are on the roadmap.
UK-focused stores, prices in GBP.
Never fabricates — every link existed at
resolved_at; missing prices arenull, never 0 or "free".Answers arrive as readable text and
structuredContent;statusissuccess,partial(withpartial_sources), orno_results(an answer, not an error).Hosted at
https://mcp.rootvine.ai/mcp(no key) or locally vianpx rootvine-mcp; read-only, open-world tools.
Enables music link resolution and price discovery for tracks and albums available on Amazon.
Enables music link resolution and streaming availability lookups for tracks and albums on Apple Music.
Enables discovery of direct links and pricing for music and albums on Bandcamp.
Enables music link resolution and price discovery for purchasing tracks and albums via the iTunes Store.
Enables music link resolution and streaming availability lookups for tracks, artists, and albums on Spotify.
Enables music link resolution and streaming availability lookups for tracks and albums on Tidal.
Enables discovery of music-related video links and availability on the YouTube platform.
Enables music link resolution and streaming availability lookups for tracks and albums on YouTube Music.
rootvine-mcp
A neutral commerce resolution layer for AI agents. Connects Claude, ChatGPT, and other AI agents to trusted product and media data via the Model Context Protocol — covering every path from streaming to collector editions.
What it does
When a user asks an AI agent "Where can I listen to Windowlicker by Aphex Twin?", RootVine resolves the query across all major streaming, purchase, and physical platforms and returns ranked results with direct links.
The same infrastructure answers the full purchase ladder: stream it, buy it digitally, or find the vinyl. Music is live today. Games, books, films, podcasts, and live events are rolling out as their verticals ship.
No ads. No sponsored placements. No pay-to-rank. Results are ranked by a neutral, deterministic algorithm: trust tier → price → availability → freshness → merchant ID. Commission rates, affiliate networks, and sponsored flags are architecturally excluded from the ranking function.
Related MCP server: sonovault-mcp
Quick Start
Hosted — nothing to install
RootVine runs as a hosted, streamable-HTTP MCP server:
https://mcp.rootvine.ai/mcpAdd it by URL in any client that accepts a remote MCP server — for example, in claude.ai: Settings → Connectors → Add custom connector. No login, no key. The same five tools as the npm package, answering from the same live sources.
Privacy: the hosted endpoint logs which tool was called, never your address or what you asked. When it looks something up on BeatsVine, it passes along an anonymous id for the caller, so BeatsVine can count how many different people asked for a song it has no page for yet. The id is a keyed hash that changes every three months, never an address, and every claude.ai user counts as a single caller. The npm package sends no such id.
Claude Desktop (local, via npm)
Add to your Claude Desktop config (~/.claude/claude_desktop_config.json):
{
"mcpServers": {
"rootvine": {
"command": "npx",
"args": ["-y", "rootvine-mcp"]
}
}
}Restart Claude Desktop. You can now ask:
"Where can I stream Galway Girl by Ed Sheeran?"
"Where can I listen to Windowlicker by Aphex Twin?"
"Find links for the new Kendrick Lamar album"
Other MCP Clients
Any MCP-compatible client can use rootvine-mcp via stdio transport:
npx rootvine-mcpTools
Pass the user's own words as query — "galway girl by ed sheeran", "what albums has Stromae released". Never build slugs: RootVine finds the page. slug still works as a deprecated alias for query (send one or the other, not both).
resolve_music
Find where to stream, buy, or collect a song or album.
Input: { query: "galway girl by ed sheeran" } — the user's words, a BeatsVine page address, or a query value from an earlier answer.
Returns: Ranked results covering:
Streaming — Spotify, Apple Music, Tidal, YouTube Music, Deezer
Digital purchase — iTunes Store, Amazon Music, Bandcamp
Physical media — vinyl, CD (via Amazon), Discogs collector listings
Every result includes prices (where available), direct links, and affiliate-tagged click-through URLs for tracking.
How the page is found: RootVine searches BeatsVine's catalogue with the words that matter (request words like "where can I stream" and glue like "by" are set aside) and opens the best match. A typo goes to BeatsVine's live lookup, which corrects it; RootVine then opens the real page and says so in resolved_as (corrected: true). A weak guess is never presented as the answer: a miss returns status: "no_results" with did_you_mean — close matches, each with a query to pass back. A title several artists recorded, asked without an artist ("shape of you"), returns those recordings to choose from rather than one picked at random.
resolve_artist
Get an artist's profile and full discography.
Input: { query: "Stromae" } — the name, a BeatsVine artist address, or artist/stromae
Returns: Genres, artist metadata, and every release BeatsVine holds, each with a query ready for resolve_music:
resolve_artist { query: "Stromae" }
→ 19 releases, e.g. album/stromae-racine-carre
resolve_music { query: "album/stromae-racine-carre" }
→ stream, purchase and physical-media linksPhysical formats — vinyl, CD, Discogs listings — are album-level products, so this is the route to collector editions. A misspelt name returns did_you_mean rather than a guess.
Two response fields worth handling:
discography_complete: false(BeatsVine'snot_yet_indexed) means BeatsVine hasn't catalogued this artist yet. An empty list then means unknown, not no releases — the text says so explicitly rather than implying an empty discography.sparse_fallback_appliedmeans singles were included because the album list was thin. That's BeatsVine's presentation choice, surfaced so it isn't mistaken for the artist's own framing.
discover_music
Browse curated music collections — charts, genre walls, moods, editorial playlists, artist spotlights, and historic charts back to 1946.
Input: { chamber?: "by-genre" | "for-this-moment" | "charts" | "by-era" | "spotlights", wall?: string, year?: number, limit?: number, resolve?: boolean }
Modes (picked by which arg is set):
Foyer (no args) — overview of all chambers and featured walls
Chamber (
chamberarg) — list walls within a chamber (e.g. all genre corridors)Wall (
wallarg: a slug,walls/slugor the wall's address) — drill into a specific wall's tracks, albums, or artistsArchive (
yeararg) — frozen chart snapshots from any year since 1946
Returns: Curated collections with honest attribution (e.g. "Curated by Deezer's editorial team", "Based on Last.fm scrobbles"). Each entry carries a query that resolve_music turns into streaming and purchase links.
Answering "what was number one when I was born — and where can I get it":
discover_music { year: 1994 } → bv-year-end-hot-100-1994 (100 entries)
discover_music { wall: "bv-year-end-hot-100-1994", resolve: true } → number one = Ace of Base, "The Sign", with its linksresolve: true fetches the page the chart itself names for number one — no search, no guessed name. If those links are slow, the chart still comes back, with a note.
Archives: the US Billboard Year-End Hot 100 in full, back to 1946, plus weekly snapshots of the live charts. UK year-end charts show their number one only, with a link to the full chart on officialcharts.com (the Official Charts Company's compilation is protected by database right); each wall says so in its publication field. Global year and decade walls mirror the US Billboard chart.
find_product
Smart router — reads the category from the user's words and routes to the right resolver.
Input: { query: "Aphex Twin Windowlicker", category: "auto" }
Detection is keyword-based: music words ("album", "vinyl", "song", "by"…) win over game words, so "Abbey Road deluxe edition vinyl" is music. Set category when you know it.
Returns: the chosen tool's answer. Music results today (streaming, digital purchase, vinyl, CD, collector editions); games answer "coming soon". Books, films, podcasts, and live event tickets will route automatically as each vertical launches.
resolve_game (coming soon)
Game price resolution across Steam, PlayStation, Xbox, Nintendo, Epic, GOG, Humble, and Fanatical. This tool is registered but not yet active — it returns an explicit "coming soon" (no links, no prices, no request made) until the games vertical launches.
Response Format
RootVine never fabricates. Every link existed at resolved_at.
Every answer comes twice: readable text, and structuredContent (MCP structured output) carrying the same facts, so an agent reads fields instead of parsing prose. Failures are plain-text errors (isError); a miss is an answer (no_results), not an error.
A resolve_music answer, abbreviated:
{
"status": "success",
"artist": "Ed Sheeran",
"title": "Galway Girl",
"kind": "track",
"results": [
{
"rank": 1,
"merchant": "Spotify",
"type": "stream",
"trust_tier": "authoritative",
"availability": "available",
"price": null,
"click_url": "https://www.beatsvine.com/r/abc123",
"url": "https://open.spotify.com/track/...",
"ranking_reason": { "code": "FREE_STREAM_T1", "summary": "Stream with no listed price, Tier 1" }
}
],
"partial_sources": [],
"warnings": [],
"resolved_as": { "query": "ed-sheeran-galway-girl", "via": "catalogue_search", "corrected": false, "note": null },
"did_you_mean": [],
"page_url": "https://www.beatsvine.com/ed-sheeran-galway-girl",
"response_id": "rv_resp_...",
"resolved_at": "2026-09-26T12:00:00.000Z",
"ttl_seconds": 86400
}statusissuccess,partial(real but incomplete —partial_sourcesnames what didn't answer) orno_results.A missing price is
null— never zero, never "free".page_urlis given only when the BeatsVine page is confirmed to exist.Limits: UK-focused stores, prices in GBP; music only today.
Roadmap
✅ Music resolution — live (stream, digital purchase, vinyl, CD, collector editions across Spotify, Apple Music, iTunes, Amazon, Bandcamp, Discogs, YouTube Music, Tidal, Deezer, and more)
✅ Music discovery — live (browse charts, genre walls, mood collections, editorial playlists, artist spotlights)
✅ Chart archives — live (frozen year-end and weekly chart snapshots back to 1946 — Billboard Hot 100, Global Top 100, UK Singles)
✅ Artist discography — live (artist profiles and full release lists, each resolvable to stream/buy/collect links)
🔜 Live events — concert, gig, and festival tickets
🔜 Games — digital keys, physical copies, and collector editions (Steam, PlayStation, Xbox, Nintendo, Epic, GOG)
🔜 Books — ebook, audiobook, paperback, hardback, and special editions (Amazon, Bookshop.org, Apple Books, Kobo, Audible)
🔜 Films & TV — streaming, rental, digital purchase, DVD, Blu-ray, and 4K steelbook
🔜 Podcasts — listen links across Apple Podcasts, Spotify, Pocket Casts, and more
Neutrality
RootVine follows a strict neutrality policy:
Rankings are determined by trust tier → price → availability → freshness → merchant ID
Commission rates, affiliate networks, and sponsored flags are architecturally excluded from the ranking function
The ranking logic runs server-side — this package is a thin client
License
MIT — © Raging Orangutan Holdings
Available Tools
5 toolsdiscover_musicCharts and collectionsARead-onlyInspect
Browse live charts, genre and mood walls, editorial playlists, artist spotlights, and chart snapshots back to 1946 — "what's trending", "number one in 1994". Charts move weekly: call rather than recall. No arguments gives the chambers and featured walls; year gives that year's snapshots; wall gives its entries, each with a query for resolve_music. Add resolve: true with wall to get number one's links in the same call. RootVine never fabricates. Every link existed at resolved_at. Limits: UK-focused stores, prices in GBP; music only today — games are not live yet. On partial, say which sources didn't answer; on no_results, tell the user plainly — never fall back to guessing a link.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| wall | No | A wall or chart-snapshot slug from an earlier answer (a BeatsVine wall address also works). Lists its entries; on a ranked chart position 1 is number one. Takes priority over `chamber` and `year`. | |
| year | No | Chart snapshots from this year (1946 to now), for questions about the past — 'number one in 1994'. Pass a snapshot's slug back as `wall` for its entries. Takes priority over `chamber`. | |
| limit | No | Max walls, entries or snapshots to return: 10 by default, 30 at most. | |
| chamber | No | Chamber to browse; omit for an overview of all chambers and featured walls. 'by-genre' = genre corridors. 'for-this-moment' = moods and activities. 'charts' = live streaming charts. 'by-era' = decades. 'spotlights' = artist features. | |
| resolve | No | With `wall`: also fetch number one's stream and buy links, in the same call. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| top | No | Number one's links, when resolve was asked for |
| mode | Yes | |
| wall | No | |
| year | No | |
| total | Yes | |
| walls | No | |
| years | No | |
| chamber | No | |
| entries | No | |
| chambers | No | |
| top_note | No | |
| snapshots | No | |
| source_url | Yes | |
| resolved_at | Yes |
TDQS
A4.6/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, but the description adds genuinely useful behavior: charts move weekly so call rather than recall, every link existed at resolved_at, no fabrication, UK/GBP scoping, and music-only (games not live). It stops short of describing pagination or the shape of results, but the output schema likely covers returns.
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?
Dense but front-loaded: what it browses, then the call-shape recipes, then trust/limits caveats. Every clause carries signal, though the trust paragraph (RootVine never fabricates, resolved_at) runs long relative to the rest.
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?
An output schema exists, so return values need not be explained; the description instead covers the gaps that matter — invocation modes, error handling on partial/no_results, geographic/currency limits, and what is not yet live. Nothing needed to call it correctly 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 coverage is 100%, so the baseline is 3, but the description adds combination semantics the schema does not: passing a snapshot slug back as `wall`, and pairing `resolve: true` with `wall` to get number-one links in one call. Priority ordering is repeated from the schema, so this is a modest lift above baseline rather than a full 5.
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?
States a specific verb (browse) plus concrete resources: live charts, genre/mood walls, editorial playlists, artist spotlights, and historical snapshots back to 1946. It also names resolve_music as the follow-on for the `query` values returned, which cleanly separates it from that sibling.
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?
Gives explicit invocation recipes: no arguments yields chambers and featured walls, `year` yields that year's snapshots, `wall` yields entries, and `resolve: true` with `wall` fetches number-one links inline. It also states when not to guess and how to handle partial/no_results outcomes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
find_productFind a productARead-onlyInspect
Start here when the category is unclear. Pass the user's words as query; RootVine reads music or games from them (keyword-based — set category when you know it) and answers in that tool's shape. Music is live; games answer "coming soon" for now. RootVine never fabricates. Every link existed at resolved_at. Limits: UK-focused stores, prices in GBP; music only today — games are not live yet. On partial, say which sources didn't answer; on no_results, tell the user plainly — never fall back to guessing a link.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The user's words: 'where can I stream Bad Guy by Billie Eilish', 'Mario Kart on Switch'. | |
| category | No | Set it when you know it; 'auto' (the default) reads it from the words. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| game | No | |
| music | No | |
| category | Yes | |
| detected | Yes | true: the category was read from the words — set `category` if it is wrong |
TDQS
A4.6/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond the readOnly/openWorld annotations: 'RootVine never fabricates', 'Every link existed at resolved_at', and specific handling instructions for partial and no_results responses. It also discloses that games are not live yet and that results are UK/GBP-focused. No contradiction with 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 information-dense and front-loaded with the key routing guidance. It earns most sentences, but the games-not-live limitation is stated twice ('games answer coming soon' and 'music only today — games are not live yet'), which is minor padding.
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 two-parameter tool with an output schema and readOnly/openWorld annotations, the description covers routing behavior, parameter usage, current limitations, geographic scope, and failure-mode handling. Nothing essential for correct selection and invocation 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 coverage is 100%, so the baseline is 3. The description adds meaningful usage meaning: `query` should be the user's raw words used for keyword-based detection, and `category` should be set when known or left to the 'auto' default. This goes beyond the schema's field descriptions.
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 opens with 'Start here when the category is unclear' and clearly explains that it takes the user's words, detects music or games, and answers in that tool's shape. This distinguishes it from the sibling resolve_* and discover_music tools by establishing it as the routing/entry-point tool.
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?
It explicitly states when to use it ('Start here when the category is unclear') and advises setting `category` when known. It also gives useful behavioral guidance for partial/no_results cases. However, it doesn't name explicit alternatives or say what to do when the category is already clear, so there are no direct when-not/alternative exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
resolve_artistArtist discographyARead-onlyInspect
An artist's live profile and discography from BeatsVine, for "what else has X made" or "X's albums". Each release has a query to pass to resolve_music for its links; vinyl, CD and collector editions are album-level, so this is the route to them. Pass the artist's name as query. discography_complete: false means not yet indexed — unknown, not empty. RootVine never fabricates. Every link existed at resolved_at. Limits: UK-focused stores, prices in GBP; music only today — games are not live yet. On partial, say which sources didn't answer; on no_results, tell the user plainly — never fall back to guessing a link.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | Deprecated alias for `query`, kept for older clients. Send exactly one of `query` or `slug`. | |
| query | No | The artist's name in plain words: 'Stromae', 'Billie Eilish'. Also takes a BeatsVine artist address or an `artist/…` query from an earlier answer. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| artist | Yes | |
| status | Yes | |
| releases | Yes | |
| resolved_as | Yes | |
| resolved_at | Yes | |
| did_you_mean | Yes | |
| release_count | Yes | |
| discography_complete | Yes | false: BeatsVine has not indexed this artist yet — an empty list means unknown, not none |
TDQS
A4.4/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the description adds significant context beyond them: 'RootVine never fabricates', 'Every link existed at resolved_at', the meaning of discography_complete: false as unknown not empty, and explicit handling instructions for partial and no_results cases. This enriches the agent's understanding of data reliability and response handling without contradicting 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 moderately long but every sentence carries weight: purpose, release linkage, index state, data integrity, store limits, and failure handling. It is front-loaded with the core purpose and then layers constraints, so the structure is effective and not wasteful.
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?
Given the output schema exists, the description covers all essential operational aspects: how to call it (artist name in query), what the output implies (each release has a query), limitations (UK stores, GBP, music only), and behavior on partial/no_results. The agent can use it correctly without missing critical context.
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 explains both parameters. The description reinforces that the artist name goes in `query` and that slug is deprecated, but it does not introduce new parameter meaning beyond what the schema provides. Baseline 3 applies because the description adds little extra semantic value.
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+resource: 'An artist's live profile and discography from BeatsVine'. It names the intended queries ('what else has X made' or 'X's albums') and distinguishes from siblings by pointing out that each release carries a query for resolve_music and that album-level editions are routed here.
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?
The description gives clear context on when to use the tool (artist discography needs) and even directs album-level editions to this route. It also notes that games are not live, hinting at resolve_game. However, it does not explicitly state 'use resolve_music for individual tracks' or when NOT to use this tool, though the mention of resolve_music implies a division of labor.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
resolve_gameGame prices (coming soon)ARead-onlyInspect
Where to buy a video game. Not live yet: every call returns an explicit "coming soon" — no links, no prices — and contacts no store. Tell the user plainly that games aren't supported yet; never guess a store link or a price. For music, use resolve_music. RootVine never fabricates. Every link existed at resolved_at. Limits: UK-focused stores, prices in GBP; music only today — games are not live yet. On partial, say which sources didn't answer; on no_results, tell the user plainly — never fall back to guessing a link.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | Deprecated alias for `query`, kept for older clients. Send exactly one of `query` or `slug`. | |
| query | No | The game's name in plain words: 'Elden Ring'. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| live | Yes | false: games are not live yet — there are no links or prices to give |
| query | Yes | |
| status | Yes | |
| message | Yes | |
| results | Yes | |
| resolved_at | Yes | |
| response_id | Yes |
TDQS
A4.6/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviors beyond the annotations: it states every call returns an explicit 'coming soon' with no links/prices and no store contact; it adds the 'RootVine never fabricates' truthfulness guarantee; and it explains the UK/GBP scope and error-response expectations. Annotations only say readOnlyHint and openWorldHint, so the description carries significant extra behavioral context with no contradiction.
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 reasonably concise and front-loaded with purpose and status. There is slight redundancy ('not live yet' appears three times, and 'never guess' appears twice), but overall each sentence contributes meaningful guidance. It earns a 4 rather than a 5 due to minor repetition.
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 stub tool with an output schema, the description is notably complete. It covers the tool's current status, user-interaction expectations, limitations (UK-focused, GBP), error-handling behavior, and sibling routing. There is no significant missing information an agent would need to call or respond correctly.
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 coverage is 100%, with both parameters (slug and query) already described in the schema. The description does not add any new parameter-specific information beyond what the schema provides, so the baseline score 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 opens with 'Where to buy a video game', a specific verb+resource statement. It immediately distinguishes itself from resolve_music ('For music, use resolve_music') and explicitly notes the tool is not live yet, so an agent knows exactly what this tool is (or will be) for and how it differs from siblings.
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?
The description gives explicit guidance: 'Not live yet' tells the agent not to expect real results; 'For music, use resolve_music' names the specific alternative; and it provides direct instructions for handling partial and no_results responses ('say which sources didn't answer', 'never fall back to guessing a link'). This is comprehensive usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
resolve_musicMusic linksARead-onlyInspect
Live stream, buy and collect links for a song or album — streaming services, digital stores, vinyl and CD — ranked by trust, price and availability, never by commission. Call it rather than recall: links and prices change; a guessed link 404s. Pass the user's words as query ("galway girl by ed sheeran"); never build slugs. On a miss, did_you_mean lists close matches, each with a query to pass back; when resolved_as.corrected is true, tell the user which recording is shown. RootVine never fabricates. Every link existed at resolved_at. Limits: UK-focused stores, prices in GBP; music only today — games are not live yet. On partial, say which sources didn't answer; on no_results, tell the user plainly — never fall back to guessing a link.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | Deprecated alias for `query`, kept for older clients. Send exactly one of `query` or `slug`. | |
| query | No | What to look up, in the user's own words: 'galway girl by ed sheeran', 'Abbey Road vinyl'. Also takes a BeatsVine page address or a `query` value from an earlier answer. Do not build slugs. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| kind | Yes | |
| title | Yes | |
| artist | Yes | |
| status | Yes | |
| results | Yes | |
| page_url | Yes | The BeatsVine page, only when it is confirmed to exist |
| warnings | Yes | |
| cover_art | Yes | |
| resolved_as | Yes | |
| resolved_at | Yes | Every link existed at this time |
| response_id | Yes | |
| ttl_seconds | Yes | |
| did_you_mean | Yes | |
| partial_sources | Yes | Sources that did not answer: say so when not empty |
TDQS
A4.7/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond the readOnlyHint and openWorldHint annotations: links existed at resolved_at, RootVine never fabricates, rankings ignore commissions, results are UK-focused with GBP prices, and edge cases like partial/no_results have explicit handling. Nothing contradicts the annotations.
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?
The description is dense but every sentence earns its place, covering purpose, usage, reliability, limits, and failure behavior. It is front-loaded with the core purpose before diving into details, and it avoids filler or repetition.
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?
Given the tool's complexity and the existence of an output schema, the description still provides complete operational context: how to call it, what to do with did_you_mean and corrected results, limits, and how to surface failures. An agent can correctly invoke and interpret the response without additional information.
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?
Input schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by showing natural-language examples, allowing a BeatsVine page address or a prior query value, and repeatedly instructing 'never build slugs.' This is useful but not dramatically beyond what the schema already documents.
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 defines the tool's core job with a specific verb and resource: resolving a song or album into live stream/buy/collect links across services and formats. It further distinguishes itself from siblings by scoping to 'music only today — games are not live yet' and to 'a song or album,' separating it from resolve_artist and resolve_game.
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?
The description gives strong when-to-use guidance: 'Call it rather than recall: links and prices change; a guessed link 404s.' It also provides behavioral instructions for miss, corrected, partial, and no-results cases. However, it does not explicitly mention alternatives like discover_music or resolve_artist, though the 'song or album' and 'music only' scope implicitly excludes them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
5 tool updates
v1.4.0- Changed
discover_music7 fields changed- changed
Input schema / properties / chamber / descriptionPrevious value: -"Chamber to browse. Omit for a top-level overview of all chambers and featured walls. 'by-genre' = genre corridors (house, hip-hop, jazz, etc.). 'for-this-moment' = mood and activity walls (chill, focus, workout). 'charts' = live streaming charts. 'by-era' = decades and golden eras. 'spotlights' = editor-led artist features."New value: +"Chamber to browse; omit for an overview of all chambers and featured walls. 'by-genre' = genre corridors. 'for-this-moment' = moods and activities. 'charts' = live streaming charts. 'by-era' = decades. 'spotlights' = artist features." - changed
Input schema / properties / limit / descriptionPrevious value: -"Max items to return. Default 10, max 30. Applies to walls (foyer/chamber mode), entries (wall mode) or snapshots (year mode)."New value: +"Max walls, entries or snapshots to return: 10 by default, 30 at most." - added
Input schema / properties / resolveAdded value: +{ + "description": "With `wall`: also fetch number one's stream and buy links, in the same call.", + "type": "boolean" +} - changed
Input schema / properties / wall / descriptionPrevious value: -"Wall slug to drill into. If set, returns the wall's track/album/artist entries. Takes priority over `chamber`. Example: 'lastfm-top-electronic-tracks', 'deezer-90s-hits'. Slugs are returned in the foyer and chamber responses."New value: +"A wall or chart-snapshot slug from an earlier answer (a BeatsVine wall address also works). Lists its entries; on a ranked chart position 1 is number one. Takes priority over `chamber` and `year`." - added
Input schema / properties / wall / maxLengthAdded value: +500 - changed
Input schema / properties / year / descriptionPrevious value: -"Browse archived chart snapshots from this year. Use for questions about the past — 'what was number one in 1994', 'what was in the charts when I was born'. Archives run from 1946 to the present. Returns snapshot slugs; pass one back as `wall` to get the ranked entries, where position 1 is the number one. Takes priority over `chamber`."New value: +"Chart snapshots from this year (1946 to now), for questions about the past — 'number one in 1994'. Pass a snapshot's slug back as `wall` for its entries. Takes priority over `chamber`." - changed
Output schema / (root)Previous value: -nullNew value: +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "additionalProperties": {}, + "properties": { + "chamber": { + "additionalProperties": {}, + "properties": { + "name": { + "type": "string" + }, + "slug": { + "type": "string" + }, + "tagline": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "slug", + "name", + "tagline" + ], + "type": "object" + }, + "chambers": { + "items": { + "additionalProperties": {}, + "properties": { + "name": { + "type": "string" + }, + "slug": { + "type": "string" + }, + "tagline": { + "type": [ + "string", + "null" + ] + }, + "wall_count": { + "type": "number" + } + }, + "required": [ + "slug", + "name", + "tagline", + "wall_count" + ], + "type": "object" + }, + "type": "array" + }, + "entries": { + "items": { + "additionalProperties": {}, + "properties": { + "artist": { + "type": [ + "string", + "null" + ] + }, + "cover_url": { + "type": [ + "string", + "null" + ] + }, + "kind": { + "anyOf": [ + { + "enum": [ + "track", + "album", + "artist" + ], + "type": "string" + }, + { + "type": "null" + } + ] + }, + "page_url": { + "type": [ + "string", + "null" + ] + }, + "position": { + "type": "number" + }, + "preview_url": { + "type": [ + "string", + "null" + ] + }, + "query": { + "description": "Pass to resolve_music (resolve_artist for an artist) for links; null: no BeatsVine page yet", + "type": [ + "string", + "null" + ] + }, + "title": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "position", + "title", + "artist", + "kind", + "query", + "page_url", + "cover_url", + "preview_url" + ], + "type": "object" + }, + "type": "array" + }, + "mode": { + "enum": [ + "foyer", + "chamber", + "wall", + "archives" + ], + "type": "string" + }, + "resolved_at": { + "type": "string" + }, + "snapshots": { + "items": { + "additionalProperties": {}, + "properties": { + "entry_count": { + "type": "number" + }, + "name": { + "type": "string" + }, + "page_url": { + "type": "string" + }, + "publication": { + "anyOf": [ + { + "additionalProperties": {}, + "description": "How much of the chart BeatsVine shows: 'full'; 'headline' — the number one only, the rest at full_chart_url; 'yearly-number-ones' — each year's best seller, no overall number one", + "properties": { + "chart_owner": { + "type": [ + "string", + "null" + ] + }, + "full_chart_url": { + "type": [ + "string", + "null" + ] + }, + "mode": { + "type": "string" + }, + "note": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "mode", + "chart_owner", + "full_chart_url", + "note" + ], + "type": "object" + }, + { + "type": "null" + } + ] + }, + "slug": { + "description": "Pass as `wall`, with resolve: true for number one's links", + "type": "string" + }, + "week": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "slug", + "name", + "week", + "entry_count", + "page_url", + "publication" + ], + "type": "object" + }, + "type": "array" + }, + "source_url": { + "type": [ + "string", + "null" + ] + }, + "top": { + "anyOf": [ + { + "additionalProperties": {}, + "properties": { + "artist": { + "type": [ + "string", + "null" + ] + }, + "cover_art": { + "type": [ + "string", + "null" + ] + }, + "did_you_mean": { + "items": { + "additionalProperties": {}, + "properties": { + "artist": { + "type": [ + "string", + "null" + ] + }, + "kind": { + "enum": [ + "track", + "album", + "artist" + ], + "type": "string" + }, + "page_url": { + "type": [ + "string", + "null" + ] + }, + "query": { + "description": "Pass back as `query` to open exactly this", + "type": "string" + }, + "title": { + "type": "string" + } + }, + "required": [ + "title", + "artist", + "kind", + "query", + "page_url" + ], + "type": "object" + }, + "type": "array" + }, + "kind": { + "anyOf": [ + { + "enum": [ + "track", + "album" + ], + "type": "string" + }, + { + "type": "null" + } + ] + }, + "page_url": { + "description": "The BeatsVine page, only when it is confirmed to exist", + "type": [ + "string", + "null" + ] + }, + "partial_sources": { + "description": "Sources that did not answer: say so when not empty", + "items": { + "type": "string" + }, + "type": "array" + }, + "resolved_as": { + "additionalProperties": {}, + "properties": { + "corrected": { + "description": "The answer is for different words than asked: tell the user what is shown", + "type": "boolean" + }, + "note": { + "type": [ + "string", + "null" + ] + }, + "query": { + "type": [ + "string", + "null" + ] + }, + "via": { + "anyOf": [ + { + "enum": [ + "direct", + "catalogue_search", + "live_lookup" + ], + "type": "string" + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "query", + "via", + "corrected", + "note" + ], + "type": "object" + }, + "resolved_at": { + "description": "Every link existed at this time", + "type": "string" + }, + "response_id": { + "type": [ + "string", + "null" + ] + }, + "results": { + "items": { + "additionalProperties": {}, + "properties": { + "availability": { + "enum": [ + "in_stock", + "preorder", + "available", + "unknown" + ], + "type": "string" + }, + "click_url": { + "description": "The link to give the user", + "type": "string" + }, + "edition": { + "type": "string" + }, + "merchant": { + "type": "string" + }, + "merchant_id": { + "type": "string" + }, + "price": { + "anyOf": [ + { + "additionalProperties": {}, + "properties": { + "amount": { + "type": "number" + }, + "currency": { + "type": "string" + } + }, + "required": [ + "amount", + "currency" + ], + "type": "object" + }, + { + "type": "null" + } + ], + "description": "null when no price is listed — never zero, never free" + }, + "price_freshness": { + "type": "string" + }, + "rank": { + "type": "number" + }, + "ranking_reason": { + "additionalProperties": {}, + "properties": { + "code": { + "type": "string" + }, + "summary": { + "type": "string" + } + }, + "required": [ + "code", + "summary" + ], + "type": "object" + }, + "trust_tier": { + "enum": [ + "authoritative", + "verified", + "listed" + ], + "type": "string" + }, + "type": { + "enum": [ + "purchase", + "stream", + "subscription" + ], + "type": "string" + }, + "url": { + "type": "string" + } + }, + "required": [ + "rank", + "merchant", + "merchant_id", + "type", + "trust_tier", + "availability", + "price", + "click_url", + "url", + "ranking_reason" + ], + "type": "object" + }, + "type": "array" + }, + "status": { + "enum": [ + "success", + "partial", + "no_results" + ], + "type": "string" + }, + "title": { + "type": [ + "string", + "null" + ] + }, + "ttl_seconds": { + "type": [ + "number", + "null" + ] + }, + "warnings": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "status", + "artist", + "title", + "kind", + "results", + "partial_sources", + "warnings", + "resolved_as", + "did_you_mean", + "page_url", + "cover_art", + "response_id", + "resolved_at", + "ttl_seconds" + ], + "type": "object" + }, + { + "type": "null" + } + ], + "description": "Number one's links, when resolve was asked for" + }, + "top_note": { + "type": [ + "string", + "null" + ] + }, + "total": { + "type": [ + "number", + "null" + ] + }, + "wall": { + "additionalProperties": {}, + "properties": { + "attribution": { + "type": [ + "string", + "null" + ] + }, + "description": { + "type": [ + "string", + "null" + ] + }, + "entity_type": { + "type": [ + "string", + "null" + ] + }, + "name": { + "type": "string" + }, + "page_url": { + "type": "string" + }, + "publication": { + "anyOf": [ + { + "additionalProperties": {}, + "description": "How much of the chart BeatsVine shows: 'full'; 'headline' — the number one only, the rest at full_chart_url; 'yearly-number-ones' — each year's best seller, no overall number one", + "properties": { + "chart_owner": { + "type": [ + "string", + "null" + ] + }, + "full_chart_url": { + "type": [ + "string", + "null" + ] + }, + "mode": { + "type": "string" + }, + "note": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "mode", + "chart_owner", + "full_chart_url", + "note" + ], + "type": "object" + }, + { + "type": "null" + } + ] + }, + "slug": { + "type": "string" + } + }, + "required": [ + "slug", + "name", + "description", + "entity_type", + "attribution", + "page_url", + "publication" + ], + "type": "object" + }, + "walls": { + "items": { + "additionalProperties": {}, + "properties": { + "attribution": { + "type": [ + "string", + "null" + ] + }, + "description": { + "type": [ + "string", + "null" + ] + }, + "entry_count": { + "type": "number" + }, + "name": { + "type": "string" + }, + "page_url": { + "type": "string" + }, + "slug": { + "description": "Pass as `wall` to list its entries", + "type": "string" + } + }, + "required": [ + "slug", + "name", + "description", + "entry_count", + "attribution", + "page_url" + ], + "type": "object" + }, + "type": "array" + }, + "year": { + "type": [ + "number", + "null" + ] + }, + "years": { + "items": { + "type": "number" + }, + "type": "array" + } + }, + "required": [ + "mode", + "source_url", + "resolved_at", + "total" + ], + "type": "object" +}
- Changed
find_product4 fields changed- changed
Input schema / properties / category / descriptionPrevious value: -"Product category. Use 'auto' (default) to let RootVine detect the category automatically."New value: +"Set it when you know it; 'auto' (the default) reads it from the words." - changed
Input schema / properties / query / descriptionPrevious value: -"A natural language product query. Examples: 'Aphex Twin Windowlicker', 'Elden Ring DLC', 'where can I stream Bad Guy by Billie Eilish'"New value: +"The user's words: 'where can I stream Bad Guy by Billie Eilish', 'Mario Kart on Switch'." - added
Input schema / properties / query / maxLengthAdded value: +500 - changed
Output schema / (root)Previous value: -nullNew value: +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "additionalProperties": {}, + "properties": { + "category": { + "enum": [ + "music", + "game" + ], + "type": "string" + }, + "detected": { + "description": "true: the category was read from the words — set `category` if it is wrong", + "type": "boolean" + }, + "game": { + "additionalProperties": {}, + "properties": { + "live": { + "description": "false: games are not live yet — there are no links or prices to give", + "type": "boolean" + }, + "message": { + "type": [ + "string", + "null" + ] + }, + "query": { + "type": "string" + }, + "resolved_at": { + "type": "string" + }, + "response_id": { + "type": [ + "string", + "null" + ] + }, + "results": { + "items": { + "additionalProperties": {}, + "properties": { + "availability": { + "enum": [ + "in_stock", + "preorder", + "available", + "unknown" + ], + "type": "string" + }, + "click_url": { + "description": "The link to give the user", + "type": "string" + }, + "edition": { + "type": "string" + }, + "merchant": { + "type": "string" + }, + "merchant_id": { + "type": "string" + }, + "price": { + "anyOf": [ + { + "additionalProperties": {}, + "properties": { + "amount": { + "type": "number" + }, + "currency": { + "type": "string" + } + }, + "required": [ + "amount", + "currency" + ], + "type": "object" + }, + { + "type": "null" + } + ], + "description": "null when no price is listed — never zero, never free" + }, + "price_freshness": { + "type": "string" + }, + "rank": { + "type": "number" + }, + "ranking_reason": { + "additionalProperties": {}, + "properties": { + "code": { + "type": "string" + }, + "summary": { + "type": "string" + } + }, + "required": [ + "code", + "summary" + ], + "type": "object" + }, + "trust_tier": { + "enum": [ + "authoritative", + "verified", + "listed" + ], + "type": "string" + }, + "type": { + "enum": [ + "purchase", + "stream", + "subscription" + ], + "type": "string" + }, + "url": { + "type": "string" + } + }, + "required": [ + "rank", + "merchant", + "merchant_id", + "type", + "trust_tier", + "availability", + "price", + "click_url", + "url", + "ranking_reason" + ], + "type": "object" + }, + "type": "array" + }, + "status": { + "enum": [ + "coming_soon", + "success", + "partial", + "no_results" + ], + "type": "string" + } + }, + "required": [ + "status", + "live", + "query", + "message", + "results", + "response_id", + "resolved_at" + ], + "type": "object" + }, + "music": { + "additionalProperties": {}, + "properties": { + "artist": { + "type": [ + "string", + "null" + ] + }, + "cover_art": { + "type": [ + "string", + "null" + ] + }, + "did_you_mean": { + "items": { + "additionalProperties": {}, + "properties": { + "artist": { + "type": [ + "string", + "null" + ] + }, + "kind": { + "enum": [ + "track", + "album", + "artist" + ], + "type": "string" + }, + "page_url": { + "type": [ + "string", + "null" + ] + }, + "query": { + "description": "Pass back as `query` to open exactly this", + "type": "string" + }, + "title": { + "type": "string" + } + }, + "required": [ + "title", + "artist", + "kind", + "query", + "page_url" + ], + "type": "object" + }, + "type": "array" + }, + "kind": { + "anyOf": [ + { + "enum": [ + "track", + "album" + ], + "type": "string" + }, + { + "type": "null" + } + ] + }, + "page_url": { + "description": "The BeatsVine page, only when it is confirmed to exist", + "type": [ + "string", + "null" + ] + }, + "partial_sources": { + "description": "Sources that did not answer: say so when not empty", + "items": { + "type": "string" + }, + "type": "array" + }, + "resolved_as": { + "additionalProperties": {}, + "properties": { + "corrected": { + "description": "The answer is for different words than asked: tell the user what is shown", + "type": "boolean" + }, + "note": { + "type": [ + "string", + "null" + ] + }, + "query": { + "type": [ + "string", + "null" + ] + }, + "via": { + "anyOf": [ + { + "enum": [ + "direct", + "catalogue_search", + "live_lookup" + ], + "type": "string" + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "query", + "via", + "corrected", + "note" + ], + "type": "object" + }, + "resolved_at": { + "description": "Every link existed at this time", + "type": "string" + }, + "response_id": { + "type": [ + "string", + "null" + ] + }, + "results": { + "items": { + "additionalProperties": {}, + "properties": { + "availability": { + "enum": [ + "in_stock", + "preorder", + "available", + "unknown" + ], + "type": "string" + }, + "click_url": { + "description": "The link to give the user", + "type": "string" + }, + "edition": { + "type": "string" + }, + "merchant": { + "type": "string" + }, + "merchant_id": { + "type": "string" + }, + "price": { + "anyOf": [ + { + "additionalProperties": {}, + "properties": { + "amount": { + "type": "number" + }, + "currency": { + "type": "string" + } + }, + "required": [ + "amount", + "currency" + ], + "type": "object" + }, + { + "type": "null" + } + ], + "description": "null when no price is listed — never zero, never free" + }, + "price_freshness": { + "type": "string" + }, + "rank": { + "type": "number" + }, + "ranking_reason": { + "additionalProperties": {}, + "properties": { + "code": { + "type": "string" + }, + "summary": { + "type": "string" + } + }, + "required": [ + "code", + "summary" + ], + "type": "object" + }, + "trust_tier": { + "enum": [ + "authoritative", + "verified", + "listed" + ], + "type": "string" + }, + "type": { + "enum": [ + "purchase", + "stream", + "subscription" + ], + "type": "string" + }, + "url": { + "type": "string" + } + }, + "required": [ + "rank", + "merchant", + "merchant_id", + "type", + "trust_tier", + "availability", + "price", + "click_url", + "url", + "ranking_reason" + ], + "type": "object" + }, + "type": "array" + }, + "status": { + "enum": [ + "success", + "partial", + "no_results" + ], + "type": "string" + }, + "title": { + "type": [ + "string", + "null" + ] + }, + "ttl_seconds": { + "type": [ + "number", + "null" + ] + }, + "warnings": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "status", + "artist", + "title", + "kind", + "results", + "partial_sources", + "warnings", + "resolved_as", + "did_you_mean", + "page_url", + "cover_art", + "response_id", + "resolved_at", + "ttl_seconds" + ], + "type": "object" + } + }, + "required": [ + "category", + "detected" + ], + "type": "object" +}
- Changed
resolve_artist5 fields changed- added
Input schema / properties / queryAdded value: +{ + "description": "The artist's name in plain words: 'Stromae', 'Billie Eilish'. Also takes a BeatsVine artist address or an `artist/…` query from an earlier answer.", + "maxLength": 500, + "type": "string" +} - changed
Input schema / properties / slug / descriptionPrevious value: -"The BeatsVine artist slug, lowercase and hyphenated: 'stromae', 'radiohead', 'ed-sheeran'. Slugs keep letters of any script, so non-Latin names are valid. An 'artist/name' form is also accepted, since that is what BeatsVine's search returns for artist hits."New value: +"Deprecated alias for `query`, kept for older clients. Send exactly one of `query` or `slug`." - added
Input schema / properties / slug / maxLengthAdded value: +500 - removed
Input schema / requiredRemoved value: -[ - "slug" -] - changed
Output schema / (root)Previous value: -nullNew value: +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "additionalProperties": {}, + "properties": { + "artist": { + "anyOf": [ + { + "additionalProperties": {}, + "properties": { + "genres": { + "items": { + "type": "string" + }, + "type": "array" + }, + "name": { + "type": "string" + }, + "page_url": { + "type": "string" + }, + "query": { + "description": "Pass back to resolve_artist to open this artist", + "type": "string" + } + }, + "required": [ + "name", + "query", + "page_url", + "genres" + ], + "type": "object" + }, + { + "type": "null" + } + ] + }, + "did_you_mean": { + "items": { + "additionalProperties": {}, + "properties": { + "artist": { + "type": [ + "string", + "null" + ] + }, + "kind": { + "enum": [ + "track", + "album", + "artist" + ], + "type": "string" + }, + "page_url": { + "type": [ + "string", + "null" + ] + }, + "query": { + "description": "Pass back as `query` to open exactly this", + "type": "string" + }, + "title": { + "type": "string" + } + }, + "required": [ + "title", + "artist", + "kind", + "query", + "page_url" + ], + "type": "object" + }, + "type": "array" + }, + "discography_complete": { + "description": "false: BeatsVine has not indexed this artist yet — an empty list means unknown, not none", + "type": [ + "boolean", + "null" + ] + }, + "release_count": { + "type": [ + "number", + "null" + ] + }, + "releases": { + "items": { + "additionalProperties": {}, + "properties": { + "cover_url": { + "type": [ + "string", + "null" + ] + }, + "page_url": { + "type": [ + "string", + "null" + ] + }, + "query": { + "description": "Pass to resolve_music for this release's links", + "type": "string" + }, + "title": { + "type": "string" + }, + "type": { + "type": [ + "string", + "null" + ] + }, + "year": { + "type": [ + "number", + "null" + ] + } + }, + "required": [ + "title", + "type", + "year", + "query", + "page_url", + "cover_url" + ], + "type": "object" + }, + "type": "array" + }, + "resolved_as": { + "additionalProperties": {}, + "properties": { + "corrected": { + "description": "The answer is for different words than asked: tell the user what is shown", + "type": "boolean" + }, + "note": { + "type": [ + "string", + "null" + ] + }, + "query": { + "type": [ + "string", + "null" + ] + }, + "via": { + "anyOf": [ + { + "enum": [ + "direct", + "catalogue_search", + "live_lookup" + ], + "type": "string" + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "query", + "via", + "corrected", + "note" + ], + "type": "object" + }, + "resolved_at": { + "type": "string" + }, + "status": { + "enum": [ + "success", + "no_results" + ], + "type": "string" + } + }, + "required": [ + "status", + "artist", + "discography_complete", + "release_count", + "releases", + "resolved_as", + "did_you_mean", + "resolved_at" + ], + "type": "object" +}
- Changed
resolve_game5 fields changed- added
Input schema / properties / queryAdded value: +{ + "description": "The game's name in plain words: 'Elden Ring'.", + "maxLength": 500, + "type": "string" +} - changed
Input schema / properties / slug / descriptionPrevious value: -"The game slug. Format: game-title (lowercase, hyphenated). Example: 'elden-ring'"New value: +"Deprecated alias for `query`, kept for older clients. Send exactly one of `query` or `slug`." - added
Input schema / properties / slug / maxLengthAdded value: +500 - removed
Input schema / requiredRemoved value: -[ - "slug" -] - changed
Output schema / (root)Previous value: -nullNew value: +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "additionalProperties": {}, + "properties": { + "live": { + "description": "false: games are not live yet — there are no links or prices to give", + "type": "boolean" + }, + "message": { + "type": [ + "string", + "null" + ] + }, + "query": { + "type": "string" + }, + "resolved_at": { + "type": "string" + }, + "response_id": { + "type": [ + "string", + "null" + ] + }, + "results": { + "items": { + "additionalProperties": {}, + "properties": { + "availability": { + "enum": [ + "in_stock", + "preorder", + "available", + "unknown" + ], + "type": "string" + }, + "click_url": { + "description": "The link to give the user", + "type": "string" + }, + "edition": { + "type": "string" + }, + "merchant": { + "type": "string" + }, + "merchant_id": { + "type": "string" + }, + "price": { + "anyOf": [ + { + "additionalProperties": {}, + "properties": { + "amount": { + "type": "number" + }, + "currency": { + "type": "string" + } + }, + "required": [ + "amount", + "currency" + ], + "type": "object" + }, + { + "type": "null" + } + ], + "description": "null when no price is listed — never zero, never free" + }, + "price_freshness": { + "type": "string" + }, + "rank": { + "type": "number" + }, + "ranking_reason": { + "additionalProperties": {}, + "properties": { + "code": { + "type": "string" + }, + "summary": { + "type": "string" + } + }, + "required": [ + "code", + "summary" + ], + "type": "object" + }, + "trust_tier": { + "enum": [ + "authoritative", + "verified", + "listed" + ], + "type": "string" + }, + "type": { + "enum": [ + "purchase", + "stream", + "subscription" + ], + "type": "string" + }, + "url": { + "type": "string" + } + }, + "required": [ + "rank", + "merchant", + "merchant_id", + "type", + "trust_tier", + "availability", + "price", + "click_url", + "url", + "ranking_reason" + ], + "type": "object" + }, + "type": "array" + }, + "status": { + "enum": [ + "coming_soon", + "success", + "partial", + "no_results" + ], + "type": "string" + } + }, + "required": [ + "status", + "live", + "query", + "message", + "results", + "response_id", + "resolved_at" + ], + "type": "object" +}
- Changed
resolve_music5 fields changed- added
Input schema / properties / queryAdded value: +{ + "description": "What to look up, in the user's own words: 'galway girl by ed sheeran', 'Abbey Road vinyl'. Also takes a BeatsVine page address or a `query` value from an earlier answer. Do not build slugs.", + "maxLength": 500, + "type": "string" +} - changed
Input schema / properties / slug / descriptionPrevious value: -"The BeatsVine page slug for the track or album. Format: artist-name-song-title, lowercase and hyphenated. Slugs keep letters of any script, so non-Latin titles are valid: 'ed-sheeran-galway-girl', 'ヨルシカ-火星人'. Latin accents are folded to their base letter ('Rosalía Despechá' → 'rosalia-despecha'), and punctuation is dropped. Pass the slug undecoded — do not percent-encode it yourself."New value: +"Deprecated alias for `query`, kept for older clients. Send exactly one of `query` or `slug`." - added
Input schema / properties / slug / maxLengthAdded value: +500 - removed
Input schema / requiredRemoved value: -[ - "slug" -] - changed
Output schema / (root)Previous value: -nullNew value: +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "additionalProperties": {}, + "properties": { + "artist": { + "type": [ + "string", + "null" + ] + }, + "cover_art": { + "type": [ + "string", + "null" + ] + }, + "did_you_mean": { + "items": { + "additionalProperties": {}, + "properties": { + "artist": { + "type": [ + "string", + "null" + ] + }, + "kind": { + "enum": [ + "track", + "album", + "artist" + ], + "type": "string" + }, + "page_url": { + "type": [ + "string", + "null" + ] + }, + "query": { + "description": "Pass back as `query` to open exactly this", + "type": "string" + }, + "title": { + "type": "string" + } + }, + "required": [ + "title", + "artist", + "kind", + "query", + "page_url" + ], + "type": "object" + }, + "type": "array" + }, + "kind": { + "anyOf": [ + { + "enum": [ + "track", + "album" + ], + "type": "string" + }, + { + "type": "null" + } + ] + }, + "page_url": { + "description": "The BeatsVine page, only when it is confirmed to exist", + "type": [ + "string", + "null" + ] + }, + "partial_sources": { + "description": "Sources that did not answer: say so when not empty", + "items": { + "type": "string" + }, + "type": "array" + }, + "resolved_as": { + "additionalProperties": {}, + "properties": { + "corrected": { + "description": "The answer is for different words than asked: tell the user what is shown", + "type": "boolean" + }, + "note": { + "type": [ + "string", + "null" + ] + }, + "query": { + "type": [ + "string", + "null" + ] + }, + "via": { + "anyOf": [ + { + "enum": [ + "direct", + "catalogue_search", + "live_lookup" + ], + "type": "string" + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "query", + "via", + "corrected", + "note" + ], + "type": "object" + }, + "resolved_at": { + "description": "Every link existed at this time", + "type": "string" + }, + "response_id": { + "type": [ + "string", + "null" + ] + }, + "results": { + "items": { + "additionalProperties": {}, + "properties": { + "availability": { + "enum": [ + "in_stock", + "preorder", + "available", + "unknown" + ], + "type": "string" + }, + "click_url": { + "description": "The link to give the user", + "type": "string" + }, + "edition": { + "type": "string" + }, + "merchant": { + "type": "string" + }, + "merchant_id": { + "type": "string" + }, + "price": { + "anyOf": [ + { + "additionalProperties": {}, + "properties": { + "amount": { + "type": "number" + }, + "currency": { + "type": "string" + } + }, + "required": [ + "amount", + "currency" + ], + "type": "object" + }, + { + "type": "null" + } + ], + "description": "null when no price is listed — never zero, never free" + }, + "price_freshness": { + "type": "string" + }, + "rank": { + "type": "number" + }, + "ranking_reason": { + "additionalProperties": {}, + "properties": { + "code": { + "type": "string" + }, + "summary": { + "type": "string" + } + }, + "required": [ + "code", + "summary" + ], + "type": "object" + }, + "trust_tier": { + "enum": [ + "authoritative", + "verified", + "listed" + ], + "type": "string" + }, + "type": { + "enum": [ + "purchase", + "stream", + "subscription" + ], + "type": "string" + }, + "url": { + "type": "string" + } + }, + "required": [ + "rank", + "merchant", + "merchant_id", + "type", + "trust_tier", + "availability", + "price", + "click_url", + "url", + "ranking_reason" + ], + "type": "object" + }, + "type": "array" + }, + "status": { + "enum": [ + "success", + "partial", + "no_results" + ], + "type": "string" + }, + "title": { + "type": [ + "string", + "null" + ] + }, + "ttl_seconds": { + "type": [ + "number", + "null" + ] + }, + "warnings": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "status", + "artist", + "title", + "kind", + "results", + "partial_sources", + "warnings", + "resolved_as", + "did_you_mean", + "page_url", + "cover_art", + "response_id", + "resolved_at", + "ttl_seconds" + ], + "type": "object" +}
3 tool updates
v1.3.1- Changed
discover_music2 fields changed- changed
Input schema / properties / limit / descriptionPrevious value: -"Max items to return. Default 10, max 30. Applies to walls (foyer/chamber mode) or entries (wall mode)."New value: +"Max items to return. Default 10, max 30. Applies to walls (foyer/chamber mode), entries (wall mode) or snapshots (year mode)." - added
Input schema / properties / yearAdded value: +{ + "description": "Browse archived chart snapshots from this year. Use for questions about the past — 'what was number one in 1994', 'what was in the charts when I was born'. Archives run from 1946 to the present. Returns snapshot slugs; pass one back as `wall` to get the ranked entries, where position 1 is the number one. Takes priority over `chamber`.", + "maximum": 2100, + "minimum": 1946, + "type": "integer" +}
- Added
resolve_artist - Changed
resolve_music1 field changed- changed
Input schema / properties / slug / descriptionPrevious value: -"The BeatsVine page slug for the track or album. Format: artist-name-song-title (lowercase, hyphenated). Example: 'ed-sheeran-galway-girl'"New value: +"The BeatsVine page slug for the track or album. Format: artist-name-song-title, lowercase and hyphenated. Slugs keep letters of any script, so non-Latin titles are valid: 'ed-sheeran-galway-girl', 'ヨルシカ-火星人'. Latin accents are folded to their base letter ('Rosalía Despechá' → 'rosalia-despecha'), and punctuation is dropped. Pass the slug undecoded — do not percent-encode it yourself."
4 tool updates
- Added
discover_music - Changed
find_product1 field changed- removed
Input schema / additionalPropertiesRemoved value: -false
- Changed
resolve_game1 field changed- removed
Input schema / additionalPropertiesRemoved value: -false
- Changed
resolve_music1 field changed- removed
Input schema / additionalPropertiesRemoved value: -false
3 tool updates
v1.0.1- First observed
find_product - First observed
resolve_game - First observed
resolve_music
TDQS
A4.5/5.0
Scored across 5 tools
Disambiguation4/5
Each tool has a distinct purpose: resolving music links, resolving games (placeholder), discovering charts, resolving artists, and routing by category. find_product overlaps slightly with resolve_music and resolve_game as a meta-router, but its 'unclear category' guidance mitigates confusion. No two tools are indistinguishable.
Naming Consistency5/5
All tool names follow a consistent snake_case verb_noun pattern: resolve_music, resolve_game, resolve_artist, discover_music, find_product. The verbs (resolve, discover, find) are clear and appropriate. No mixing of conventions.
Tool Count5/5
Five tools is well-scoped for a music/game discovery and link resolution service. Each tool earns its place: three resolvers, one discoverer, and one router. Neither thin nor excessive.
Completeness4/5
For the current music-only scope, the surface is nearly complete: resolving songs/albums, discovering charts/playlists, and artist discographies. Minor gaps include album tracklists and the non-functional game resolution (explicitly marked 'coming soon'). Agents can work around these limitations.
Maintenance
ActivityMaintained
ResponsivenessNo issues
Related MCP Connectors
Music marketing for AI agents: free Smart Links, promotion campaigns, analytics, and distribution.
Create geo-targeted affiliate smart links, pull analytics, and rewrite YouTube descriptions.
The media memory layer for AI agents and their humans. Your AI client gets 29 tools to search your collection, add items, update ratings, preview music, and find patterns across everything you've read, watched, and listened to.
Search, analyze, and discover commercially released music using sonic intelligence.
Related MCP Servers
sonovault-mcpofficial
AlicenseAqualityAmaintenanceProvides access to the SonoVault music metadata API, enabling search and retrieval of information about 90M+ tracks, artists, labels, and releases, including ISRC, ISWC, and cross-platform IDs.15243 npmMIT
Dynamoi MCPofficial
AlicenseNot gradedqualityBmaintenanceLets AI agents help artists and labels prepare releases for promotion by creating Smart Links, checking campaign readiness, and managing platform connections.67 npm3MIT- FlicenseNot gradedqualityDmaintenanceEnables music search, metadata retrieval, local audio analysis (tempo, key, energy), recommendations, song recognition, and classical work resolution via Spotify, Last.fm, AudD, MusicBrainz, and Songkick APIs.-