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

Annotations only indicate non-read-only and non-destructive. The description adds valuable behavioral context: 'Live enforces sample bounds, neighbor ordering, and segment BPM limits' and 'Omit sampleTime to preserve playback timing.' These details inform the agent about constraints and side effects beyond the annotations, though it does not mention auth, rate limits, or the exact mutation outcome.

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 concise sentences with no fluff. The main purpose is front-loaded, followed by key behavioral notes. Every sentence earns its place, and the description is appropriately sized for the tool's complexity.

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?

Despite the concise format, the description omits the critical two-step plan/apply workflow: it does not explain that you must first call with dryRun=true to get planHash and confirmationToken, then call with dryRun=false. It also does not mention the importance of expectedStateVersion or how these fields interact. For a mutating tool with 8 parameters and no output schema, this is a significant gap that could lead to incorrect usage.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds meaning by explaining that sampleTime is in seconds and that omitting it preserves timing, which is beyond the schema's 'Optional source position in seconds.' It also hints at the plan/apply pattern by mentioning 'Plan or apply,' though it does not detail the dryRun/confirmationToken flow. Overall, it adds marginal value over 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?

The description clearly states the tool's purpose: 'Plan or apply an audio warp anchor.' It names the specific resource (audio warp anchor) and the action (add/apply), and distinguishes it from siblings like move_audio_warp_marker and remove_audio_warp_marker by the term 'anchor' and the plan/apply duality. It also adds specificity with the sampleTime omission behavior, making the purpose unmistakable.

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 usage by stating it is for adding a warp marker, which contrasts with move/remove siblings, and explains the plan/apply workflow. However, it does not explicitly mention alternatives or provide exclusions (e.g., 'use move_audio_warp_marker for moving existing markers'). The context is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds behavioral detail: 'Loudness measures the source stream; channel selection applies to optional analyses,' clarifying how loudness and channelIndex interact, and reiterates the source-only nature. This goes beyond annotations without contradicting them.

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 with no fluff. The primary action and scope are front-loaded in the first sentence, and the second clarifies technical nuances. Every clause earns its place, making it highly efficient.

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 tool with 12 parameters and no output schema, the description adequately covers scope and measurement behavior. It could mention the return structure (e.g., analysis results object), but the detailed parameter schema and clarity on what is measured make it sufficient for correct invocation. Minor gap in output description, but not critical.

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 12 parameters are already documented. The description adds a small amount of context (e.g., 'bounded window' implies startSeconds/durationSeconds, channel selection applies to optional analyses), but does not materially enhance understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Measure') and a precise resource ('an exact Session or Arrangement audio clip's local source file over a bounded window'). It explicitly notes 'Source-only, not rendered clip or track audio,' which distinguishes it from potential siblings like analyze_audio_file or get_audio_clip_state. This gives clear purpose and differentiation.

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

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

The description clarifies that it operates on the source file, not the rendered audio, which tells the agent when not to use it (e.g., if rendered audio is needed). However, it does not explicitly name alternatives like analyze_audio_file or get_audio_clip_state, leaving some routing inference to the agent. Still, the scope is well-defined.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: loudness measures the source stream, channel selection applies only to optional analyses, and it requires external tools (ffmpeg/ffprobe). It also clarifies that pitch measurement is not pitch correction, adding transparency beyond the schema.

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

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

The description is three concise sentences with no redundancy. It front-loads the primary purpose, then clarifies scope, exclusions, and prerequisites. Every sentence adds necessary information without filler.

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

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

For a tool with 11 parameters and multiple optional analyses, the description provides adequate context: it states what it measures, what is optional, exclusions, and external requirements. It does not describe the return format, but the lack of an output schema makes this less critical; the description's clarity about the measurements implies the output. It is reasonably complete for an agent to call it correctly.

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

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

Schema coverage is 100%, so each parameter is documented. The description adds valuable semantic clarification: 'Loudness measures the source stream; channel selection applies to optional analyses' clarifies how channelIndex behaves, and 'Not Live processing or pitch correction' clarifies the intent of targetMidiNote. This goes beyond the schema's basic field 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 clearly states the tool measures local source audio loudness, true peak, format, and optional spectral analyses, with a specific verb and resource. It differentiates from sibling tools like analyze_audio_clip by explicitly stating 'local source audio' and 'Not Live processing,' making its scope distinct.

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

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

It provides clear context on when to use the tool: for local source files requiring ffmpeg/ffprobe, and explicitly excludes Live processing and pitch correction. However, it does not name alternative tools (e.g., analyze_audio_clip) or specify when not to use it beyond these exclusions, leaving some inference to the agent.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, which the description reinforces with 'without editing notes'. It adds valuable context: results are deterministic and include specific output elements (candidates, inversions, Roman-numeral function, ambiguity, chromatic pitch classes). No contradiction with 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 two sentences with zero fluff. It front-loads the core purpose, then lists return types and explicitly states read-only behavior. Every sentence earns its place.

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

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

For a two-parameter tool with no output schema, the description compensates by listing the returned data (chord candidates, inversions, etc.). It also clarifies the read-only nature and the dependency on current key/scale. Missing details like how to obtain clip IDs are covered by sibling tools and not necessary here.

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% – both clipId and trackId are fully described in the schema. The description adds little beyond the schema, only implying 'one exact MIDI clip' refers to clipId. Since the schema already documents parameters well, 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 clearly states a specific verb ('Analyze') and resource ('MIDI clip chord events'), with precise qualifiers: 'sustained-note-aware', 'one exact MIDI clip', and 'against the current Live key and scale'. This differentiates it from siblings like analyze_midi_clip_scale and get_midi_clip_notes, so an agent knows exactly what it does.

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 usage for chord analysis but does not explicitly state when to use this tool versus alternatives like analyze_midi_clip_scale or get_midi_clip_notes. No exclusions or alternative routing are provided, so an agent must infer from the name and 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 carry readOnlyHint=true and destructiveHint=false, so the bar is lower, but the description adds real value beyond them: the analysis is state-dependent (relative to the 'current Live key and scale'), returns computed per-note data (scale degrees, chromatic note IDs), and frames corrections as 'bounded' and non-mutating. The explicit 'Read-only' restatement is consistent with the annotations and reinforces the non-destructive contract.

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 totaling roughly 40 words, with action, scope, and context front-loaded. Outputs are listed compactly, and the non-destructive guarantee closes it. Every sentence earns its place; nothing repeats schema or annotation content.

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

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

With no output schema, the description properly names the return shape (pitch names, scale degrees, chromatic note IDs, correction candidates), and the inputs are fully covered by the schema. Minor gaps: 'bounded' is undefined, and the source of the 'current Live key and scale' is not linked to a context tool like get_song_musical_context. Still, an agent has enough to call this 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 description coverage is 100%; both trackId and clipId are documented with concrete formats (e.g., 'track-N:clip-M from list_clips'). The description adds no parameter-specific detail, but it doesn't need to — the schema carries the full burden. 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 opens with a specific verb+resource: 'Analyze one exact MIDI clip against the current Live key and scale.' It enumerates concrete outputs (per-note pitch names, scale degrees, chromatic note IDs, bounded correction candidates) that clearly distinguish it from siblings like analyze_midi_clip_chords (harmony) and correct_midi_clip_to_scale (mutation). The word 'exact' scopes it to a single clip, separating it from broader state/context tools.

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

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

Clear context is established: this is a read-only analysis tool that depends on the current Live key and scale and returns preview correction candidates 'without editing notes.' This implies the preview-before-correct workflow with correct_midi_clip_to_scale and rules out use for actual editing. However, no sibling is named explicitly and no when-not-to-use condition is stated, so it falls just short of a 5.

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

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

Annotations are minimal (readOnlyHint=false, destructiveHint=false) and the description adds context beyond them: it discloses a 'guarded' mechanism implying expectedStateVersion checks, a deterministic seed, and promise of 'complete note readback' for verification. It does not contradict the annotations, and for a mutation-capable tool it appropriately signals that changes are controlled and observable. It stops short of detailing exact side effects or irreversible edits, but given the annotations carry little, the description adds meaningful behavioral 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?

The description is a single, front-loaded sentence that conveys the core action ('Plan or apply'), the guarded deterministic nature, and the two promised outcomes ('exact native context' and 'complete note readback'). There is no filler or repetition of schema data; every phrase earns its place, making it easy for an agent to parse quickly.

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 has 15 parameters, a nested fill object, and a plan/apply confirmation flow, the description is fairly terse. It does not explain the two-phase workflow or the relationship between dryRun, planHash, and confirmationToken, though the schema partly covers these. The promise of 'complete note readback' helps set output expectations, but the description alone leaves an agent uncertain about prerequisites and sequencing. Overall it is adequate but not fully complete for a tool of this complexity.

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

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

Schema description coverage is 73%, which is moderate but not fully self-sufficient. The description itself provides no parameter-specific meaning, leaving parameters like bars, grid, and startBar without elaboration in either the description or schema. However, most critical parameters (dryRun, confirmationToken, expectedStateVersion, preserveAccentsAbove, etc.) do have schema descriptions that adequately explain their roles, so the tool remains usable without extra description-level parameter guidance.

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

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

