write_melody

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

No annotations are present, so the description carries the full burden. It does disclose real output behavior (motif development, chord tones on strong beats, stepwise recovery, half-close then tonic) and hints at non-determinism via 'Try several seeds'. However it omits key operational behavior: that a MIDI item must already exist (item_id required), what replace=true destroys, and what the call actually writes.

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?

Two sentences, purpose front-loaded, and the long stylistic clause is at least substantive rather than filler. 'Try several seeds' is an actionable closing line. Slightly dense but no wasted sentences.

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 14-parameter generative mutation tool with no annotations and no output schema, the description is thin on essentials: it never states the item must exist first, whether existing notes are preserved or overwritten, or what the tool returns/where the notes land (e.g. into the MIDI item). Understanding the musical output is good, but the operational picture is incomplete.

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 only 64%, so the schema does not fully carry the load, and the description adds almost no parameter-level meaning beyond the seed hint ('try several seeds'). Params with no description anywhere (replace, velocity, syncopation, chord_length, top-level start) are left unexplained, so the description does not compensate for the coverage gap.

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 and resource ('Composes a melody'), and 'over chords' precisely scopes the operation so it is separable from siblings like harmonize_melody (which derives chords from a melody) and write_bassline. The melodic-characteristics clause reinforces what kind of melody is produced rather than merely restating the name.

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 description makes clear you need chords to compose over, and 'Try several seeds' is a usable generation tip. There is no explicit when-to-use/when-not versus harmonize_melody, add_midi_notes, or save_motif, and no prerequisites are named.

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