plan_midi_chord_voice_leading

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), lowering the burden. The description adds genuinely useful behavioral traits beyond that: 'deterministic' output, the 'octave-only' movement constraint, and the algorithmic anchor on the first chord. These traits clarify what the plan will do without contradicting the read-only annotation.

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?

A single 14-word sentence that front-loads the core purpose and packs every phrase with meaning: 'deterministic', 'octave-only', 'complete chord onsets', and 'anchored to the first chord'. No filler words; each element earns its place.

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 6 required parameters, no output schema, and only 67% schema coverage, the description captures the algorithm's essence but leaves meaningful gaps: the plan's return format is unspecified, minPitch/maxPitch semantics are undocumented, and the relationship to apply_midi_chord_voice_leading is unstated. An agent invoking this tool would need to infer what the plan output looks like.

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 67% (mode, clipId, noteIds, trackId documented), while minPitch and maxPitch lack descriptions in both the schema and the description. The phrases 'octave-only' and 'anchored to the first chord' provide helpful algorithmic context for interpreting mode and noteIds, but the description adds no direct parameter-level meaning and does not compensate for the minPitch/maxPitch 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?

The description names a specific verb ('Plan'), a resource (MIDI chord voice leading), and a precise scope ('octave-only', 'complete chord onsets', 'anchored to the first chord'). The 'octave-only' qualifier and the anchoring detail distinguish it from siblings like plan_midi_chord_inversion, plan_midi_drop_voicing, and plan_midi_transposition, though it never names a sibling explicitly.

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?

No guidance is given on when to choose this tool over its many alternatives, most notably the plan-vs-apply split with apply_midi_chord_voice_leading and the cluster of other planning tools (inversion, drop voicing, doubling, diatonic harmony). The description defines the operation but leaves all selection criteria to inference.

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