write_euclidean

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=false, so the write nature is covered structurally; the description confirms it targets a Session clip. However, the one behavior an agent most needs with destructiveHint=true — whether writing replaces or appends to existing notes in the clip — is never stated, nor are limits such as 'Drum Rack pads only' beyond the pitch examples.

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 content is dense and largely front-loaded, and every element (example, polyrhythm note, pitch map) adds information. But the opening is a dangling fragment with no verb, and the reference material is jammed into one run-on block rather than structured, which slightly impedes fast scanning.

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 described. What is missing relative to a 6-parameter destructive write tool is prerequisite state (target clip/track must exist, likely a Drum Rack), overwrite semantics, and description of the non-layer parameters; the rich layers documentation is the main thing keeping this above inadequate.

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% and the layers items are open objects with no declared properties, so the description carries real weight here: the worked example documents the pitch/pulses/steps/rotation keys and their meaning, which the schema does not. But bars, velocity, steps_per_beat, track_index and clip_index get no explanation of semantics or interaction (e.g. how velocity applies across layers, how bars relates to steps), leaving half the surface undocumented.

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 first line names a specific resource and effect: Euclidean rhythms (pulses spread evenly over steps) written into a Session clip, with polyrhythm and classic-pattern context. It is clearly distinguishable from pattern-writing siblings like write_drum_pattern or generate_melody, though it never names those alternatives explicitly and the opening sentence is a verbless fragment.

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 only implied: the examples (3/8 tresillo, 5/8 cinquillo, 7/16 samba, 5/16 bossa) and the note that mixed step counts produce polyrhythms tell the agent what the tool is good for. There is no explicit when-to-use/when-not guidance, no statement of prerequisites (must the clip already exist? which track type?), and no comparison to sibling pattern generators.

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