instruments

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

No annotations are provided, so the description carries the full burden and does well: it discloses that list/show are read-only, that remove cannot delete shipped catalog entries, that load verifies the FX actually landed, and that errors name the problem with nothing half-registered. Missing are permission/auth expectations and what the successful return payload looks like for save/load.

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

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

Purpose is front-loaded, but the body is a single semicolon-chained paragraph mixing six actions, making it harder to scan than a per-action list. Every clause is substantive, yet the run-on density works against quick lookup during a tool call.

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

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

For a 13-parameter, six-action tool with no annotations and no output schema, the description covers the mutation contracts, refusal rules and cross-action workflow reasonably well. Gaps remain on the 'show' action's behavior, the 'overwrite' path, and what load/save_rig return (beyond play_track_guid for rigs).

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

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

With 69% schema coverage the description adds real meaning beyond the schema: it explains that 'maps' are the note-map names the generators consume, that range is the playable range and library is the source preset string, and that allow_existing_fx controls the FX-present refusal. Unexplained are 'notes', 'overwrite' semantics, and how 'tag' interacts with 'tags' on save.

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

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

The opening clause names a concrete resource ('named instrument library') and the reason it exists ('so a sound is picked by name instead of by plugin index'), then enumerates each action's verb. It is clearly distinguishable from generic FX tools, though it never explicitly contrasts with the nearby instrument_inventory sibling.

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

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

Per-action conditions are stated: save is for a sound the user already loaded by hand on 'track', load is for an EMPTY track and refused when FX exist unless allow_existing_fx, save_rig is for multi-output instruments whose sends/folders must come along. It also tells the agent to use the entry's note maps when writing notes. It stops short of naming which sibling to prefer (e.g. instrument_inventory).

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