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

Annotations already declare non-destructive/non-idempotent/openWorld, so the safety profile is covered. The description adds real behavioral context beyond structure: explicit validation behavior ('Live enforces sample bounds, neighbor ordering, and segment BPM limits') and the unit convention for sample positions. It still doesn't describe the dry-run token lifecycle or what a plan returns, but the added constraints are 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?

Three short sentences, each load-bearing: operation, conditional parameter behavior, and validation constraints. Front-loaded with the verb and resource; 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 an 8-parameter mutation tool with no output schema, the description covers the operation model, the dry-run/apply split, and the key Live-side constraints. It stops short of clarifying prerequisites (e.g., the confirmationToken chain is documented only in the schema), but nothing critical is omitted.

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 adds little beyond the schema for individual parameters — the seconds unit is already stated in the sampleTime schema description — though 'omit sampleTime to preserve playback timing' gives mild semantic framing for that field.

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 (plan/apply) and resource (audio warp anchor/marker), and the sibling set (move_audio_warp_marker, remove_audio_warp_marker, propose_audio_transient_warp) makes the distinct add operation easy to place. An agent can tell what this tool does 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 implies the plan-then-apply workflow and when to omit sampleTime ('preserve playback timing'), which is genuine usage context. However, it never names an alternative tool or states when to use this versus move/remove/propose warp operations, so routing remains inferential.

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 cover the safety profile (destructive, non-idempotent, open-world), so the bar is lower. The description adds a real behavioral constraint that annotations cannot express: the remove action is blocked while macro mappings exist because the mapping target is not exposed, and it reports the observed count after acting.

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 that front-load the capability and then the removal guard. Slightly dense prose ('one native add/remove macro action on an exact rack') costs it a point, but nothing 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 mutating, non-idempotent tool with no output schema, the description covers the action scope, the destructive-path refusal, and the report-back behavior, with annotations carrying safety. Remaining gaps (pagination/return shape) are minor since it explicitly says it reports the observed count.

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 dryRun/confirmationToken/planHash/expectedStateVersion are all already documented in the schema. The description adds the notion of 'exact rack' and the plan-vs-invoke duality but no syntax or format detail beyond the schema, so the 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?

Names a specific verb pair (plan/add/remove) plus the exact resource (one native macro action on an exact rack) and states the outcome (report the observed count). This is clearly separable from siblings like map_rack_macro_to_parameter and rename_rack_macro 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?

Gives a concrete precondition for the destructive path: removal is refused while any macro mapping exists, with the reason (Live does not expose the affected mapping target). It does not explicitly route the agent away from sibling tools, but the when-to-use context is clear.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: the target-note output is a 'review-only absolute clip-pitch proposal,' it accounts for 'current pitch settings,' it is bounded in duration, and it operates on source rather than rendered audio. It does not describe return format or limits like the 60s window cap, but the annotation bar is already met.

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-loads the core operation on the source file over a bounded window, then layers scope limits and exclusions. Sentences are dense but each carries distinct information; the phrasing is slightly compressed to the point of opacity in places, but nothing 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?

With no output schema and 13 parameters, the description does the necessary work of scoping source-vs-rendered audio and defining the monophonic/stable precondition for the pitch proposal. It leaves the multi-flag analysis outputs (spectrogram, transients, resonance) to the schema, which is acceptable given full 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 description coverage is 100%, so all 13 parameters are documented in structured data, setting the baseline at 3. The description reinforces semantics for targetMidiNote (a proposal, not correction), channel selection, and pitch-event grouping, but adds little syntax or defaults beyond what the schema already states.

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+scope: 'Measure an exact Session or Arrangement audio clip's local source file over a bounded window.' It explicitly distinguishes itself from adjacent capabilities with 'Not rendered clip or track audio' and 'No edit or correction,' so an agent can separate it from analyze_audio_file and the various mutation tools.

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?

Clear conditions are given for the pitch path ('when the source window is stable and monophonic') and scope exclusions ('Loudness measures the source stream; channel selection applies to optional analyses'). However, it never names a concrete alternative tool (e.g., analyze_audio_file) to route between, so it stops short of explicit when-vs-which 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?

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real context beyond them: the dependency on ffmpeg/ffprobe, that the target-note result is a 'review-only whole-clip offset proposal' that 'never edits or corrects', and that it only applies to stable monophonic windows. It does not disclose cost, runtime, or failure modes on 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?

Front-loaded with the core verb and measurement list, and nearly every clause carries information (scope, exclusions, prerequisites). It is dense but a few parenthetical qualifiers could be trimmed without loss.

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 12-parameter analysis tool with no output schema, the description reasonably covers what is measured, the source-stream vs channel split, the windowing default, and the prerequisite tooling. It stops short of describing the returned structure, which matters since no output schema exists, but the enumeration of analyses largely substitutes for that.

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 carries per-parameter meaning (frames, bucket counts, defaults, window limits). The description adds only marginal semantics, mainly clarifying that channelIndex affects optional analyses rather than the loudness measurement. 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+resource ('Measure local source audio') and enumerates the distinct measurements: loudness, true peak, format, plus optional spectral/pitch/transient analyses. It distinguishes itself from Live processing and pitch correction, though it never names its closest sibling analyze_audio_clip, so an agent must infer the source-file vs clip 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?

Provides useful when-not guidance ('Not Live processing or pitch correction') and an explicit prerequisite ('Requires ffmpeg and ffprobe'). It also clarifies scoping rules ('Loudness measures the source stream; channel selection applies to optional analyses'), but gives no explicit routing between this tool and analyze_audio_clip or the other audio-analysis 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?

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral detail beyond that: sustained-note awareness, deterministic output, and a concrete enumeration of returned artifacts (candidates, inversions, Roman-numeral function, ambiguity, chromatic pitch classes).

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 with the core verb and scope front-loaded. The trailing 'Read-only' mildly duplicates the readOnlyHint annotation, but the description is otherwise free of 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?

With no output schema, the description usefully enumerates what is returned. Combined with the two fully documented params and annotation-covered safety profile, an agent has enough to invoke it correctly, though the lack of sibling differentiation 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 description coverage is 100%, so both parameters (trackId, clipId) are already documented in the schema. The description adds no syntax or usage detail for them, so the baseline 3 for full schema coverage 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?

Specific verb (Analyze) plus resource (sustained-note-aware chord events in one exact MIDI clip) and scope (against current Live key and scale). It implicitly distinguishes itself from analyze_midi_clip_scale by naming 'chord events', but never explicitly names or contrasts that sibling.

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 routing is given. The 'against the current Live key and scale' phrase supplies context for the operation but not selection guidance, and the very close sibling analyze_midi_clip_scale is left unaddressed.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral detail by specifying the exact return contents (pitch names, scale degrees, chromatic note IDs, bounded correction candidates) and reaffirms that no editing occurs. It does not cover error handling or performance, but adds substantial context beyond annotations.

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 three tight sentences, front-loading the core action, then detailing returns, and closing with a read-only reminder. Every sentence contributes useful information with no wasted words.

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 two required parameters, 100% schema coverage, and no output schema, the description adequately explains the purpose and return values. It could be more complete by noting prerequisites (e.g., current Live key/scale must be set) or how it relates to sibling analysis tools, but it is sufficient for correct 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 100%, and the schema already documents both trackId and clipId with clear descriptions. The tool description adds no additional parameter semantics, such as format constraints or interaction between parameters, 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 verb ('Analyze') and resource ('one exact MIDI clip against the current Live key and scale'), and clarifies it does not edit notes, which distinguishes it from editing siblings like correct_midi_clip_to_scale. However, it does not explicitly differentiate from the analyzing sibling analyze_midi_clip_chords.

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 explicit guidance on when to use this tool versus alternatives is provided. The description implies its purpose but does not mention related tools such as analyze_midi_clip_chords or get_midi_clip_notes, nor does it state prerequisites or exclusions.

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/idempotentHint/non-destructive, so safety is covered. The description adds scope transparency beyond that: it discloses the groove limitation and that the measurement is over stored note data, not playback. It stops short of describing return shape or handling of empty clips.

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 measurement action, then the constraint. No filler or redundant restatement of the 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?