The description clearly states a specific action ('Plan or apply') and a specific resource ('guarded deterministic drum variation'), and adds distinguishing qualifiers like 'exact native context' and 'complete note readback' that signal a careful, state-aware operation. However, it does not explicitly differentiate from sibling tools such as plan_drum_variation or humanize_midi_notes, so an agent might need to inspect the schema to see why this tool is unique.

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 usage pattern (dry-run then confirm), and 'guarded' hints that it should be used when state integrity matters. Yet there is no explicit statement of when to choose this tool over alternatives, no mention of prerequisites (e.g., needing a prior plan or confirmation token), and no exclusion of cases where a simpler tool would suffice.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false. The description adds 'guarded' (implying a confirmation-gated flow) and 'complete readback verification' (post-apply checks), which are behavioral traits beyond the annotations. However, it stays vague — it never explains the dryRun→planHash/confirmationToken contract or what the mutation actually rewrites in the clip. No contradiction with annotations.

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

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

A single front-loaded sentence with no wasted words. The dual verb 'Plan or apply' leads, and the qualifiers earn their place. It could be slightly more specific, but for its length it is efficient and well-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?

This is a complex tool: 11 parameters, 8 required, a two-phase guarded operation, and no output schema. The one-sentence description doesn't explain the dryRun/confirmationToken lifecycle, what a plan returns (planHash, confirmationToken), or what happens to the clip's notes on apply. With no output schema to fall back on, the description leaves critical workflow knowledge undocumented.

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. The description doesn't add per-parameter meaning beyond the schema, but the schema itself carries detailed descriptions (e.g., dryRun's 'Omit or true to return a plan; false requires a valid confirmationToken'). The description contributes only workflow framing, not parameter detail, 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?

States a clear verb+resource: 'Plan or apply guarded chord arpeggiation.' It adds specificity with 'stable native note IDs' and 'complete readback verification.' However, it doesn't explicitly differentiate from the sibling plan_midi_chord_arpeggiation tool; the dual-mode hint is implicit rather than explicit, and no alternative 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?

No guidance on when to use this tool versus alternatives. It doesn't mention plan_midi_chord_arpeggiation for plan-only workflows, doesn't explain the two-phase dryRun/apply decision, and offers no exclusions. An agent must infer the use case entirely from the schema, which is inadequate for an 11-parameter tool.

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

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

Annotations only state readOnlyHint=false and destructiveHint=false, leaving the description to carry behavioral context. The description adds valuable safety information: it is 'guarded', preserves existing notes, and verifies every native addition. This goes beyond the schema and annotations, giving the agent confidence that the operation is non-destructive and safe. It doesn't mention the two-phase plan/apply requirement, but that is partly covered by the schema parameters.

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, well-structured sentence. It front-loads the core action ('Plan or apply guarded chord doublings') and then adds two relevant qualifiers. There is no fluff, and it is easy to scan.

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

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

This is a mutation tool with a plan/apply pattern (dryRun, planHash, confirmationToken). The description does not explain that applying requires a prior dry run and confirmation token, nor does it clarify the relationship to the plan-only sibling. While the schema covers these parameters, the description's job is to synthesize the workflow, which it fails to do. An agent might not realize the two-step process or the need to validate the plan before applying.

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% – every parameter is described with its purpose. The description does not add meaning beyond the schema. It mentions 'preserving existing notes' which loosely relates to noteIds but doesn't clarify parameter interactions. Since the schema fully documents parameters, 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 clearly states the tool's function: to plan or apply chord doublings. It is specific about the verb ('plan or apply') and resource ('chord doublings'), and it adds important constraints ('guarded', 'preserving existing notes', 'verifying every native addition'). This distinguishes it from sibling tools like plan_midi_chord_doubling and other apply_midi_* tools.

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

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

The description implies usage for chord doubling but does not explicitly state when to use this tool versus the sibling plan_midi_chord_doubling or other chord manipulation tools. It mentions 'plan or apply' but doesn't clarify that applying requires a prior plan or that planning alone might be better served by the dedicated planning tool. No exclusions or alternatives are named.

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

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

Annotations only indicate readOnlyHint=false and destructiveHint=false, so the description adds useful context by mentioning 'guarded' (implying safety checks) and 'complete native note readback verification' (a behavioral trait of verifying results). It does not explicitly state that the tool modifies the clip, but the annotation already covers that. The verification detail goes beyond the structured fields, adding 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?

The description is a single, concise sentence that front-loads the primary action. It avoids redundancy but is slightly dense. It could have mentioned the two-step dry-run/apply workflow explicitly, but it remains concise and well-structured for its 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?

This is a complex tool with 9 parameters, a required expectedStateVersion, and a dry-run/apply workflow indicated by planHash and confirmationToken. The description does not explain the workflow, prerequisites (like obtaining track/clip IDs), or what the tool returns. Without an output schema, the description should provide more guidance, but it is minimal. An agent would need to infer the process entirely from the schema, making this incomplete for a tool of this complexity.

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

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

The input schema has 100% description coverage, with all 9 parameters documented. The description itself adds no additional parameter meaning or relationships. Since the schema already explains each parameter thoroughly, the baseline of 3 is appropriate; the description does not enhance understanding of parameters 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 clearly states the action ('plan or apply guarded chord inversions') and adds a verification component ('complete native note readback verification'). It distinguishes from the sibling plan_midi_chord_inversion by including 'apply', and the mention of 'guarded' hints at a safety mechanism. The verb+resource is specific enough for an agent to understand the tool's core function.

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

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

No guidance is provided on when to use this tool versus the sibling plan_midi_chord_inversion or other apply_* tools. The description does not explain that this combines planning and applying, nor when a dry-run is needed versus direct application. The schema implies a two-step workflow but the description gives no explicit direction.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the agent knows this mutates but is non-destructive. The description adds 'guarded' (implying a two-phase dry-run/confirm protocol) and 'complete native note readback verification', which go beyond the annotations. However, for a mutating tool the description carries substantial burden and does not disclose what gets modified, reversibility, or how the guard is enforced.

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 that front-loads the primary action ('Plan or apply guarded chord voice leading'). It is efficient, though bordering on under-specification for a tool with 10 parameters and a two-phase workflow.

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

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

This is a complex two-phase mutation tool (10 params, 7 required, dryRun/confirmationToken/planHash/expectedStateVersion protocol, no output schema). The description does not explain the guard sequence, when a dry run is required, what the readback verification validates, or failure/error behavior. An agent would struggle to invoke this correctly without inspecting the schema closely.

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%, with most parameters (mode, clipId, dryRun, noteIds, trackId, confirmationToken, expectedStateVersion) already documented in the schema. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

The description states a specific operation (chord voice leading) with a dual 'plan or apply' mode, which distinguishes it from the plan-only sibling plan_midi_chord_voice_leading. 'Guarded' and 'readback verification' add useful specificity. It is clear but could more explicitly position itself as the apply counterpart to the plan-only 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?

No guidance on when to use this tool versus plan_midi_chord_voice_leading or the other apply_midi_* siblings. The 'plan or apply' phrasing implies a workflow but does not explain when each mode is appropriate or which alternative to prefer. No exclusions or decision conditions are provided.

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 description adds significant behavioral context beyond the sparse annotations (readOnlyHint=false, destructiveHint=false). It discloses that the operation is guarded (requires expectedStateVersion), supports a planning mode (dryRun) and atomic application with confirmation tokens, and performs verified additions/removals. This goes beyond what annotations provide, though it could be clearer about 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 dense sentence listing many features without clear structure or front-loading. It's not overly long but packs in technical jargon that makes it hard to parse quickly. It could be better organized with separate clauses or a clearer emphasis on the planning/apply workflow.

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 high complexity (15 parameters, planning vs. apply workflow), the description is somewhat thin. It doesn't explicitly explain the dryRun/confirmationToken flow that is central to using the tool correctly. The schema covers this, but the description should highlight it. It also doesn't mention return values, though no output schema exists.

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

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

Schema coverage is 93%, so the input schema already documents parameters thoroughly. The description mentions concepts like inversions, voicing modes, and slash basses that map to parameters, but it doesn't add new semantics beyond what the schema descriptions already provide. It's adequate but doesn't compensate for any gaps.

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

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

The description clearly states the tool plans or applies chord rebuilding, which is a specific verb and resource. It mentions key features like per-onset functions, recipes, inversions, and voicing modes. However, it does not explicitly differentiate itself from its sibling plan_midi_diatonic_chord_quality, though it does mention 'Plan or atomically apply' which covers both modes.

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

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

No guidance on when to use this tool versus alternatives. It doesn't mention when to choose this over other chord tools like apply_midi_chord_inversion or plan_midi_diatonic_harmony. The description is purely declarative, leaving the agent to infer usage context.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description adds meaningful behavioral context: it signals guarded execution and explicitly promises preservation of source notes and expression. It does not discuss repeated-application side effects or scale/tonality assumptions, but it goes beyond the structured 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 a single front-loaded sentence with no filler. It packs the action, the guarded nature, the resource, and the preservation constraint into one efficient statement.

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

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

This tool has 8 parameters, 5 required, and no output schema, yet the description is only one sentence and leans heavily on schema field descriptions. It does not state preconditions such as valid track/clip or scale context, nor what happens when applying harmony to already-harmonized notes, which an agent would need for fully confident usage.

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 parameter is already well documented in the schema. The description adds only conceptual framing ('scale-aware harmony additions') and does not provide additional parameter-level semantics beyond what the input schema already contains. Baseline 3 is appropriate.

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

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

The description names a specific action ('Plan or apply'), a specific resource ('scale-aware harmony additions'), and a key invariant ('preserving source notes and expression'). It is clear about what the tool does, but it does not explicitly differentiate itself from siblings like plan_midi_diatonic_harmony or apply_midi_diatonic_chord_quality, so it falls short of a 5.

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

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

The phrase 'Plan or apply guarded' plus the dryRun/confirmationToken schema descriptions imply a two-phase workflow: plan first, then apply with a token. However, the description itself gives no explicit guidance on when to choose this tool over the sibling planning tool or other harmony tools, and it states no exclusions or 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 indicate a mutating, non-destructive tool. The description adds 'guarded' but does not explain the two-step plan-then-apply workflow (dryRun + confirmationToken) that the schema reveals. It doesn't disclose that applying modifies the clip's notes or that a plan is required first. It adds minimal behavioral context beyond the annotations, though it correctly implies mutability.

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 efficiently conveys the tool's purpose and scope, placing the core action ('Plan or apply') first. Every word earns its place.

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

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

For an 8-parameter tool with a guarded two-step workflow (dryRun/confirmationToken) and no output schema, the description is too sparse. It does not explain that applying requires a confirmationToken from a prior dry run, nor does it clarify the distinction from plan_midi_diatonic_transposition. The agent must infer critical workflow details from the schema, which is not ideal 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 100% and all parameters have descriptive comments. The description adds no additional parameter-level meaning beyond what the schema provides (e.g., scaleSteps is already defined as movement in degrees of Live's current scale). Baseline 3 is appropriate because the schema carries the semantic 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?

The description states a specific verb ('Plan or apply') and resource ('scale-degree MIDI transposition') with a clear scope ('guarded', 'bound to Live's current key and scale'). It distinguishes itself from generic transposition tools by specifying diatonic scale-degree behavior, and its dual plan/apply nature differentiates it from the plan-only sibling plan_midi_diatonic_transposition.

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 usage for scale-degree transposition bound to the current key/scale but does not explicitly name alternatives or exclusion criteria. It does not mention when to prefer this over plan_midi_diatonic_transposition (which is plan-only) or when a plan should be followed by an apply. Guidance is implied, not 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 only indicate readOnlyHint=false and destructiveHint=false, so the mutation nature is minimally conveyed. The description adds 'guarded' and 'complete native note readback verification', which are useful behavioral facts beyond the annotations. However, it doesn't describe what happens to selected notes, the confirmation/expectedStateVersion checks, or what verification entails in practice.

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 sentence with no filler; the core action and key verification behavior are front-loaded. It could be slightly clearer on the two-phase workflow, but the sentence is compact and purposeful.

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

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

For a complex 8-parameter, no-output-schema tool, this one-sentence description omits the crucial two-phase plan/apply workflow, the need for expectedStateVersion, and the relationship to plan_midi_drop_voicing. The schema covers parameter mechanics, but the description doesn't orient the agent on how to sequence calls or interpret the 'readback verification' result. This is insufficient for a guarded mutation tool.

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

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

Since schema coverage is 100% and individual parameters have detailed descriptions (e.g., dryRun, confirmationToken, expectedStateVersion), the description doesn't need to re-explain them. The phrase 'Plan or apply' loosely mirrors the dryRun semantics but adds no parameter-specific detail. Baseline 3 applies because the schema carries the 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 action ('Plan or apply') on a specific resource ('guarded chord drop voicings'), and the phrase 'Plan or apply' hints at the dry-run/apply workflow that distinguishes it from plan-only siblings like plan_midi_drop_voicing. However, it doesn't explicitly name or contrast the sibling, so differentiation is implicit rather than explicit.

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

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

The description gives no explicit when-to-use guidance, exclusions, or alternatives. It does not mention plan_midi_drop_voicing or explain when to plan vs apply. 'Plan or apply' implies two modes, but the agent is left to infer the workflow 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 indicate a modifying non-destructive operation (readOnlyHint=false, destructiveHint=false). The description adds a valuable guarantee: it preserves onset, pitch, velocity, probability, and expression metadata. However, it does not disclose other behavioral aspects like side effects on note durations, whether changes are reversible, or that a confirmation step is involved.

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

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

The description is a single, efficient sentence that front-loads the purpose and the key benefit (preserving metadata). No unnecessary words or repetition; it is well-structured and easy to parse.

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 tool with 9 parameters and a two-step plan/apply workflow, the description omits critical context: it does not explain the dry-run/apply distinction, the requirement for a confirmationToken, what 'guarded' means, or return values. With no output schema, the agent is left without guidance on expected results. The description is too minimal for the tool's complexity.

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

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

Schema descriptions cover all 9 parameters (100% coverage), so the description adds no extra semantic meaning. It references 'gateRatios' and 'gridBeats' implicitly but provides no new information beyond what the schema already states. Baseline 3 is appropriate given high 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 description states a specific action ('Plan or apply guarded MIDI gate durations') on a clear resource (MIDI gate durations) and mentions preservation of metadata. However, it does not explicitly distinguish this from sibling 'plan_midi_gate_pattern' or other apply_* tools, and the 'Plan or apply' phrasing is somewhat ambiguous without 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 guidance on when to use this tool versus planning-only tools (e.g., plan_midi_gate_pattern) or other apply_* tools. The schema implies a two-step dry-run/apply process (dryRun, planHash, confirmationToken), but the description does not mention prerequisites, such as needing a plan first or providing a confirmationToken for the apply phase.

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 state readOnlyHint=false and destructiveHint=false. The description adds two meaningful behavioral traits: 'guarded' (implying a confirmation mechanism) and 'preserving pitch, timing, velocity, mute, and expression metadata' (a non-destructive guarantee). It does not explain what 'guarded' means in terms of the dryRun/confirmationToken workflow, but that is covered in the schema. The description does not contradict annotations, and it adds some 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?

The description is a single, concise sentence that starts with the primary action ('Plan or apply guarded MIDI playback probabilities') and front-loads the key scope. It has no filler or redundancy. It could benefit from a second sentence on the guarded confirmation workflow, but as written it is compact and clear enough for a first pass.

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 (8 parameters, a two-phase dry-run/apply workflow, no output schema), the description alone is somewhat incomplete: it never mentions that applying requires a planHash and confirmationToken, or that dryRun=true returns a plan. However, the schema descriptions for dryRun, planHash, and confirmationToken explain this completely, so an agent reading the full definition (description + schema) has enough context. The description could still summarize the workflow to make the entire tool definition more self-contained, but it is not severely deficient.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not directly explain any parameter, but it uses the word 'probabilities' which aligns with the probabilities array parameter. It doesn't add extra meaning about the relationship between noteIds and probabilities or the dryRun flow; the schema already does that. The description adds no significant semantic value beyond the schema, hence a 3.

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

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

The description states a specific verb and resource: 'Plan or apply guarded MIDI playback probabilities' and adds a clear scoping guarantee: 'preserving pitch, timing, velocity, mute, and expression metadata.' This distinguishes it from non-probability MIDI tools like apply_midi_velocity_curve or apply_midi_gate_pattern. However, it does not explicitly differentiate itself from the sibling plan_midi_probability_pattern, and saying 'Plan or apply' could confuse an agent about whether to call the planning tool instead.

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 alternatives. It does not mention that this is the apply companion to plan_midi_probability_pattern, nor does it say 'for probabilistic note occurrence use this, for deterministic gating use apply_midi_gate_pattern.' The only hint is the phrase 'MIDI playback probabilities,' which is an implied usage rather than an explicit selection rule. An agent must infer from the name and schema that this applies a precomputed probability plan.

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

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

Annotations only say non-readonly and non-destructive. The description adds that it preserves velocity, probability, mute, release velocity, and velocity deviation, and uses 'guarded' to hint at the confirmation flow, going beyond the annotations.

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

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

A single concise sentence that front-loads the primary action and key constraints without unnecessary 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 tool with 10 parameters and a plan/apply guarded flow, the description lacks context on the two-phase process (dry run, confirmationToken, expectedStateVersion) and does not reference related tools. An agent would need to infer the flow from parameters.

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 covers all parameters with descriptions (100%). The tool description adds no additional parameter semantics beyond what the schema already provides, 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 description states a specific verb (plan or apply) and resource (MIDI ratchets) and lists the attributes preserved (velocity, probability, mute, release velocity, velocity deviation), clearly distinguishing it from other pattern tools by name and content.

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

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

No explicit guidance on when to use this tool versus its plan counterpart (plan_midi_ratchet_pattern) or other apply_midi_* tools. The description does not mention the dry-run/apply flow 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 only indicate readOnlyHint=false and destructiveHint=false, which is low-information for a mutating tool. The description adds some meaningful behavior clues: the operation is 'guarded' and returns 'complete native readback', but it does not disclose side effects, reversibility, or the difference between plan and apply outcomes.

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 one compact sentence with the key distinction (plan vs apply) front-loaded. Every term earns its place, though phrases like 'guarded' and 'native readback' are jargon-heavy.

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, dryRun/apply split, guarded writes, no output schema), the description is somewhat thin. It does mention readback and guarding, but it omits the plan-then-confirm workflow and does not explain what the returned plan or readback contains.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds mild semantic value by tying 'optional bass voice leading' to the mode parameter and 'guarded' to the state/token safety mechanism, but it mostly relies on the schema rather than compensating or enriching 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?

The description states a clear action ('Plan or apply') and resource ('scale-aware chord remapping') with useful modifiers ('guarded', 'optional bass voice leading', 'complete native readback'). It distinguishes this as a plan-or-apply tool, though it does not explicitly reference sibling plan_midi_scale_chord_remapping or other alternatives, so it stops just 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?

No explicit guidance is given about when to use this tool versus the sibling plan_midi_scale_chord_remapping or other MIDI chord tools. 'Plan or apply' implies the dryRun/apply workflow, but the description does not state the required sequence (dry run first, then apply with confirmationToken) or any 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?

The description adds meaningful behavioral context beyond the annotations: it explicitly guarantees preservation of pitch, velocity, probability, mute, release velocity, and velocity deviation, and it discloses the plan-vs-apply duality. It does not fully explain what 'guarded' means or the confirmation-token lifecycle, but those are partly evident in the schema, and the description offers no misleading safety claims.

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, compact sentence that front-loads the core action and key preservation constraints. It avoids redundancy with the input schema, and every phrase earns its place; 'guarded' is slightly vague but not wasteful.

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

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

For a nine-parameter mutation tool with no output schema, the description stays quite terse: it omits the two-phase workflow (dry run then confirmationToken), the role of expectedStateVersion, and how it relates to plan_midi_strum_pattern. The schema covers parameter mechanics, but the description alone is not enough to orient an agent in a complex, guarded mutation flow.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already fully documents all nine parameters. The description's mention of preserved attributes relates to note properties but does not add specific meaning to direction, spreadBeats, noteIds, or the dryRun/confirmationToken flow 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 action ('plan or apply') and a specific resource ('guarded chord strumming'), and it lists the preserved MIDI attributes, so the tool's core purpose is immediately clear. However, it does not differentiate this tool from the sibling plan_midi_strum_pattern or other apply_midi_* tools, leaving some ambiguity about when this is the right choice.

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

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

The description provides no guidance on when to use this tool versus plan_midi_strum_pattern or other MIDI apply tools. It merely says 'plan or apply', which is a workflow hint, but it does not state when a dry run is required, when a confirmation token is needed, or which sibling to prefer for planning-only scenarios.

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

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

Annotations only signal non-read-only and non-destructive; the description adds that the operation is guarded and performs complete native readback verification after applying. It does not detail failure or conflict behavior, but it provides meaningful context beyond annotations.

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

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

One front-loaded sentence contains purpose, scope, guard condition, and verification guarantee. There is no filler or repetition of schema details.

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

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

The description complements a rich schema by stating the guarded plan/apply flow and verification, and the schema itself explains dryRun, planHash, and confirmationToken. However, with no output schema, it leaves the plan and readback result structure unspecified.

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

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

Schema description coverage is 100%, so each parameter's meaning and constraints are already documented. The description adds no per-parameter elaboration and only lightly contextualizes the plan/apply workflow.

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?

Description names the specific operation (MIDI transposition), its chromatic scope, and its guarded plan/apply nature. 'Chromatic' and 'complete native readback verification' separate it from diatonic and plan-only sibling tools.

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

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

It conveys that the tool both plans and executes, and 'chromatic' implies the non-diatonic case, but it does not explicitly name alternative tools or state when not to use it. Usage context is inferable rather than clearly stated.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the description correctly implies a guarded mutation. The description adds the key behavioral guarantee that timing, pitch, duration, probability, and expression metadata are preserved, which is valuable context beyond the annotations. It does not detail failure modes or confirmation token expiry, but the guarded dry-run/apply pattern is disclosed.

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

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

A single, dense sentence that front-loads the action ('Plan or apply'), names the resource, and lists the preservation guarantees. No wasted words; every phrase earns its place.

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

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

For a guarded mutation tool with 100% schema coverage and no output schema, the description is nearly complete. It explains the plan/apply duality and the preservation guarantees. It could add a note about the confirmation token being required for apply, but the dryRun parameter description already covers that.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters. The description adds the preservation guarantee and the guarded plan/apply semantics, but does not add meaning beyond what the schema's parameter descriptions already provide. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Plan or apply'), a specific resource ('guarded MIDI velocity curve'), and explicit preservation guarantees ('preserving timing, pitch, duration, probability, and expression metadata'). This clearly distinguishes it from sibling planning tools like plan_midi_velocity_curve and other apply_midi_* tools.

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

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

