transform_clip

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

Beyond destructiveHint=true, the description adds the crucial detail that the result is written to another slot by default and that targeting the same slot overwrites the source — directly explaining the destructive case. It also states key/scale default to the song's scale. It does not cover failure modes (non-MIDI clip, occupied target slot), which keeps it at 4.

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 destination/overwrite rule is front-loaded where it matters most, and the operation list is dense but skimmable with parenthetical clarifications. The single packed paragraph is slightly hard to parse for eight operations, 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?

An output schema exists so return values need not be explained, and the mutation semantics are covered. But for an 8-parameter, 0%-coverage, destructive tool, unresolved items remain: the repeated parameter name mapping (which index is source vs. target), the amount default discrepancy, and behavior when the target slot is already occupied.

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 0% schema coverage, the description carries the full load and mostly does: it defines amount per operation (factor for diminish, scale steps for transpose, beats for displace, steps per copy for sequence), notes repeats for sequence, and covers key/scale and target-slot defaults. Gaps remain: track_index vs clip_index are never explained as source coordinates, and the stated diminish default of 2 conflicts with the schema's amount default of 0.

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 specific verb (develop/transform a motif) and a specific resource (a Session MIDI clip), plus the destination behavior (write to another slot, default next empty slot below). It also enumerates the concrete operations. It does not differentiate itself from siblings like transpose_clip, swing_clip, humanize_clip, or duplicate_clip_loop, so it falls short of a 5.

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?

Usage is implied by 'Develop a motif... and write the result to another slot', which tells the agent this is a creative-variation tool rather than a simple edit. However, there is no explicit when-to-use vs. when-not guidance and no pointers to the overlapping siblings (transpose_clip, humanize_clip, duplicate_clip_loop), which an agent would need to choose correctly.

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