With no output schema, the description carries more burden, and it adequately conveys what is analyzed, at what resolution, and the known limitation. An agent could still want clarity on result shape or empty/degenerate clip behavior, but nothing prevents a correct 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 coverage is 75%, so the baseline is 3. The description adds meaning beyond the schema by spelling out the three grid slots (straight16, eighthTriplet, sixteenthTriplet) and the one-to-eight-bar cycle, giving semantic context the enum alone lacks. trackId/clipId remain undocumented in the description.

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: 'Measure stored MIDI note timing offsets and velocity accents' against named grid slots over a bounded bar range. This is clearly distinguishable from sibling analyzers like analyze_midi_clip_scale and analyze_midi_clip_chords, which address pitch content rather than timing/velocity feel.

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 a real boundary condition: it reports an assigned native groove but 'cannot measure its playback effect or extract a Live Groove Pool pattern.' That implies when-not-to-use, but no alternative tool is named (e.g. a groove-pool extraction tool), so routing still requires 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?

Annotations already declare write, open-world, non-idempotent, and non-destructive traits. The description adds 'guarded deterministic', 'exact native context', and 'complete note readback', which are useful behavioral signals but remain vague.

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 little waste, but it is arguably too terse for a 15-parameter guarded workflow and does not separate plan versus apply behavior.

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 mutation tool with a nested fill object, 11 required parameters, and no output schema, the description omits the dry-run/apply workflow, confirmation token, return shape, and key parameter semantics.

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 73% and many parameters are documented in the schema, but the description adds no parameter-specific meaning beyond broad terms like deterministic and native context.

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 plan/apply a drum variation with descriptive modifiers, but 'variation' is opaque and the description does not distinguish it from sibling plan_drum_variation despite overlapping 'plan' wording.

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 is given, and it does not mention alternatives such as plan_drum_variation or explain the dry-run versus confirmation-token workflow.

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=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description usefully adds 'guarded' (confirmation workflow) and 'complete readback verification' (it validates the result), which go beyond the annotations. It does not explain whether existing notes are replaced or preserved, how expectedStateVersion conflicts behave, or the single-use nature of the token, so it remains mid-tier.

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 filler; the core operation ('chord arpeggiation') comes first and every qualifier earns its place. Nothing is redundant or padded.

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?

This is a high-complexity mutation tool with 11 parameters, a multi-step dry-run/confirmation/plan-hash workflow, and no output schema. The description mentions 'guarded' and 'readback verification' but never explains the plan → confirm → apply sequence, the role of expectedStateVersion, or what a caller must do before applying. For a tool of this complexity the description is too thin to guide correct 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 100%, so every one of the 11 parameters already carries its own documentation (gate, mode, seed, dryRun, confirmationToken, planHash, expectedStateVersion, etc.). The description only echoes 'stable native note IDs', adding no syntax or format detail beyond the schema. Baseline 3 applies 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?

The description states a specific verb+resource ('chord arpeggiation') and adds qualifiers (guarded, stable native note IDs, readback verification) that make the operation recognizable. However, it never distinguishes itself from the sibling 'plan_midi_chord_arpeggiation', and 'Plan or apply' leaves the reader unsure whether this is the planning tool or the mutating tool. Clear purpose but no sibling differentiation.

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 'Plan or apply' implies a two-phase dry-run-then-commit workflow, and 'guarded' hints at the confirmation-token guardrail, so usage is weakly implied. But there is no explicit statement of when to call this versus 'plan_midi_chord_arpeggiation', nor any prerequisite guidance (e.g., needing a prior dry run, or that the note IDs must be existing chord onsets). No exclusions are given.

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 non-read-only, non-idempotent, and non-destructive. The description adds useful behavioral context beyond them: changes are 'guarded', existing notes are preserved, and every native addition is verified. It does not explain the confirmation-token gate or state-version requirement in prose, so the additions are meaningful but partial.

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 is dense but earns its words by conveying plan/apply duality, guarding, preservation, and verification. 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 non-idempotent mutation tool with eight parameters and no output schema, the description covers intent and safety posture, and the schema covers parameters. It omits the dry-run/confirmation workflow and what a plan returns, leaving some gaps an agent would need to reconstruct from structured fields.

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 eight parameters (mode enums, dryRun semantics, planHash, confirmationToken, expectedStateVersion). The description adds no syntax or format 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?

States a specific verb and resource: it produces chord doublings (octave doubling) and can either plan or apply them. It does not explicitly distinguish itself from the sibling plan_midi_chord_doubling, so an agent must infer the plan/apply split from 'Plan or apply' plus the dryRun parameter.

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 explicit when-to-use, when-not, or alternative selection is given despite a directly competing plan_midi_chord_doubling sibling. The dry-run-then-apply workflow is only inferable from the schema's dryRun/confirmationToken fields, not stated in the description.

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=false, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: chord inversions are 'guarded' and results are confirmed via 'complete native note readback verification,' which tells the agent mutations are re-validated. It does not disclose permission needs, failure/rejection behavior, or what a stateVersion mismatch does for a 9-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 front-loaded sentence with no filler, opening on the action verb. It is efficiently sized, though arguably too terse to carry any operational detail for a 9-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?

With 100% schema coverage and no output schema, most of the operational contract lives in the schema, so the description is minimally complete. But the 'guarded' plan-then-confirm workflow across dryRun/planHash/confirmationToken and the expectedStateVersion staleness check are never described at a level that helps an agent sequence the calls.

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 9 parameters including dryRun, planHash and confirmationToken. The description adds essentially nothing parameter-specific, so the baseline 3 for a high-coverage schema 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 and resource ('Plan or apply guarded chord inversions') so the agent knows the operation. However, it does not distinguish itself from the sibling plan_midi_chord_inversion, which appears to cover the planning half of the same workflow, leaving the 'or' to be inferred from the dryRun parameter rather than the text.

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 offers no when-to-use guidance, no exclusions, and no routing to alternatives such as plan_midi_chord_inversion or apply_midi_chord_arpeggiation. 'Plan or apply' hints at two modes but never states which conditions select each one; that inference is left entirely to the schema.

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 generic flags (not read-only, not destructive, not idempotent, open-world). The description adds meaningful behavior beyond them: 'guarded' signals a confirmation/plan-hash gate, and 'complete native note readback verification' discloses a post-write verification step. It still doesn't explain what is mutated or the plan→confirm sequence.

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 filler. It is appropriately sized, though it compresses two distinct behaviors (plan and apply) into one clause without 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?

No output schema exists and there are 10 parameters including a state-version/token workflow. The description gestures at the guard and verification but does not explain the required dry-run-then-apply sequencing or what readback verification returns, leaving gaps for a complex 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 80%, so the schema already documents mode, dryRun, confirmationToken, planHash, expectedStateVersion, and noteIds. The description adds no parameter-level meaning beyond that, making the baseline 3 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 names a specific verb+resource: 'chord voice leading' with a plan/apply duality. It is clear what the tool does, though it never names the sibling plan_midi_chord_voice_leading and instead folds the planning case into the same tool via dryRun, which slightly muddies the plan-vs-apply 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?

