generate_melody

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

The description adds real behavioral context beyond the annotations: deterministic seeding and the musical rules the generator follows. However, the annotations declare destructiveHint=true and the description never says what gets destroyed, namely whether existing notes in the target clip are replaced or appended, which is the single most important thing for an agent to know here.

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?

Three tight sentences, no filler, with the musical intent front-loaded before the parameter hints. The contour list is a bit of an inline dump but still earns its space.

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?

For a 13-parameter destructive mutation into an existing clip, the description covers only three parameters and never addresses the required track_index/clip_index targets, the key/scale/chords inputs, or the overwrite semantics. An output schema exists, so return values need not be described, but the input and mutation side is clearly under-explained.

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 has to compensate. It does explain contour's five named values, density's 0..1 range with anchor examples (0.3 ballad, 0.7 busy), and seed's determinism, but key, scale, chords, numerals, low, high, velocity and beats_per_chord are left entirely bare, which is a substantial shortfall across 13 parameters.

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 gives a concrete verb and resource ("Generate a singable melody over a progression") and adds musical specifics: chord tones on strong beats, mostly steps, phrase shape, breaths. An agent can picture the output immediately. It does not, however, distinguish this from the sibling tool write_melody, which sounds like the same job.

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?

"Change seed for another idea; same seed = same melody" tells the agent how to iterate, which usefully implies this is a generation-not-retrieval tool. But there is no statement of when to prefer this over write_melody, nor any prerequisite about the target clip/track needing to exist or being overwritten.

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