apply_midi_chord_arpeggiation

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

Annotations declare readOnlyHint=false and destructiveHint=false. The description adds 'guarded' (implying a confirmation-gated flow) and 'complete readback verification' (post-apply checks), which are behavioral traits beyond the annotations. However, it stays vague — it never explains the dryRun→planHash/confirmationToken contract or what the mutation actually rewrites in the clip. No contradiction with annotations.

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?

A single front-loaded sentence with no wasted words. The dual verb 'Plan or apply' leads, and the qualifiers earn their place. It could be slightly more specific, but for its length it is efficient and well-structured.

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?

This is a complex tool: 11 parameters, 8 required, a two-phase guarded operation, and no output schema. The one-sentence description doesn't explain the dryRun/confirmationToken lifecycle, what a plan returns (planHash, confirmationToken), or what happens to the clip's notes on apply. With no output schema to fall back on, the description leaves critical workflow knowledge undocumented.

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 100%, so the baseline is 3. The description doesn't add per-parameter meaning beyond the schema, but the schema itself carries detailed descriptions (e.g., dryRun's 'Omit or true to return a plan; false requires a valid confirmationToken'). The description contributes only workflow framing, not parameter detail, which is acceptable given full schema coverage.

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?

States a clear verb+resource: 'Plan or apply guarded chord arpeggiation.' It adds specificity with 'stable native note IDs' and 'complete readback verification.' However, it doesn't explicitly differentiate from the sibling plan_midi_chord_arpeggiation tool; the dual-mode hint is implicit rather than explicit, and no alternative is named.

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?

No guidance on when to use this tool versus alternatives. It doesn't mention plan_midi_chord_arpeggiation for plan-only workflows, doesn't explain the two-phase dryRun/apply decision, and offers no exclusions. An agent must infer the use case entirely from the schema, which is inadequate for an 11-parameter tool.

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