create_drum_pattern

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

Beyond destructiveHint=true, the description quantifies the destruction (the target slot's existing clip is replaced, recoverable with one undo_last), names a precondition that can cause failure, discloses that voices absent from the kit are reported in missing_voices, notes the file lands at a specific path with a fixed 120 BPM, and states it never creates tracks. That is exactly the extra context annotations cannot carry.

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?

Front-loaded with the action, then layers, then destination, then constraints — no filler sentences. Some clauses are densely packed (the layer/replacement sentence and the destination sentence each carry multiple rules), which costs a little readability.

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?

With no output schema, the description still explains the relevant return information (missing_voices and the beginner-facing 'about' explanation), plus preconditions, side effects, and recovery. For a 7-parameter mutating generator this is as complete as the definition can reasonably be without the schema text.

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 description coverage is 0%, so the description carries the full burden and largely succeeds: it defines style, the layers shape with a concrete example including pulses/steps, style:null semantics, the track/slot pairing, and file_name behavior. Gaps remain for name, rotation, and whether the kit-mapping is keyed on the voice enum, which the agent must read from the schema alone.

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?

"Write a drum beat in a style, repeated over bars" is a specific verb plus resource, and the drum-voice framing plus the Drum Rack requirement distinguishes it cleanly from melodic siblings like create_bassline, create_chord_progression, and create_midi_clip.

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 a genuine routing decision between the two destinations (track+slot writes into Live; file_name writes a .mid and works with Live closed), states the precondition that the track must hold a Drum Rack kit, and explains style:null for layer-only patterns and the 4/4 constraint. It never explicitly contrasts itself with create_midi_clip or write_midi_file, so the agent must infer those boundaries.

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