Skip to main content
Glama

Search Discogs Catalog

discogs_search
Read-only

Search the Discogs catalog for releases, masters, artists, or labels to find release and master IDs; narrow by artist, year, format, country, catalog number, or barcode to identify an exact pressing.

Instructions

Search the Discogs catalog for Releases (pressings), Masters, artists or labels.

Use it to find a release_id or master_id by name, or to find the exact pressing the Owner is holding by narrowing with artist, year, Format, country, catalog number or barcode. Each result carries the release_id/master_id for discogs_get_release and the other tools. Results are paged: the response states the page and the total. Do not use it to check what the Owner has or wants: use discogs_list_collection or discogs_list_wantlist, and discogs_match_collection for a list of albums.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "discogs_search"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNoPage of results, from 1.
typeNoWhat to find: release (default, a specific pressing), master (the album as a whole), artist or label. The filters apply to release and master searches only.release
yearNoOnly this release year.
catnoNoCatalog number as printed, e.g. PB 41447.
limitNoResults per page.
queryNoFree text: artist, title, label or any mix, e.g. 'Kind of Blue'.
artistNoOnly this artist.
formatNoOnly this Format, e.g. Vinyl, CD, Cassette, LP.
barcodeNoBarcode digits, or other identifier text such as a matrix/runout etching: Discogs matches it against every identifier of a Release.
countryNoOnly Releases from this country, e.g. UK, Japan.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds genuinely useful behavior beyond that: results carry release_id/master_id for feeding discogs_get_release and other tools, and results are paged with the response stating the page and total. It stops short of noting anything about result ordering, rate limits, or empty-result behavior, so it is strong but not exhaustive.

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?

Front-loaded with the one-line purpose, then usage, then the downstream-ID payoff, then the explicit exclusion. Three short paragraphs, no filler, and the most decision-relevant routing information is placed last so it is not buried mid-sentence.

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 read-only search tool with no output schema, the description supplies what an agent still needs: what fields the results expose (release_id/master_id) and how paging works (response states page and total). Combined with full schema coverage and the readOnly/openWorld annotations, nothing required 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.

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 all ten parameters including examples (e.g. 'PB 41447', 'Kind of Blue'). The description only restates the narrowing filter list without adding syntax, precedence, or interaction rules (such as how `query` combines with the structured filters). Baseline 3 is appropriate when the schema does the heavy lifting.

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 first sentence names a specific verb (search) and resource (Discogs catalog) and enumerates the four searchable entity types (Releases/pressings, Masters, artists, labels), which maps directly to the `type` enum. It is immediately distinguishable from siblings like discogs_get_release or discogs_list_collection.

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 states the primary use case (find a release_id or master_id, pin down the exact pressing via artist/year/Format/country/catno/barcode) and then explicitly states what NOT to use it for, naming the correct alternatives: discogs_list_collection, discogs_list_wantlist, and discogs_match_collection. Both positive and negative routing are covered.

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