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

With no annotations, the description carries the full behavioral burden. It usefully discloses that it 'returns the notes chosen' and that voice leading is applied, but for a mutation tool it omits critical behavior: whether existing notes are overwritten, what the 'replace' flag does, whether it requires a selected/existing MIDI item, and what happens on failure. Significant gaps for a write operation.

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, front-loaded with the action and inputs, and the return behavior is appended efficiently. Every clause earns its place and there is no filler.

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 mutation tool with no annotations and no output schema, two sentences are too thin. It should cover the replace/add semantics, the 'selected' item_id convention, and interaction with existing item content; as written an agent cannot confidently predict the side effects of calling it.

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 77%, so the schema already documents most parameters (key, voicing, rhythm, bass_octave, chord_length). The description restates the chord-symbol/Roman-numeral input and voicing/rhythm concepts but adds no syntax or constraint detail beyond the schema, which matches the baseline 3 for high-coverage schemas.

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 ('Writes a chord part') plus the accepted input forms ('chord symbols or Roman numerals with a key') and the two axes it controls (voicing, comping rhythm). This is clearly more than a restated name, but it never distinguishes itself from adjacent writers like write_bassline, write_melody, or harmonize_melody, so it stops short of the 5 bar.

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?

There is no when-to-use or when-not-to-use guidance and no named alternative. An agent must infer that this is the tool for chords versus write_melody or harmonize_melody entirely on its own, and nothing tells it about prerequisites such as needing an existing MIDI item.

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

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

No annotations are provided, so the description carries the full behavioral burden. It reveals one useful trait, that the result's 'lanes' explains where each lane landed, but omits whether existing notes are overwritten (the 'replace' flag is only defaulted in schema, not explained), whether the item_id must exist first, or how unmatched lane names are resolved beyond the schema's brief hint.

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, front-loaded with the core action, and the second sentence adds non-redundant return-value context. No filler, though the second sentence is a touch cryptic ('and why') without much elaboration.

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 9-parameter, nested-object mutation tool with no annotations and no output schema, the description covers the action and hints at the output ('lanes'), which is helpful. But it leaves gaps around side effects (replace behavior, whether an existing MIDI item is required) that an agent would need before invoking it correctly.

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 89%, so the schema already documents nearly every parameter (step, start, swing, channel, patching/velocity syntax in 'pattern', humanize). The description adds no parameter detail beyond what the schema supplies, so the baseline 3 applies.

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 (programs) and resource (drums, step-sequencer style) on the track's drum instrument. It is distinguishable from siblings like add_midi_notes or write_bassline, though it never names the closest alternatives such as add_genre_groove or map_drum_kit to sharpen the boundary.

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?