'Plan or apply' implies the mode selection is driven by dryRun, and 'guarded' hints at the confirmation workflow, but the description gives no explicit when-to-use/when-not or reference to the alternative planning tools among the many siblings. Usage must be inferred from the schema.

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=false, destructiveHint=false, and idempotentHint=false. The description adds important behavioral context beyond annotations: the operation is 'guarded' and 'atomic', retains 'stable voices', and performs 'verified additions/removals'. This tells the agent it is a controlled mutation rather than an unchecked bulk edit.

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 definition is a single front-loaded sentence with no filler. It packs many parallel capabilities into a compact statement, though the density makes it slightly run-on. Every clause contributes a distinct capability.

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 high schema coverage and rich annotations, the description provides enough high-level context for an agent to understand the tool's role. It does not explain the two-step dry-run/apply workflow or expectedStateVersion requirements, but those are documented in the schema parameters. No output schema exists, so return-value explanation is not required.

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 93%, so the schema already documents nearly every parameter in detail. The description summarizes parameter concepts (recipes, inversions, voicing modes, slash basses) but adds no syntax, format, or constraint details beyond what the schema provides. Baseline 3 is appropriate 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?

The description states a specific verb-resource pair: planning or atomically applying functional-harmony chord rebuilding. It enumerates concrete features (per-onset functions, recipes, inversions, voicing modes, slash basses) that distinguish it from generic MIDI tools. It does not explicitly name its sibling plan_midi_diatonic_chord_quality, but the apply/plan framing makes the scope 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?

The phrase 'Plan or atomically apply' implies the dryRun workflow, but the description never states when to use this tool versus plan_midi_diatonic_chord_quality or other chord tools. It gives no explicit when-not conditions or alternative recommendations. Usage is only inferable from the parameter schema and annotations.

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=false, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds useful context beyond that: it preserves source notes and expression (i.e., adds voices rather than mutating originals) and 'guarded' implies the plan/confirm flow, but it does not mention the confirmationToken or planHash requirement that governs the real write.

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 tight sentence with the core action front-loaded and no wasted clauses. The word 'guarded' is slightly opaque jargon, which keeps it just short of ideal.

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 eight-parameter, non-idempotent write tool, the description is thin. It conveys the musical intent and that source notes are preserved, and the schema plus annotations fill in the mechanical details, but the two-phase plan/apply workflow and the meaning of 'guarded' are never explained in prose.

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 eight parameters (including degreeOffsets, dryRun, confirmationToken, expectedStateVersion) are already documented in the schema. The description adds no parameter-level detail beyond what the schema 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 specific verb pair (plan/apply) and resource (scale-aware harmony additions), which is more informative than a bare name restatement. It does not, however, name or contrast with the closely related siblings (plan_midi_diatonic_harmony, apply_midi_diatonic_transposition), so an agent cannot fully disambiguate from the text 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?

There is no explicit when-to-use or when-not-to-use guidance. The description says 'Plan or apply' but never explains the relationship to the sibling plan_midi_diatonic_harmony tool or when to prefer each, leaving routing to inference from the schema's dryRun field.

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 the safety profile (not read-only, non-idempotent, non-destructive, open-world). The description adds genuinely useful context that the operation is 'guarded' and depends on Live's current key/scale, but it does not spell out what the guard is, that notes are actually rewritten, or that the result varies with external musical state.

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 waste and the core scope stated immediately. It is arguably too terse for an 8-parameter mutation tool, 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 guarded, non-idempotent MIDI mutation with 8 parameters and no output schema, the description leaves the two-phase plan/apply lifecycle and the effect on note data entirely to the schema. Adequate but with clear gaps an agent must infer.

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 eight parameters (including dryRun, planHash, confirmationToken, scaleSteps) are documented in the schema itself. The description's references to 'scale-degree' movement and the current key/scale corroborate scaleSteps and the global-state dependency but add no syntax or format 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 (transpose) and resource (MIDI notes) with two distinguishing qualifiers: 'scale-degree' and 'bound to Live's current key and scale'. This separates it from the sibling chromatic apply_midi_transposition without needing to open the schema, 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?

'Plan or apply' hints at the two-phase dry-run/confirm workflow, and 'guarded' implies a safety gate, but the conditions for choosing plan vs apply are only encoded in the dryRun/confirmationToken schema fields, not stated here. No guidance on when to prefer this over apply_midi_transposition or plan_midi_diatonic_transposition.

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 a non-read-only, non-idempotent, non-destructive mutation. The description adds that results are 'guarded' and verified via 'complete native note readback', hinting at safety behavior, but never explains what 'guarded' means (state-version guard, confirmation token) or what gets modified. Modest value beyond annotations.

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 filler. It is efficiently sized, though 'guarded' is a vague qualifier that does not fully earn its place without explanation.

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 8-parameter, five-required mutation tool with multiple voicing/mutation siblings, the description is thin: it omits the plan-then-apply confirmation workflow this tool clearly supports and gives no differentiation from plan_midi_drop_voicing. The 100% schema coverage and annotations carry most of the load, keeping it merely adequate.

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 eight parameters including mode, dryRun, planHash and confirmationToken are self-documented. The description adds no parameter meaning, 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 and resource (apply chord drop voicings) plus a distinctive trait (guarded, note readback verification), so an agent knows what it does. However, it does not distinguish itself from the sibling plan_midi_drop_voicing, and the 'Plan or apply' phrasing blurs the plan/apply 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 'Plan or apply' wording implies dual-mode usage and the schema's dryRun param clarifies the plan/apply split, but the description never says when to use this tool versus plan_midi_drop_voicing or other voicing siblings. Guidance is inferable only from structured fields, 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 declare readOnlyHint=false and destructiveHint=false but the description adds valuable behavior: guarded per-note edits that preserve note IDs, durations and expression metadata, the dry-run/plan-vs-transfer workflow, and the rejection of groove-assigned targets. It does not cover permissions or the confirmation-token lifecycle in depth.

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?

Four compact sentences, each earning its place, with the core purpose front-loaded. Slightly dense but 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 10-parameter tool with nested template objects and no output schema, the description covers the key behavioral constraints (planning vs applying, audio-vs-MIDI limits, preservation guarantees, groove rejection). It could say more about the expectedStateVersion/planHash flow, but the essentials are present.

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 already 90%, so baseline is 3, but the description adds non-obvious semantics tying template type to parameter values (audio feel requires velocityAmount zero because audio strength is not MIDI velocity) and clarifies timingAmount/velocityAmount as blend amounts.

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 (plan or transfer) and resource (a stored-MIDI feel template or measured audio feel summary) applied to exact target note IDs. It explicitly distinguishes itself from Live Groove Pool baking and implies its relationship to save/load/analyze feel-template siblings.

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 when-to-use conditions: MIDI templates support timing+velocity blends, while audio feel is timing-only and forces velocityAmount zero. It also states a rejection condition (target with an assigned native groove). It stops short of naming alternative tools to use instead.

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 the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true). The description adds real value by promising that onset, pitch, velocity, probability and expression metadata are preserved, i.e. only gate durations change, and the word 'guarded' hints at the dry-run/token safety gate. It does not state reversibility, state-version conflicts, or failure behavior beyond what the schema's confirmationToken/dryRun fields imply.

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 filler, putting the verb and resource first and the preservation guarantee second. It is dense but every clause carries information; the only mild cost is that the attribute-preservation list makes the sentence long.

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 a fully documented schema and annotations covering the safety profile, the description is adequate but incomplete: it never resolves the overlap with plan_midi_gate_pattern despite the name implying apply-only, and it omits how the plan-hash/confirmation-token workflow invalidates on state change.

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 every parameter including dryRun, planHash, confirmationToken and expectedStateVersion is already documented. The description adds only the general notion of 'gate durations' and does not clarify semantics such as how gateRatios map to ordered noteIds or how gridBeats interacts with them; 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 ('plan or apply') and resource ('MIDI gate durations') and further scopes it by naming the attributes preserved. It is distinguishable from siblings like apply_midi_velocity_curve or apply_midi_ratchet_pattern, though it never names its closest sibling plan_midi_gate_pattern, whose relationship is left 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?

No when-to-use guidance is given. The description does not explain when to use this dual plan/apply tool versus the dedicated plan_midi_gate_pattern sibling, nor when to omit dryRun versus pass false, nor any preconditions. Everything about invocation flow has to be inferred from the schema.

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=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful context by saying the operation is 'guarded' and preserves pitch, timing, velocity, mute, and expression metadata, but it does not explain the guarded confirmation flow or idempotency implications beyond what annotations imply.

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 front-loaded sentence with zero wasted words. It efficiently covers the tool's dual purpose and its preservation guarantees.

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 8-parameter tool with a two-step guarded workflow, expected state versioning, and no output schema, the one-sentence description is thin. The schema covers parameter details fully, so an agent can reconstruct the workflow, but the description itself does not explain the plan/apply flow or the role of state versions.

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 8 parameters are fully documented in the input schema, including dryRun, planHash, confirmationToken, and expectedStateVersion. The description adds no parameter syntax or meaning beyond what the schema already provides, making the baseline 3 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 ('plan or apply') and resource ('guarded MIDI playback probabilities') with a clear preservation scope. It does not explicitly name or differentiate from the sibling plan_midi_probability_pattern, though the dual-mode wording hints at the relationship. An agent can tell what the tool does, but sibling routing is left 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 provides no when-to-use guidance, no conditions for choosing between planning and applying, and no mention of alternatives such as the plan-only sibling. Any usage workflow must be inferred entirely from schema parameters like dryRun and confirmationToken.

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=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is largely covered. The description adds useful preservation semantics for velocity, probability, mute, release velocity, and velocity deviation, but omits mutation guardrails, token requirements, and version-check 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?

It is a single, front-loaded sentence with no wasted text. However, the term 'guarded' is undefined and the sentence carries little operational detail.

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?

This is a complex tool with 10 parameters, 7 required fields, no output schema, and a dryRun/planHash/confirmationToken two-step workflow. The description omits the guarded apply workflow, token handling, and expectedStateVersion semantics, leaving significant gaps for correct 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 100%, so every parameter is documented in the schema itself. The description does not add syntax or workflow meaning 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 and resource: planning/applying MIDI ratchets. The phrase 'Plan or apply' is informative, but it does not explicitly distinguish this tool from the sibling plan_midi_ratchet_pattern or from other apply_midi_* tools.

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 when-to-use guidance, no conditions for choosing plan vs apply, and no mention of the dryRun/confirmation-token workflow. It does not name the sibling plan_midi_ratchet_pattern or say when this tool is preferable.

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 establish a non-readonly, non-idempotent, non-destructive, open-world mutation. The description adds genuinely useful context beyond that: the operation is 'guarded' (confirming the dry-run/confirmation-token gating) and provides 'complete native readback', which is valuable since there is no output schema. It does not, however, detail reversibility or stateVersion consequences.

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 waste, covering the plan/apply duality and the key behavioral traits. It is dense and jargon-heavy ('complete native readback') but not padded.

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 with a confirmation-token guard and no output schema, the description is minimal. The readback hint and 'guarded' note help, but the dry-run/confirm workflow and interaction with expectedStateVersion are left entirely to the schema, so it is only adequately 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 parameters are already documented (including mode, dryRun, confirmationToken, planHash). The description echoes 'optional bass voice leading' (mode=voice_leading) but adds no syntax or format detail beyond the schema. Baseline 3 applies 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 pair (plan/apply) and resource (scale-aware chord remapping) with scope details (guarded, optional bass voice leading). It is clear what the tool does, though it never explicitly names the sibling plan_midi_scale_chord_remapping to explain the difference between this and the pure planner.

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?

'Plan or apply' implies the dryRun branching, so usage is somewhat inferable, but there is no explicit when-to-use/when-not guidance and no mention of the alternative planning tools (plan_midi_scale_chord_remapping, plan_midi_chord_voice_leading) the agent should consider 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?

Annotations already declare the write/guard profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds real value beyond that by stating what is preserved (pitch, velocity, probability, mute, release velocity, velocity deviation) and that the operation is 'guarded', telling the agent the mutation is scoped to onset timing rather than note content.

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 core action front-loaded and no filler. It earns its place, though 'Plan or apply' is slightly ambiguous phrasing that could be tightened.

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 9 parameters, no output schema, and annotations present, the description covers purpose and preservation semantics but leaves the plan-vs-apply route to sibling tools and the guard/confirmation workflow entirely to the schema. Adequate but with a clear routing gap given the near-identical plan_midi_strum_pattern sibling.

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 every parameter (including the dryRun/confirmationToken/planHash guard flow and direction/spreadBeats semantics) is already documented in the schema. The description adds no parameter-level detail beyond the schema baseline.

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+resource (apply chord strumming) and the guarded plan/apply duality. However, it does not differentiate itself from the sibling plan_midi_strum_pattern, so an agent must still infer which of the two strum tools to pick.

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 says nothing about when to choose this tool over plan_midi_strum_pattern, apply_midi_chord_arpeggiation, or the other apply_* MIDI tools. The plan-vs-apply distinction is only hinted at via the dryRun parameter in the schema, with no explicit guidance in the description.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the description only needs to add context. 'Guarded' and 'complete native readback verification' add some signal beyond annotations, but neither is explained (what the guard is, what verification returns, reversibility) 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, front-loaded sentence with no filler. It is appropriately sized, though 'complete native readback verification' is dense jargon that would benefit from a brief plain-language gloss.

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 8-parameter mutation tool with no output schema, the description is adequate but thin: it omits the confirmation-token flow, failure modes, and whether partial transformations are rolled back. The fully-described schema compensates for much of this, keeping it at minimum viable rather than broken.

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 8 parameters including dryRun, planHash and confirmationToken. The description adds essentially no parameter-level meaning beyond the word 'chromatic', 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 (transposition) and resource (chromatic MIDI notes) and the 'chromatic' qualifier implicitly distinguishes it from the diatonic sibling apply_midi_diatonic_transposition. It also signals the plan-or-apply duality, but it never names a sibling explicitly, which is what a 5 requires.

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 'Plan or apply' hints at the two-phase workflow and that a planning mode exists, but it gives no explicit when-to-use guidance, no condition selecting this over plan_midi_transposition or the diatonic variant, and no statement of prerequisites. Usage 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?

Annotations already declare a non-read-only, non-destructive, non-idempotent mutation, so the bar is lower. The description adds real value by stating exactly which attributes survive unchanged (timing, pitch, duration, probability, expression), which is a meaningful write-side guarantee beyond the annotations.

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 filler that packs the scope, the mode, and the preservation guarantee. Nothing is redundant.

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 guarded two-phase mutation tool with no output schema, the description omits any mention of the confirm-with-token workflow, the state-version precondition, or error behavior. The schema covers these, so the definition is adequate but not self-sufficient for safe 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 100%, so every parameter including dryRun, planHash, and confirmationToken is already documented. The description adds no parameter-level detail beyond the schema, 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+resource (apply a MIDI velocity curve) and captures the dual plan/apply nature with 'Plan or apply'. However it never names the plan_midi_velocity_curve sibling, so an agent gains only implicit differentiation from that near-identical tool.

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 'guarded' framing and 'plan or apply' implies a dry-run-first workflow, but the description never says when to use this versus plan_midi_velocity_curve. The actual dry-run/confirm mechanics live only in the schema, leaving usage guidance 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?

Annotations only declare safety/idempotency flags; the description goes well beyond, disclosing the two-phase plan-then-confirm flow, SHA-256 source hashing, binding to current clip state, native pitch readback verification, the 60-second length cap, and the stereo-channel-agreement requirement. That is rich behavioral context an agent needs before invoking a 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?

Three dense sentences with no filler: purpose+constraints first, mechanism/verification second, exclusions last. Front-loaded and every clause carries information, though the middle sentence is packed tightly enough to slow reading.

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 no-output-schema, 7-parameter mutation tool, the description covers the preconditions, safety flow, and scope limits that an agent needs. It does not describe the plan/result shape, but with no output schema that is only a minor residual 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 description coverage is 100%, so every parameter (clipId, dryRun, planHash, confirmationToken, targetMidiNote, expectedStateVersion, trackId) is already self-documented. The description hints at the plan/confirm relationship but adds no per-parameter syntax or format detail beyond the schema, so the 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 (plan/apply) and resource (Live clip coarse/fine pitch offset) with a clear scope qualifier: full-source monophonic analysis of a local source. An agent can tell it apart from MIDI-oriented siblings like apply_midi_transposition or MIDI plan_* 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 delimits when the tool applies (whole-clip tuning of a stable monophonic source up to 60s) and explicitly rules out adjacent cases: note-by-note vocal correction, rendered audio analysis, and audible validation. It lacks an explicit named-alternative pointer, but the exclusions do the routing work.

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 declare a non-readonly, non-idempotent mutation, and the description's 'Plan or set' hints at a two-phase dry-run/commit flow beyond what annotations state. However, it omits the optimistic-concurrency requirement, reversibility, and the confirmation-token lifecycle that the schema parameters imply.

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 waste, and the 'Plan or set' phrasing efficiently surfaces the two-phase nature. It is arguably too terse for the tool's complexity, but nothing is padded.

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?

This is a mutation tool with a non-trivial confirmation workflow (planHash, short-lived single-use confirmationToken, expectedStateVersion concurrency guard) and no output schema. The description does not explain the required dry-run-then-commit sequence, leaving the agent to reverse-engineer the protocol from parameter names.

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 six parameters including dryRun, planHash, and confirmationToken. The description adds no parameter-level meaning beyond it, matching the baseline for fully covered 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 ('arm') and resource ('record-arm state') with a scoping qualifier ('one exact track'). It clearly implies track-arming rather than clip or transport operations, though it doesn't name any sibling to distinguish itself from.

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. Nothing tells the agent it must run a dry run before committing, or which alternative to prefer for arming multiple tracks or arming via mixer settings.

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 readOnly/openWorld/idempotent/non-destructive, so the bar is lower, yet the description still adds real behavior: symlinks and non-audio files are skipped, results are paged, and metadata (tags/favorites) is joined optionally. It does not describe ordering or what an empty page means, but this is well beyond the annotation baseline.

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?

Four tight sentences, front-loaded with the core action, then optional metadata, then how to chain into search, then exclusions. No filler and every sentence carries distinct information.

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 paged local-directory listing with no output schema, the description covers scope, paging, optional metadata, and skips, which is enough to invoke correctly. It leaves the shape of returned entries (file vs folder fields) unspecified, which is a minor gap given no output schema exists.

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 limit/offset defaults and rootPath semantics documented in the schema itself. The description echoes the optional metadata join and paging behavior but adds no new parameter-level detail (e.g., ordering, offset stability), 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 ('Page through') and resource ('immediate subfolders and audio files inside a configured local Splice root'), scoping it to immediate children rather than recursive search. This clearly separates it from siblings like search_local_splice_samples and list_local_splice_roots.

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 actionable context: 'Returned folder paths can be searched individually when a broad search is truncated,' which tells the agent how this tool composes with search. It also names explicit exclusions ('not Splice cloud browsing, downloads, or license verification'). It stops short of naming a specific sibling alternative for those excluded cases, 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 already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuine value beyond that: the result is 'persistable JSON' and explicitly excludes hidden plugin state, samples, automation, and mappings, which tells the agent what it will NOT get back.

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, no filler, with the core action front-loaded and the exclusions trailing. The first sentence is dense with an enumeration, but every listed item is a real captured element 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 read-only capture tool with a single documented parameter and no output schema, the description conveys output format (persistable JSON), content coverage, and exclusions. Only the relationship to sibling capture/save/load tools remains implicit.

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?

Single parameter with 100% schema description coverage, so the schema already documents trackId (track-N/return-N/master). 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?

Names a specific verb (capture) and resource (device chain snapshot) and enumerates the concrete contents captured: ordered devices, nested rack topology, exposed parameters, mixer state, chain mixer, drum rack routing, pad mute/solo. This is far more than a tautology. It does not, however, explicitly distinguish itself from close siblings like capture_device_parameter_snapshot or capture_track_state_snapshot, so the agent must infer 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 second sentence supplies scope boundaries ('Not a native rack or preset; excludes hidden plugin state, samples, automation, and mappings'), which is useful negative guidance. But there is no positive when-to-use statement and no naming of alternatives among the save/load/recall/capture siblings, leaving selection 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?

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description adds real behavioral value by disclosing a 'consistent live identity check' and the categories of state it deliberately excludes (hidden plugin state, samples, automation, mappings), which the annotations do not 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 tight sentences with the primary action front-loaded and the exclusion caveat following. No filler, though the second sentence is somewhat dense and could be split for scanability.

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 more burden for the returned JSON. It notes the payload is 'persistable' and lists exclusions, but does not describe the structure or fields of the captured snapshot, leaving a modest gap for a capture 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 100% with only 2 params, and the schema descriptions already explain the trackId and deviceId formats (track-N, return-N, master, list_devices). The description adds no additional parameter semantics, so 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+resource ('Capture exposed device parameters as persistable JSON') and clarifies it is not a native preset. It distinguishes itself from the sibling recall_device_parameter_snapshot by verb, though it does not explicitly address capture_device_chain_snapshot.

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 says what the tool excludes (hidden plugin state, samples, automation, mappings) but never states when to use it versus alternatives such as capture_device_chain_snapshot, list_device_parameters, or save_device_parameter_snapshot-style tools. No when/when-not guidance is given.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior the annotations don't convey: the consistency requirement that all track snapshots and the final hierarchy must match one state version, plus an explicit exclusion list of what is not captured (clips, samples, plug-in state, automation, mappings).

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 dense sentences, front-loaded with the action and scope, then the exclusion list. No filler; every clause adds a constraint an agent needs.

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 signal the return shape, which it does ('persistable JSON'). With annotations covering safety and the parameter schema complete, the definition is nearly self-sufficient; only sibling differentiation and explicit when-to-use routing are 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 coverage is 100% and the single busTrackId parameter is fully documented ('Stable track ID returned by list_tracks'), so the schema carries the semantics. The description adds nothing about the parameter beyond implying the target is an existing Group Track. 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 (capture) and resource (Group Track plus nested groups and descendant tracks) with an ordering constraint ('in Live order') and output format ('persistable JSON'). It does not distinguish itself from close siblings like save_group_system_snapshot, load_group_system_snapshot, or recall_group_system_snapshot, so an agent must check those separately.

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 clarifies scope of capture ('Read-only; does not save clips, samples, hidden plug-in state, automation or mappings, or create/recall tracks'), which implies this is the in-memory snapshot step before saving. However, it never states when to use this versus save_group_system_snapshot or recall_group_system_snapshot, leaving the choice 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?

Adds substantial behavior beyond the annotations: the target is chosen by Live and may create or change clips across multiple MIDI tracks or add a scene, so the effect is non-deterministic and multi-target. It also discloses the readiness requirement and what is reported back (immediate slot changes, note count/digest changes), which is exactly the extra context an agent needs for a non-idempotent open-world 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?

