Skip to main content
Glama

search_by_reference

Use this when the user wants licensable music that sounds like a song they name or link. Do not use it to identify, play or download the reference recording itself. Find AINSOF music that SOUNDS LIKE a reference. Accepts a YouTube, Spotify, Apple Music or Deezer link, or 'artist - title'. SoundCloud is not supported because it exposes no permitted preview clip; TikTok is not supported because its published metadata identifies the post caption, not the recording. Ask for the artist and title instead. Use it when the user asks for AINSOF music similar to that reference: it matches the reference against the AINSOF catalog using available audio or metadata. Supply musical_description with concrete style, groove and instruments when supported by the user's description or reliable knowledge of the reference; omit it if uncertain. This adds a separate catalog-context search. Returned candidates are not verified sound-alikes; musical suitability requires listening. Records by other artists cannot be licensed from AINSOF, so this returns our cues rather than a reading list. The first reply is often still_running because it resolves the reference through public or authorized metadata and compares a permitted preview clip by sound — call it again with the same link and it picks up the search already running.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "link": "<link>"
    },
    "name": "search_by_reference"
  }
}

Input Schema

NameRequiredDescriptionDefault
linkYes
top_kNoNumber of candidates requested. Values below fifteen are normalized to fifteen.
musical_stylesNoKnown English genre labels from the user's request or reliable knowledge of the reference, e.g. disco, funk. Omit if uncertain. Matches catalog genre tags (including single words) and may return fewer cues. Multiple styles are alternatives, not proof of their combination. Never invent a genre to fill this field.
musical_descriptionNoKnown musical style, groove and instrumentation, preferably in English. Include the user's constraints. Do not invent traits or treat the artist/title as a musical description.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / top_k / default
      Previous value: -8New value: +15
    • changedInput schema / properties / top_k / description
      Previous value: -"Number of candidates requested. Values below eight are normalized to eight."New value: +"Number of candidates requested. Values below fifteen are normalized to fifteen."
  2. Changed4 schema fields changed
    • changedInput schema / properties / top_k / default
      Previous value: -10New value: +8
    • addedInput schema / properties / top_k / description
      Added value: +"Number of candidates requested. Values below eight are normalized to eight."
    • addedInput schema / properties / top_k / maximum
      Added value: +25
    • addedInput schema / properties / top_k / minimum
      Added value: +1
  3. Changed1 schema field changed
    • changedInput schema / properties / musical_styles / description
      Previous value: -"Known English genre labels from the user's request or reliable knowledge of the reference, e.g. disco, funk. Omit if uncertain. Matches catalogue genre tags (including single words) and may return fewer cues. Multiple styles are alternatives, not proof of their combination. Never invent a genre to fill this field."New value: +"Known English genre labels from the user's request or reliable knowledge of the reference, e.g. disco, funk. Omit if uncertain. Matches catalog genre tags (including single words) and may return fewer cues. Multiple styles are alternatives, not proof of their combination. Never invent a genre to fill this field."
  4. Changed1 schema field changed
    • addedInput schema / properties / musical_styles
      Added value: +{
      +  "description": "Known English genre labels from the user's request or reliable knowledge of the reference, e.g. disco, funk. Omit if uncertain. Matches catalogue genre tags (including single words) and may return fewer cues. Multiple styles are alternatives, not proof of their combination. Never invent a genre to fill this field.",
      +  "items": {
      +    "maxLength": 80,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 4,
      +  "type": "array"
      +}
  5. Changed1 schema field changed
    • addedInput schema / properties / musical_description
      Added value: +{
      +  "description": "Known musical style, groove and instrumentation, preferably in English. Include the user's constraints. Do not invent traits or treat the artist/title as a musical description.",
      +  "maxLength": 1000,
      +  "type": "string"
      +}
  6. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Adds substantial behavior beyond the annotations: the first reply is often still_running, calling again with the same link resumes the in-flight search, matching uses public/authorized metadata plus a permitted preview clip, and returned candidates are unverified sound-alikes requiring a listen. It also sets the licensing expectation that other artists' records cannot be returned. Nothing here contradicts the readOnlyHint=false / idempotentHint=false profile, and the resume-on-repeat-call note is consistent with non-idempotency.

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 triggering condition and the 'not for identifying the reference' exclusion are front-loaded, which is the right ordering. There is mild redundancy — the sound-alike purpose is restated in a standalone sentence, and the 'not a reading list' point echoes the earlier exclusion — but no sentence is purely filler.

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 an asynchronous, open-world search with no output schema, the definition covers everything an agent needs to call it correctly and set expectations: accepted input formats, polling behavior, the unverified nature of results, and the licensing constraint. The only omissions are the two optional refinement parameters, which the schema fully documents.

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 75%, so a mid-to-high baseline is warranted, and the description genuinely compensates for the undocumented 'link' parameter by enumerating accepted formats (YouTube, Spotify, Apple Music, Deezer URL, or 'artist - title'). It also adds real guidance for musical_description ('supply concrete style, groove and instruments... omit if uncertain'). It never mentions top_k or musical_styles, which are only explained by the schema, so it stops short of full compensation.

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 and resource ('Find AINSOF music that SOUNDS LIKE a reference') and explicitly carves out what it is not: identifying, playing, or downloading the reference recording itself. The distinction between the source recording and the catalog sound-alike is clear enough to separate it from find_similar or search_music without opening their schemas.

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 triggering conditions ('when the user wants licensable music that sounds like a song they name or link'), explicit exclusions, and the correct fallback for unsupported sources ('Ask for the artist and title instead'). It even explains why SoundCloud and TikTok are excluded, which lets an agent explain the limitation to a user rather than silently failing.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources