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

Annotations already declare this is a destructive mutation, and the description adds important behavioral context: Live enforces sample bounds, neighbor ordering, and segment BPM limits. It also distinguishes planning from applying via the first sentence, though it does not fully detail the confirmation-token workflow or what is irreversibly changed.

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 tightly written sentences with no waste. The core purpose is front-loaded, followed by practical parameter guidance and then validation constraints.

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 the presence of an output schema, full parameter descriptions, and destructive annotations, the description covers the key action, sampleTime semantics, and Live-enforced constraints. It could be slightly richer about the plan-vs-apply token flow, but the structured fields already carry that detail.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema provides the baseline parameter documentation. The description adds meaning beyond the schema by explaining that omitting sampleTime preserves playback timing and that explicit sample positions are in seconds, which clarifies the most semantically important optional parameter.

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 apply an audio warp anchor." It is clear what the tool does and implies its dual plan/apply nature, though it does not explicitly distinguish itself from siblings like move_audio_warp_marker or remove_audio_warp_marker.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives parameter behavior (omit sampleTime to preserve playback timing) but does not state when to use this tool versus alternatives such as move_audio_warp_marker, remove_audio_warp_marker, or quantize_audio_clip. There are no explicit when-not conditions or prerequisite 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 destructive=true, readOnly=false and idempotent=false, so the safety profile is covered. The description earns credit on top by disclosing the removal precondition and its underlying reason (Live does not expose the affected mapping target) plus the fact that the result reports an observed count — context the 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 zero filler: the action and its post-condition come first, the constraint and its rationale second. Every clause adds 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?

An output schema exists, so return format need not be explained, and schema coverage is complete. What is missing is any framing of the dryRun → planHash/confirmationToken → execute sequence and expectedStateVersion staleness handling across the two calls, which matters for a non-idempotent multi-step mutation.

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 seven parameters including the action enum, dryRun, planHash and confirmationToken are already documented, giving baseline 3. The description adds only the 'exact rack' scoping nuance and none of the optimistic-concurrency semantics behind expectedStateVersion, so it does not exceed the 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?

The description names a specific verb pair (add/remove) on a specific resource (native rack macro count) scoped to 'an exact rack', and adds a post-condition ('report the observed count'). It does not name the adjacent siblings (rename_rack_macro, map_rack_macro_to_parameter, randomize_rack_macros) that an agent might confuse it with, so it stops short of full 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?

'Plan or invoke' hints at the dryRun-then-execute workflow without stating which mode to use first or how planHash/confirmationToken flow. The one real exclusion is given clearly ('Removal is refused while any macro mapping exists'), which is valuable, but no alternative tool is named for the case where a mapping must be handled 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?

Goes well beyond the annotations by enumerating exactly what is bound (notes, timing, devices, routing, topology), what is NOT touched (tracks, notes, mutes, playback), restore semantics (adoption-time mutes rather than an unknown baseline), and hard refusal conditions. This is unusually rich behavioral context; the destructiveHint=true annotation is consistent with creating persistent handle state even though musical content is unchanged.

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 purpose and each subsequent sentence adds a distinct behavioral fact (persistence, binding scope, restore semantics, refusals, limitations). Dense and jargon-heavy but largely waste-free.

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, multi-step tool the description covers behavior, prerequisites and refusals well, and an output schema exists so return values need not be explained. The notable gap is the missing explanation of the plan→dryRun→token execution flow, which matters 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 67%, and the description adds only the mapping that the two targets are 'explicitly chosen existing MIDI parts'; it does not clarify the dryRun/planHash/confirmationToken plan-and-confirm workflow or expectedStateVersion. Baseline 3 is appropriate since the schema carries most parameter meaning.

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

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

States a specific verb+resource: 'Plan or bind a new runtime comparison handle to two explicitly chosen existing MIDI parts,' which is precise and actionable. It clarifies persistence ('including after restart'), but it never names the sibling comparison tools (prepare_/select_/get_instrument_comparison), so an agent cannot disambiguate the family from the description 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?

Provides concrete when-not conditions ('Refuses active pairs, recording, solo, live-input conflicts and two unmuted tracks') and scope notes ('Does not prove historical identity or matching copies'). It gives real context for when this is applicable, but stops short of naming an alternative tool or stating the plan-vs-bind selection path against 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?

Goes well beyond the annotations: 'optimistic revision checks' discloses the concurrency contract, 'apply retains original dry-run and confirmation guards' discloses the mutation safeguards, and 'Interrupted execution is never replayed' explains the non-idempotency that idempotentHint=false only implies. It does not spell out auth/permission requirements or what destructive effects actually occur.

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 purpose, then a dense sequence of action-specific clauses, each carrying distinct information with no filler. The single-run-on style makes it slightly hard to scan 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 12-parameter destructive mutation with only 42% schema coverage, the description covers the action semantics and key safety traits well, and the output schema removes the need to explain returns. However, the unexplained 'feedback' action and undocumented revision/decision/token parameters leave gaps an agent must guess at.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 42%, so the description should carry more load. It does define six of the seven action enum values in prose (useful, since the schema gives no description for 'action'), but it omits the 'feedback' action entirely and says nothing about expectedRevision, expectedStateVersion, decision, planHash, or confirmationToken. Partial compensation only.

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 ('Advance one durable session phase') and immediately qualifies it with the concurrency model ('optimistic revision checks'). An agent can tell this is the phase-progression driver of a session workflow, distinct from start_/get_production_session. It does not name a sibling explicitly, so it falls short of 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 routes the agent across the action enum, giving a condition for each: propose for a bounded specialist, choose for a saved alternative, resume for inspection of fresh state, replan for a new proposal, evaluate for completion. This is genuine when-to-use guidance. It lacks explicit when-not-to-use framing against sibling session tools.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so credit goes to what is added: muted material is included, loop repeats and trimmed clip boundaries are reflected, and size caps are implied via the schema. 'No focus changes' and the exclusion list are genuinely behavioral context 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?

Front-loaded with scope first, then output content, then the optional flag, then exclusions. It is dense and slightly telegraphic in places ('projected stored-MIDI tonal evidence with loop repeats and trimmed boundaries'), but nearly every clause 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?

With an output schema present, the description needn't explain return shape, and it focuses on scope, exclusions, and the optional harmony mode. What an agent needs to call it correctly is essentially present; only explicit guidance on the fallback tool for excluded material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description still adds meaning: includeHarmony is characterized as literal chord candidates plus gaps and ambiguity, and the evidence is described as projected stored MIDI. It does not add syntax for startBeats/endBeats or trackIds 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?

Opens with a specific verb+resource+scope: 'Read one explicit Arrangement beat window across all or selected ordinary tracks.' It then names its outputs (overlapping clips, projected stored-MIDI tonal evidence) and explicitly contrasts itself against adjacent analyses ('Not playback, a detected key, or a meter/key map'), which separates it from siblings like analyze_midi_parts and get_midi_clip_notes.

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 inclusion/exclusion rules: includes muted material, excludes audio, drums, recording and large clips, and states that includeHarmony is what unlocks timed pitch sets and chord candidates. It stops short of naming the sibling to use instead when the window is audio or drums, so the agent knows what not to expect but not where to go.

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 read-only, idempotent, non-destructive behavior, so the bar for additional disclosure is lower. The description still adds meaningful context: loudness uses the source stream, optional analyses use the selected channel, results are approximate/review-only, and rendered clip/track audio is excluded.

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 front-loaded with the core action and then adds only relevant qualifiers. Three sentences carry purpose, limitations, and stream/channel behavior without obvious 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?

Given the tool's complexity, the rich input schema, annotations, and output schema, the description covers the key behavioral boundaries an agent needs. The main remaining gap is explicit alternative-selection guidance rather than return-value or schema detail.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3 even without description-level parameter detail. The description adds useful cross-parameter meaning, especially that a target note proposes absolute clip pitch accounting for current pitch settings and only applies to stable monophonic windows.

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: measure a Session or Arrangement clip's local source window, with optional note events. It clearly distinguishes this from rendered clip/track audio, but it does not explicitly differentiate itself from nearby analysis siblings such as analyze_audio_file or compare_audio_reference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by constraints such as 'review only,' 'no edits or correction,' and 'Excludes rendered clip/track audio.' However, it does not explicitly say when to choose this tool over alternatives or name the sibling tools it should replace.

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 safe-read profile (readOnly, idempotent, non-destructive). The description adds genuinely new behavior: requires ffmpeg/ffprobe, loudness is measured on the source stream while optional analyses follow channelIndex, and pitch/offset output is advisory with no correction of moving notes.

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?

Dense but front-loaded: the measurement scope comes first, then caveats and the dependency. Dense and telegraphic in places 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?

With an output schema present, return values need not be explained; annotations cover safety. The description supplies the dependency requirement, channel semantics, and the analytical limits an agent needs to invoke this 12-param tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: it links targetMidiNote to a review-only whole-clip offset, and clarifies why channelIndex exists (optional analyses only, loudness stays on source).

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

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

Opens with a specific verb (Measure) and enumerates the resources (loudness, true peak, format, spectrum, spectrogram, pitch, note events) on a local source file. 'Excludes Live processing' and 'local source' implicitly separate it from Live-object siblings like analyze_audio_clip, though no sibling is named.

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?

Explains that the target-note output is review-only and limited to stable monophonic windows, and clarifies the source-stream vs selected-channel split. It gives constraints but never states when to choose this over analyze_audio_clip or analyze_midi_parts.

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, and the description reinforces this with 'without editing notes. Read-only.' Beyond that it adds genuinely useful behavior: 'sustained-note-aware' handling, 'deterministic' output, and dependence on the current Live key/scale context. It stops short of disclosing edge cases (empty clips, non-chordal material).

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 zero filler; the core purpose leads and the return contents plus read-only guarantee follow. No wasted clauses.

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?

An output schema exists, so return values need not be spelled out, yet the description helpfully previews the result shape (candidates, inversions, Roman-numeral function, ambiguity, pitch classes). Combined with 100% schema coverage and full annotation set, nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both trackId and clipId (including the list_clips/list_arrangement_clips ID provenance) are already documented in the schema. The description adds no further meaning about the parameters, 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 (analyze) and resource (chord events in one exact MIDI clip) and clarifies it runs against the current Live key and scale. The chord-focused framing clearly separates it from sibling analyzers like analyze_midi_clip_scale and analyze_midi_parts without needing 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?

Usage is implied: it is a read-only analysis tool that does not edit notes. However, it never states when to choose this over closely related siblings such as analyze_midi_clip_scale or analyze_midi_feel, nor any prerequisites, so the agent must infer the situation.

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 'without editing notes. Read-only.' largely restates them. The one piece of genuine added context is that results depend on the current Live key/scale and that correction candidates are 'bounded', hinting at a cap the agent should expect.

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

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

Two compact sentences with the core action front-loaded and the read-only guarantee trailing as a qualifier. The final 'Read-only.' is slightly redundant given annotations and costs a few words, but nothing else 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 a full output schema and complete annotations, the description only needs to flag the state dependency on the current Live key/scale — which it does — and it does so in a single clip scoped tool. Missing only a note on what happens if no scale is set or how many candidates the bound caps.

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 both parameters (clipId, trackId) are documented in-schema down to their source tools. The description's only contribution is 'one exact MIDI clip', reinforcing that a single clip is targeted rather than a range, 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 with scope ('Analyze one exact MIDI clip against the current Live key and scale'). The key/scale framing implicitly separates it from sibling analyzers like analyze_midi_clip_chords and analyze_midi_feel, but 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?

Usage is only implied: it is clearly the inspection step that precedes correct_midi_clip_to_scale or the plan_midi_diatonic_* family, but the description never says when to choose this over analyze_midi_clip_chords or get_midi_clip_notes, nor does it state any 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 carry readOnly, idempotent, non-destructive and closed-world, and the description reinforces 'Read-only' consistently. It adds genuine value beyond the annotations by clarifying the scope boundary that 'assigned native groove playback is not measured or extracted', which is not derivable from the structured fields.

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

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

Three compact clauses front-load the core action, then defaults, then the read-only/scope caveat. Every segment carries information and nothing is repeated from the schema or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need not be described, and annotations cover the safety profile; the description supplies scope, defaults, and the crucial stored-vs-native-groove exclusion. The only gap is the absence of guidance on choosing this tool over its analysis siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 83% schema coverage the baseline is 3, but the description meaningfully synthesizes several parameters: the 1-8 bar range, optional exact notes (noteIds), and cycle origin (originBeats), plus defaults. The grid enum values are left to the schema, which is fine, though no extra semantic detail is added there.

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 (measure) and resource (stored MIDI timing/velocity) scoped by grid slot and clip-meter bar range, which is far more precise than a tautology. It does not name or differentiate itself from close siblings such as analyze_midi_parts or analyze_midi_clip_scale, leaving the agent to infer which analysis applies.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the analysis context ('stored MIDI', 'beat zero' default) and scopes out native groove playback, but never states when to reach for this tool versus alternatives like get_clip_groove_context or inspect_clip_groove_postconditions. Usage is inferrable from the scope statement rather than explicit.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description adds substantive context beyond them — the analysis outputs (per-part register, duration-weighted pitch classes, combined diatonic compatibility) and the hard input restrictions (audio/drums/recording/oversized excluded, loop/marker ranges only). "No edits or focus changes" largely restates readOnlyHint but reinforces it rather than contradicting.

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 dense sentences, front-loaded with the core action and followed by output summary, exclusions, and safety note. Every sentence carries information, though the final "No edits or focus changes" is mildly redundant against the annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be spelled out, and annotations cover the safety profile. The description fills the remaining gaps — scope, exclusions, and analysis nature — leaving only minor omissions like pagination/size behavior, which is already bounded by the schema's note 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 coverage is 100% and the single `parts` parameter is fully documented in the schema itself. The description's "1-8 explicit clips" mirrors the schema's minItems/maxItems rather than adding new syntax or format detail, so the 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-plus-resource ("Read 1-8 explicit Session/Arrangement clips together... Report per-part register, duration-weighted pitch classes and combined diatonic compatibility") that distinguishes it from single-clip analyzers like analyze_midi_clip_scale or analyze_midi_clip_chords. It also explicitly excludes adjacent scopes ("not simultaneous playback or detected key"), so an agent can tell what this tool is not.

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 and exclusions: "Loop/marker ranges only," "Audio, drums, recording and oversized clips are excluded explicitly." It does not name a sibling alternative by name (e.g. analyze_midi_clip_scale for one clip), so routing between tools is left partly 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 destructive=true, idempotent=false, readOnly=false, so safety is covered. The description adds that this is a two-phase 'plan or apply' operation and that it is 'guarded', implying state-version/token checks, but never states what gets mutated, what the guard rejects, or what 'readback' returns.

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 restatement of the tool name. It is efficient, though 'exact native context and complete note readback' reads as padding that displaces more useful 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?

For a 15-parameter, 11-required, nested-object, destructive mutation with an output schema, this one-liner is far too thin. It omits the plan/confirm handshake mechanics (expectedStateVersion, planHash, confirmationToken), what 'guarded' protects against, and any indication of failure or partial-application 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?

At 73% schema coverage the schema documents most parameters (seed, timingAmount, velocityAmount, preserveAccentsAbove, confirmationToken, planHash, dryRun), so baseline is 3. The description adds no meaning beyond those labels and does nothing to compensate for the ~27% undocumented surface.

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 verb+resource ('apply ... drum variation') and hints at scope ('deterministic', 'guarded'), but the qualifiers 'exact native context' and 'complete note readback' are opaque jargon. It fails to distinguish from the sibling plan_drum_variation, with which 'Plan or apply' creates overlap.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use, when-not, or prerequisite guidance. The key routing decision – dryRun plan vs. token-based apply – is left entirely to the schema, and the near-identically named sibling plan_drum_variation is never addressed.

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, idempotent=false and non-readonly, so the safety profile is known; the description adds genuine context on top: the operation is 'guarded', it relies on stable native note IDs, and it performs complete readback verification after mutation. It stops short of saying what exactly is destroyed (note start times/pitches rewritten) or how failure/rollback behaves.

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

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

A single sentence with no filler, front-loading the verb and the guarded/verified nature of the operation. It is dense 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 an 11-parameter destructive mutation with an output schema, the description covers the safety posture and verification but omits the mechanics of the plan/execute handshake (dryRun → planHash + confirmationToken) and the optimistic-concurrency role of expectedStateVersion. Adequate but leaves an agent to infer the workflow order from the schema alone.

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 is already documented, and the description adds little parameter-level meaning beyond echoing 'stable native note IDs' for noteIds. 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?

States a specific verb ('Plan or apply') and resource ('chord arpeggiation') plus the key invariant of stable native note IDs, which is concrete enough to act on. It does not, however, explicitly distinguish itself from the sibling plan_midi_chord_arpeggiation or other apply_midi_* siblings, leaving the plan-vs-apply routing implicit in the word 'or'.

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' and 'guarded' imply a two-phase preview-then-commit flow, and the presence of dryRun/planHash/confirmationToken in the schema supports that reading. But the description never says when to choose this over plan_midi_chord_arpeggiation, nor does it state any prerequisite (e.g. that a plan must be obtained first, or that notes must form complete chord onsets).

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, non-idempotent, non-read-only, so safety is covered. The description adds value by saying existing notes are preserved and every native addition is verified, but it omits the guarded two-step token/stateVersion contract that a destructive mutation demands.

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

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

A single front-loaded sentence with no wasted words. It is efficient, though the brevity contributes to the missing workflow guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a rich 8-param schema and an output schema, the factual surface is well covered by structured fields. What remains unexplained is the plan-vs-execute flow and how expectedStateVersion, planHash, and confirmationToken sequence together, which matters for a destructive 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 per-parameter descriptions and an enum on mode, so the description need not re-document them. It adds nothing beyond the schema, making 3 the appropriate 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?

The verb (plan/apply) and resource (chord doublings) are named, but the phrasing 'Plan or apply' blurs the split with the sibling plan_midi_chord_doubling, leaving the agent unclear on whether this is the executor or the planner. A specific action is conveyed but sibling differentiation is weak.

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, when-not, or routing to alternatives such as plan_midi_chord_doubling or the other apply_midi_* transforms. The dryRun/plan-token workflow, which decides whether this mutates or only plans, is never described.

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 readOnlyHint=false, so the mutation risk is covered. The description adds useful context with 'guarded' and 'complete native note readback verification,' but it does not explain what the guard entails, such as confirmation tokens, plan hashes, or state-version requirements.

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

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

The description is a single front-loaded sentence with no filler. It is efficient, though the 'Plan or apply' phrasing is slightly ambiguous and could be clarified without adding much length.

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?

An output schema exists, so the description need not explain return values, and annotations cover the destructive nature. However, for a complex destructive mutation with 9 parameters and token/hash workflow, the description does not sufficiently convey the plan-then-apply workflow or the role of expectedStateVersion.

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 input schema already documents all parameters in detail. The description does not add parameter-level meaning beyond what the schema provides, so the baseline score 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?

The description names a specific verb and resource: applying guarded chord inversions. It is clear what the tool does at a high level, but it does not differentiate itself from the sibling plan_midi_chord_inversion tool or explain why it says 'Plan or apply.'

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 that the tool supports a dry-run planning mode and an execution mode, but it gives no explicit conditions for choosing this tool over plan_midi_chord_inversion. There is no stated when-to-use or when-not-to-use 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 declare destructiveHint=true and non-idempotent behavior, and the description adds that the operation is "guarded" and includes native note readback verification. It does not explain what is overwritten, how confirmation tokens or expectedStateVersion protect the operation, or the practical consequences of a non-dry run.

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

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

A single compact sentence with the core purpose front-loaded and no filler. It is efficient, though the phrase "guarded" is doing vague work 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?

Output schema and annotations cover return format and safety profile, and 80% of parameters are documented. For a destructive, state-versioned, 10-parameter mutation tool, the description still omits the critical plan-then-apply workflow and the role of readback verification.

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 most parameters already carry documentation and the baseline is 3. The description adds no parameter-specific meaning, such as how noteIds, minPitch/maxPitch, or the planHash/confirmationToken pair should be used.

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 voice leading," plus the verification behavior. It does not distinguish itself from the sibling plan_midi_chord_voice_leading, despite both "plan" and "apply" appearing in the description.

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?

Mentions "Plan or apply" and the schema has a dryRun parameter, so the planning/execution split is implied. However, it never explicitly says when to use this tool versus plan_midi_chord_voice_leading or when to go through the dry-run/confirm 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 destructive=true, readOnly=false and idempotent=false, so safety is largely covered. The description adds genuine value beyond that: atomicity ("atomically apply"), a guard/verification step ("verified additions/removals"), and preservation of untouched material ("stable retained voices"). It stops short of stating permission or failure/precondition 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 sentence with the action front-loaded, and nothing is repeated. The feature enumeration is dense and reads more as a keyword list than prose, which slightly hurts scanability, but there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need not be explained, and annotations cover the destructive profile. For a 15-parameter, 6-required guarded mutation, though, the description never explains the plan/apply verification flow (expectedStateVersion, planHash, confirmationToken) or its relation to the plan_ sibling tool, leaving the agent to reconstruct the workflow from the schema alone.

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. The description's enumeration (per-onset functions, recipes, inversions, voicing modes, slash basses) maps onto harmonicFunctions, chordSize/chordSizes, inversions, voicingModes and bassDegrees but adds little syntax or semantics 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 clear verb pair ("Plan or atomically apply") and a specific resource ("functional-harmony chord rebuilding"), so an agent knows it edits chord qualities rather than the harmony/transposition siblings. It does not, however, distinguish itself from close siblings like plan_midi_diatonic_chord_quality, apply_midi_diatonic_harmony, or apply_midi_scale_chord_remapping, and terms like "guarded" and "rebuilding" remain jargon.

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" hints at a two-phase dry-run/commit workflow, but the description gives no explicit when-to-use conditions, prerequisites, or pointer to an alternative sibling. The agent is left to infer which tool handles which harmony scenario.

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 destructiveHint=true and non-idempotent, so the description's job is supplementary. It adds real value by stating the operation is 'guarded' and that source notes and expression are preserved, which tells an agent the mutation is additive and state-version-checked rather than a rewrite.

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; 'guarded' and the preservation clause both earn their place. It is efficient, though a brief clause on the plan/apply split would have been worth the extra 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?

Annotations and an output schema cover safety and returns, but the description omits the two-phase planning protocol (dryRun, planHash, confirmationToken, expectedStateVersion) that is central to invoking this tool correctly. For an 8-parameter destructive tool, that is a real 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 is already documented in the schema (degreeOffsets, noteIds, planHash, confirmationToken). The description adds no syntax or constraint detail beyond the schema, which is the expected baseline when the schema carries the load.

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 apply') and resource ('scale-aware harmony additions'), which is enough to distinguish it from generic transposition or chord tools. It does not explicitly name plan_midi_diatonic_harmony as the planning-only sibling, so the plan-vs-apply duality is only hinted at.

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 workflow, but the description never states when to use dryRun versus execute, or that a planHash/confirmationToken from planning is required for apply. 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 disclose destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds that the operation is 'guarded' and bound to Live's current key and scale, but it does not explain what the guard protects, what gets mutated, or how plan tokens/state versions affect 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?

The description is a single front-loaded sentence with no filler. It conveys the core operation and scope efficiently, even if other dimensions need more 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?

Given a rich schema with full parameter descriptions, an output schema, and destructive/idempotency annotations, the description does not need to repeat return values or parameter details. It is nearly complete but remains terse about the guarded plan/apply workflow for a destructive operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all eight parameters, including scaleSteps, dryRun, confirmationToken, and planHash. The description reinforces the scale-degree/key-scale context but does not add parameter semantics beyond what the schema provides.

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 operation: 'Plan or apply' a 'scale-degree MIDI transposition' 'bound to Live's current key and scale.' This distinguishes it from generic transposition and from purely planning tools, though it does not explicitly name the sibling alternatives.

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 dry-run versus execution modes, and 'guarded' implies a safe workflow, but the description does not state when to use this tool versus plan_midi_diatonic_transposition, apply_midi_transposition, or other siblings. Usage is implied rather than explicitly guided.

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, and the description adds real context beyond them: the confirmation-token/hash guard implied by 'guarded' and post-write verification via 'complete native note readback'. It stops short of saying what happens to the original notes or whether the edit 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?

A single front-loaded sentence with no filler, but terms like 'guarded' and 'native note readback verification' are dense jargon that would benefit from one clarifying clause rather than standing alone.

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?

An output schema exists, so return-value explanation is unnecessary, and the plan/apply guard is mentioned. However, for a destructive mutation of MIDI notes across eight parameters, the description omits what the operation replaces or removes and what the dry-run output contains, leaving meaningful gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter including mode, dryRun, planHash, confirmationToken, and noteIds is already documented in the schema. The description adds no syntax or constraint detail 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?

States a specific verb+resource ('apply ... chord drop voicings') and adds two distinguishing traits: guarded execution and native note readback verification. It does not name the closely related sibling plan_midi_drop_voicing, so the boundary between 'plan' and 'apply' is left implicit even though the description opens with 'Plan or apply'.

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' plus the dryRun parameter implies a two-phase workflow, but the description never states when to prefer this over plan_midi_drop_voicing, nor what preconditions (complete chord onsets, stable note IDs) must hold before calling. Usage is inferable rather than stated.

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

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

Beyond the annotations, the description discloses that edits are guarded per-note operations, preserve note IDs/durations/expression metadata, and reject targets with a native groove. It also distinguishes MIDI timing+velocity behavior from audio timing-only behavior, which is meaningful behavioral context for a destructive 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?

The description is front-loaded with the core action, then adds constraints and behavioral notes in four dense, relevant sentences. Every sentence contributes to correct selection or invocation, with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the high schema coverage, output schema, and annotations, the description covers the major behavioral and selection concerns: MIDI vs audio feel, preservation guarantees, native-groove rejection, and non-groove-pool scope. It does not explicitly explain the dryRun/planHash/confirmationToken execution flow, but those details are documented in the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is high at 91%, so the baseline is 3. The description adds useful meaning by explaining that MIDI templates support timing and velocity blends, audio feel is timing-only, and velocityAmount must be zero for audio summaries, directly clarifying key parameter behavior beyond the schema descriptions.

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

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

The description gives a specific verb/resource/action: transferring or planning a stored-MIDI feel template or audio feel summary onto exact target note IDs. It explicitly distinguishes the operation from Live Groove Pool baking and from targets with a native groove, so an agent can tell what this tool is for without opening sibling schemas.

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 states when to use the tool: applying MIDI or audio feel templates to target notes, with the important audio-specific rule that velocityAmount must be zero. It also states when not to use it: targets with an assigned native groove and groove-pool baking. It does not name the specific sibling tools for measuring or saving templates, but the intended usage 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 flag this as destructive, non-idempotent, non-read-only, so the safety bar is partly met. The description adds real value by specifying that only gate durations are altered and onset/pitch/velocity/probability/expression are preserved — an important blast-radius statement. However 'guarded' is never unpacked: nothing about the expectedStateVersion conflict behavior, the single-use confirmation token, or whether a partial application can occur.

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 repetition, and the preservation clause is the most useful piece of information in it. 'Guarded' is the one soft word that does not pay rent on its own.

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?

An output schema exists, so return values need not be explained, and the schema covers parameters. What is missing is the operational context of a destructive, state-version-checked mutation: the plan-then-apply contract that the presence of planHash and confirmationToken implies. For a 9-parameter destructive tool this leaves a meaningful 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 all nine parameters are already documented inline (gridBeats, gateRatios, noteIds, dryRun, planHash, confirmationToken, expectedStateVersion). The description adds no extra semantics about how gridBeats and gateRatios interact or how noteIds must align to onsets. Baseline 3 applies when the schema carries the load.

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-phrase and resource: setting MIDI gate durations, with the added qualifier that other note attributes (onset, pitch, velocity, probability, expression) are left intact. It never mentions plan_midi_gate_pattern, which is a sibling with a nearly identical name, so an agent cannot tell from this description alone why 'Plan or apply' lives here rather than there.

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 a two-mode flow but never says when to use dryRun/planHash/confirmationToken or when to prefer the dedicated plan_midi_gate_pattern sibling. No prerequisites, no exclusions, no statement of what happens if you call it without a plan token.

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, idempotentHint=false, and openWorldHint=false, so the mutation risk is covered by structured data. The description does add real value by disclosing that all other note attributes are preserved, and 'guarded' hints at the state-version/token safeguard. It omits the two-phase plan→apply contract, the single-use confirmation token, and that the operation is irreversible.

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 resource and preservation scope front-loaded; nothing is padded. The only weakness is that bundling 'Plan or apply' into one phrase creates ambiguity rather than saving 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?