The description implies the tool is for step-sequencer-style drum programming but gives no explicit when-to-use, prerequisites (e.g. the item must already exist and be on a drum instrument), or when a sibling like add_midi_notes or add_genre_groove would be the better choice.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose one genuine trait beyond the schema: the result includes plugin behavior info for plugins creaper recognizes (relevant since there is no output schema). It omits failure modes, permission/install prerequisites, and side effects on the existing chain, which is a meaningful gap for a mutation tool.

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 short sentences, front-loaded with the core action, with no filler. The trailing clause about 'how they work' is slightly vague but still earns its place by hinting at return content.

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 4-parameter mutation tool with no annotations and no output schema, the description is thin: it never addresses what happens on a failed/ambiguous plugin name or how it interacts with the existing FX chain. Full schema coverage offsets some of this, making it minimally adequate rather than complete.

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 100%, so the schema already documents track, fx_name, position, and show in detail, including the 'master' value. The description's 'use master for the master bus' merely restates the track parameter's schema text, adding no syntax or format detail beyond it.

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+resource ('Adds a plugin to a track's FX chain') that clearly separates it from siblings like remove_fx, update_fx, and set_fx_parameter. It does not name those siblings explicitly, so an agent must infer the boundary rather than being told it.

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?

The parenthetical tells the agent how to target the master bus, which is a useful targeting cue, but there is no when-to-use guidance relative to add_vocal_chain, add_parallel_compression, or apply_track_template, and no when-not or prerequisite statement (e.g., that the plugin must be installed). Usage is implied rather than stated.

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

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

No annotations are provided, so the description carries the full burden. It never discloses that this is a mutation that writes MIDI notes onto a track, whether it overwrites existing content (the 'replace' param exists but is unexplained), permission requirements, or what happens on repeat. Behavioral context is largely absent.

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 compact sentence, front-loaded with the verb and resource. Nothing is wasted, though its brevity comes at the cost of the missing usage and parameter detail noted elsewhere.

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 6-parameter mutation tool with no annotations, no output schema, and only 33% schema coverage, the description is too thin. It omits what replace, humanize, start, and repeats do, and does not explain the return or side effects, leaving an agent with real gaps before invocation.

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 only 33% (item_id and repeats documented in the schema). The description mentions no parameters at all, leaving genre, start, replace, and humanize undocumented in both the description and the schema. It adds no meaning beyond the structured fields.

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 ('Programs') and resource ('a genre's signature drum groove') and adds the mechanism ('from its profile') and the swing detail. It is clearly distinguishable from generic siblings like add_midi_notes, though it does not explicitly contrast with add_drum_pattern, which is the nearest alternative.

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 when-to-use or when-not guidance. The description does not tell the agent how this differs from add_drum_pattern or add_midi_notes, nor that a genre profile (get_genre_profile/list_genres) is the source it depends on. Usage is only weakly implied by the phrase 'genre's signature groove'.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses that supplying end_bar yields a region, but that fact is already stated in the end_bar schema field, so the description adds little beyond it. Nothing is said about permissions, overlap with existing markers, reversibility, or failure modes for a mutation tool.

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 tightly written sentence that front-loads the primary action and appends the conditional region behavior as a parenthetical example. Every clause earns its place with no filler.

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 5-parameter mutation tool with no annotations and no output schema, the description is thin: it omits ordering constraints (end_bar relative to bar), what happens to an existing marker of the same name, and confirmation of what is returned. The schema covers most parameter detail, but behavioral context is left largely unaddressed.

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 high (80%), with bar, beat, color, and end_bar each documented in the schema, so the baseline is 3. The description adds only the end_bar-as-region relationship and an illustrative example, which mildly reinforces but does not substantially extend the schema's own wording.

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 specific verb ('Adds') and resource ('a marker'), plus a clear dual behavior: a marker, or a region when end_bar is supplied. It is distinct from siblings like edit_marker and delete_marker by virtue of the create verb, though it never explicitly names them to reinforce the distinction.

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 implicitly tells the agent when a region is created (when end_bar is given), which is useful conditional guidance, but offers no when-to-use-vs-alternatives framing, no prerequisites (e.g. project must be open), and no steering away from edit_marker for modifying existing markers.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it says nothing beyond 'adds'. It does not state whether events append to existing CC data or overwrite, whether the item must already exist, channel defaulting, or any failure/return behavior for this mutation.

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 efficient sentence with the verb front-loaded and no filler. It is a fragment rather than a full sentence, but every word 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?

For a mutation tool with no annotations, no output schema, and only 33% top-level schema description coverage, the description should disclose more: the 'selected' magic value for item_id, the meaning of the channel default, and append-vs-overwrite semantics. As written it is too thin to call the tool confidently.

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 low (33%), but the nested CCEvent definition documents cc, value, and position in detail. The description partially compensates by naming controller types that map to the cc parameter (mod wheel, expression, sustain, pitch bend). It adds no meaning for item_id, channel, or how events are ordered.

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 ('Adds controller events') and enumerates representative cases (sustain pedal, mod wheel, expression swells, pitch bend), so the agent knows exactly what class of MIDI data it writes. It does not explicitly distinguish itself from the sibling family get_midi_cc / delete_midi_cc, but the verb makes the intent unambiguous.

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 when-to-use, when-not-to-use, or alternative guidance. It never states the prerequisite that item_id must come from create_midi_item/get_track_details, nor that get_midi_cc should be used first to inspect existing controllers. The agent must infer all usage context.

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

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

With no annotations provided, the description carries the full behavioral burden. It does disclose one genuinely useful, non-obvious trait — 'The item grows to fit notes past its end' — which the schema does not state. But it omits other behavior a mutation tool needs to surface: what happens to existing notes by default (overwrite vs append), what the call returns, and any auth/precondition requirements.

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 tight sentences, front-loaded with the primary action and followed by one high-value behavioral fact (auto-growth). No filler, no restating the tool name, and every clause 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?

For a 3-param mutation tool with no annotations and no output schema, the description is adequate but thin: it never clarifies the append-vs-replace default, the precondition that a MIDI item must exist, or what the call yields. The auto-grow note helps, but not enough to call the definition fully complete.

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 67%: item_id, replace, and every nested Note field (pitch, start, length, channel, velocity) are documented in the schema, including units and defaults. The description adds no parameter meaning beyond that, so the baseline 3 for schema-doing-the-work applies.

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 specific verb+resource ('Writes notes into a MIDI item') and even illustrates content types, so the core action is unambiguous. However, it does not distinguish itself from closely related siblings like edit_midi_notes, write_melody, write_bassline, or add_chord_progression, leaving the agent to infer that this is the low-level primitive.

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?

There is no explicit when-to-use or when-not-to-use guidance. Nothing tells the agent whether to prefer add_midi_notes over edit_midi_notes, write_melody, or write_bassline, nor that a MIDI item must already exist (a dependency on create_midi_item). Usage is only implied by the verb 'Writes'.

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

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

With no annotations provided, the description carries the behavioral burden. It usefully states that a bus is created and that the original track remains untouched, which is valuable signal-flow context. However, it omits whether the operation is reversible, whether it modifies project state beyond creating a bus, and what permissions or side effects are involved.

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 description is a single efficient sentence with no filler. It is not explicitly front-loaded with an action verb, but the concept is immediately clear and appropriately sized for the tool.

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?

The description explains the audio concept but does not provide usage context, alternatives, or operational details such as mutation scope. Since the schema fully documents the three parameters and no output schema exists, the main remaining gap is guidance on when and why to invoke this tool versus its many siblings.

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 100%, so the schema already documents track, blend_db, and compressor thoroughly. The description adds no parameter-level meaning, but baseline 3 is appropriate when the schema carries parameter semantics.

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 clearly identifies the effect being added: a New York-style parallel compression bus with a heavily compressed copy blended under the original. The name supplies the verb, and the description supplies the specific audio-processing concept. It does not, however, distinguish this tool from sibling routing or FX tools such as add_fx or setup_sidechain.

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?

The description explains what parallel compression is but gives no explicit guidance on when to use this tool versus alternatives like add_fx, setup_sidechain, or create_bus. It also does not mention prerequisites such as track selection or mix context. Usage must be inferred entirely from the tool name and concept.

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

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

No annotations are provided, so the description carries full burden. It states the tool inserts a program change event but omits where it's inserted (at position on channel within item), whether it's a write/mutation, permission or selection requirements for item_id='selected', and what happens to existing program changes. For a MIDI-write tool with zero annotation coverage this is a notable gap.

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 well-formed sentence, front-loaded with the primary action, no filler. The parenthetical list of synth types is informative but slightly long; still efficient overall.

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?

Given 6 parameters, no annotations, and no output schema, the description is adequate in framing the tool's purpose but thin on operational behavior (insertion point, mutation semantics, selection handling). It could do more to compensate for missing annotations.

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 83%, so the schema already documents most parameters (item_id, program, bank_lsb/msb, position, channel defaults/ranges). The description adds the domain concept that 'bank select' is optional and goes first, which is useful context but not deep parameter syntax beyond the schema.

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?

Clear verb ('switches the sound') and resource (MIDI instrument program) with scope qualifiers about which synths respond to program changes. However it doesn't explicitly distinguish this from add_midi_cc (which could also write bank select CCs) or add_midi_notes, leaving sibling differentiation implicit.

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?

The description implies use for GM/hardware/multitimbral synths, giving implicit context for when the tool applies. It doesn't state when to avoid it (e.g., non-GM plugins, plugin parameter automation) or name alternatives like add_midi_cc for raw bank select.

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

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

With no annotations, the description carries the full behavioral burden and does so richly: it discloses side effects (talkbox adds one audio track after the melody's; vocoder builds three tracks), the return value (a measured clarity score alone and in the mix), and instructs the agent to act on that score rather than guess. This is substantial context beyond any structured field.

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 core purpose is front-loaded and every paragraph carries real information (mode behavior, sparsity rules, return value). However, the talkbox/vocoder mechanics are partly restated from the schema's style field, and the three-paragraph length is heavier than strictly needed, leaving minor redundancy.

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 7-parameter mutation tool with no annotations and no output schema, the description covers what's needed: side effects on track structure, which item_id input to supply, how lyrics map to notes, sparsity constraints, and the clarity-score return. Nothing an agent needs to call it correctly is missing.

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 100%, so the schema already documents all 7 parameters, including the style enum and lyrics syntax. The description reinforces the talkbox/vocoder distinction and lyric sparsity but adds little parameter-level detail beyond the schema — baseline 3 is appropriate.

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 opens with a concrete verb+resource ('Makes a synth sing words') and specifies exactly what is manipulated: the TTS voice over a melody item's notes. It further distinguishes the two output modes (talkbox = one shaped audio track; vocoder = three tracks with ReaVocode), letting an agent tell this apart from siblings like add_vocal_chain or chop_vocal without opening the schema.

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 strong when-to-use guidance: robot vocals only work when sparse ('short hook of a few words, repeated... at most one syllable per beat'), and explicitly warns that dense/fast verses 'turn to mush'. It also directs the agent to reference list_speech_voices for voices and to act on the clarity score. It stops short of naming sibling alternatives (e.g., add_vocal_chain) to route away from, so a 4 rather than 5.

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

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

No annotations exist, so the description carries the full burden and does disclose meaningful behavior: the exact chain created, the automatic-vs-manual split depending on plugin choice, and the caveat that it is a tweakable starting point. It does not state idempotency, whether re-running duplicates FX, or what is returned, leaving some mutation-tool gaps.

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 compact sentences, front-loaded with what gets built before the conditional-plugin detail and the scope caveat. Every sentence carries information; only slight density cost from the semicolon-laden last line.

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 5-parameter mutation tool with no annotations and no output schema, the description covers what is created and how configuration differs by plugin, which is the bulk of what an agent needs. It omits any mention of return values or failure/idempotency behavior, a minor gap for a creative convenience tool.

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 80%, so the schema already documents eq, compressor, track, and reverb_send_db. The description adds the meaningful behavioral note that eq/compressor overrides change whether the chain is auto-configured, but says nothing about the 'character' enum values or reverb_send_db, so it only marginally exceeds the schema.

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+resource (add a vocal chain to a track) and enumerates its contents: high-pass and tone EQ, then a compressor. It also distinguishes itself from generic siblings by noting it is a 'starting point' rather than a full mixing tool, and it explicitly names 'no de-esser' as a scope boundary.

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?

Gives clear context: with REAPER's ReaEQ/ReaComp it is configured automatically, whereas with other plugins the FX are added and the user must call set_fx_parameters to configure them. That routes the agent to a sibling in the non-default case. It stops short of an explicit 'use this instead of add_fx when...' rule, so not a 5.

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

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

Annotations only declare readOnlyHint=true; the description adds a genuine performance trait by disclosing that rendering is offline (faster than real time) yet takes noticeable time for long ranges, which matters for timeout and batching decisions. It does not say whether the call blocks or how results are returned, keeping it short of a 5.

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?

Purpose and scope are front-loaded in the first clause, and the second sentence covers the one non-obvious cost. The metric enumeration is long but each item is informative, so it is close to fully earning 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?

With no output schema, the description takes on the burden of describing results and does so by listing every measured quantity, and the readOnly annotation covers the safety profile. What remains thin is the absence of usage routing against sibling analysis tools.

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 100%, so track, start_bar, and end_bar are already fully documented, and the description only echoes the track/master distinction without adding bar-range or fraction semantics. Baseline 3 is appropriate when the schema carries the parameter burden.

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 pair (renders and measures) on a specific resource (the mix or one track) and enumerates exactly the metrics produced, from LUFS and true peak to stereo correlation and frequency balance. The metric list is distinctive enough that an agent can separate this from measure_tracks, analyze_sample, or show_spectrogram without opening another schema.

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?

The phrase 'the mix or one track' implies when each mode applies, but there is no explicit when-to-use, when-not-to-use, or named alternative (measure_tracks, compare_mix_to_style, analyze_sample all sit nearby). Usage is inferable but not stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered and the bar is lower. The description still adds real behavioral context: the key is "detected" unless supplied, the analysis spans chords-over-time plus cadences and non-chord tones, and a second item can be analyzed against the chords. It does not mention any failure modes (e.g., what happens with a non-MIDI or empty item), which keeps it from a 5.

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 front-loaded sentence with the verb and resource first, followed by a colon-list of outputs and one parenthetical conditional. Every clause earns its place, though the list is dense enough that it reads more as an inventory than as structured guidance.

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?

There is no output schema, so the description must describe return values — and it does, enumerating key, chords, Roman numerals, functions, cadences, non-key notes, and non-chord tones. Combined with readOnlyHint covering safety and the schema covering item_id, an agent has enough to call this correctly; only error/edge behavior is unaddressed.

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 75%, so the schema carries most of the load. Even so, the description adds meaning beyond the schema for two parameters: it clarifies that the key is auto-detected when omitted (the schema only shows a null default), and it explains that melody_item_id analyzes a melody against the detected chords for non-chord tones — a purpose the schema states only tersely. Only the resolution enum remains unexplained.

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 and resource ("Reads a MIDI item and explains its harmony") and then enumerates exactly what it produces: key, chords over time, Roman numerals, functions, cadences, non-key notes, and non-chord tones with a melody. This is far more specific than a tautology, but it never distinguishes itself from close siblings such as analyze_progression, identify_chord, or check_voice_leading, which also operate on harmonic analysis.

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 reader infers that you call this when you want a harmonic read-out of a MIDI item. The description does state one conditional usage case ("with a melody item ... non-chord tones"), which is helpful, but it gives no explicit when-to-use/when-not guidance and never routes the agent to or away from analyze_progression, identify_chord, or reharmonize.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower; the description still adds value by disclosing that the key is auto-detected when omitted and by enumerating the analytical features returned (secondary dominants, Neapolitan/augmented sixths, cadence detection, matched famous progressions). It does not mention input validation or failure modes for unparseable chords, which is a minor gap.

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 front-loaded sentence that states the operation first and then lists outputs; despite the long enumeration, every clause carries distinct information and there is no filler.

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 carries the return-value burden and does so by naming the analysis categories returned, and the parameters are well covered by the schema. The only shortfall is the absence of any guidance on when to prefer this over sibling analysis tools.

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 100%, so the baseline is 3; the description nonetheless adds meaning beyond the schema by clarifying that 'key' is auto-detected when not supplied (the schema only shows a null default) and that analysis is Roman-numeral oriented, which frames how the chords parameter is interpreted.

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+resource ('Roman-numeral analysis of a progression') and enumerates the analytical outputs (numerals, function, cadences, borrowed chords), so an agent knows exactly what it produces. It does not, however, distinguish itself from close siblings such as analyze_harmony, identify_chord or suggest_progressions, which an agent could easily confuse it with.

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 implied by the subject matter (analyzing a chord progression), and 'the key (detected if not given)' hints at input flexibility. But there is no explicit when-to-use, when-not-to-use, or routing to alternatives like analyze_harmony or identify_chord, leaving the agent to infer which analysis tool fits.

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

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

Annotations only declare readOnlyHint=true, so the description carries the behavioral disclosure burden and does so well: it spells out the concrete facts returned (loop/one-shot classification, drum identity, pitch, tempo in bars, key, late-start flag). It adds real information beyond the annotation, though it doesn't discuss edge cases like unsupported formats.

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?

One tight sentence, front-loaded with the core action and then the returned attributes. Every clause earns its place with no filler.

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 must convey return content, which it does thoroughly for a one-parameter read tool. It is nearly complete; only edge-case behavior (invalid/non-audio paths, very long files) is left unstated.

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 100% and the schema already documents the single 'path' parameter as an audio file path. The description adds no path syntax, format, or constraint detail, so the baseline 3 applies.

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 (listens to/analyzes) and resource (one sample) and enumerates the attributes it extracts: loop vs one-shot, drum type, pitch, tempo, bars, key, late start. The single-sample scope distinguishes it from the broader analyze_audio sibling, though it never names that 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?

Usage is implied by the purpose (inspect one sample file to learn its characteristics), but there is no explicit when-to-use or when-not-to-use guidance, nor any routing to analyze_audio for longer material. Adequate but leaves the choice between the two analysis tools to inference.

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

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

No annotations are provided, so the description carries the full burden. It indicates a mutation ('Adds') but omits whether existing tracks are affected, required permissions, or what happens if the name is invalid.

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?

Single front-loaded sentence with no wasted words. It is appropriately sized for a one-parameter tool.

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 simple one-parameter mutation tool with full schema coverage, the description states the core action and the schema supplies the parameter reference. However, with no annotations and no output schema, it omits prerequisites and behavioral details (e.g., where tracks are inserted), leaving clear gaps.

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?

The schema covers the single parameter at 100% coverage with a clear description pointing to list_track_templates. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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 uses a specific verb ('Adds') and resource ('track template's tracks to the project'), making the action clear. It does not distinguish itself from related siblings like create_track or save_track_template, nor does it name the complementary list_track_templates tool in the description, so it stops short of a 5.

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 when-to-use, when-not-to-use, or alternative is stated. The agent must infer that a template name is needed and that list_track_templates should be called first; the schema notes this but the description does not.

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

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

With no annotations, the description carries the full burden, and it does substantial work: it discloses offline playback, that a temporary item is created and removed afterwards, and precisely what attributes are measured (range, pitch-follow/transposition, ADSR, brightness, character). It omits whether the audition is audible in real time and roughly how long a call takes, which are the remaining gaps.

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 well-formed sentences, front-loaded with what the tool does and followed by when to use it; the detailed attribute list is dense but informative rather than padding. Slightly long, but every clause 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?

No output schema exists, so the description must convey return values, and it does so thoroughly via the enumerated report fields. Combined with the offline/temporary-item disclosure, it covers most of what an agent needs, missing only duration/audibility expectations and parameter-level detail.

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 only 40%; only notes and track carry descriptions, while channel, velocity and note_seconds have bare titles. The description mentions 'notes across the range' but adds no format, channel, velocity or timing semantics, so it fails to compensate for the documented-parameter 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 action (plays notes offline, then reports) on a specific resource (the track's current instrument/sound), plus the exact analysis outputs it produces. No sibling tool does this – analyze_audio, get_instrument_notes and get_track_details all differ, and the description makes that distinction clear.

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?

Explicitly names two use cases: verifying a patch you designed, and characterizing an unfamiliar sound or preset. It does not name a concrete alternative tool or state when not to use it, so it stops short of the top tier.

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

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

Annotations only carry destructiveHint=true, and the description adds substantial behavioral context beyond that: it performs a destructive multi-step mix, but saves a copy of the project first when it has a file, and deliberately leaves user-set EQ/compression/panning untouched. It also discloses resource behavior ('one render pass') and the -6 dBFS headroom outcome, which an agent needs to predict the effect.

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 purpose is front-loaded and the final sentence usefully points at verification tools, but the core is a sprawling run-on sentence enumerating every mixing step. Much of that enumeration is closer to internal implementation detail than selection-relevant information, so it is denser than it needs to be.

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 complex, destructive multi-step tool it covers the essentials: what is changed, what is protected, the safety copy, and the recommended follow-up checks; dry_run is left to the schema. Without an output schema the description carries the return burden, and it only implies reporting via the schema's dry_run text rather than describing normal results, which keeps it from a 5.

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 100%, so the schema already documents style, reverb, dry_run, end_bar, sidechain and start_bar, setting the baseline at 3. The description echoes behavior associated with some flags (reverb return, sidechain ducking under kick, measuring a range) but adds no format or syntax detail beyond the schema, and never mentions dry_run.

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+resource ('A whole first mix in one call') and enumerates the concrete operations performed, from per-track measurement through role assignment, leveling, high-passing, compression, panning, reverb send, sidechain ducking and headroom. An agent can instantly distinguish it from narrow siblings like add_vocal_chain, setup_sidechain or master_to_target.

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 provides clear workflow context by routing the agent to verification tools ('Then check it: show_spectrogram, check_vocal_clarity, compare_mix_to_style') and states a preservation rule for already-configured tracks. It never says when NOT to use it (e.g. instead of the single-purpose mixing siblings), so it stops short of full when/when-not guidance.

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

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

With no annotations, the description carries the full behavioral burden and does substantial work: it discloses the implementation (one sampler instance per drum), the key-mapping convention (General MIDI), and the downstream benefit that samples can be swapped by name later. It does not cover permissions, error conditions, or what the call returns, but the core side-effect profile is well conveyed.

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, front-loaded with the core action and mechanism; the second sentence handles legitimate scope concern (works with any samples) in a single clause. No filler or repetition.

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 moderately complex setup tool with a nested samples object and no annotations, the description covers purpose, mechanism, and sample scope adequately. It stops short of describing return values or error behavior, and there is no output schema to offload that, so a small gap remains.

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 100%, so baseline is 3; every parameter including the nested samples map, release_s, velocity_db and trim_silence already has schema-level documentation. The description adds no parameter detail beyond the schema.

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 ('Builds a drum kit from sample files'), naming the concrete mechanism (one ReaSamplOmatic5000 per drum on GM keys), which is far more than a tautology. It implicitly distinguishes itself from the general sampler tool, but does not explicitly separate itself from siblings like build_sampled_instrument or map_drum_kit.

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 when-to-use, when-not, or alternative guidance is given. The track prerequisite ('an empty track, or one without another instrument') lives only in the schema, and no sibling such as build_sampled_instrument or add_drum_pattern is referenced to route the agent. The scope note about accepting any samples is not usage guidance.

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

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

With no annotations the description carries the full burden, and it discloses meaningful behavior: per-sample key stretching, tuning from the actually-played pitch measured in cents, the caveat that file names are sometimes an octave off, plus velocity response, note-offs and release. It stops short of stating side effects on the project, whether it returns/creates anything inspectable, or auth/permission needs.

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?

Purpose is front-loaded, and the second sentence delivers the sibling contrast. The parenthetical enumerations are slightly sprawling but each clause contributes actionable detail (tuning, octave discrepancy, velocity, release), so little is wasted.

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 7-parameter build tool with 100% schema coverage and no output schema, the description covers purpose, key behaviors and the alternative tool well. The main gap is silence on what the call produces or how it interacts with existing project state, though the schema partly covers the track-creation behavior.

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 100%, so all seven parameters including reach, release_s and velocity_db are already documented in the schema. The description reinforces behavior (stretch of keys, velocity response, release) but adds no syntax or format detail beyond what the schema provides, which is the baseline 3.

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 ('Builds') and resource ('playable instrument from pitched sample files'), and explicitly names the sibling it is not (build_drum_kit). The parenthetical examples (strings, brass, pizzicato, choir, synth) pin down the input domain, so an agent can distinguish it from drum-kit and audio-insertion tools without opening a schema.

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?

Clearly routes melodic work here versus build_drum_kit ('Better than build_drum_kit for melodic parts'). It does not spell out prerequisites or when-not-to-use cases beyond that contrast, and find_samples is only referenced in the schema, so the guidance is clear but not fully explicit.

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

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

readOnlyHint=true already establishes this is a safe read, so the bar is lower. The description still adds real behavioral context: the specific 16-second window plus export tail it renders, that it measures level, that it also reports song length, and how region changes the target. It stops short of disclosing cost/thresholds or whether the render is a full offline bounce.

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?

Every clause is front-loaded and informative: the core check comes first, the detection list second, the length report third, and the region override last. There is no filler or restated name/title.

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 helpfully enumerates the endings it detects and notes it reports song length, which approximates the return content, and annotations cover safety. What is still missing is any indication of thresholds or pass/fail semantics (how quiet is 'too quiet'), which matters for acting on the result.

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 100%, so both tail_seconds and region are already fully documented in the schema. The description's 'plus the export tail' and 'with region, checks that region instead' essentially restate those schema entries rather than adding new meaning, so this lands at the baseline 3.

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 states a specific verb and resource ('checks how the song ends') and goes further by naming the exact mechanism (renders the last 16 seconds plus export tail, measures level) and the conditions it detects (fade-out, quiet/silent end, tail cut mid-ring, lingering stinger). This clearly separates it from generic analysis siblings like analyze_audio or check_tuning.

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 ties the check to 'how it will be used', and the kind enum in the schema supplies the use-case framing (continuous/ending/stinger). There is no explicit when-to-use statement, no mention of when this check should precede an export or be skipped, and no named alternative tool.

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

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

Annotations only declare readOnlyHint=true, so the description carries most of the burden, and it does: it discloses that the tool renders the track (non-trivial offline work), what it measures, and the accuracy caveats for chords and polyphony. It does not mention cost/latency or failure modes on empty or silent tracks, which keeps it from a 5.

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 question it answers, then organized by input type with a closing caveat sentence. At roughly 85 words it is dense but nearly every clause carries information; the parenthetical asides are the only mild padding.

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?

No output schema exists, so the description must convey what comes back, and it does describe the metrics (cents off, semitone distance, count outside key/chords). With 100% parameter coverage and a read-only annotation, only the absence of explicit cost/performance expectations leaves a small gap.

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 100%, so the baseline is 3, but the description adds genuine meaning: it explains that 'key' and 'chords_item' are the reference used to count out-of-key pitches, which the schema labels but does not functionally tie together. This clarifies why those optional params change the result rather than just what they are.

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?

Opens with a specific question tied to a concrete action ('Renders the track and measures what actually sounds'), then splits the behavior by input type (MIDI part vs audio). An agent can immediately tell this is a pitch-accuracy measurement tool and not a generic analyzer like analyze_audio or measure_tracks.

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 clear applicability context: MIDI parts measure each held note's pitch, audio measures distance to nearest semitone and count outside key/chords, and it notes 'Mono lines measure best; chords are judged by their top note.' That is real when-it-works guidance, but it never names a sibling alternative or states an explicit exclusion, so it stays at 4 rather than 5.

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

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

readOnlyHint=true already tells the agent this is a safe, non-mutating measurement, so the bar is lower. The description usefully adds that the clean reference is the spoken words and how to read the two-result (alone vs in-mix) outcome, but it does not disclose return format, the cost of rendering the master for the in-mix check, or timing behavior.

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 tight sentences, front-loaded with what is measured before the decision guidance. Every clause earns its place, with no filler or restatement of the tool name.

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 four-parameter read-only diagnostic with no output schema, the description covers purpose, method, and how to act on the result, which is enough for correct invocation. It is slightly thin on what the returned values look like (no output schema exists), but the interpretation guidance largely compensates.

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 100%, with all four parameters (track, in_mix, end_bar, start_bar) documented in the schema including defaults and the 1-based fractional bar convention. The description adds no parameter-level detail beyond what the schema already provides, so the baseline of 3 is appropriate.

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 resource (a robot vocal's word intelligibility) and the method (STOI against clean spoken words), so the agent knows exactly what is measured. It is clearly distinct from sibling diagnostics like check_tuning, check_ending, or show_spectrogram without needing to open any schema.

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?

Explicitly says to 'use it instead of guessing' and provides interpretation rules (clear alone but not in mix = mix burying it; unclear alone = change words/notes/voice/style). It gives strong context but does not name alternative tools (e.g. analyze_audio, measure_tracks) or state when not to use it, so it falls short of the full when/when-not/alternatives bar.

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

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

readOnlyHint=true is already declared, so the safety profile is covered; the description goes further by enumerating the exact musical rules enforced (parallel fifths/octaves, hidden octaves, crossings, spacing, leading tones/sevenths) and by stating the asymmetric behavior of the two modes. It still does not say whether the realization is returned or inserted into the project, nor what the output looks like.

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 tight sentences: the domain is stated first, then the two mode behaviors are contrasted. No filler, and the most important framing information is front-loaded.

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 does partially compensate by describing what each mode returns. But for a three-parameter, zero-required tool it omits key behaviors: whether an omitted 'key' is inferred, whether 'chords' and 'voicings' are mutually exclusive, and whether the generated realization is written into the project or just returned — a meaningful ambiguity next to siblings like add_midi_notes.

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 100%, and each parameter carries a formatting example ('A minor', 'F# dorian'; voicings low-to-high). The description reinforces the chords-vs-voicings distinction but adds no syntax or constraint detail the schema lacks, so the baseline of 3 applies.

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 domain (common-practice voice leading) and states exactly what the tool produces in each mode: an SATB realization from chords, or a rule-violation list from voicings. It is clearly separable from harmony siblings like analyze_harmony or harmonize_melody, though it never names an alternative 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?

Usage is implied through input-type branching — pass 'chords' to generate, pass 'voicings' to check — which is genuinely helpful. However, there is no statement of when to prefer this over the other harmony tools, no prerequisites, and no handling of what happens if both or neither are supplied.

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

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

With no annotations, the description carries the full behavioral burden. It discloses only the playback effect ('the one that plays') and says nothing about whether other takes are muted, hidden, deleted, or how this interacts with comping or existing take lanes — significant gaps for a state-changing tool.

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 short sentence with the core action front-loaded. The trailing parenthetical is mildly redundant with the main clause but costs little 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 simple one-required-parameter tool with no output schema this is minimally adequate, but it omits the natural workflow linkage to list_takes (where take numbers come from) and the consequences of switching the active take.

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 100%, and the schema already documents every parameter, including cross-references (item_id from create_midi_item/get_track_details, take from list_takes). The description adds no parameter meaning beyond the schema, so the baseline of 3 applies.

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 states a concrete verb and effect: making a take the one that plays. It implies selection/activation rather than listing, which distinguishes it from the neighboring list_takes and explode_takes. However, it doesn't explicitly name alternatives, so the differentiation is inferential.

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?

The parenthetical 'for picking the best performance' hints at intent, but there is no statement of when this should be used versus explode_takes or list_takes, nor any prerequisite (e.g., that takes must exist first).

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

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

With no annotations, the description carries the full burden and does well: it discloses the algorithm (syllable slicing, 16th-note placement), the tuning constraint ('at most a tritone, correcting its tuning'), and the output shape ('One item per chop, all ordinary audio to edit afterwards'). It doesn't address failure modes or prerequisites, but for a creative generation tool the behavioral profile is well covered.

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 sentences, front-loaded with the core purpose, then usage routing, then result shape. The genre flavor ('the house / future-bass way') and 'one item per chop' line both carry information rather than padding.

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 9-parameter tool with no annotations and no output schema, the description gives the creative context, the process, and the return shape ('one item per chop, ordinary audio to edit afterwards'), which substitutes for a missing output schema. Parameter format details are left to the schema, which is acceptable given near-high coverage.

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 78%, so the schema already documents most parameters (key, path, seed, chords, pattern, chords_item). The description adds concept-level meaning beyond that, notably the 'at most a tritone' tuning rule governing how the chords/key parameters act on each slice, tying the params together into a coherent effect.

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 ('Turns a real vocal sample into rhythmic vocal chops') and then details the transformation (slices at syllables, 16th-note pattern, shifts onto chord/key). It also distinguishes itself from the sibling add_robot_vocal with 'Real voices beat robot vocals, so use this first when the user's samples have vocals.' An agent can tell this apart from the robot-vocal sibling without opening either schema.

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?

'Use this first when the user's samples have vocals' gives a clear selection condition, and 'Real voices beat robot vocals' strongly implies the add_robot_vocal alternative. It stops short of explicitly naming that alternative tool or stating an exclusion, but the routing intent is unambiguous.

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

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

Annotations already declare destructiveHint=true, and the description adds genuinely new context beyond that: the operation is 'Undoable' (reversibility) and defaults to clearing everything. That reversibility note is exactly the kind of extra behavioral signal annotations cannot convey.

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 compact clauses, front-loaded with the action and immediately followed by the default scope and reversibility guarantee. No filler.

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 6-parameter destructive mutation with no output schema and partial annotation coverage, the definition covers the essentials: what is destroyed, whether it is reversible, and the default range. It is only slightly thin on the fx/parameter path and on prerequisites.

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% with descriptions on track, target, start_bar and end_bar but none on fx and parameter. The description reinforces the range concept and its all-by-default behavior, matching start_bar/end_bar, but supplies no syntax or format detail and says nothing about the fx/parameter pairing.

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 ('Removes automation points') with scope ('in a range', default all), which cleanly separates it from the read_automation/write_automation siblings. It stops short of naming those siblings explicitly, so it lands just below the top tier.

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?

The scope note '(default: all of them)' implies the caller can narrow the operation, but there is no explicit when-to-use guidance, no prerequisite (e.g., must automation exist, must a selection be set), and no pointer to write_automation or read_automation as alternatives.

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

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

readOnlyHint=true already establishes this is a safe read. The description adds genuinely useful context beyond the annotation: it distinguishes dimensions that receive objective 'verdicts' (loudness, true peak, dynamics, low-end mono) from those merely 'reported to judge by ear' (low end, tone). It does not disclose the return shape or what a verdict looks like, but the verdict/by-ear split is real added value.

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 dense sentence front-loads the core action and uses a colon/semicolon to partition the metrics cleanly. No wasted words, though the verdict/by-ear split compresses a lot into one clause.

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 carries the burden of explaining results; it partially does so via verdicts vs by-ear reporting, but leaves the format of a 'verdict' and the origin of style profiles unspecified. Adequate but with visible gaps for a comparison tool.

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 75%, so the schema largely documents track, start_bar, and end_bar. The description mentions the 'style profile' but never says where style values come from or how they relate to siblings like list_genres/get_genre_profile. Baseline 3 is appropriate.

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 pair (measures the mix, compares it against a style profile) and enumerates the dimensions analyzed. The agent can tell what the tool produces, though it does not distinguish this from siblings like analyze_audio, measure_tracks, or master_to_target.

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 when-to-use guidance and no alternatives named. Given the cluster of analysis/comparison siblings (analyze_audio, measure_tracks, master_to_target), an explicit routing cue would be expected but is absent; usage is only implied by the description of what gets measured.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the post-fader routing behavior, but says nothing about what happens to the tracks' existing master sends, whether existing routing is altered or destroyed, required permissions, or error behavior when a track reference is invalid.

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 front-loaded sentence with a colon separating the action from its purpose; the routing explanation earns its place and there is no filler.

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 annotations and no output schema, the description should shoulder more of the behavioral load. It covers purpose and routing well but omits the return value, the effect on pre-existing sends, and failure modes for a 4-parameter mutation tool.

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 100%, so name, tracks, fx, and color are already documented in the schema with examples. The description adds no parameter-level detail beyond what the schema provides, which is the expected baseline when the schema does the heavy lifting.

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 ('Creates a submix bus') and adds the routing semantics that define a bus — tracks send post-fader to it instead of the master. It does not, however, distinguish this from conceptually adjacent siblings like create_folder or set_send, which an agent might reasonably confuse it with.

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?

The description implies the use case (grouping tracks so they can be processed and leveled together) but gives no explicit when-to-use guidance, prerequisites, or alternatives such as create_folder or set_send. Usage is left to inference from the concept.

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

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

With no annotations, the description carries the full burden and does well: it discloses that a new folder track is created above the tracks, that they route through it, and that effects on the folder act like a bus. It does not say whether the operation is reversible (undo), what happens to pre-existing folder membership, or what the call returns, which keeps it short of a 5 for a mutation tool.

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, zero waste, front-loaded with what the tool produces, then the disambiguating alternative. Nothing is repeated from the schema or annotations.

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 structural mutation with no annotations and no output schema, the description covers the essential semantics: what gets created, how routing changes, and the bus behavior. The only notable gap is the absence of any statement about the return value or reversibility, which would matter for a routing-altering operation.

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 100%, so name, color (#RRGGBB) and tracks are already documented in the schema. The description adds only the concept of grouping 'tracks', which the schema already conveys; baseline 3 is appropriate.

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 states a specific verb+resource ('Groups tracks in a folder') and immediately explains the resulting structure: a new folder track above the grouped tracks that they play through. It also explicitly names the sibling it is not (create_bus), so an agent can distinguish the two without opening either schema.

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 an explicit alternative and the condition that selects it: 'Use create_bus instead to keep tracks where they are and send them.' This is a clean when-to-use-this vs when-to-use-the-other statement, which is exactly what an agent needs to route between the two grouping tools.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that the item is empty, defaults to 4 bars, and returns an item_id—useful beyond the schema—but omits permissions required, side effects, error conditions, and whether it overwrites existing items.

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 front-loaded sentence with no wasted words. It states the action, default behavior, and return value efficiently.

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 6-parameter creation tool with no annotations and no output schema, the description covers the core action and return value but leaves gaps: it doesn't explain track selection details (covered partially by schema), what happens on invalid input, or how to chain with sibling tools. Adequate but 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 description coverage is 67% (moderate), so the schema already documents track, length_qn, start_bar, and start_beat. The description adds the default length ('default 4 bars') but does not clarify name, length_bars, or how parameters interact. Baseline 3 is appropriate.

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 states a specific verb (Creates) and resource (empty MIDI item), and clarifies it returns an item_id for later note/chord/drum operations. It distinguishes implicitly from siblings like add_midi_notes by emphasizing creation vs. adding, but does not name any 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?

The phrase 'for adding notes, chords or drums' implies this tool is a prerequisite step before note-adding tools, but there is no explicit when-to-use, when-not, or named alternative. The workflow is suggested rather than spelled out.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that the returned result describes known instruments ('what they are and how they behave'), which is real information beyond the schema. However, it says nothing about side effects on existing tracks when position is used, permissions, reversibility, or failure modes for unknown instruments.

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, front-loaded with the primary action, with no padding. The second sentence is slightly imprecise ('what they are and how they behave') but is short and earns its place by describing the result.

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?

No output schema exists, so the description's note about returned instrument metadata is genuinely needed and present. Still, for a 5-parameter mutation tool with no annotations, it omits the effect of inserting at a position and any error behavior, leaving real gaps.

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 80%, so the schema already documents color, position, instrument, and show_instrument (only 'name' is bare). The description reinforces the instrument concept and notes the post-condition of loading an instrument, but adds no format, default, or constraint detail beyond what the schema provides. Baseline 3 is appropriate.

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 ('Adds a track') and adds the meaningful qualifier that an instrument can be attached so MIDI produces sound. This distinguishes it from adjacent tools like create_midi_item or create_bus, though it never names those siblings 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?

There is no when-to-use, when-not-to-use, or alternative-selection guidance. The phrase 'optionally with an instrument so MIDI on it makes sound' hints at a common case but never tells the agent when to prefer create_track over apply_track_template, create_bus, or other track-creation paths.

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

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

Annotations already declare destructiveHint=true, so the safety profile is covered. The description adds a constraint not present in structured data: built-in maps are protected and must be overridden instead. It does not state whether the call errors on built-ins or what happens to references to the deleted map.

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?

One sentence with the action front-loaded and the constraint in a tight parenthetical. Nothing is wasted and no information is buried.

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?

The tool is simple, destructive intent is annotated, and there is no output schema to explain. However, the undefined 'instrument' argument and the unstated failure behavior for built-in maps leave gaps an agent must guess at.

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% for the single required 'instrument' parameter, so the description carries the full burden and fails it. It never clarifies whether 'instrument' is the map name, the target drum instrument, or a map identifier, leaving a real ambiguity for invocation.

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 ('Deletes a saved drum map'), which cleanly separates it from save_drum_map and list_drum_maps among the siblings. It does not explicitly name those siblings or route the agent, so it stops short of a 5.

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?

The parenthetical gives an explicit when-not condition: built-in maps can't be deleted. That is real routing guidance beyond the bare purpose, though it doesn't name the alternative action or tool (e.g. override, or where to find saved maps).

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

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

Annotations already declare destructiveHint=true, so the risky nature is covered structurally. The description adds one genuinely useful behavioral fact beyond the annotations: the operation is undoable, which softens the destructive profile. However it says nothing about scope of removal, whether the item's MIDI/audio content is preserved, or any confirmation requirement.

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 front-loaded sentence with zero padding. It is efficient, though arguably too terse to be maximally useful for a destructive operation.

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 one-parameter delete tool with a destructiveHint annotation and a fully covered schema, the essentials are present, and the undo note helps. It still leaves open what exactly an "item" is in this DAW and whether deletion cascades (e.g. to associated notes or automation), which matters for a destructive tool with no output schema.

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 100% and item_id is fully documented in the schema (MIDI item id from create_midi_item/get_track_details, or "selected"). The description adds no parameter detail beyond the schema, so the baseline 3 applies.

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?

"Deletes an item" states a clear verb and resource, but "item" is generic and the definition does nothing to distinguish it from siblings like delete_track, delete_marker, delete_midi_notes, or delete_sound that share the same verb. An agent can infer it targets an arrangement item only by cross-referencing the schema's reference to create_midi_item.

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?

There is no when-to-use guidance, no mention of alternatives (e.g. edit_item vs split_item vs this), and no prerequisites. The parenthetical "(undoable)" is the only context offered and it is not framed as a usage rule.

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

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

The destructiveHint: true annotation already flags this as a write/destroy operation, so the description only needs to add context — and it does: it explicitly limits the blast radius by stating the audio or MIDI under the marker/region survives. It does not mention reversibility or whether undo (a sibling tool) applies, but the key destructive-scope question is answered.

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 well-formed sentence, front-loaded with the action and resource, where the parenthetical clarification is the only extra clause and it clearly 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?

For a simple deletion tool with a destructiveHint annotation and no output schema, the description covers what is deleted and what is preserved, which is the essential information. The notable remaining gap is the region flag's semantics, and secondarily whether the deletion is undoable, neither of which is addressed.

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 50%: the 'marker' parameter is documented (name or number) in the schema, while 'region' has no description at all. The description's phrase 'marker or region' hints that region is a mode switch, but it never explains how the boolean interacts with the marker argument, so it only partially compensates 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?

Specific verb (deletes) plus specific resource (marker or region), and the parenthetical bounds what is NOT removed (audio/MIDI). It is unambiguous and distinguishable from add_marker and edit_marker by verb alone, but it never names those siblings or routes the agent between them.

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?

There is no when-to-use guidance: nothing says to use edit_marker to rename/move instead, or that delete_item handles the underlying media. The parenthetical describes scope of deletion, not the conditions that select this tool over its neighbors.

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

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

destructiveHint=true already flags this as a destructive operation, so the bar is lower; the description still adds real value by disclosing the dangerous no-filter default (deletes everything) and that the change is recoverable via 'One undo step'. It does not say how many events were removed or what permissions are needed.

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, zero padding, front-loaded with the action and followed by the destructive default and the undo reassurance. Every clause 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?

For a destructive, filter-driven tool with no output schema and no docs on most params, the description covers the essential risk (bulk deletion when unfiltered) and reversibility. It is close to complete, though the missing per-parameter semantics is the remaining gap.

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?

With only 17% schema coverage, the description must carry the load. It explains the collective filter semantics and the null-means-all default (not stated in the schema), and hints at cc=64, but never clarifies kind, channel, or the start/end time units, leaving five params largely opaque.

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 ('Deletes') and resource ('controller events'), and the qualifier 'matching the filters' plus the sustain-pedal/pitch-bend examples make the scope unmistakable. The contrast with sibling verbs (add_midi_cc, get_midi_cc) and with delete_midi_notes is clear from 'controller events', though no sibling is named 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?

Gives concrete usage context: clear the sustain pedal (cc=64) or old pitch bends, and states the important default that all matching events are removed when no filters are passed. No explicit routing to alternatives (get_midi_cc, delete_midi_notes), so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true, so the safety profile is covered. The description adds meaningful behavioral context beyond that: deletion scope is controlled by filters, and omitting them deletes every note in the item. It does not mention irreversibility/undo or confirmation, which keeps it from a 5.

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 compact sentence that front-loads the action and immediately qualifies it with the unfiltered-destruction caveat. No filler, no redundancy.

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 needed, annotations covering destructiveness, and full schema parameter documentation, the description supplies what is missing most: that unfiltered calls delete everything. Minor gaps remain, such as whether filters combine as AND and whether the deletion is undoable.

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 100%, so all four parameters (item_id, start, end, pitch) are already documented in the schema, establishing a baseline of 3. The description only restates the filter concept ('with no filters') without adding syntax, units, or combination semantics beyond what the schema says.

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 (deletes) and resource (notes from a MIDI item), which is enough to distinguish it from delete_item, delete_midi_cc, and delete_note. However, it does not explicitly contrast itself with the other note-editing/deleting siblings such as edit_midi_notes or delete_note, so sibling differentiation is left to inference.

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?

The clause 'with no filters, all of them' implicitly tells the agent that calling without filters is allowed and destructive, which is a form of usage guidance. There is no explicit when-to-use vs. alternative (e.g., 'use edit_midi_notes to remove a subset by editing'), so guidance remains implied.

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

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

Annotations already declare destructiveHint=true, and the description only restates the mutation with no added behavioral context. It omits whether deletion is permanent, whether it can be undone (an 'undo' sibling exists), or any confirmation/permission requirements expected of a destructive tool.

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 short sentence that is front-loaded and waste-free. It is appropriately sized for a trivial single-parameter tool, though its brevity comes at the cost of any useful guidance.

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 destructive operation with no output schema, the description should at least indicate irreversibility or recoverability (undo, trash). It provides no such context, so an agent cannot judge the risk or expected outcome of the call.

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 100% and the single parameter is documented in the schema as 'The note's id from find_notes'. The description adds nothing beyond this, so the baseline 3 applies since the schema carries the full burden.

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 ('Deletes a saved note'), which is unambiguous against most siblings. However, with many delete_* siblings (delete_sound, delete_marker, delete_midi_notes, delete_item), it does not clarify that this targets a saved text note rather than MIDI notes — the 'saved' qualifier hints at this but does not route the agent 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 on when to use this versus alternatives or prerequisites. It never distinguishes itself from delete_midi_notes or delete_marker, nor does it mention that note ids come from find_notes/save_note, leaving the agent to infer usage entirely.

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

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

The destructiveHint=true annotation already declares this is a destructive operation, so the bar is lower. The description adds the useful irreversibility note ('can't be undone'), which reinforces permanence beyond the annotation's binary flag. However, it says nothing about side effects (e.g., whether the sound must be unused) or required permissions.

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 short sentences, front-loaded with the action and immediately followed by the critical warning. Zero filler.

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 single-parameter destructive tool with no output schema, the description plus annotations cover the essentials: what it does, that it is destructive, and that it is irreversible. Only edge-case behavior (e.g., deleting a sound still referenced by a project) is unaddressed.

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 100% — the single 'name' parameter is fully documented in the schema as 'The sound's exact name.' The description only references 'a sound from the library' and adds no matching or syntax detail, so baseline 3 is appropriate.

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: 'Deletes a sound from the library.' An agent can immediately tell what it does. It stops short of naming or contrasting with siblings like update_sound or delete_drum_map, but the purpose itself is unambiguous.

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?

There is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives. The destructive framing implies caution, but the description never states conditions or prerequisites for deletion.

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

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

Annotations already declare destructiveHint=true, so the safety profile is partly covered. The description adds two things beyond that: the cascading scope ('everything on it') and reversibility ('undoable'), plus the confirmation requirement. That said, it doesn't state return behavior or whether undo history/automation is affected.

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 short sentences, front-loaded with the action and scope, followed by the caveat. Every clause earns its place with zero waste.

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 single-parameter, irreversible-looking mutation whose destructive nature is already flagged by annotations, this covers scope, reversibility, and a confirmation step. Only minor gaps remain (e.g., whether the removal frees sends/routing or affects undo history), which are acceptable given the tool's simplicity.

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 100%, with the track parameter documented as 'Track number, or its exact name'. The description adds nothing about the parameter beyond the schema, so the baseline of 3 applies.

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 (Deletes) and resource (a track), and clarifies scope with 'everything on it'. This distinguishes it cleanly from the many sibling deletions (delete_item, delete_sound, delete_marker, delete_note, etc.) that target different resources.

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?

The instruction 'Confirm with the user first' gives a clear invocation precondition, which is real guidance. However, it never names alternatives (e.g., remove_fx, freeze_tracks, or simply muting) or explains when deleting a track is preferable to those, so the when-to-use-vs-alternatives dimension is only implied.

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

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

With no annotations, the description carries the full burden, and it does disclose one real behavioral trait: copies are placed back to back (i.e. appended sequentially rather than stacked). It says nothing about what identifiers the new copies receive, whether the source item is left untouched, or how the 256-copy ceiling behaves.

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 short sentences, front-loaded with the core action and no filler. The parenthetical examples earn their space by grounding an abstract operation, though they slightly delay the behavioral fact about placement.

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?

A four-parameter mutation tool with no annotations and no output schema; the description omits return behavior (what ids/handles the new copies get) and the multi-copy semantics. Adequate for basic invocation but leaves real gaps for an agent planning follow-up operations on the duplicated items.

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 75%, with item_id, start_bar and start_beat documented in the schema itself, so the schema does the heavy lifting. The description adds no parameter meaning at all – notably it never mentions that a count parameter exists for multiple copies, which is the key semantic distinction from 'copy once'.

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?

Names a specific verb (copies) and resource (item), and the examples ('repeat a 4-bar loop', 'reuse the chorus') make the operation concrete. It does not distinguish itself from adjacent siblings such as create_midi_item or place_loop, so an agent must infer the boundary from the name alone.

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 implied through the musical examples rather than stated: there is no explicit 'use this when you want N consecutive copies, otherwise use X' routing. No alternatives or exclusions are named, and no prerequisites are mentioned.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does not say whether the edit is destructive, how unspecified properties are treated, whether parameters combine in one call, or whether the item must exist first — a serious gap for a 17-parameter mutation tool.

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 compact sentence with the operation list front-loaded and no filler. The catch-all 'or otherwise edits' weakens precision slightly but costs nothing structurally.

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 17 parameters, no annotations, no output schema and only 59% schema coverage, the one-line description is not sufficient. It omits which parameters apply to audio versus MIDI, interaction/ordering between move, trim and fade parameters, and any notion of undo or reversibility.

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 59%, and the description's high-level verb list loosely mirrors the parameter groups (move/trim/fade/re-pitch). It adds the useful signal that some parameters are audio-only, but relies on the schema for the rest; baseline 3 fits given partial coverage.

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 (edits) plus an enumeration of the operations it performs (moves, trims, fades, re-pitches) on a bounded resource (audio or MIDI item). An agent can place it apart from create_midi_item, delete_item, split_item and duplicate_item, though those siblings are never named to sharpen the boundary.

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 when-to-use guidance, no prerequisites, and no alternatives named. The only faint signal is 'otherwise edits', which implies modifying an existing item, but nothing tells the agent when to pick this over split_item or duplicate_item.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not state permissions, reversibility, side effects, error behavior, or how name clashes are resolved beyond what the schema already says about the region parameter.

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, front-loaded sentence with two compact examples. Every element earns its place and there is no redundant filler.

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 an unannotated mutation tool with eight parameters and no output schema, the description is adequate but incomplete. It covers the article of the operations but omits critical behavioral context such as conflict resolution, required permissions, and side effects.

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 63%, so the description must compensate. It loosely maps actions (rename, move, resize, recolor) to parameters like new_name, start_bar/end_bar, and color, but leaves end_beat, new_name, and start_beat without added meaning.

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 specific verbs (renames, moves, resizes, recolors) and the target resource (marker or region), with examples that make the scope unambiguous. It is clearly distinguishable from siblings like add_marker and delete_marker.

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?

The description gives no guidance on when to use this tool versus alternatives such as add_marker, delete_marker, or edit_item. The examples illustrate capabilities but do not establish when this tool is the right choice.

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

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

With no annotations, the description carries the burden and does disclose real behavioral traits: mutations are scoped ('the rest stay as they are') and reversible in a specific granularity ('One undo step'). It does not cover auth/preconditions or return format, but for a MIDI edit tool the disclosure of partial-edit and undo semantics is substantive.

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 purpose and operations, then closes with the two most behaviorally important facts (filter scoping, undo granularity). Dense but every clause earns its place given 15 operations; the operation enumeration is long but justified by the breadth of the tool.

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 30-parameter, 15-operation tool with no output schema and no annotations, the description covers the operation space, filter scoping, and undo semantics adequately. It leans on the schema for per-parameter detail, which is reasonable given the rich enum description, leaving only minor gaps (prerequisites, selection interaction).

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 60%, between the low and high baselines, so the schema already documents much of the per-parameter meaning (grid, key, scale, steps, chords_item, etc.). The description reinforces the operation groupings but adds little parameter syntax beyond what the schema's own operation and property descriptions provide.

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 ('Edits existing MIDI notes') and enumerates the full operation surface (quantize, humanize, transpose, snap, velocity, strum, legato, motif development). It cleanly distinguishes itself from siblings like add_midi_notes, delete_midi_notes, and get_midi_notes by the 'existing' qualifier.

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?

'Edits existing MIDI notes' plus 'Filters pick which notes; the rest stay as they are' gives clear context for when this applies versus creation or deletion tools. It stops short of explicitly naming the alternative tools or stating exclusions, so it is clear context but not full when/when-not routing.

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

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

With no annotations, the description carries the full burden. It does disclose the key side effect — one new track is created per take — which is genuine behavioral value. However, it doesn't say whether the source item survives, whether the operation is reversible/undoable, or how the new tracks are named or routed.

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?

One sentence, front-loaded with the effect and closed with the rationale. Zero filler, nothing to trim.

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?

Adequate for a one-parameter tool with no output schema: the agent knows what happens and why. It falls short on the state of the original item and on whether this applies to audio takes as well as the MIDI item implied by the schema, which matters for a track-creating operation.

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 100% and there is a single required parameter fully documented in the schema (item_id, including the 'selected' sentinel). The description adds nothing about the parameter, so the baseline 3 applies.

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-effect ('puts each take on its own new track') plus the motivating use case ('compare or comp them side by side'), which is far clearer than a name restatement. It doesn't explicitly contrast with nearby take tools like list_takes or choose_take, but the resource and effect are unambiguous.

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?

The clause 'to compare or comp them side by side' implies the scenario in which the tool is useful, but there is no explicit when-to-use/when-not guidance and no named alternative (e.g., choose_take for selecting a single take, or list_takes for inspection).

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

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

With no annotations, the description carries the full load. It discloses that it exports the master with its effects applied and reports loudness and true peak, which is meaningful behavior. It does not, however, cover overwrite behavior, where files land, or the gain-only adjustment caveat beyond what already lives in the schema.

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 tightly written sentences with zero waste. The core action is front-loaded and the sequencing hint follows immediately.

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 tool with no output schema and no annotations, the description does mention the return-relevant facts (loudness and true peak). It is adequate, though it could say more about the write side effects given the absence of annotations.

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 79%, so the schema itself documents nearly all 14 parameters well. The description adds no additional parameter semantics (formats, bit depth, targets) beyond what the schema already carries, so the baseline 3 applies.

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 (Exports) plus the exact resource (the finished mix/master with its effects) and the outputs (audio file, loudness and true peak report). This is clear, but it does not explicitly distinguish itself from close siblings like export_stems and export_regions, only mentioning master_to_target.

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?

Provides a useful workflow hint ('Use master_to_target first for a release master'), which implies sequencing. However, there is no when-not guidance and no explicit contrast with export_stems/export_regions, so the agent must infer when to choose this over those siblings.

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

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

With no annotations, the description carries the full burden and does so well: it describes one-shot processing (mono unless listed in stereo, DC removed, leading/trailing silence trimmed, peak set), loop handling (seamless crossfade, length reported), dithering by bit depth, and even a warning when a region clips the sound's tail. It omits overwrite behavior, permission requirements, and error/return handling.

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 core behavior (region-per-file export in one pass) is front-loaded, and the remaining sentences are dense with specifics rather than filler. It is long, but each clause conveys distinct processing behavior, so little reads as waste.

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 9-parameter mutation tool with no annotations and no output schema, the description is substantially complete on processing behavior and workflow. Remaining gaps are overwrite semantics, return value, and any permission/cost considerations, which are minor relative to what is covered.

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 high at 89%, so the baseline is 3. The description adds interpretation for peak_db, stereo, and loops (explaining how they change output), but parameters like overwrite, sample_rate, folder, and bit_depth are left entirely to the schema.

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: exports each region of the project as its own file named after the region, in one render pass. This clearly distinguishes it from a single-file or stem export. It does not, however, explicitly distinguish itself from siblings like export_mix or export_stems, leaving the agent to infer the difference.

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?

The closing instruction ("Put each sound in its own region with a little room after it, then call this once") gives useful preparation context and implies the when. But it never names or contrasts the alternative export tools (export_mix, export_stems), so the choice among them is left implicit.

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

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

With no annotations, the description carries the behavioral burden and does well: it discloses the signal chain ('post-fader, with its effects but not the master's') and the alignment behavior ('all the same length so they line up from the same start'). It leaves some gaps, such as overwrite behavior and error handling when files already exist, but the core behavioral traits are clearly stated.

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, front-loaded sentence that opens with the core action and then adds the most important qualifiers. No filler or repetition; every phrase contributes useful context.

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?

The description covers purpose, usage, and key behavioral traits well. But for a 10-parameter tool with no annotations, no output schema, and only 30% schema description coverage, it leaves parameter semantics largely undocumented, which limits an agent's ability to invoke it correctly with non-default settings.

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 only 30% across 10 parameters. The description does not explain any parameter names or semantics (e.g., start_bar, end_bar, tail_seconds, bit_depth, sample_rate, overwrite). It only describes the overall output concept, so it fails to compensate for the low schema coverage.

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: 'Exports each track as its own audio file.' The parenthetical details (post-fader, track effects but not master) further clarify the output. It does not explicitly name or contrast with siblings like export_mix or export_regions, so sibling differentiation is implicit rather than explicit.

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?

Gives clear use contexts: 'for mixing elsewhere, remixes, or sharing parts.' This tells the agent when the tool is appropriate. However, it does not state when not to use it or name alternative tools for adjacent tasks, leaving the agent to infer the boundaries.

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

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

No annotations are provided, so the description carries the full burden. It discloses useful behavior: the file starts at the song's start, output goes at bar 1, tempo and positions are baked in. But it doesn't state whether the export mutates the project, what permissions are needed, or whether the file is written to disk vs returned (no output schema), leaving a real behavioral gap.

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 sentences, but the first sentence is a long run-on that mixes purpose, consumers, and output semantics. The workflow guidance is useful but not tightly front-loaded. Some redundancy between 'writes a melody item' and the export framing.

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 4-param export tool with no annotations and no output schema, the description covers purpose, workflow, and downstream consumption well. It omits the return shape (does it return a file path? a status?) which matters when no output schema exists, keeping it from a 5.

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 100%, so the schema already documents all four parameters including the melody mark and lyric syntax. The description adds almost no parameter detail beyond what the schema provides, so baseline 3 is appropriate.

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 (writes/exports) and resource (melody item + lyrics as MIDI file) and directly names the downstream consumer class (singing synths). Distinguished from siblings like write_melody or export_mix by its vocal-MIDI target.

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?

Description explains the workflow context (export the MIDI, then render the vocal with the singer, then insert_audio_file at bar 1, then mix). That is strong when-to-use guidance for the follow-up steps. However it does not explicitly name when NOT to use it versus alternatives like add_robot_vocal or write_melody.

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

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

The readOnlyHint annotation already tells the agent this is a safe non-mutating analysis call. The description adds value by enumerating the analysis dimensions and the named modulation types (pivot, ii-V, chromatic mediant, etc.), which compensates somewhat for the absent output schema, but says nothing about result format or whether one route is ranked.

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?

One front-loaded sentence with no filler. The parenthetical list of route types is dense but each item earns its place by signaling the tool's output vocabulary; only the truncated opening ('How to change key:') is slightly awkward.

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 usefully names what the analysis returns (closeness, pivot chords, route types) and both required parameters are schema-documented. It stops short of describing ordering ('smoothest to most dramatic' is mentioned, which helps) but format/pagination details remain unspecified.

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 100%, with both from_key and to_key documented and exampled in the schema. The description implies a pair of keys but adds no format or constraint detail beyond what the schema already provides, so the baseline 3 applies.

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 states a clear purpose - computing how to change key between two keys - and enumerates the specific dimensions returned (key closeness, shared pivot chords, chord routes). It is clearly distinct from theory siblings like reharmonize or suggest_progressions, though it does not explicitly name them.

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?

Without a stated verb or scenario, usage is only implied: you would call it when planning a key change. There is no explicit when-to-use or when-not-to-use guidance relative to reharmonize, analyze_progression, or suggest_progressions, all of which live in the same harmonic-analysis neighborhood.

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

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

readOnlyHint=true already declares this as a safe read. The description adds that it surfaces preferences/plugin notes as inputs to later tasks, but says nothing about return format, matching behavior, or how topic/search/subject combine to filter. With annotations covering safety, this is an added-context-only score of 3.

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 tight sentences, front-loaded with the core action before the usage hint. No filler or repetition; only slightly terse given the undocumented parameters.

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?

No output schema and low parameter documentation mean the description must carry more, but it leaves 'subject' undefined and gives no sense of what a recall returns or how results are ranked/filtered. Adequate for a simple read tool, but with clear gaps.

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 33% – 'search' is documented in-schema but 'topic' and 'subject' are not. The description only obliquely touches two topic values ('preferences', 'plugin') and never explains what 'subject' means or how it differs from 'search'. It does not compensate for the low coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.