Skip to main content
Glama

ampache_catalogs

Destructive

Manage Ampache catalogs, run catalog add/clean/verify/update tasks, inspect catalog files and folders, and handle flags, ratings, plays, or song deletion with write confirmation.

Instructions

Catalogs, catalog tasks (add_to_catalog, clean_catalog, verify_catalog, update_catalog, gather_art), catalog file/folder, flag, rate, record_play, and song_delete. Writes run only when confirm is true and AMPACHE_ALLOW_WRITES=true. List actions default to offset 0 and limit 25 (max 500). Actions: catalog, catalog_action, catalog_add, catalog_create, catalog_delete, catalog_file, catalog_folder, catalogs, flag, rate, record_play, scrobble, song_delete, update_art, update_artist_info, update_from_tags.

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": "ampache_catalogs"
  }
}

Input Schema

NameRequiredDescriptionDefault
idNo
uriNo
dateNo
fileNo
flagNo
nameNo
pathNo
songNo
taskNo
typeNo
userNo
albumNo
limitNo
actionYesAmpache operation to call.
artistNo
clientNo
filterNo
folderNo
offsetNo
ratingNo
catalogNo
confirmNoBoolean true runs the write when AMPACHE_ALLOW_WRITES is true. Omit it or pass false for a dry-run preview that sends nothing. The string true is rejected.
cat_nameNo
passwordNo
songmbidNo
usernameNo
albummbidNo
overwriteNo
artistmbidNo
media_typeNo
file_patternNo
gather_typesNo
folder_patternNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

B3.3/5.0
Behavior4/5

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

Annotations already mark this as destructive, non-read-only, non-idempotent, and open-world. The description adds valuable behavioral context beyond that: write gating via confirm and AMPACHE_ALLOW_WRITES, dry-run behavior when confirm is omitted or false, rejection of string true, and list pagination defaults. It still does not identify which specific actions are writes versus reads.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but front-loads the resource and action scope, then covers write gating and pagination. The action list is repeated in slightly different forms, but overall it remains efficient for a multi-action tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 33-parameter multi-action tool with no output schema, the description is too high-level. It covers write safety and pagination but does not map parameters to actions or explain the behavior of most operations, leaving an agent unable to invoke many actions correctly from the description alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 6%, so the description must compensate for 33 parameters. It explains confirm, offset, and limit, and lists action values, but leaves most parameters such as id, uri, file, path, task, catalog, rating, and the various mbid fields undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource (catalogs) and enumerates the operations it covers, including catalog tasks, file/folder actions, flag, rate, record_play, and song_delete. It is clear enough to distinguish this as the catalog-management tool, though it does not explicitly contrast itself with siblings like ampache_library.

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?

It gives important usage conditions for writes: confirm must be true and AMPACHE_ALLOW_WRITES must be true, otherwise it is a dry-run. It also states list pagination defaults. However, it does not explain when to choose this tool over sibling tools or provide per-action guidance.

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