Wait — recalibrating: this is a destructive mutation with eight parameters, an output schema, and a required two-phase plan/apply protocol using expectedStateVersion, planHash, and confirmationToken. The description never explains that protocol, which an agent must know to invoke it successfully. That gap keeps it at 3.

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, and expectedStateVersion are documented in the schema. The description only reinforces the meaning of `probabilities` implicitly through the preservation list; it adds no semantic 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 and resource: 'Plan or apply guarded MIDI playback probabilities.' The preservation clause (pitch, timing, velocity, mute, expression) narrows exactly what is and isn't touched. It never names or distinguishes itself from the sibling plan_midi_probability_pattern, which is confusing given the description itself says 'Plan or apply'.

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 statement of when to use this tool versus plan_midi_probability_pattern or the other apply_midi_* siblings, and no guidance on when to run with dryRun=false. The only hint is the ambiguous 'Plan or apply' phrasing, which conflates the two phases an agent must choose between.

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 and idempotent=false, so the safety profile is covered. The description adds real value by naming what is preserved (velocity, probability, mute, release velocity, velocity deviation), but omits the guarded plan-then-apply flow that a destructive tool should disclose.

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 spends its one clause on preservation while omitting the more decision-critical plan/execute distinction.

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?

An output schema exists so return values need not be explained, but for a destructive 10-parameter mutation tool the description is thin: it never explains the dryRun/planHash/confirmationToken safety sequence that an agent must follow to avoid an unintended write.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all ten parameters are already documented in the schema. The description adds no syntax, format, or relationship detail beyond that, which is the correct 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 ('Plan or apply') and resource ('guarded MIDI ratchets') plus the properties preserved. However, the 'Plan or apply' phrasing collides with the sibling plan_midi_ratchet_pattern, leaving the boundary between the two tools unclear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no prerequisites, and no routing to the sibling plan_midi_ratchet_pattern despite the description literally claiming to also 'plan'. The dry-run vs execute workflow implied by the dryRun/planHash/confirmationToken params is not surfaced.

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 disclose that the operation is destructive, non-idempotent, and not read-only. The description adds 'guarded' and 'complete native readback,' but does not explain what is guarded, what state is changed, or how confirmation tokens and state versions protect the 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?

The definition is a single front-loaded sentence with no wasted text. Its compression contributes to the ambiguity around plan versus apply, but it remains efficiently structured.

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 a rich schema, output schema, and destructive annotations, the description only needs to carry the high-level workflow. It gives a useful summary but leaves the critical plan/apply/confirmation flow implicit, which is a meaningful gap for a destructive tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter is already documented in the schema. The description mentions voice leading and scale awareness, but does not add syntax or usage details beyond what the parameter descriptions provide.

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

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

The description names a specific musical resource and transformation: scale-aware chord remapping with optional bass voice leading. It is clear enough to identify the tool's general function, but it does not distinguish this apply tool from the sibling plan_midi_scale_chord_remapping 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?

It says 'Plan or apply,' which hints at dry-run versus execution, but gives no explicit conditions for choosing between planning, dry-run, and destructive apply. It also does not mention the sibling plan tool or prerequisites for a real mutation.

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, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds that pitch, velocity, probability, mute, release velocity, and velocity deviation are preserved during the operation, which is useful context, but it does not explain what 'guarded' means or what exactly gets modified.

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 no wasted words. However, the phrase 'Plan or apply' is slightly ambiguous in a tool named apply_midi_strum_pattern and could be tightened for a clearer distinction from the planning sibling.

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 the tool's complexity (9 parameters, state versioning, token-based execution, output schema), the description is thin. The schema and annotations carry much of the load, but the description omits workflow guidance (plan-then-apply, dryRun semantics) and does not clarify what 'guarded' entails, leaving the agent to infer critical usage details.

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 every parameter, including dryRun, expectedStateVersion, planHash, and confirmationToken. The description does not add meaning beyond the schema for any of these 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?

The description states a specific verb pair ('Plan or apply') and resource ('chord strumming'), making the core purpose clear. It does not explicitly differentiate this tool from the sibling plan_midi_strum_pattern, leaving some ambiguity about which tool handles pure planning versus execution.

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 guidance on when to use this tool versus the sibling plan_midi_strum_pattern or when to set dryRun to true. The phrase 'Plan or apply' implies both modes exist but does not tell the agent which conditions select one over the other.

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

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

The annotation already declares destructiveHint=true and readOnlyHint=false, so the safety profile is clear. The description adds useful context with 'guarded' and 'complete native readback verification', but it does not state what is mutated, whether changes are reversible, or how the confirmation token and expected state version protect the 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?

The description is a single front-loaded sentence with no wasted language. It conveys the core purpose and verification behavior 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?

The output schema exists, so return values need not be explained, and the annotations carry the destructive safety profile. However, for a guarded plan/apply workflow with confirmation tokens, plan hashes, and expected state versions, the description should say more about the dry-run-to-apply sequence and what 'guarded' entails.

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 are documented in the input schema. The description adds no parameter-level meaning beyond the schema, which is the baseline expectation when the schema is this complete.

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

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

The description names a specific verb and resource: guarded chromatic MIDI transposition with native readback verification. It is clear what the tool does, but it does not distinguish this apply tool from the sibling plan_midi_transposition, and the phrase 'Plan or apply' blurs that boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no explicit guidance on when to use this tool versus plan_midi_transposition or apply_midi_diatonic_transposition, nor does it explain prerequisites such as when a dry run is required. Any workflow implication comes from the parameter schema rather than 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 a destructive, non-idempotent mutation, so the description is not burdened with safety disclosure. It adds useful scope by saying timing, pitch, duration, probability, and expression metadata are preserved, clarifying exactly what the operation should not alter.

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 no redundant restatement of schema or annotations. Every clause earns its place by naming the operation and the attributes it preserves.

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 complete annotations, full schema coverage, and an output schema, the description provides enough context about affected and preserved data to invoke the tool correctly. Its only notable omission is routing guidance relative to the planner 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% and documents all 8 parameters, including curve variants and the guard fields. The description adds no parameter-level meaning 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 and resource ('plan or apply a MIDI velocity curve') and lists preserved attributes, making the operation recognizable. However, it does not differentiate from the sibling plan_midi_velocity_curve, and 'Plan or apply' blurs whether this is the execution tool or also a 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?

The description gives no explicit when-to-use guidance, no alternatives, and no prerequisites. It does not mention plan_midi_velocity_curve or explain when dryRun/planHash/confirmationToken should be used, leaving selection to inference from the name and 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?

Goes well beyond the destructive/non-idempotent annotations by disclosing the confirmation mechanism (SHA-256 source hash + current clip state binding) and post-apply native pitch readback verification, plus the 'every stereo channel must agree' precondition. It does not state what happens on hash/state mismatch or whether the change is undoable, leaving some mutation risk opaque.

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 the core operation front-loaded and the exclusions correctly placed last. The phrasing is compressed to the point of being terse ('Every stereo channel must agree'), but no sentence is 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?

An output schema exists, so return values need not be explained, and for a destructive mutation the description covers the source constraints, confirmation binding and verification. Minor gaps remain around failure modes and reversibility, but the essential call path is fully described.

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 baseline is 3, but the description adds real meaning: it explains the plan/apply token-and-hash flow implied by planHash/confirmationToken and ties expectedStateVersion to 'current clip state' binding. It still does not explain how targetMidiNote interacts with the 'coarse/fine pitch offset' computation.

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), a precise resource (Live clip coarse/fine pitch offset) and scope constraints (whole-clip, monophonic, <=60s local source). It excludes adjacent categories ('not note-by-note vocal correction, rendered audio analysis, or audible validation') but never names a concrete sibling tool to contrast with, which keeps it 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 plan-vs-apply split is clear from 'Plan or apply' plus the dryRun parameter, and the closing sentence gives explicit when-not conditions (no note-by-note correction, no rendered analysis, no audible validation). It stops short of naming an alternative tool for those excluded cases.

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, idempotent=false and openWorld=true. Beyond that, the description adds real behavioral context: the strict unchanged-task-state requirement, sequential receipt dependency, and the fact that it returns bounded result references and observed postconditions rather than a verdict. It stops short of stating what state is mutated or what the destructive effect is.

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 but front-loaded sentences with no filler; the plan/execute distinction leads. It is efficient, though the phrasing is abstract enough that some sentences require re-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?

An output schema exists, so return values need not be spelled out (the description still flags bounded references and postconditions). For a high-complexity, 8-parameter, destructive, two-phase tool, the prerequisites and sequencing are covered adequately, leaving only per-parameter detail to the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 63% across 8 parameters. The description usefully implies the dryRun-confirmationToken relationship ('plan... or execute using that exact plan's confirmation') and the expectedStateVersion/operationIndex semantics through 'unchanged task state' and 'later operations'. But planHash and previousReceiptId semantics are left entirely to the schema, so it only partially compensates for the coverage gap.

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

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

The description states a specific two-mode verb+resource: plan a proposed operation via its original tool, or execute using that plan's confirmation. An agent can grasp that this is a plan/execute gate for a single production operation, though 'one proposed operation' stays abstract and no sibling (e.g. run_production_task) is named for disambiguation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides ordering/prerequisite guidance ('requires unchanged task state; later operations require the preceding applied receipt'), which implies when the tool can be invoked. However, it never names an alternative tool or states when NOT to use this versus the sibling production/lifecycle tools, so usage context is implied rather than explicit.

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

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

Annotations already declare destructiveHint=true, non-idempotent, and non-read-only, so the safety profile is covered. The description adds the notion of a 'guard' and partial/verified state, hinting at optimistic concurrency via expectedStateVersion, but it never explains what gets destroyed, why a confirmation token is needed, or what 'partial state' means.

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

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

A single compact sentence that is front-loaded with the operation. It is efficiently sized, though the second clause ('inspect verified and partial state') is too ambiguous to fully earn 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?

An output schema, full annotation coverage, and 100% schema descriptions carry most of the load, but for a destructive, token-gated mutation the description omits the two-phase guarded workflow (plan hash, confirmation token, state-version check) and its relationship to get_track_arm_context.

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 (armed, dryRun, trackId, planHash, confirmationToken, expectedStateVersion) is already documented in the schema. The description adds no syntax, format, or interaction detail beyond that, 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?

The verb 'arm' and resource 'track' are present, but 'Guard exact-track arming; inspect verified and partial state' is cryptic - it is unclear whether the tool arms a track, verifies an arming attempt, or inspects state, or all three in a guarded flow. It does not differentiate itself from the sibling get_track_arm_context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no preconditions, and no mention of the obvious alternatives like get_track_arm_context or the plan/dryRun workflow. An agent has to infer the guarded two-phase pattern from the schema alone.

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?

Beyond the destructiveHint=true annotation, the description discloses concrete side effects: it changes the global loop/playhead and starts global playback that runs until stopped, other tracks may sound, and on partial failure it reports observed controls without restoring the earlier Session phase. Reversibility, blast radius, and failure semantics are all covered and consistent with 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?

Every sentence carries distinct information (preconditions, track filtering, global side effects, failure behavior), and the key scope constraint is front-loaded. The phrasing is dense and jargon-heavy, which costs some readability but not correctness.

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, non-idempotent transport-mutating tool, the description covers preconditions, what changes, what is not restored, and failure reporting, and an output schema exists so return values need not be explained. The main gap is that related tools with overlapping effects (return_tracks_to_arrangement) are not contrasted.

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 seven parameters (beats, hashes, tokens, stateVersion). The description adds only marginal parameter meaning, mainly the "reject Groups / explicit ordinary tracks" constraint on trackIds and an implicit plan-vs-execute distinction. Baseline 3 is appropriate when the schema carries the parameter burden.

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

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

The description states a specific verb+resource ("Plan/start a looping Arrangement passage") and narrows scope ("Return only explicit ordinary tracks from Session override; reject Groups"). It does not, however, distinguish itself from the closely related sibling return_tracks_to_arrangement or plan_arrangement_repeat, so it stops short of full 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?

Clear preconditions are given: stopped transport, recording off, no pending launches, and "Requires all profile." That is actionable context for when the tool applies. There is no explicit exclusion or named alternative (e.g. return_tracks_to_arrangement), so it stays below 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?

Adds substantial context beyond the destructiveHint=true annotation: exactly what is destroyed (devices in Session and Arrangement), the environmental prerequisites, the internal re-verification of identity, selection, and file coverage, and an honest caveat that no audible-equivalence is claimed.

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 destructive commit and its side effect, then layers advice, prerequisites, and verification caveats. Dense but every clause carries information; only the verification detail is mildly tangential.

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 an output schema present, return values need no explanation, and the description fully covers preconditions and side effects. The two-phase dryRun/planHash/confirmationToken execution flow implied by the schema is not addressed, a minor completeness gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all five parameters are documented in the schema already; the description adds nothing about dryRun, planHash, confirmationToken, or expectedStateVersion. Baseline 3 is correct when the schema carries the parameter burden.

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

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

States a specific verb+resource: 'commit one whole ordinary track to audio, removing its devices in Session and Arrangement.' This is a clear, distinct action from siblings like export_audio_track or set_track_freeze_state, though it never names one to sharpen the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides actionable preconditions (saved Set, stopped transport, unarmed visible target, macOS English Live) and a workflow cue ('Duplicate first to keep an editable source'). It lacks an explicit contrast against alternative render/freeze/export tools, so it stops short of 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 establish read-only, idempotent, non-destructive, closed-world behavior, so the description is free to add filtering semantics the annotations cannot express: symlinks and non-audio files are skipped, and metadata (tags/favorites) is only joined on request. This is meaningful behavioral context beyond the structured fields.

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 enumeration behavior, then the metadata option, then the paging handoff, then the exclusions. No filler and every clause 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?

With an output schema present and 100% schema coverage, the description only needs to cover behavior: paging, optional metadata join, filtering rules, and scope exclusions. All of these are present, leaving nothing an agent needs missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so limit, offset, rootPath, and includeMetadata are all documented in the schema already. The description only restates the metadata join and the paging concept without adding format or constraint detail, so baseline 3 is appropriate.

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

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

States a specific verb ('Page through') and resource ('immediate subfolders and audio files inside a configured local Splice root'), and explicitly scopes itself against related capabilities ('not Splice cloud browsing, downloads, or license verification'). An agent can separate this from list_local_splice_roots and search_local_splice_samples 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?

Gives clear operative context: use it to enumerate a root, and 'returned folder paths can be searched individually when a broad search is truncated' implies the handoff to a search tool. Explicit exclusions are stated. However, it never names the sibling tool to switch to, so the routing is inferred rather than spelled out.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine value beyond that: the output is 'persistable JSON' and it explicitly enumerates what is NOT captured (hidden plugin state, samples, automation, mappings), which prevents false expectations about completeness. It stops short of describing failure modes or size limits.

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, verb-front-loaded, with the capability list first and the exclusion note second. The enumeration of captured fields is long but each item is informative; no filler sentences. Slightly dense but structurally sound.

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?

An output schema exists, so return shape need not be restated, and the one parameter is fully covered by the schema. Annotations carry the safety profile and the description supplies scope and exclusions. What remains missing is the relationship to the save/load/recall siblings, which is the main open question for this 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?

There is a single parameter with 100% schema coverage, and the schema itself documents the accepted forms (track-N from list_tracks, return-N from get_set_mixer, master). The description adds no parameter-specific meaning, so the baseline of 3 applies when the schema does all 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?

The verb 'Capture' plus a detailed enumeration of the resource (ordered devices, nested rack topology, exposed parameters, mixer state) makes the purpose unambiguous. It also clarifies what it is not ('Not a native rack or preset'), but it never distinguishes itself from the close siblings capture_device_parameter_snapshot or capture_track_state_snapshot, so an 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?

Usage is only implied: capture a device chain into persistable JSON. The negative scoping ('Not a native rack or preset; excludes hidden plugin state, samples, automation, and mappings') hints at boundaries but is framed as content scope, not as a when-to-use rule. It gives no guidance on the capture → save → load → recall lifecycle it sits inside, so an agent has no explicit routing to alternatives.

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

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

Annotations already establish the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), lowering the bar. The description still adds real behavioral content: the captured payload is persistable JSON, a 'consistent live identity check' is performed, and hidden plugin state, samples, automation and mappings are excluded from scope. The phrase 'live identity check' remains somewhat cryptic, keeping this from a 5.

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

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

Two tightly written sentences with zero filler. The core action and the persistable-JSON output are front-loaded, and the exclusion clause that follows is genuinely informative 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?

With an output schema present the return shape need not be described, and annotations cover the safety profile, so the remaining burden is scope and orientation. The description covers excluded content well. The residual gap is that it never says the snapshot is later consumed by recall_device_parameter_snapshot, nor distinguishes itself from the chain/track/group snapshot variants.

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 both parameters are documented in place (trackId referencing list_tracks/get_set_mixer/master, deviceId referencing list_devices). The description adds no additional parameter meaning or syntax, 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 and resource ('Capture exposed device parameters as persistable JSON') and clarifies what it is not ('Not a native preset'). It does not, however, differentiate itself from sibling snapshot tools such as capture_device_chain_snapshot or capture_track_state_snapshot, which the agent must distinguish on its own.

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?

'Not a native preset: excludes hidden plugin state, samples, automation and mappings' bounds the scope and implicitly suggests when to prefer it over save_native_device_preset. But there is no explicit when-to-use statement, no precondition (e.g. that a device must be selected/loaded), and no routing to the related recall_device_parameter_snapshot sibling.

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 read-only, idempotent and non-destructive, but the description adds real context beyond them: it enumerates exactly what state is excluded (clips, samples, hidden plug-in state, automation, mappings) and asserts the atomicity guarantee that every track snapshot and the hierarchy must match one state version. That is useful behavioral disclosure not present in the structured fields.

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 zero redundancy. The positive definition (what is captured, in what order, as what) leads, and the read-only/exclusion caveats follow, making it well front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With annotations covering the safety profile, an output schema handling return values, and full parameter documentation, the description only needs to add scope and exclusions, which it does. A brief pointer to the paired save/recall tools would make it self-sufficient, but nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single parameter with 100% schema coverage, and the schema already explains it ('ID from list_tracks'). The description adds no further meaning about busTrackId, so the baseline of 3 applies.

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

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

The description states a specific verb (capture) and resource (an existing Group Track, nested groups and all descendant tracks) and adds the output form (persistable JSON in Live order). It implicitly separates itself from save/load/recall siblings by naming 'capture', but it does not explicitly contrast with the similar capture_track_state_snapshot, so it falls just 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 gives negative scoping ('read-only; does not save clips, samples, hidden plug-in state, automation or mappings, or create/recall tracks'), which tells the agent what this is not. However, it never states when to prefer it over capture_track_state_snapshot or how it feeds save_group_system_snapshot/recall_group_system_snapshot, leaving usage largely implied.

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

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

Annotations already declare destructiveHint=true and non-idempotent, so the mutation profile is covered. The description adds value beyond that: the created track is muted/monitor-off, cleanup stops and disarms only this capture even after client disconnect, and 'no isolated-stem, hardware or listener proof' warns the agent that success is not independently verifiable. That last caveat is slightly telegraphic but is genuinely useful context.

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 purpose, then preconditions, then lifecycle/cleanup behavior, then limits. No filler; the only cost is that the final sentence is compressed into a near-note form ('No isolated-stem, hardware or listener proof') that takes a re-read.

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, a full schema, and an output schema, most burden is carried elsewhere, and the description still covers preconditions, what is created, cleanup semantics, and verification limits. The remaining gap is the explicit handoff to the capture-status and finish siblings, which an agent would need for the full 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 coverage is 100%, so beats range, name length, dryRun/planHash/confirmationToken and expectedStateVersion are all documented in the schema itself. The description adds no parameter-level semantics beyond that, so the baseline 3 applies.

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

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

States a specific verb pair ('Plan or start') and resource ('bounded Live Resampling recording of current playback into a new muted, monitor-off audio track'), which is far more than a restatement of the name. It does not, however, name the lifecycle siblings (get_live_audio_capture / finish_live_audio_capture), so an agent must infer the pairing from names 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?

'Requires playback, recording off and no armed tracks' gives concrete preconditions, which is real usage guidance. But it never says when to use dryRun/plan versus execute, nor points to get_live_audio_capture or finish_live_audio_capture as the follow-up and teardown steps, leaving the multi-call workflow 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?

Annotations already flag destructive=true, but the description goes well beyond them: it enumerates concrete side effects (may start playback, add scenes, change tempo), states what is NOT available (no exact buffer preview, no automatic rollback), and describes the verification work done (rechecks identities, routing, arms, monitoring). That is exactly the extra context an agent needs before invoking a destructive tool.

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

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

The scope statement is front-loaded and every sentence carries content — side effects, gating flag, and return/limitation notes. It is dense to the point of being telegraphic ('Rechecks native identities, existing note/timing, routing, arms, monitoring and musical/recording state'), which costs a point on readability.

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, non-idempotent capture operation with a rich output schema, the description covers side effects, the required opt-in flag, and the absence of rollback/preview. What's missing is the failure/precondition surface: what happens when there is no recent MIDI input or when expectedStateVersion is stale.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all five parameters are already documented. The description only re-touches allowExistingClipChanges with the phrase 'require explicit', adding a mild conditional on top of the schema's 'Explicit authority ... default false'. dryRun/planHash/confirmationToken/expectedStateVersion get no added semantics, which is acceptable given full schema coverage.

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

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

The first sentence names a specific verb + resource + target scope: capturing Live's recent MIDI input into Session globally. That distinguishes it from the adjacent get_midi_capture_context sibling. It loses a notch because 'hidden recent MIDI input' is jargon-rich and doesn't clarify what 'hidden' means in practice.

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 states one conditional rule — known playing-clip changes require allowExistingClipChanges — which is real usage guidance. However, it never says when to call this vs. get_midi_capture_context or when not to call it (e.g., no recent input, wrong arm state). Usage is implied by the name rather than stated.

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

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

Goes well beyond the destructiveHint=true/no-idempotency annotations by disclosing that partial work remains with no rollback or replay, that there is no rendered audio or mixer recall, that Live may adjust copied start markers, and that full-row launch can affect Arrangement overrides and empty tracks. These are exactly the side-effect details an agent needs before an irreversible 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?

Purpose is front-loaded, but the body is dense and contains cryptic fragments such as 'Updated bridge; all profile.' and 'Binds sources/layouts and rechecks at undo entry' that consume space without conveying actionable meaning. Sentence count is reasonable but not every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present (so return values need no explanation) and annotations covering the safety profile, the description still supplies prerequisites and side effects. It is nearly complete; only the meaningless trailing fragments keep it from being fully 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 each of the six parameters is already documented in the schema and the baseline is 3. The description reinforces anchor placement ('below the selected anchor') and naming, but adds no semantics for dryRun, planHash or confirmationToken beyond what the schema 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 compound verb+resource: 'capture AND immediately launch the currently playing Session combination as a named scene below the selected anchor.' This clearly separates it from plain create_scene and launch_scene siblings. The phrasing is jargon-heavy but the action is still identifiable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete preconditions for when this is valid: 'Requires playing transport, all explicit/implicit arms off, recording/count-in off and settled launches.' That is real when-to-use guidance. It stops short of naming alternative tools (e.g. create_scene or launch_scene) for the cases those preconditions fail.

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 still earns credit for disclosing the exact scope of the capture and, importantly, what is NOT captured. It does not say where the snapshot is held or how it relates to the save/recall siblings, so it stops short of full transparency.

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, both dense with information, with the verb and scope front-loaded and the exclusion list packed at the end. Slightly heavy noun-stacking ('nested rack parameters, chain mixer, Drum Rack note routing') but no wasted sentence.

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?

An output schema exists, so return-value description is not required, and the description covers the non-obvious boundary (what is excluded) that an agent could not infer. The remaining gap is the relationship to the save/load/recall snapshot siblings in a very large toolset.

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?

Only one parameter (trackId) with 100% schema description coverage ('ID from list_tracks'), so the schema already carries its meaning. The description adds no interpretation of trackId or of what the resulting snapshot is keyed to; 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 ('JSON snapshot of group membership, track mixer, routing, devices...') with an enumerated contents list, which is far more precise than the name alone. It does not explicitly contrast itself with the sibling save_track_state_snapshot / load_track_state_snapshot / recall_track_state_snapshot trio, leaving the capture-vs-save distinction 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 negative scoping ('Not a native track preset; excludes clips, hidden state, samples, automation and mappings') implies when this tool is appropriate, but it never states a triggering condition or names save_track_state_snapshot as the follow-up when persistence is desired. Usage is inferable rather than directed.

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, non-idempotent, and closed-world. The description adds genuinely useful behavioral context beyond them: the lease is atomic (no double-claim race) and does not load the plugin or save a file, which bounds the side effects of an otherwise 'destructive' claim. It doesn't cover lease expiry/timeout semantics, which would be nice for a non-idempotent mutator.

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 no waste. The action and the atomicity constraint come first, then the return/side-effect clarification.

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 an output schema present, return values needn't be explained, and the description still clarifies that the preset is returned without plugin load or file writes. The main missing element is lease lifetime/timeout behavior for a non-idempotent claim, which matters operationally.

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 required parameters are documented in the schema itself. The description only echoes 'for a worker' and never explains the productSlug scoping role; baseline 3 applies since the schema carries the load.

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 — atomically lease one pending NKS generation job for a worker — which is a distinct action from the read sibling get_nks_generation_job and the complete/fail siblings. It does not name those siblings explicitly, so the differentiation is implicit rather than spelled out.

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' and 'one pending job' implies the queue-consumer context, but there is no explicit guidance on when to claim versus reading status with get_nks_generation_job or when to complete/fail a claimed job. The agent must infer the 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 destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds substantive context beyond that: stopped transport, macOS English Live, binding saved references and source bytes, verifying Project-relative sample copies, large library copying, and an explicit no-portability-guarantee caveat. It stops short of saying what existing Set content is overwritten.

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

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

The purpose is front-loaded in the first sentence, followed by compact precondition and caveat sentences. Each sentence carries information, though the telegraphic phrasing ('Binds saved references and source bytes') is dense and the final caveat sentence is somewhat cryptic.

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, non-idempotent operation with an output schema and full parameter coverage, the description supplies the key preconditions, side effects and caveats an agent needs. It does not define the four media categories or state whether an existing saved Set is overwritten, but overall it is complete enough to call correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and all five parameters are documented in the schema, including dryRun, planHash and confirmationToken. The description adds no parameter-level meaning and does not mention the plan/confirmation workflow, 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 and resource: 'Collect all four native media categories into the current Project and save its clean named Live 12 Set.' An agent can distinguish this from the read-only sibling get_project_media, though the description never names that sibling or save_live_set explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives real preconditions ('Requires stopped transport and macOS English Live') and a caution ('Can copy large libraries'), which implies usage context. It never states when to choose this over get_project_media or save_live_set, or when not to use it, so guidance remains implicit rather than explicit.

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

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

Adds substantial behavior beyond annotations: SHA-256 identity binding before and after measurement, 512 MiB per-file limit, attenuation-only level-match proposals, and explicit exclusions for playback, normalization, mix edits, and quality judgment. These details are consistent with the read-only, idempotent, non-destructive 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 dense but front-loaded and well organized: purpose first, then binding/limits, outputs, read-only scope, and environment requirement. Every sentence contributes operational information, with only minor terseness in phrases like 'All profile'.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.