drum_workshop

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

With no annotations, the description carries full burden and does so well: it explicitly warns that REAPER is never changed, no model is invoked, no winner is selected, and comparisons measure structural similarity rather than musical quality. It also discloses the preparation prerequisite for evaluate. This is unusually transparent.

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?

The description is compact and action-oriented, with key caveats front-loaded in the first two sentences. Some domain terms (candidate.dsl, intent.json, wildcard requests) are unexplained jargon, but no sentence is wasted.

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?

It covers workflow constraints and safety well, but because there is no output schema it leaves return behavior unspecified, and 'export MIDI' has no corresponding action value. The description also doesn't state what feedback does after it records explicit user input. These gaps matter for correct invocation.

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?

Schema coverage is 75%, so parameters are mostly self-documenting. The description adds meaning by clarifying what actions imply (candidates, intent.json, structural-similarity comparison, audition feedback) and by defining the workshop-folder flow, going beyond the bare schema text.

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 description states specific capabilities: preparing composition requests, comparing drum DSL candidates, exporting MIDI, and recording feedback. However, it lists 'export MIDI' as an action while the action enum only exposes prepare/evaluate/feedback, leaving that capability unmapped and slightly muddying the tool's boundaries.

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?

It gives useful procedural context, such as 'The calling agent writes candidate.dsl and intent.json before evaluate' and 'Local files only; never changes REAPER,' which implies a safe offline workflow. It never names alternatives among the many sibling tools like insert_performance_audition or transcribe_drums, so an agent must infer when this tool is the right choice.

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