The description implies the two-phase workflow ('Plan or apply') and the dryRun/confirmationToken parameters make the when-to-use explicit. However, it does not explicitly name alternatives or state when not to use this tool versus plan_midi_velocity_curve or other apply_midi_* 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?

The description adds the dual-mode notion of 'plan or set,' and the annotations already establish this is a mutating but non-destructive operation. It does not explain concurrency guards or the single-use confirmationToken in prose, though those details are present in the schema; this is adequate but not richly transparent.

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 or redundancy. It is compact and easy to parse, even though it skips details that the schema already provides.

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 tool with a two-phase dry-run/confirm workflow, the description alone is minimal, but the parameter descriptions fill in the planHash/confirmationToken behavior. With no output schema and no explicit summary of the response shape, the overall definition is adequate but not fully self-contained.

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 six parameters are already well documented in the input schema. The description contributes only the 'one exact track' scoping and does not add meaning beyond the schema, meeting the baseline of 3.

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

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

The description names a specific action (plan or set) and a precise resource (record-arm state of one exact track), which is enough to distinguish it from bulk mixer or transport tools. It does not explicitly name a sibling alternative, 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?

There is no guidance about when to use the dry-run planning mode versus the confirming execution mode, nor any mention of alternative tools such as set_transport_recording_context. The agent must infer usage from the tool name and parameter schema.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context about what is captured and what is intentionally excluded, making the tool's behavior predictable.

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

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

Two sentences, no wasted words, purpose stated first, and exclusions listed succinctly. Every sentence adds value.

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

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

For a read-only capture tool, the description explains the output format (persistable JSON), the scope (ordinary/Return/Main tracks), and exclusions. It does not mention return schema or pagination, but none is required for this simple 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%, and the parameter description ('track-N from list_tracks, return-N from get_set_mixer, or master') is already complete. The description does not add extra meaning to trackId, 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 exactly what it does: captures an ordered list of top-level devices and exposed parameters as persistable JSON, with explicit exclusions. This distinguishes it from siblings like capture_track_state_snapshot (broader state) and capture_device_parameter_snapshot (single device).

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

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

The description clarifies scope by listing exclusions (hidden plugin state, samples, automation, nested devices, mappings), which implies when not to use it. However, it does not explicitly name alternative tools or provide a direct 'use when' vs 'use instead' comparison.

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 annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds context beyond that: the capture is persistable JSON and performs a consistent live identity check. This enriches the agent's understanding of behavior without contradicting 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?

Two dense sentences with no filler. The core action and scope are front-loaded, and the exclusion clause earns its place by preventing confusion with preset-based workflows.

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 two-parameter read-only capture tool, the description covers purpose, output format, and scope exclusions. The 'consistent live identity check' phrase could be more explicit about failure behavior, but nothing essential to invoking the tool 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%, and both trackId and deviceId are already clearly documented as stable IDs from specific sources. The description does not add 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?

The description uses a specific verb and resource ('capture exposed device parameters') and immediately clarifies that it is not a native preset, distinguishing it from related siblings like capture_device_chain_snapshot and recall_device_parameter_snapshot. It also states the output is persistable JSON, leaving no ambiguity about what the tool does.

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

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

The description provides clear scope: it targets exposed device parameters and explicitly excludes hidden plugin state, samples, automation, and mappings. It does not explicitly name alternative tools, but the exclusion wording effectively indicates when this tool is appropriate.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: the result is a consistent, persistable JSON snapshot, not a native track preset, and it intentionally omits certain state categories. No contradiction with 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 two sentences with no filler. The primary action and output type are front-loaded, and the second sentence efficiently lists exclusions. Every clause earns its place.

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

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

For a single-parameter, read-only capture tool with annotations covering safety, the description adequately states what is captured, what is excluded, and that the output is a persistable JSON snapshot. It does not detail the exact JSON shape or how to later restore the snapshot, but this is not critical given the schema and the simple read-only nature of the 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%, with trackId documented as 'Stable track ID returned by list_tracks.' The description's phrase 'existing track' adds slight emphasis on validity, but it does not meaningfully extend the parameter semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Capture') and precisely defines the resource: 'one consistent, persistable JSON snapshot of an existing track's mixer, routing, and exposed parameters for ordered top-level devices.' It also distinguishes itself from a native track preset and names exclusions, making it clear what the tool does and does not capture relative to siblings.

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

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