Four sentences, front-loaded with the action and scope, then risk, reporting, and prerequisites. Dense but each sentence carries distinct information; 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 complex, non-idempotent, open-world mutation with no output schema, the description covers effects, uncertainty of target, return shape, and readiness/confirmation prerequisites. An agent can plan or invoke this correctly without further inference.

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 (dryRun, planHash, confirmationToken, expectedStateVersion) are already documented. The description only echoes the plan/confirm distinction, adding no syntax or format 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?

States a specific verb (plan/invoke) plus the exact resource (Live's native Capture MIDI into Session View) and the input scope (recently played MIDI on audible tracks). No sibling tool performs Capture MIDI, so the definition is self-distinguishing without needing to name a competitor.

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 for invocation ('recently played MIDI on audible tracks') and states a prerequisite ('native can_capture_midi readiness and confirmation'), plus routes note inspection to a separate tool. It does not name specific alternatives or exclusions, so it falls 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?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context by specifying that the snapshot is 'one consistent, persistable JSON' and by scoping exactly what state is included vs excluded — useful for predicting the result of a read 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 tightly packed sentences with the core action and scope front-loaded and exclusions trailing. The enumeration is dense but each item earns its place by defining scope; slightly long but not wasteful.

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 effectively serves as a return-value contract by listing the captured state, and the exclusion list prevents over-expectation. Only the relationship to the save/load/recall sibling tools is left implicit.

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 trackId parameter is fully documented in the schema ('Stable track ID returned by list_tracks'). The description adds no parameter detail, so the 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 (capture) and resource (track state snapshot), then enumerates exactly what the snapshot contains (group membership, mixer, routing, devices, rack params, drum routing) and what it omits. This lets an agent distinguish it from save/load/recall variants 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?

The 'Not a native track preset' note and the explicit exclusion list imply when this tool fits, but there is no explicit routing to alternatives such as save_track_state_snapshot or capture_device_chain_snapshot, nor any stated prerequisite beyond a valid trackId.

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 declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, but the description adds genuinely non-obvious behavior: the claim is atomic, and it does NOT load the plugin or save a file. That side-effect boundary is useful context beyond the annotations. It does not disclose lease duration or expiry, which would have pushed it higher.

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 with the core action front-loaded and the return value plus side-effect boundary second. No filler; every clause carries information.

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 explains the return ("its catalog preset"). It is largely complete for the claim action, though it omits the lease lifecycle (duration/expiry, requirement to heartbeat or complete), which matters given the sibling tools around this workflow.

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 workerId and productSlug are already documented in the schema; the description adds no semantics beyond them. Baseline 3 applies when the schema carries the parameter documentation.

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?

It states a specific verb ("lease") and resource ("NKS generation job") with clear scope ("one pending"). It does not explicitly name the sibling alternatives it overlaps with (get_nks_generation_job, enqueue_nks_generation_jobs), so separation from those 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 phrase "for a worker" implies the caller is a job-consuming worker, but there is no explicit when/when-not, no mention of what to do after claiming (heartbeat/complete/fail), and no named alternative to route to. Guidance is only weakly 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, readOnlyHint=false, and idempotentHint=false, so the mutation/non-idempotent profile is covered. The description adds the meaningful evidence precondition (the job's preset must contain verified saved artifacts), but stops short of saying what completing does to the job or artifacts, or whether the state change is reversible.

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 with no waste; the state precondition is front-loaded and the scope exclusion ("does not generate or validate") follows 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 mutating lifecycle tool with full annotations and a fully documented two-parameter schema and no output schema, the description covers the key gate (verified evidence) and scope exclusions. It is largely complete, with only minor gaps around post-completion state or failure 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 description coverage is 100%, so both presetId and workerId are already documented in the schema as a stable catalog ID and a lease owner identity. The description adds no format, ownership, or lease semantics beyond what the schema provides, 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+resource ("Mark an owned NKS job done") and clarifies scope with "Does not generate or validate the artifact itself." It clearly separates itself from generation/validation concerns, though it does not name the sibling lifecycle tools (fail_nks_generation_job, heartbeat_nks_generation_job) it could be confused 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?

Gives an explicit precondition for invocation: "only after its catalog preset contains verified saved-artifact evidence." This is a clear when-to-use condition. However, it names no alternative tools and gives no when-not guidance beyond the single precondition.

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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true). The description adds real behavioral context beyond that: the operation is 'guarded' (plan then apply), it only touches chromatic notes, existing in-scale notes 'are never changed', and equal-nearest cases require an explicit tie break. It does not detail the confirmation-token lifecycle, but that 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?

Three tight sentences with the core purpose front-loaded, followed by the direction/tie-break constraint and the non-destructive guarantee. Every sentence earns its place, though the third sentence is a slight restatement of the guard already implied by the first.

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 mutating, open-world tool with no output schema, the description conveys the operation, its scope constraints, and the guarded plan/apply nature, while the schema covers the confirmation workflow. Missing is explicit mention of the dry-run/confirmationToken handshake and the stateVersion precondition, but those are schema-documented.

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 89% schema description coverage, the schema already documents all nine parameters, including tieBreak 'Required only for equal nearest choices'. The description largely restates those enum semantics rather than adding new meaning, 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 specific verb and resource ('guarded pitch correction of exact chromatic MIDI notes') plus the scope ('into the current Live scale'), which cleanly separates it from siblings like analyze_midi_clip_scale (read-only analysis) and apply_midi_diatonic_transposition. An agent can identify the operation and its target 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?

The 'Plan or apply' phrasing signals the dual dry-run/commit mode and 'Direction is explicit; equal nearest choices require an explicit tie break' gives concrete conditions for the direction and tieBreak inputs. It stops short of naming alternatives (e.g. analyze_midi_clip_scale, apply_midi_diatonic_transposition) or stating exclusions, so it is clear context but not full routing 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?

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is largely covered. The description adds the plan/create duality beyond the annotations, but omits the two-phase confirmation-token workflow, the expectedStateVersion conflict behavior, and any reversibility note — meaningful gaps for a mutating 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 efficient sentence with no filler, front-loading the verb and resource. It is arguably over-brief for a six-parameter, two-phase workflow tool, but no sentence 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 six-parameter mutation tool with no output schema, the minimal description is only adequate because the schema compensates with 100% parameter coverage. The crucial plan-then-confirm interplay between dryRun, planHash, and confirmationToken is left to the agent to infer from individual field docs.

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 every parameter (including dryRun, planHash, and confirmationToken) is already documented in the schema. The description only restates the position semantics ('exact beat position'), adding nothing beyond the schema baseline.

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 ('Plan or create') and resource ('Arrangement cue point') with a scope qualifier ('exact beat position'). The create semantics are clearly separable from siblings like rename_arrangement_cue_point, delete_arrangement_cue_point, and list_arrangement_cue_points, 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?

No when-to-use guidance is given. The description hints at a plan-vs-create duality but never says when to plan (dryRun), when to commit, or that committing requires a confirmationToken from a prior dry run.

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 flag a non-read-only, non-idempotent, open-world mutation, but the description adds real value beyond them: the two-phase plan/confirm model, the fact that the confirmed plan binds source identity, size, and modification time, and that Live validates the audio format. It does not mention reversibility or failure modes, but the added context 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?

Two dense sentences with the core action and its scope constraints front-loaded and no wasted wording. The second sentence adds only genuinely non-obvious behavioral detail.

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 8-parameter mutation tool with no output schema, the plan/confirm lifecycle and validation behavior are covered, and annotations carry the safety profile. Minor gaps remain around what a caller should do on validation failure or how the plan result is shaped, but the essentials for correct invocation are present.

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 every parameter (including dryRun, planHash, confirmationToken) is already documented in the schema. The description adds no syntax or format detail beyond that; 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 and resource ('Plan or import a local audio file') plus tight scope constraints ('one exact empty Session slot on an unfrozen audio track'), which implicitly separates it from create_midi_clip and the arrangement-clip tools. It stops short of naming any sibling, so differentiation relies on inference rather than explicit contrast.

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 plan-then-import workflow is implied by 'Plan or import' and reinforced by the dryRun/confirmationToken parameters, but the description never says when to choose this over alternatives (e.g., analyze_audio_file first, or create_midi_clip) nor states prerequisites like the track being unfrozen beyond the scope phrase. Usage must be inferred.

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 non-read-only, non-idempotent, non-destructive. The description adds real behavioral context beyond that: it binds meter/tempo/grid/destination and a state version, and notes that native execution verifies every generated note. It does not spell out the dry-run/confirmationToken gating, but the schema covers that.

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 with the core action front-loaded and the secondary behavioral note (state binding + native verification) after. No filler or repetition 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 an 11-parameter mutation tool with no output schema, the description covers purpose, precondition, the state-binding model, and result verification. The remaining gaps (the plan/confirm protocol details) are handled by the schema's parameter descriptions, so the definition is largely self-sufficient.

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 82% and the schema itself documents the significant parameters (dryRun, confirmationToken, planHash, expectedStateVersion, nested lane fields). The description's mention of meter, tempo, grid, lanes, destination, and state loosely maps to the parameters but adds no syntax or format detail 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 set ('plan or create'), a specific resource ('multi-lane drum pattern'), and the target container ('empty Session clip'). It is clear what the tool does, though it does not explicitly distinguish itself from close siblings like plan_drum_pattern or edit_drum_pattern_clip.

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 'in an empty Session clip' implies a precondition, and 'Plan or create' hints at the two-phase workflow. However, there is no explicit when-to-use guidance versus plan_drum_pattern (planning only) or edit_drum_pattern_clip (editing an existing pattern), which an agent would want spelled out given the crowded sibling set.

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=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that deletion is not exposed via the public API. But it omits the two-step dry-run/confirmation-token workflow that governs how a create actually happens, leaving that entirely to 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 tight sentences with the core action front-loaded and the sibling pointer plus limitation trailing. No filler, though the plan/create ambiguity could have been resolved in the same 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 annotations covering the safety profile, full schema coverage on five parameters, and no output schema required, the description supplies the scope and sibling routing an agent needs. The main residual gap — explicitly summarizing the dry-run-then-confirm flow — is mitigated by richer schema descriptions.

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 dryRun, planHash, confirmationToken, and expectedStateVersion are fully documented in the schema; that sets the baseline at 3. The description adds only that the name is optional, no syntax or workflow detail beyond 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?

The description states a specific verb and resource (create a groove in Live's Groove Pool) and distinguishes scope by noting the optional name and the deferral of tuning to set_groove. It is clearly separable from siblings like set_groove and get_clip_groove_context, though the 'Plan or create' duality is left for the schema to disambiguate.

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 routes the agent to set_groove for post-creation adjustment and rules out deletion, which is useful negative guidance. However, it gives no explicit when-to-use context versus other creation tools (e.g., create_midi_clip, create_scale_chord_progression_clip) and no prerequisite framing.

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 declare the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=true), and the description is consistent with them while adding one genuine precondition: the target slot must be exactly empty. However, it omits the entire dry-run/confirm lifecycle, including that the token is short-lived and single-use, which is the most behaviorally important thing about this 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 scope constraint front-loaded and zero filler. It is efficient, though the terseness borders on under-specification for a nine-parameter mutation 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 nine-parameter, non-idempotent mutation tool with no output schema, the description is barely a fragment. It omits the plan→confirm flow, token validity, and why expectedStateVersion must be observed immediately before planning, leaving the agent to reverse-engineer the workflow from parameter descriptions.

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 nine parameters, including expectedStateVersion, dryRun, planHash, and confirmationToken. The description adds no parameter meaning beyond the empty-slot constraint, 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?

Names a specific verb pair ('Plan or create') and resource ('MIDI clip') with a scoping constraint ('exact empty Session slot'). An agent can tell this is a MIDI clip creator, but the description does nothing to separate it from siblings like create_scale_melody_clip, create_drum_pattern_clip, or create_audio_clip, all of which also create clips.

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 'Plan or create' faintly implies a two-mode workflow, but the description never states when to plan vs. when to commit, never mentions the confirmationToken/planHash handshake, and names no alternative tool. An agent gets no routing guidance beyond the bare verb.

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 this is a non-read-only, non-idempotent, non-destructive, open-world mutation, so the safety profile is covered. The description adds a bit of context (planning vs. committing, append-on-omitted-index), but does not explain what state is altered or the confirmation-token requirement beyond what the schema states.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with the core action, and every clause (nested racks, omitted index appends, drum-pad separate) carries distinct information. 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 an 8-param mutation with annotations and no output schema, the description covers the key conceptual points (plan vs. create, track scope, append behavior). It stops short of describing the plan/commit round-trip result or any prerequisites, but it is largely sufficient for correct 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 coverage is 88%, so the schema carries most parameter meaning, giving a baseline of 3. The description adds genuine value by documenting the append-on-omission behavior of the undescribed 'index' parameter, pushing it slightly above baseline.

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 ('create a named empty chain in an exact rack') with scope details (ordinary/Return/Main track, nested racks). It is clearly distinguishable from siblings like rename_rack_chain, set_rack_chain_mixer, and set_rack_chain_note_routing.

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 'Plan or create' phrasing implies the dry-run/confirm flow, and 'Drum-pad assignment is separate' lightly routes the agent away from a sibling behavior. But there is no explicit when-to-use, when-not-to-use, or named alternative, leaving usage mostly inferred.

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 the safety profile (non-read-only, non-destructive, non-idempotent, open-world). The description adds behavior beyond that: Live auto-prefixes the displayed return letter and the result reports the observed display name, which is a naming side-effect an agent cannot get from annotations or 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 tight sentences, front-loaded with the action and scope, with only the naming caveat following. No filler, though it is brief enough to leave the commit flow to the schema.

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 a dry-run/confirm-token two-step flow, the description covers the naming outcome but never mentions the plan-then-commit sequencing, ordering/letter-assignment effects, or state-version requirements, relying entirely on the schema for those.

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 documents all five parameters including the raw-label meaning of 'name' and the dryRun/confirmationToken flow. The description restates the name-prefix semantics rather than adding new parameter 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 and resource ('Plan or append a Return Track') and its purpose ('shared send effects'), and clarifies it uses Live's native bus API. It is clear, though it does not explicitly differentiate itself from close siblings such as route_tracks_to_return_bus or create_track.

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 'Plan or append' implies a two-mode workflow, and the schema's dryRun description carries the actual when-to-use detail. The description itself offers no explicit guidance on when to choose this tool over routing or track-creation 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?

Annotations already declare non-read-only, non-destructive, non-idempotent, open-world, so the safety profile is covered. The description adds real context beyond that – 'native execution verifies every generated note' and the empty-clip requirement – but omits the two-step dryRun/confirmationToken/planHash workflow, which is the tool's most important behavioral nuance.

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 dense sentences with the operation and scope front-loaded and no filler. Slightly jargon-heavy ('Binds the Live key... state version') but each clause carries information.

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 17-parameter mutation tool with no output schema, the description conveys purpose, scope, and verification but leaves the critical plan/confirm token flow entirely to the schema. Adequate minimum viable, with a clear gap given the tool's complexity.

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 76%, so the schema documents most of the 17 parameters. The description names the bound dimensions (key, progression, rhythm, register, destination, state version), giving a useful mental model, but 'key' is not actually a parameter and no format or coupling details are added 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 ('create one scale-aware bassline') plus a scope constraint ('in an exact empty Session clip'), and the 'Plan or create' phrasing signals it also covers the dry-run path. It does not name the adjacent plan_scale_bassline / create_scale_melody_clip siblings, so routing still requires 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 'exact empty Session clip' precondition is useful implied guidance on when the tool is applicable. However, it never states when to prefer this over plan_scale_bassline (plan-only) or create_scale_melody_clip, leaving the agent to infer the choice from the name.

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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lowered. The description adds genuine extra context: that native execution independently rederives signed harmony and verifies every note, and that the target clip must be empty. It doesn't spell out the token/single-use flow, which is left to 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 no filler; the create/plan distinction and the verification guarantee are both front-loaded. Every clause carries information.

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 19-parameter, 12-required tool with nested objects and no output schema, the description is thin: it omits the dry-run/confirmation-token workflow and any explanation of the harmonic-function or articulation options. The schema carries most of the burden, but the description could do more for such a complex 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?

With 19 parameters and only 68% schema description coverage, the description adds no parameter-level meaning beyond what the schema provides. Key concepts like degrees, harmonicFunctions, voiceLeading, and chordRecipes are only explained in the schema itself, so this is a baseline adequate score.

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 pair ('Plan or create') and resource ('functional scale-degree chord progression'), plus a scope constraint ('one exact empty Session clip'). This distinguishes it from the pure-planning sibling plan_scale_chord_progression, 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?

'Plan or create' hints at the dry-run vs execute duality, and the schema's dryRun/confirmationToken params fill in the mechanics. But there is no explicit when-to-use guidance or comparison against plan_scale_chord_progression or create_midi_clip, leaving the choice 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?

Annotations already establish non-read-only, non-idempotent, non-destructive behavior. The description usefully adds that key/meter/grid/destination/state are bound and that 'native execution verifies every generated note,' plus the implicit dry-run gate from its plan/create framing — meaningful context beyond the structured hints, though it omits reversibility and failure 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?

Two sentences, front-loaded with the action and target, with no filler. The second sentence is information-dense but has no waste; it could still be slightly clearer about the plan→confirm sequence.

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 16-parameter, 13-required mutation tool with no output schema, the description is thin: it never explains that a dry run yields planHash/confirmationToken, that expectedStateVersion must match, or what verification returns. The schema covers parameters, but the workflow an agent must follow to actually create the clip is left largely unexplained.

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 69%, so most parameters carry their own docs. The phrase 'Binds Live key, meter, grid, destination, and state' gestures at some parameters but adds no semantics for the 16 params, notably the planHash/confirmationToken/expectedStateVersion workflow, so it does not compensate for the remaining gap.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb pair and resource ('plan or create one exact scale-degree melody') plus the target context ('empty Session clip'), which distinguishes it from write-only siblings like create_midi_clip. It does not, however, explicitly name the closest sibling (plan_scale_melody) or the other scale-clip creators, so the differentiation is implied rather than stated.

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 implies when the tool applies via 'in an empty Session clip' and the plan-vs-create modality of dryRun, which is useful context. But it never tells the agent when to prefer this over plan_scale_melody or create_scale_bassline_clip, nor what happens if the clip is not empty, leaving usage largely inferable.

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=false, destructiveHint=false, openWorldHint=true, and idempotentHint=false. The description adds meaningful behavioral context beyond those annotations: native execution rechecks neighboring scene records, verifies the new scene, and completes in one Live undo step. It does not cover authorization or rate limits, but the added validation and undo details are 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?

The description consists of two tightly written sentences with no filler. The core purpose and most important behavioral detail are front-loaded, and every sentence contributes useful information.

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 dry-run and confirmation-token mechanics, the description covers the core dual mode, exact insertion index, native revalidation, and atomic undo behavior. The schema provides the remaining parameter details, and annotations cover the safety profile. It could say more about expectedStateVersion, but the schema already defines that requirement.

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. The description only alludes to the index parameter ('exact insertion index') and dry-run mode ('Plan or create'); it does not add meaning for expectedStateVersion, planHash, or confirmationToken beyond what the schema provides. A 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 and resource: 'Plan or create a Session scene at an exact insertion index.' This clearly identifies the operation and scope. It does not explicitly differentiate itself from sibling tools such as launch_scene, list_scenes, or other create_* tools, so it falls 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 description does not say when to use this tool versus alternatives like list_scenes, launch_scene, or delete_session_object. It implies a plan/create mode through the phrase 'Plan or create,' but provides no conditions, prerequisites, or exclusions to guide selection.

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 declare the safety profile (not read-only, not idempotent, not destructive, open-world), and the description adds genuinely new behavioral context: native execution rechecks neighboring track context, verifies the inserted track type and name, and does so in a single Live undo step. That undo/verification detail is exactly the kind of trait 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 tight sentences with no filler, and the core verb/resource is front-loaded before the behavioral detail. Slightly dense in the second sentence, but every clause carries information.

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 output schema, the description covers the planning/execution duality and the undo semantics well, and the schema handles the token/version mechanics. It does not describe what a dry run returns, but that gap is modest given the schema's parameter-level hints.

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 71%, with descriptions on name, dryRun, planHash, confirmationToken, and expectedStateVersion. The description only adds the notion of an 'exact insertion index' for the index parameter, which is marginal beyond the schema's minimum:0 constraint. Baseline 3 is appropriate when the schema does most of the work.

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 and resource ('Plan or create an audio or MIDI track') plus the scoping detail 'at an exact insertion index'. This clearly separates it from siblings like create_return_track, create_midi_clip, and create_scene, which an agent can distinguish without opening 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?

The phrase 'Plan or create' implies a two-mode workflow, but the description never says when to plan versus when to execute, nor points to the dryRun/confirmationToken parameters that govern this. The guidance is implied rather than explicit, so the agent must read the schema to learn the actual 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?

Annotations already declare destructive=true, readOnly=false, idempotent=false, so safety context is covered. The description adds genuinely non-obvious behavior: preview reports loop interval vs start/end markers, Live may retain pre-loop playback material, a new processed source is created, and the selected interval is not a guarantee of exclusive source-file bounds.

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 opening sentence is front-loaded and specific, but later sentences are dense and jargon-heavy ('Binds audio and loop state and reads back native results') and 'in current units' is left undefined, costing clarity without adding proportionate value.

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, 6 params, and a destructive mutation, the description covers mode behavior and source-file caveats reasonably well. It still omits practical concerns like undo/reversibility and what the native result looks like, which an agent performing a destructive crop would want.

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 every parameter is already documented in-schema. The description adds no per-parameter syntax or format detail beyond that; 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 clear verb (crop) and an exact resource (one audio clip), with a plan/apply duality. It never names a sibling tool, but 'crop' is distinctive enough against the surrounding edit_session_object/audio tools that an agent can place 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 phrase 'Plan or apply' implies two modes but gives no explicit when-to-use, prerequisites, or alternatives. The routing logic (dryRun/confirmationToken/planHash) lives only in the schema, not the prose.

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 non-idempotent, so the safety profile is covered. The description adds genuinely new behavior: deletion is undoable in Live, other timeline material is preserved, and a confirmation step is required — useful context beyond the structured hints.

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, correctly front-loaded with the action and scope, then prerequisites. No wasted text.

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 tool with a plan/confirm protocol, the description conveys the intent, scope and confirmability, and the schema covers the mechanics. It could better spell out the plan→confirm→execute sequence, but the essential information an agent needs is present.

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 clipId, trackId, dryRun, planHash, confirmationToken and expectedStateVersion. The description references identity and confirmation but adds no syntax or format detail beyond the schema. 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 action (plan or delete) on a specific resource (one exact Arrangement clip) and adds the scope constraint 'preserving other timeline material'. This distinguishes it from generic delete_clip, 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?

Specifies the prerequisites for use ('Requires current clip identity and confirmation') and reveals that the operation is a two-phase plan-then-confirm flow. It does not, however, state when to prefer this over delete_clip or delete_session_object.

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