Skip to main content
Glama

discogs_collection

DestructiveIdempotent

Manage a Discogs collection: add or remove releases, organize folders, set ratings and custom fields, and retrieve estimated value with confirmed writes and dry-run previews.

Instructions

discogs_collection covers the collection toolset (15 operations). Token is sent as Authorization: Discogs token= and never in the query string. Local stdio server for one user. Not a hosted service. Writes need confirm set to the boolean true and DISCOGS_ALLOW_WRITES=true. Omit confirm for a dry-run preview that does not send the request. Actions: add_release: POST /users/{username}/collection/folders/{folder_id}/releases/{release_id}. Add a release to a collection folder. Add targets folder 1 (Uncategorized), not folder 0 (All). create_folder: POST /users/{username}/collection/folders. Create a collection folder. delete_folder: DELETE /users/{username}/collection/folders/{folder_id}. Delete a collection folder. Folder 0 and folder 1 cannot be deleted. Warning: This deletes a collection folder. Folder 0 (All) and folder 1 (Uncategorized) cannot be deleted. delete_instance: DELETE /users/{username}/collection/folders/{folder_id}/releases/{release_id}/instances/{instance_id}. Remove a release instance from the collection. Warning: This removes a release instance from the collection. delete_release_rating: DELETE /releases/{release_id}/rating/{username}. Delete the authenticated user's rating for a release. Warning: This deletes the user's rating for the release. find_release: GET /users/{username}/collection/releases/{release_id}. Find a release across collection folders. get_folder: GET /users/{username}/collection/folders/{folder_id}. Get one collection folder. get_value: GET /users/{username}/collection/value. Get the estimated value of the collection. list_fields: GET /users/{username}/collection/fields. List custom collection fields. list_folder_releases: GET /users/{username}/collection/folders/{folder_id}/releases. List releases in a collection folder. list_folders: GET /users/{username}/collection/folders. List collection folders. Folder 0 is All. Folder 1 is Uncategorized. set_release_rating: PUT /releases/{release_id}/rating/{username}. Set the authenticated user's rating (1-5) for a release. update_field: POST /users/{username}/collection/folders/{folder_id}/releases/{release_id}/instances/{instance_id}/fields/{field_id}. Set a custom field value on a collection instance. update_folder: POST /users/{username}/collection/folders/{folder_id}. Rename a collection folder. Folder 0 and folder 1 cannot be edited. update_instance: POST /users/{username}/collection/folders/{folder_id}/releases/{release_id}/instances/{instance_id}. Change the rating of a collection instance or move it to another folder.

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": {
      "action": "<action>"
    },
    "name": "discogs_collection"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyNoJSON object for writes, or {csv} for inventory uploads. Tokens are redacted in output.
queryNoOpenAPI query parameters, such as page or per_page.
actionYesDiscogs operation to call.
paramsNoOpenAPI path parameters, such as release_id or username.
confirmNoSet to the boolean true to execute the write. Omit this field for a dry-run preview. false and the string true are rejected.
include_image_urlsNoIf true, keep image URL strings (images, thumb, cover_image, avatar_url). URLs are never fetched. Default false drops those fields.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.3/5.0
Behavior5/5

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

Well beyond the annotations, the description discloses auth transport (token in Authorization header, never query string), the local single-user stdio deployment, the write-gating env var, and dry-run-by-omission semantics. It also flags destructive consequences per operation ('This deletes a collection folder', 'removes a release instance from the collection') and the protections on folder 0 and folder 1.

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?

General constraints (auth, server model, write gating) are front-loaded before the action catalog, which is the right structure for a dispatcher. It is long but the length is driven by 15 operations; there is minor redundancy where a 'Warning:' sentence restates the preceding sentence (delete_folder, delete_instance, delete_release_rating).

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 15-action, 6-parameter dispatcher with no output schema, the description covers auth, safety, dry-run behavior, folder invariants, and per-action endpoints—enough to invoke correctly. It stops short of describing pagination for the list_* actions or the shape of returned collection data, which an agent handling list_folder_releases would still need.

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 baseline would be 3, but the description adds real value by mapping each action to its path template, which tells the agent that add_release needs username/folder_id/release_id while update_field additionally needs instance_id and field_id. It does not explain the query object (page/per_page) or the body payload shapes, which keeps it below 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?

The description states this is the collection toolset (15 operations) and then names every action with its HTTP verb and path, e.g. 'add_release: POST /users/{username}/collection/folders/{folder_id}/releases/{release_id}'. Combined with the sibling names (database, info, lists, user, wantlist), an agent can immediately tell this is the collection-scoped tool.

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

Usage Guidelines3/5

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

There is useful operational guidance: writes require confirm=true plus DISCOGS_ALLOW_WRITES=true, omitting confirm produces a dry-run, and add_release should target folder 1 rather than folder 0. However, there is no explicit routing guidance telling the agent when to reach for this tool versus discogs_wantlist or discogs_user; usage is only implied by the 'collection toolset' framing.

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