The description conveys a clear context for use: capturing a track-level snapshot of mixer, routing, and exposed top-level device parameters. It also provides explicit when-not guidance by excluding clips, nested devices, hidden state, samples, automation, and mappings, but it does not name a specific alternative tool to use 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 provide only readOnlyHint=false and destructiveHint=false. The description adds significant behavioral detail: the tool can either plan or apply, it requires an explicit direction, equal nearest choices require a tie-break, and existing in-scale notes are never changed. This goes well beyond the annotations and discloses the tool's guarded, non-destructive behavior.

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

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

Two terse sentences with no filler. The main verb and resource are front-loaded, followed by the two most critical behavioral constraints (explicit direction/tie-break and preservation of in-scale notes). Every clause earns its place.

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

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

For a tool with 9 parameters and no output schema, the description captures the core behavior, the plan/apply distinction, the direction/tie-break requirement, and the safety guarantee. It relies appropriately on the schema for parameter-level details (planHash, confirmationToken, dryRun) and does not need to restate them. A minor gap is that it does not explain what 'current Live scale' refers to contextually, but this is not critical for correct invocation.

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

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

Schema description coverage is 89% (8 of 9 properties have descriptions; only 'direction' lacks one). The description adds a little rationale for the direction and tieBreak parameters ('equal nearest choices require an explicit tie break') but largely restates what the schema already communicates (e.g., tieBreak 'Required only for equal nearest choices'). It does not add substantial per-parameter meaning 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?

Description opens with a specific verb and resource: 'Plan or apply guarded pitch correction of exact chromatic MIDI notes into the current Live scale.' It clearly distinguishes this tool from the many sibling plan_midi_*/apply_midi_* tools by naming the scale-correction purpose and the 'guarded' constraint, which is further clarified as never changing existing in-scale 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?

The description implies when to use it (when needing pitch correction of MIDI notes to the current Live scale) but does not explicitly state when not to use it or which alternative sibling (e.g., plan_midi_diatonic_transposition, apply_midi_scale_chord_remapping) would be preferred. The plan/apply duality is implied by 'Plan or apply,' but no comparison to other pitch-correction tools is given.

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

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

Annotations already indicate a mutating, non-destructive operation (readOnlyHint=false, destructiveHint=false). The description adds the two-phase intent ('Plan or create') and the beat-position requirement, but it does not disclose that planning is a dry run or that execution requires a valid confirmationToken and expectedStateVersion.

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 redundancy. It efficiently communicates the core purpose and positional constraint without wasting 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?

The tool's two-step planning/creation workflow is not explicitly described; the agent must infer it from the schema's field descriptions (dryRun, planHash, confirmationToken). There is no output schema, so return values are not described, but the parameter descriptions partially compensate for this 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 the schema fully documents all six parameters. The description adds 'exact beat position' which reinforces timeBeats, but it adds no further meaning beyond the schema's already detailed parameter 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 states a specific verb ('Plan or create') and resource ('Arrangement cue point') with a positional constraint ('exact beat position'). This clearly distinguishes it from sibling tools like list_arrangement_cue_points, rename_arrangement_cue_point, delete_arrangement_cue_point, and jump_to_arrangement_cue_point.

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

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

The description provides no guidance on when to use this tool versus siblings, nor does it explain when to plan versus create. The plan/execute flow is implied only by the name and schema, not clarified in the description.

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

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

Annotations provide readOnlyHint=false and destructiveHint=false, and the description adds meaningful behavioral context beyond them: the plan/import two-phase flow, the binding of source file identity/size/modification time, and Live's audio-format validation. It does not detail failure behavior, but the added transparency is useful 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?

The description is two compact sentences with no filler. The first sentence front-loads the action and key preconditions, while the second adds the essential confirmation behavior and validation 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 two-phase tool with eight parameters and no output schema, the description conveys the core workflow, preconditions, and validation behavior clearly. The main gap is that it does not explicitly describe what the dry-run returns or what happens on failed validation, though the rich parameter schema partially compensates for this.

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

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

The schema already documents all eight parameters with 100% coverage, including dryRun, planHash, confirmationToken, and expectedStateVersion. The description reinforces the plan/import workflow but does not add per-parameter 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 clearly states the action: plan or import a local audio file into a specific empty Session slot on an unfrozen audio track. This precise verb-resource pairing distinguishes it from MIDI creation tools and arrangement placement tools, such as create_midi_clip and place_session_clip_in_arrangement.

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 clear context for when to use the tool: local audio file, exact empty Session slot, unfrozen audio track, two-phase plan/import flow. It does not name explicit alternatives or exclusions, but the conditions are specific enough for an agent to select it appropriately.

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 write nature (readOnlyHint: false) and non-destructive nature (destructiveHint: false). The description adds the verification behavior ('native execution verifies every generated note') and the binding of state, which is useful. However, it does not explicitly describe the two-phase plan/execute flow (dryRun, planHash, confirmationToken) that the schema implies, nor what happens on state mismatch. Given annotations already disclose safety, the description adds moderate context but leaves execution details to schema.

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

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

The description is two sentences with no redundant wording. The core action is front-loaded, and each clause adds value—'Plan or create' plus the empty-clip constraint, and the state-binding and verification details. It is efficient and well-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?

For an 11-parameter tool with a two-phase execution model and numerous siblings, the description lacks essential usage context. It does not explain the empty-clip requirement explicitly (why empty, what happens if not), does not describe the dry-run then confirm pattern, and does not clarify how it differs from edit_drum_pattern_clip or create_scale_bassline_clip. The schema describes parameters but the description fails to tie them together into a coherent workflow. This is a significant gap for a tool of this complexity.

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

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

Schema coverage is high (82%), with descriptions for most parameters including activeSteps, gate, note, role, and the plan/execute fields. The description provides a high-level summary of parameters ('binds current meter, tempo, grid, lanes, destination, and state') but does not add specific syntax or relationships beyond the schema. Since the schema carries the semantic weight, the description adds minimal extra value.

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

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

The description states a specific verb ('plan or create') and a precise resource ('multi-lane drum pattern in an empty Session clip'). It clearly differentiates from siblings like edit_drum_pattern_clip and apply_drum_variation by emphasizing emptiness and creation, while also mentioning state binding. This is a clear and distinct purpose.

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 usage for creating new drum patterns in empty Session clips but does not explicitly contrast with alternatives such as edit_drum_pattern_clip or other creation tools. It lacks explicit 'when to use' or 'when not to use' guidance, though the context of 'empty clip' gives some hint. The absence of explicit exclusions leaves the agent to infer appropriate usage from sibling names and 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 only indicate it's not read-only and not destructive, but the description adds useful context: it mentions the dry-run/confirmation token flow implicitly via schema and states that deletion is not exposed. It does not explicitly mention that creation is not directly executed (only planned), but the schema's dryRun/confirmationToken parameters imply a two-phase process. The description does not contradict annotations, so no contradiction.

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

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

Two sentences, front-loaded with the main action and optional name, then directs to set_groove and clarifies deletion. No fluff, every sentence 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 no output schema, the description could be expected to explain what the plan/confirmation flow returns, but it doesn't. However, the schema documents the parameters sufficiently. It explicitly mentions the two-phase constraint (dryRun/confirmationToken) through the schema, and the fact that deletion is not available fills a contextual gap. Overall, adequate but could benefit from a note on the return value of a successful plan.

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 5 parameters are documented. The description adds the notion of 'base grid' and 'amounts' which relate to the groove's properties but doesn't detail them in the description. It doesn't elaborate on the dryRun/confirmationToken flow beyond what the schema says. Baseline 3 is appropriate.

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

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

The description clearly states it creates a groove with an optional name, and mentions adjusting afterward with set_groove. This distinguishes it from related operations like set_groove, though it could be more specific about what 'create' entails (e.g., whether it adds to the pool or just plans).

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

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

Explicitly says to use set_groove for adjustments and mentions that deletion is not exposed. This gives clear guidance on what this tool is for and what it is not for, effectively routing the agent to the correct 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?

Beyond the annotations, the description discloses two modes of behavior ('Plan or create') and a safety-relevant precondition ('exact empty Session slot'). However, it does not explain what happens if the slot is not empty, whether the create step can stale-fail, or what side effects occur after confirmation; with no readOnlyHint, the mutation burden is only partially covered.

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

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

The description is a single front-loaded sentence with no filler. It efficiently communicates the action, the resource, and the slot preconditions.

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

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

For a nine-parameter tool with a two-phase dry-run/confirm workflow and no output schema, the description is adequate but thin. The schema explains the parameters individually, but the description does not clarify the recommended invocation sequence (plan first, then execute with confirmationToken) or what the returned plan/confirmation payload looks like.

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

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

The input schema has 100% description coverage for all nine parameters, so the schema carries the parameter documentation burden. The description adds only the 'exact empty Session slot' context, which loosely reinforces trackId/clipId semantics but does not add new parameter detail.

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

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

The description uses a specific verb phrase, 'Plan or create', and names the resource, 'MIDI clip', with a clear locative constraint, 'in an exact empty Session slot'. It is clearly distinct from sibling clip creators that target drums, scales, or audio, though it does not explicitly name an alternative.

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

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

The description implies the intended use case: creating a MIDI clip in an empty Session slot, possibly after a planning/dry-run step. It does not explicitly state when not to use it, such as when editing an existing clip or when targeting Arrangement, nor does it mention any sibling 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 indicate a non-read-only, non-destructive operation, and the description adds that it can plan or create, and that omitting index appends—behavior not in the annotations. This is valuable context beyond the schema. However, it does not disclose the two-step dry-run/confirmation flow, which is implied by the schema's dryRun parameter, nor does it mention any side effects beyond appending. The description provides moderate additional insight 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?

The description is three short sentences, each carrying essential information: the core purpose, an important default behavior, and a distinction from separate functionality. It is front-loaded with the primary action and scope, and every sentence earns its place without redundancy or fluff. This is an exemplary level of conciseness for a tool with 8 parameters.

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

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

The tool has 8 parameters and no output schema, so the description must cover high-level purpose and non-obvious behaviors. It does this by stating the scope (track types, nested racks), appending behavior, and separation from drum-pad assignment. The dry-run/confirmation process is documented in the schema's dryRun parameter, so the description does not need to repeat it. Overall, the description provides sufficient context for an agent to correctly invoke the tool, though it could mention the need for a confirmation token for actual creation (already in 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?

With 88% schema description coverage, most parameters are already explained. The description adds semantic meaning to the index parameter by stating 'Omitted index appends,' which is not in the schema. This clarifies a key behavioral aspect. The description also indirectly clarifies the name parameter ('named empty chain'). Given the high schema coverage, the baseline is 3, and the description provides enough extra context to warrant a 4.

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

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

The description clearly states the tool's function: to plan or create a named empty chain in a specific rack, with scope including ordinary, Return, and Main tracks and nested racks. It distinguishes itself by noting 'Drum-pad assignment is separate,' which prevents confusion with related operations. The verb 'Plan or create' and the resource 'named empty chain' are both specific and unambiguous.

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

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

The description implies when to use this tool (for creating chains) but does not explicitly mention alternative tools or when not to use it. It notes that drum-pad assignment is separate, which hints at a different tool, but it doesn't name the alternative or provide exclusion criteria. The context is clear but lacks 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?

The description goes beyond the annotations by revealing the plan-or-append behavior and the non-obvious naming nuance: the name is a raw label and Live adds the displayed return-letter prefix. This is meaningful context for both dry-run planning and the eventual append, and it does not contradict readOnlyHint=false or destructiveHint=false.

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: the first states the actionable purpose, and the second explains the one nuance that could otherwise cause a wrong invocation. No filler or redundancy.

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

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

For a tool with no output schema and only boolean annotations, the description plus the fully documented schema cover the key decisions: plan vs append, raw-name handling, and the display-name result. It could be stronger by explicitly stating that appending requires a prior dry-run confirmation, but that is already encoded in the dryRun/planHash/confirmationToken parameters.

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 five parameters. The description adds value by clarifying that `name` is the raw label rather than the final displayed name, and by telling the agent that the result reports the observed display name, which is useful when interpreting the output.

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 concrete operation ('Plan or append a Return Track') and ties it to a specific Live feature (shared send effects via the native bus API), making it distinguishable from generic create_track or set_return_mixer. It also clarifies that the result is the observed display name, so the tool's objective is unambiguous.

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

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

The description provides clear contextual scope ('Return Track for shared send effects') and implies the planning/append workflow, so an agent can infer when this tool applies. However, it does not explicitly contrast this with siblings like create_track or set_return_mixer, nor state when not to use it, leaving usage guidance 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?

The description adds some useful behavior beyond annotations: 'native execution verifies every generated note' and the requirement of 'an exact empty Session clip.' However, it does not disclose the plan/execute sequencing, the single-use confirmation token requirement, or what happens if the clip is not empty. Since readOnlyHint=false and destructiveHint=false are present, the safety profile is partly covered, but the state-changing semantics remain under-explained.

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 compact at two sentences and front-loads the core action and target. The second sentence is dense jargon that lists concepts without explanation, but it is still efficient and not padded. It earns a strong score for conciseness despite some loss of clarity.

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

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

With 17 parameters, a plan/execute split, and no output schema, this description is too short to be complete. It never mentions that a dry run must precede execution, that planHash and confirmationToken are required for the non-dry-run mode, or what the returned plan/confirmation looks like. The schema carries most of the burden, but the description leaves critical orchestration details implicit.

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

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

Schema description coverage is 76%, so most parameters carry their own meaning. The description adds only a high-level conceptual grouping ('key, progression, rhythm, register, destination, state version') without mapping to actual parameter names or explaining interactions like stepBeats dividing chordBeats. This is adequate but not additive enough to 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 states a clear verb-resource pair: 'Plan or create one scale-aware bassline in an exact empty Session clip.' It identifies the artifact type (bassline, not melody or chord progression) and the destination, which helps distinguish it from siblings like create_scale_melody_clip. It does not explicitly name a differentiating sibling, so it loses the top score.

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

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

No guidance is given about when to use this tool versus alternatives such as plan_scale_bassline or create_scale_melody_clip. The 'Plan or create' phrasing hints at two modes, but the description does not explain the dry-run-then-confirm flow or when each mode is appropriate. This leaves the agent to infer usage from the schema fields like dryRun and confirmationToken.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries most of the behavioral burden. It does add useful context ('one exact empty Session clip' precondition, 'verifies every generated note'), but it omits the critical two-phase commit: that dryRun=true returns a plan, that committing requires a confirmationToken, and that execution rederives harmony. The 'Plan or create' phrase is a weak stand-in for describing the actual dry-run-then-confirm behavior an agent must follow. No contradiction with annotations—'create' is consistent with readOnlyHint=false.

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 short at two sentences and front-loads the primary verb ('Plan or create'), which is structurally sound. However, the second sentence is dense with undefined jargon ('independently rederives the signed harmony') that consumes space without adding actionable clarity, so it is not maximally economical.

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

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

This is a high-complexity tool—19 parameters, 12 required, a nested articulation object, a two-phase dry-run/commit flow, and no output schema—but the description gives relatively little of the operational context an agent needs. It mentions the empty-clip precondition and verification behavior, but does not explain the return values (no output schema to fall back on) or the mechanics of the dry-run-to-confirmation flow. For a tool this intricate, the description should carry significantly more weight.

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 68%, so the schema already documents most parameters (degrees, trackId, clipId, chordBeats, startBeats, articulation, etc.) with adequate descriptions, justifying the 3 baseline. The description's phrases 'functional' and 'signed harmony' add a hint about the harmonicFunctions parameter (diatonic, secondary_dominant, borrowed_parallel_minor) beyond the bare schema, but it does not systematically clarify the dryRun/planHash/confirmationToken interaction—arguably the most semantically charged parameter group.

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-plus-resource ('Plan or create... chord progression in one exact empty Session clip') and scopes it to functional scale-degree chord progressions, which distinguishes it from sibling creation tools like create_scale_bassline_clip and create_scale_melody_clip. It loses a point for the opaque 'signed harmony' jargon in the second sentence and because the dual plan-or-create nature is only gestured at 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?

No guidance is given on when to use this tool versus its counterpart plan_scale_chord_progression, and the dryRun/confirmationToken workflow—which is arguably the tool's defining usage pattern—is not explained. The schema hints at the two-phase commit through dryRun and planHash, but the description never tells the agent to first run a dry run or to prefer this over the separate planner 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?

The description adds meaningful behavioral context beyond the annotations: it reveals the dual plan/execute mode ('Plan or create'), the precondition of an 'empty Session clip,' and that 'native execution verifies every generated note.' It also hints at state binding ('Binds Live key, meter, grid, destination, and state'), although this phrasing is somewhat cryptic.

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 two concise sentences with no filler. The primary purpose is front-loaded, and the second sentence adds behavioral specificity about native execution and state binding. Every clause earns its place.

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

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

For a 16-parameter, mutating tool with no output schema, the description is too sparse. It does not explain the dry-run/confirmation-token flow (despite 'Plan or create' hinting at it), what the tool returns, how to obtain the required trackId/clipId/expectedStateVersion, or how it relates to sibling planning tools like plan_scale_melody.

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 69%, leaving five parameters without descriptions (grid, repeats, maxPitch, minPitch, motifBars). The tool description does not clarify these undocumented parameters; it only broadly mentions 'grid' and 'scale-degree' without explaining values, defaults, or relationships. The description therefore fails to compensate for the schema 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 clearly states a specific action and resource: 'Plan or create one exact scale-degree melody in an empty Session clip.' It distinguishes this from sibling tools by specifying 'scale-degree melody' and 'empty Session clip,' making it easy to tell apart from bassline, chord, and other clip-creation tools.

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

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

The description implies the tool is for creating or planning a scale-degree melody in an empty Session clip, which provides some contextual guidance. However, it never explicitly says when to use this instead of related tools like plan_scale_melody, create_scale_bassline_clip, or create_midi_clip, and it offers no exclusions or 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 only indicate readOnlyHint=false and destructiveHint=false, so the description carries the burden of disclosing behavioral traits. The description mentions 'plan or create' but doesn't explain that dryRun returns a plan without mutating state, that creation requires a confirmationToken, or that expectedStateVersion enforces optimistic concurrency. These are critical behavioral details for safe invocation.

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 concise sentence with no wasted words. It is front-loaded with the core action. However, given the tool's complexity (6 parameters, two-phase workflow), it may be too terse, missing important workflow context. It earns a 4 for brevity but not a 5 due to under-specification.

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 tool with 6 parameters, a two-phase plan/confirm workflow, no output schema, and no annotation beyond safety hints, the description is inadequate. It fails to explain the necessary sequence of operations (dryRun to get planHash/confirmationToken, then confirm), the role of expectedStateVersion, or what happens on creation. An agent cannot reliably invoke this tool correctly based solely on the description.

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

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

The description adds meaning beyond the schema by clarifying that 'index' refers to an exact insertion position and that 'plan or create' relates to the dryRun parameter. Since schema coverage is high (83%), the baseline is 3, but the description provides useful context for index and the planning/creation flow, justifying a 4.

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

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

The description clearly states the verb (plan or create) and resource (Session scene) with a specific detail (exact insertion index). It distinguishes from sibling tools like list_scenes and launch_scene by indicating creation. However, it doesn't explicitly differentiate the planning vs. creation phases, which are implied by the parameters.

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 that the tool is used to create scenes, but it doesn't provide explicit guidance on when to use it versus alternatives, nor does it explain the two-step dryRun-then-confirm workflow. No exclusions or alternative conditions are given, leaving the agent to infer usage from the parameters.

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 (readOnlyHint=false, destructiveHint=false) establish this is a mutating but non-destructive operation. The description adds the plan-vs-execute duality, which is genuinely useful context beyond annotations. However, it does not disclose the optimistic-concurrency requirement (expectedStateVersion) or the short-lived single-use confirmationToken mechanics, which are significant behavioral traits for a write operation.

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

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

A single front-loaded sentence with zero filler. The verb and resource come first, and the distinguishing constraint (insertion index) is placed at the end. Every word earns its place.

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

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

For a 7-parameter tool with a plan-then-commit workflow (dryRun → planHash → confirmationToken) and optimistic concurrency (expectedStateVersion), the description is too thin. It never explains the required call sequence or the fact that execution depends on a prior dry-run token. With no output schema and this workflow complexity, an agent is left to infer the orchestration entirely from parameter descriptions.

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

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

Schema description coverage is 71%, and the description fills the two gaps: 'audio or MIDI' maps to the undocumented `type` enum, and 'exact insertion index' maps to the undocumented `index` parameter. This adds real meaning beyond the schema, compensating for the uncovered parameters.

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

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

The description states a clear verb ('create') and resource ('audio or MIDI track') with the precise constraint 'at an exact insertion index'. It distinguishes from return-track and scene creation but does not explicitly disambiguate against siblings like create_audio_clip or create_midi_clip, which an agent could confuse with track creation of a given type.

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

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

No when-to-use or when-not-to-use guidance is given. The description does not name alternatives (create_return_track, create_audio_clip, create_midi_clip) or state conditions for choosing this tool over them. The 'Plan or create' phrasing hints at the two-phase workflow but offers no direction on when to plan versus execute.

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 description goes beyond the destructiveHint annotation by disclosing specific behavioral nuances: 'Live may retain pre-loop playback material and creates a processed source,' and 'Selected interval is not a guarantee of exclusive source-file bounds.' It also mentions that it 'Binds audio and loop state and reads back native results,' providing a comprehensive picture of side effects and state changes. This is exemplary 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?

The description is composed of four sentences, each carrying meaningful information: the core action, preview behavior, retention/processing caveats, and state binding. It is dense but not verbose, front-loading the main purpose. Slightly technical jargon (e.g., 'pre-loop playback material') could be clearer, but overall it's concise and well-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?

The description covers the essential aspects: planning vs. applying, preview output, potential retention of source material, creation of a processed source, the bounds caveat, and state binding. It does not detail return values or error conditions, but given the lack of an output schema and the presence of a clear two-step workflow (dryRun and confirmation) in the schema, the description is largely complete for an agent to understand the tool's behavior and side effects.

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

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

Schema description coverage is 100%, so all parameters are already documented with clear meanings (e.g., dryRun, confirmationToken, expectedStateVersion). The description adds little beyond what the schema provides; it references 'Plan or apply' which aligns with dryRun, but doesn't enrich parameter semantics further. Per the baseline rule for high coverage, a 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 clearly states the tool's function: 'Plan or apply Live native cropping of one exact audio clip.' It specifies the resource (audio clip) and the action (crop), and distinguishes itself from other audio tools by mentioning 'native cropping' and 'one exact audio clip.' No ambiguity.

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

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

The description explains the two operating modes ('Plan or apply') and hints at a preview/report behavior, but it does not explicitly compare to alternatives or state when to choose this over other clip-editing tools. Since there is no direct sibling crop tool, the lack of explicit alternatives is acceptable, but it still doesn't provide clear when-to-use guidance beyond its own purpose.

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

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

Annotations already declare destructiveHint=true, so the description adds value by noting 'deletion is undoable in Live' and that it preserves other timeline material, which goes beyond the annotation's generic destructive flag. It also highlights the confirmation requirement, adding operational context without contradicting 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?

Two sentences with no filler. The purpose is front-loaded, and the critical constraints (exactness, preservation, undoability) are stated succinctly. Every clause earns its place.

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

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

For a destructive tool with a safety mechanism, the description covers the core workflow (plan/delete), prerequisites, and undoability. It does not explicitly describe the dry-run/confirmation flow, but the schema descriptions for dryRun, planHash, and confirmationToken fill that gap. With no output schema and 6 parameters, this is reasonably complete.

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

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

Schema coverage is 100% and each parameter has a descriptive comment. The description itself does not add extra meaning beyond the schema—it mentions 'clip identity' and 'confirmation' which map to clipId and confirmationToken, but the schema already explains these. Baseline 3 is appropriate since the schema carries the parameter documentation 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 clearly states the verb 'delete' (and 'plan') with a specific resource 'one exact Arrangement clip', and adds the distinguishing constraint 'preserving other timeline material'. This separates it from siblings like delete_clip, move_arrangement_clip, and duplicate_arrangement_clip.

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

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

The description implies a two-phase workflow ('Plan or delete') and notes prerequisites ('Requires current clip identity and confirmation'), but does not explicitly contrast with alternatives such as delete_clip for session clips or when a dry run is mandatory. The 'Plan or delete' phrasing suggests when to use it, but no explicit exclusions or alternative routing is given.

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

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

The annotation destructiveHint is false, but the description says 'delete' which is inherently destructive. This is a direct contradiction. The description does not disclose the two-phase confirmation requirement, and the annotation misrepresents the tool's destructive nature.

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 sentence and front-loads the core action, but it is too sparse to be useful. It is concise in length but not in meaning—missing essential operational context.

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

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

For a destructive, two-phase operation with 5 parameters and no output schema, this description is completely inadequate. It fails to mention the planning step, confirmation requirements, or any prerequisites. An agent cannot safely call this tool based on this description 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 coverage is 100%, so the baseline is 3, but the description adds no value beyond restating 'one exact Arrangement cue point.' It does not explain the relationship between dryRun, planHash, and confirmationToken, or why expectedStateVersion is required—critical semantics for correct invocation.

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

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

The description clearly states the action (delete) and the resource (Arrangement cue point), and distinguishes it from siblings like create, rename, or jump. However, 'Plan or delete' is slightly ambiguous—it could imply two separate modes but doesn't explicitly clarify the two-phase dry-run/execute pattern.

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

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

No guidance is given on when to use this tool versus alternatives. It doesn't mention the prerequisite of planning (dryRun) before deletion, the need for expectedStateVersion, or that a confirmationToken is required for the actual delete. The description leaves the agent to infer the workflow 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?

The description adds meaningful behavior beyond the destructiveHint annotation by revealing the two-phase plan-or-delete workflow and narrowing the destructive action to one exact occupied Session clip. This gives an agent useful context about preflight planning before a destructive call.

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 or redundant restating of the tool name. Every word contributes to the core meaning.

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 rich parameter schema and destructive annotations, the description is mostly sufficient. The main gap is that it does not explicitly explain the plan-confirm-delete confirmation flow or output semantics, though the schema's dryRun, planHash, and confirmationToken fields cover most of that burden.

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 parameters are already well-documented. The description adds no direct parameter-level detail, but its 'plan' and 'exact' wording loosely aligns with dryRun and expectedStateVersion without expanding on them.

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 operation ('Plan or delete') and a precise resource ('one exact occupied Session clip'). It clearly differentiates from the sibling delete_arrangement_clip by identifying the target as a Session clip.

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

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

The resource type implies when to use this tool versus arrangement-clip tools, but the description does not explicitly name alternatives or state when-not-to-use conditions. Usage context is implied rather than directly 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?

The destructive annotation already flags the risk, and the description adds the plan/dry-run mode and exact-target qualifier. However, it does not disclose that an actual delete requires a prior dry run, valid confirmationToken, and expectedStateVersion; the two-phase behavior is left to the schema.

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

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

One front-loaded sentence with no filler; every phrase ('Plan or delete', 'exact loaded device', chain types) 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?

The rich schema covers trackId/deviceId resolution and the plan/confirm parameters, and annotations cover the destructive nature, so the short description is not fatal. Still, a tool with six parameters and no output schema could state the required dry-run-then-confirm sequence more directly.

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

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

Schema description coverage is 100%, and each parameter has a detailed explanation, so the baseline applies. The description adds no parameter-level detail beyond hinting at the dryRun/delete dichotomy that the schema already documents.

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 the specific action ('Plan or delete') on a specific resource ('one exact loaded device') and constrains scope to 'ordinary, Return, Main, or rack chain.' This is enough to tell it apart from sibling delete/move tools such as delete_session_object or move_device.

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 useful scope context (loaded device, specific chain types) but never says when to prefer this over alternatives like set_device_active or move_device, nor when a dry-run plan should be used instead of a direct delete. Usage guidance is therefore only implied.

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

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

Beyond the destructiveHint annotation, the description adds that Return deletion exposes its devices and affected track-send lanes, and that content deletion needs 'explicit content authority.' This gives useful insight into side effects and mode-dependent behavior without contradicting 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?

Two sentences with no filler: the first states action, resource, and a key condition; the second flags an important behavioral edge case for Return Tracks. The structure is front-loaded and every phrase earns its place.

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

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

For a destructive multi-parameter tool, the description covers the core plan/delete duality and the notable Return-deletion side effect. It leaves concurrency and token mechanics to the schema, which is acceptable since those are already documented; but a direct mention of the required dryRun-to-token flow would have made it more self-contained.

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 schema description coverage at 88%, the schema already explains most parameters in detail. The description adds only loose hints like 'explicit content authority' mapping to allowContent and the plan/delete concept mapping to dryRun/confirmationToken, but doesn't materially expand on the individual parameter meanings.

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

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

The description names a specific verb ('Plan or delete'), a precise resource set ('exact track, Return Track, scene, or Session clip'), and a distinguishing qualifier ('explicit content authority'). It differentiates from sibling tools like delete_clip or delete_arrangement_clip by covering multiple session-object types and mentioning the return-track-specific side-effect disclosure.

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 a two-phase dry-run/confirm workflow via 'Plan or delete' and scopes to session objects via 'Session clip,' but it never explicitly says when to use this tool vs alternatives like delete_clip or delete_arrangement_clip, nor states prerequisites like expectedStateVersion or confirmationToken. The guidance is implicit rather than direct.

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

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

Annotations only say non-read-only and non-destructive; the description adds valuable behavior: 'preserves the source' and 'validates its identity again at the native write boundary'. It also hints at a two-phase plan/duplicate flow, though it does not detail the confirmation mechanism.

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

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

Two sentences, front-loaded with purpose and key constraints. No wasted words; every clause adds meaning.

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

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

The tool has 7 parameters and no output schema, but the description plus 100% schema coverage covers the essentials. It does not explicitly explain the two-phase commit pattern (dryRun → plan → confirm), but the schema describes those parameters and the description's 'Plan or duplicate' hints at it. Adequate for a moderately complex tool.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds the 'non-overlapping' constraint on startBeats and 'same track' context for trackId, but these are minor enhancements; it does not explain planHash or confirmationToken beyond what the schema already 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 states a specific verb (duplicate), resource (Arrangement clip), and constraints (non-overlapping, same track, exact copy). It clearly distinguishes from move/delete/place tools by emphasizing duplication and preservation.

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 clearly conveys this is for duplicating arrangement clips, which narrows context among siblings like duplicate_clip, duplicate_clip_loop, and move_arrangement_clip. However, it does not explicitly state when not to use it or mention alternatives, so it misses the 'exclusions' that would earn 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?

The description adds that the tool supports a planning mode in addition to execution, which is not present in the annotations. However, it does not describe side effects like whether an occupied destination slot is rejected or overwritten, or the exact state mutation behavior. Since annotations only say readOnlyHint=false and destructiveHint=false, the description adds some but not rich 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?

The description is a single, front-loaded sentence with no filler. It conveys the core action and target clearly. However, it may be too terse to convey the full workflow, but for purpose clarity it is efficient.

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

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

For a 7-parameter tool with no output schema, the description is incomplete. It does not explain the two-phase invocation (dry run then confirm), the role of expectedStateVersion, or the outcome of the operation. The agent must infer the workflow from parameter names and descriptions, which is risky.

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

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

The schema already describes all seven parameters thoroughly (100% coverage), so the baseline is 3. The description adds minor semantic context by specifying the source must be 'occupied' and destination 'empty', which clarifies the meaning of clipId and destinationClipId, but does not explain the dryRun/confirmationToken interaction.

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 action ('Plan or duplicate') on a specific resource ('an exact occupied Session clip') with a destination condition ('into an exact empty slot'). This clearly distinguishes it from siblings like duplicate_clip_loop and duplicate_arrangement_clip, which target different resources or modes.

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

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

The description provides no guidance on when to choose this tool over alternatives such as duplicate_clip_loop or duplicate_arrangement_clip, nor does it explain the prerequisite of planning before execution. 'Plan or duplicate' hints at a workflow but does not specify required steps like dryRun first.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, covering mutability and safety. The description adds the 'Plan or duplicate' distinction, hinting at a dry-run/execute flow, but does not disclose side effects (e.g., whether a new clip is created, whether the source is altered) or the confirmation token requirement beyond what the schema already states. Given the annotation coverage, the description provides modest additional behavioral 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?

The description is a single concise sentence that front-loads the primary purpose. It has no fluff or redundancy, but it is so terse that it omits important usage context, which slightly reduces the efficiency of the definition as a whole.

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 six parameters, a two-phase plan/execute flow, and no output schema, the description is far from complete. It fails to explain when to use dryRun versus actual execution, the meaning of 'loop region', or the expected result of duplication. The schema covers parameters but not the operational context, leaving the agent with insufficient guidance to call the tool correctly without additional investigation.

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 six parameters have descriptions. The tool description adds no parameter-specific meaning beyond what the schema already provides, such as the meaning of dryRun or confirmationToken. Baseline 3 is appropriate since the schema carries the full 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 clear verb (plan or duplicate) and a specific resource ('the current loop region of one exact clip'), which distinguishes it from sibling tools like duplicate_clip (whole clip) or duplicate_arrangement_clip. It is not a tautology and conveys the core action, though 'Plan or duplicate' is slightly ambiguous about the two-phase nature.

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

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

No guidance is given on when to use this tool instead of alternatives like duplicate_clip or duplicate_arrangement_clip. The description does not mention any conditions, exclusions, or preferred usage context, leaving the agent to infer that it is for loop-region duplication without explicit routing.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the description doesn't need to restate safety. The description adds the dual plan/execute behavior and the optional naming behavior, which is useful. However, it doesn't disclose that a dry run is required before execution, that confirmationToken is single-use, or what happens to the original object. The description doesn't contradict 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 a single sentence that front-loads the core action and scope. It's concise and doesn't waste words, though it could benefit from a brief note about the plan/execute workflow.

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 tool with 8 parameters and a two-phase plan/execute workflow, the description is somewhat thin. It doesn't explain the dryRun/confirmationToken flow, which is critical for correct invocation. However, the schema covers most parameters, and the annotations cover the safety profile. The lack of an output schema means the description could have explained what the plan response looks like, but it doesn't.

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 88%, so the schema already documents most parameters. The description adds the meaning of 'name' (for a duplicated track) and clarifies the plan/duplicate dual mode, but it doesn't explain the relationship between dryRun, planHash, and confirmationToken beyond what the schema says. Baseline 3 is appropriate given high 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 description states a specific verb ('Plan or duplicate') and resource ('track, Session scene, or clip'), and mentions optional naming of a duplicated track. It distinguishes the tool's scope from siblings like duplicate_clip and duplicate_arrangement_clip, though it doesn't explicitly name them.

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

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

The description implies a two-phase workflow (plan via dryRun, then execute with confirmationToken) through the schema, but the description itself doesn't state when to use this tool versus alternatives like duplicate_clip or duplicate_arrangement_clip. The dryRun/confirmationToken mechanism is only implied by parameter descriptions, not explained in the tool 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 declare readOnlyHint=false and destructiveHint=false. The description adds 'guarded replacement' and 'preserves unrelated notes', which provides some safety context, but it omits the two-phase plan/apply flow, the need for expectedStateVersion, and the confirmation token mechanism. The description carries partial burden but is incomplete.

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 concise sentences that are front-loaded with the core purpose and include a key safety behavior. No filler or redundancy.

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

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

For a tool with 10 parameters and a two-phase guarded workflow, the description is too sparse. It omits essential workflow details such as the dryRun/confirmationToken flow, how to obtain planHash, and the role of expectedStateVersion, making safe invocation difficult without deep schema inspection.

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 70%, leaving bars, grid, and startBar without descriptions. The description does not add any parameter-level meaning; it relies entirely on the schema. Given the gaps, the description should compensate but does not.