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

With no annotations, the description carries the full burden and does well: it discloses the install/gating dependency, that full-mix capture is refused, and that cursor placement matters before calling. It does not cover failure modes beyond the refusal (e.g. what happens when capture is disabled or the track name is ambiguous).

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

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

Front-loads the action and return payload, then follows with prerequisites and the cursor instruction. The parenthetical metric list is long but each item is meaningful, and there is no filler.

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

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

No output schema exists, so the description must convey return value, and it does via the measured-data enumeration plus the diagnostic intent. Combined with the gating and cursor prerequisites, an agent has what it needs to invoke correctly; only edge-case behavior remains unstated.

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

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

Schema coverage is 100% and both parameters are documented there (track as case-insensitive unique substring, seconds default 10). The description adds no parameter-level detail, so the baseline 3 for a fully documented schema applies.

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

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

States a concrete verb and resource ('capture one verified-isolated track and return MEASURED mix data') and enumerates the returned metric families, so the agent knows this performs measurement, not playback or snapshotting. It does not name a sibling it is distinct from (e.g. profile_track, get_mix_snapshot), so differentiation is implied rather than explicit.

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

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

Gives real preconditions: Post Mortem installed, capture enabled, edit cursor parked where the track is playing, and the explicit exclusion that full-mix fallbacks are refused. It does not state when to prefer this over sibling analysis tools such as profile_track, so context is clear but alternative routing is absent.

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses the snapshot-before-mutation behavior, full rollback on any failure, and re-read verification of the restoration before reporting. It omits permission/auth requirements and the meaning of transaction_id, but the destructive-operation lifecycle is unusually well 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?

Two tight sentences, zero filler. The atomic scope is front-loaded and the rollback guarantee follows immediately, so the most decision-relevant information comes first.

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

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

For a destructive multi-write tool with no annotations and no output schema, the description covers the critical safety behavior (atomicity, snapshot, rollback, verification). It falls short on transaction_id semantics and any indication of what is returned on success, which an agent invoking a transaction tool would benefit from.

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

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

Schema coverage is 67% with three parameters. The description only refers generically to 'envelopes' and adds nothing about the writes item shape beyond what the schema sketch shows, and transaction_id is undocumented in both schema and description. Baseline 3 is appropriate since the schema does most of the work.

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

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

States a specific verb and resource: 'Atomically write several FX-parameter envelopes ... in one undo block.' The plural-plus-atomic framing implicitly separates it from the single-write siblings (write_automation, set_fx_param), but it never names an alternative explicitly, so the differentiation is left to inference.

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

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

The mention of 'several ... e.g. a stereo pair' and 'one undo block' implies the batch/atomic case is the reason to pick this tool, but there is no explicit when-to-use or when-not-to-use statement and no named alternative such as write_automation for single envelopes.

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

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

With no annotations, the description carries the full burden and does well: it discloses atomicity ('ONE undo block'), single round-trip cost, clean failure behavior, and that one Ctrl+Z reverts everything. It does not mention dry_run or the return_partial_results/no-rollback mode, so the error-handling story is only partially told.

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

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

Three tight sentences with the core guarantee (one undo block, one round-trip) front-loaded, followed by the input shape and the motivating use case. No sentence is filler.

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

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

For a batching tool with no output schema and no annotations, the description conveys the essential contract (atomic undo, one round-trip, clean failure). It omits return-value expectations and the dry_run / partial-results paths, which would matter for an agent deciding how to interpret results, but nothing critical is missing.

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

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

Schema coverage is 80%, so the schema already documents dry_run, commands, stop_on_error, and return_partial_results; only undo_label is bare. The description's 'commands: [{type, payload}]' mostly restates the schema example rather than adding format or semantics, so the baseline 3 applies.

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

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

States a specific verb (run) and resource (several bridge commands) with the distinguishing scope: as ONE undo block and one round-trip. An agent can immediately tell this apart from siblings like raw_command or set_fx_param, which act on a single operation.

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

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

Explicitly says to use it for multi-step edits and gives a concrete example ('several set_fx_param calls'), which implicitly routes the agent away from issuing those calls individually. It lacks an explicit when-not (e.g. single-command or read-only cases), so it falls 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?

With no annotations, the description carries the full burden and does so well: it discloses the write-gating flag, where the flag lives, how to set it, that it is read once per bridge load, and that the call is synchronous and blocks the bridge for the render duration. It also explains the fallback behavior for item-based tracks.

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

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

Front-loaded with the action and result before the gating detail, and every clause carries operational weight. The middle section is dense and hyphen-heavy, which slows parsing slightly, but there is little genuine 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?

Covers the hard parts an agent cannot infer: gating, reload semantics, fallback scope, and blocking behavior. The one gap is the output — 'returns its evidence scope' is asserted but never described, and there is no output schema to fall back on, though this is minor relative to the rest.

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 86%, so the schema already documents nearly every parameter including defaults and the edit-cursor/no-selection start behavior. The description adds no parameter-level detail beyond that and does not clarify precedence among the four overlapping targeting options (track, track_contains, target_track_guid, use_selected_track).

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

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

States a specific verb and resource — 'Render a track capture to WAV' — plus the scope of what gets returned ('evidence scope'). It also pre-empts a likely confusion by clarifying that only isolated_track with isolation_verified=true yields true per-track audio, which no sibling tool overlaps with.

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

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

Gives a concrete precondition set (allow_audio_writes=true or the legacy allow_risk_level_3 fallback, plus a reload_bridge or REAPER relaunch) and states explicitly what is NOT required (save_project, preference rights). It does not point to an alternative tool for the full_mix fallback case, so it stops short of full when-to-use guidance.

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

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

With no annotations, the description carries the burden and does disclose real traits: the isolation requirement and the refusal of full-mix fallbacks, plus that it captures audio and returns spectra/tables. It omits whether transport/playback must be running and what 'verified-isolated' entails, leaving some operational behavior unstated.

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

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

Three dense sentences with the key constraint front-loaded and no filler. The 'for YOU to diagnose' emphasis is slightly informal but earns its place by clarifying the division of labor.

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 audio-analysis tool with full schema coverage and no output schema, it covers inputs, output shape, and refusal behavior adequately. The main gap is that 'Same requirements as analyze_track' defers needed detail rather than stating it inline.

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 'tracks' (two or more names) and 'seconds' (default 30). The description's '2+' constraint largely repeats the schema's 'Two or more track names', adding no syntax or format detail, so baseline 3 applies.

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

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

States a specific verb (capture) and resource (2+ tracks' spectra plus a contested-band masking table), and implicitly differentiates from single-track analysis by referencing analyze_track requirements. The 'Post Mortem cross-track masking' framing is jargon-heavy but the core action is clear.

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

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

Gives a clear precondition (2+ verified-isolated tracks) and an explicit when-not ('Full-mix fallbacks are refused'), plus a pointer to analyze_track for shared requirements. It stops short of naming a sibling to use instead for the non-isolated case, so it is not fully prescriptive.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses preconditions (freshness, single-track, 10-second window, no prior comparison), which is genuinely useful. However it does not state what completing the panel actually does to state (persist? notify? irreversible?), what failure looks like when the handoff is stale, or what is returned.

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

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

Two sentences, front-loaded with the action and dependency, no padding. The dense jargon in the second sentence is compact but costs a little readability.

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

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

With no annotations and no output schema, the description should do more: it explains entry conditions but not the resulting state change or failure/error behavior for a tool that clearly mutates onboarding status. Adequate for a two-parameter tool but leaves the outcome opaque.

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

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

Schema description coverage is 100%, so both parameters (track, diagnosis) are already documented in the schema with equivalent meaning. The description adds only the emphasis that the diagnosis must be the 'exact' one you wrote, which is marginal. Baseline 3 applies.

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

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

States a specific verb+resource: send the diagnosis (produced by analyze_track) to the 'Post Mortem panel'. The dependency on a sibling is explicit, so an agent can place it in the workflow. It is somewhat jargon-laden ('Post Mortem panel', 'first-run onboarding'), but the action is identifiable.

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

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

Gives clear sequencing ('After analyze_track'), a prerequisite ('fresh matching 10-second single-track handoff'), and an exclusion ('comparisons cannot complete first-run onboarding'), which routes against compare_tracks. It lacks explicit when-not guidance for any other tool, but the core usage conditions are present.

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

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

No annotations are provided, so the description carries the full behavioral burden, yet it only notes that a readback is returned. It never states that this mutates the project, what happens to unmentioned settings, whether dry_run previews changes, or any permission/auth requirements.

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

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

Single front-loaded sentence with no wasted words, but for a 13-parameter tool it is arguably undersized rather than genuinely concise. Efficiency is high; sufficiency is not.

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

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

A complex 13-param mutation tool with no annotations, no output schema, and 46% schema coverage needs considerably more description than one sentence. Key gaps remain around targeting logic, dry_run behavior, and the FX-related 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 only 46% across 13 parameters, and the description names just three concepts (input/device-channel, arm, monitor) that map loosely to a few params. The numerous FX-related and targeting parameters (fx_guid, fx_scope, fx_index, target_track_guid, etc.) receive no semantic explanation in either place.

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

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

States a specific verb ('Set') plus three concrete resources (MIDI input, record arm, monitoring) and notes the readback return. An agent can tell it apart from the read-oriented sibling get_midi_inputs, though the description never names that sibling explicitly.

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

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

No guidance on when to use this versus alternatives such as track, get_midi_inputs, or link_fx_midi_cc, and no prerequisites or preconditions are stated. The 'return readback' phrase hints at a verify workflow but is not framed as usage guidance.

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

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

With no annotations, the description carries the full burden and does well: it discloses that the project is mutated, that the write is undo-block wrapped, that every leg is attempted even after a failure, and that a dead bridge heartbeat causes a near-instant refusal. It does not state permission/auth requirements, which is the main remaining gap.

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

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

Five sentences, each load-bearing, with the core action front-loaded and the destructive default surfaced immediately after. No filler or repetition of the field list already in the schema.

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

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

For a 15-parameter, no-output-schema mutation tool the description is nearly complete: it covers mutation safety, the destructive default, partial failure semantics, and how results are reported per leg. It leaves dry_run's preview behavior and tempo/low_string interactions to the schema.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning beyond the schema: it explains the seeds array is split across [guitar_l, guitar_r, bass] so the stereo width comes from two performances, and it re-states the replace default and position anchor in operational terms. That is real semantic value on top of the schema text.

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

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

States a specific compound action ('lay down or re-cut a whole four-track jam') and enumerates exactly what it produces: two double-tracked guitars, a locked bass, and drums. The scope is precise enough to separate it from single-part siblings like insert_riff or insert_groove without opening a schema.

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

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

Gives real when-to-use context: by default it REPLACES the four tracks from `position`, and the caller passes replace=false to append instead. It also notes the two guitars get distinct seeds so width is two performances. It stops short of naming alternative sibling tools (e.g. insert_riff, insert_groove) for single-part work.

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

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

With no annotations, the description carries the full burden and discharges most of it: it flags the operation as destructive, notes it is undo-block wrapped, and that it supports dry_run for safe preview. It does not describe return format or what happens to surrounding content, but the key safety behaviors are surfaced.

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 leads with the verb and resource, then adds the three most decision-relevant caveats (destructive, undo-block, dry_run) with zero filler.

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

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

For a 9-parameter destructive tool with no output schema and no annotations, the description supplies the critical safety context an agent needs. It stops short of clarifying the nested position-object options or default behavior, but those are covered by the schema.

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

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

Schema coverage is 67% and the schema itself documents range, track, dry_run, track_contains, target_track_guid, and use_selected_track in detail. The description only echoes the all_tracks and dry_run options and adds no syntax or format guidance beyond the schema, so it is at 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 specific verb (Delete), resource (media items), and scope (in a time range on one track or all_tracks). An agent can immediately tell what the tool does and its targeting breadth without opening the schema.

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

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

It advises confirming intent and notes dry_run support, which implies a preview-then-execute workflow, but it never states when to prefer this tool over sibling mutation tools like raw_command or batch. Usage is implied rather than explicitly framed.

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

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

With no annotations, the description carries the full burden. It discloses that operations are undo-block wrapped, supports dry_run, that fuzzy resolution works against the installed-plugin cache, and that dry_run add requires exact fx_name. It also warns about live recording context. Missing: whether any operation is destructive or reversible beyond undo, permission requirements, or error behaviors beyond the fuzzy resolver note.

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

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

Front-loads the action enumeration well, but the description is bloated with repetitive anti-pattern warnings ('Do NOT precheck', 'do NOT hedge', 'do NOT narrate a plan') that could be consolidated. The all-caps emphasis ('JUST RUN add IN ONE CALL') feels like shouting and harms readability. Several sentences do not earn their place relative to the core purpose.

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 13 parameters, no output schema, and no annotations, the description provides essential context: undo-block wrapping, dry_run semantics, fuzzy resolution behavior, master track targeting, and live-recording awareness. It is missing explicit guidance on fx_index/fx_scope/to_index usage and error conditions for multi-track matches, but covers the most critical behavioral aspects for an agent to invoke 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 69%, so the schema documents most parameters. The description adds meaning for dry_run (preview, and the special case that dry_run add needs exact fx_name, no fuzzy resolution) and for track targeting (track:"master" targets master). However, other parameters like fx_index, fx_scope, to_index, and track_contains are left entirely to the schema. The description adds value but does not fully compensate for the 31% gap.

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

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

States specific verb+resource (FX chain operations) and enumerates the four actions (add, remove, bypass, move). It distinguishes from siblings like scan_fx by explicitly telling the agent NOT to use scan_fx for prechecking. However, the description is cluttered by anti-pattern instructions, which dilute the core purpose statement.

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 states when to use this tool (to add a plugin, just run add in one call) and when not to use alternatives (do NOT precheck with scan_fx). Directly addresses the common failure mode of prechecking and hedging. This is exactly what usage guidelines should do.

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

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

With no annotations provided, the description carries the full burden. It declares 'Read-only,' which is essential and correctly signals safety. However, it discloses nothing about cost, latency, or size on large projects, and the read-only claim is not backed by a readOnlyHint annotation.

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

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

Four terse clauses front-load the resource and enumerate returned content, then close with the safety and timing notes. 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 read-only project-context tool with no output schema and one fully documented boolean parameter, the description is nearly complete: it says what is read, that it is read-only, and when to run it. It could add a note about output size or pagination behavior on large projects, but nothing critical is missing.

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

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

Schema coverage is 100% and the single parameter (include_fx) is fully documented in the schema. The description mentions 'with FX names' but adds no detail on the toggle's semantics beyond what the schema 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?

Specific verb (Read) and resource (the open REAPER project), with an explicit inventory of what is returned: name, tempo, transport, cursor, time selection, tracks with FX names, markers, regions. This distinguishes it from narrow siblings like get_status, get_track_routing, or scan_fx.

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

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

Gives a clear usage condition: 'Run before ambiguous edits,' which tells the agent when this broad read is warranted. It doesn't name specific alternatives (e.g., get_status for a lighter query), so it falls short of the explicit when-not/alternatives bar.

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

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

With no annotations, the description carries the full burden, and it does disclose two meaningful traits: it is non-mutating (does not create or arm) and it enumerates the returned data (state, inclusive-range points, neighbors, automation items, duplicate times, content hash). It omits auth requirements, error conditions, and rate limits, keeping it short of a 5.

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

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

Two tightly written sentences with zero filler, and the read-only, non-creating nature is front-loaded before the return-value enumeration. 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 13-parameter tool with no output schema and no annotations, the description should explain parameter selection and any constraints. It covers returns reasonably but leaves the bulk of the parameter surface undocumented, which is a substantial completeness gap.

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

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

Schema description coverage is only 31% across 13 parameters, so the description is expected to compensate but mentions none of them. Critical inputs such as fx_scope (the only enum), start_time/end_time, param_index, and include_neighbors are left entirely to the bare schema, leaving roughly nine parameters effectively undocumented.

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

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

States a specific verb ('Read') and resource ('FX-parameter envelope'), and the clause 'without creating or arming it' signals it is the read counterpart to write/automation tools. It does not name a sibling explicitly (e.g. write_automation, get_fx_parameters), so an agent must infer the distinction from the resource noun alone.

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

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

Implies usage via 'one existing envelope' and 'without creating or arming it', suggesting it is for inspecting an already-existing envelope. However, it never names the alternative write tool or states a precondition, so the when-to-use-vs-siblings decision is left to inference.

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

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

With no annotations, the description carries the full burden, and it does disclose one important trait: output is auto-paginated. That is genuinely useful context an agent could not infer from the schema. However, it never states that the operation is read-only, nor whether it errs on ambiguity (the schema hints at errors for multi-match track_contains), so behavioral coverage remains partial.

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

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

Two compact sentences, zero filler. The scope constraint and the return-field list lead, and the usage directive follows, so the most decision-relevant information is front-loaded.

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

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

For a 9-parameter tool with no annotations and no output schema, the description does useful work (it substitutes for the missing return-value doc via the field list, and flags auto-pagination). But it leaves the majority of parameters semantically unexplained, so an agent must still reverse-engineer fx_scope, fx_index, and the track-selection cluster from the schema alone.

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

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

Nine parameters with only 56% schema description coverage, and the description explains none of them beyond urging the use of param_index. Non-obvious parameters like fx_index, fx_scope (the only enum), and include_values receive no clarifying text in the description, so the coverage gap is not compensated.

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

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

States a specific verb and resource ('Full parameter list for ONE FX'), scopes it (single FX, not a bank), and enumerates the returned fields (index, name, normalized value, display value). The 'ONE FX' emphasis plus the return-field list clearly separates it from scan_fx, which presumably covers many plugins.

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?

'Scan before setting parameters; prefer param_index from this scan over name matching' gives a clear workflow trigger and an explicit preference over the alternative (name matching), presumably feeding set_fx_param. It stops short of naming the sibling tools it pairs with or stating when this scan is unnecessary.

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

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

With no annotations and no output schema, the description carries the full burden. It implies a read operation and names the returned fields, but says nothing about permissions, error behavior, or what happens with the many targeting parameters. Multiple conflicting target selectors are left completely undisclosed.

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

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

A single efficient sentence with the key information front-loaded. It is arguably too terse given 9 parameters, but there is no wasted wording.

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

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

For a 9-parameter tool with no annotations and no output schema, this description is far too thin. It does not explain the target-selection model, the dry_run semantics, or error conditions, leaving the agent unable to call it confidently.

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

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

Schema coverage is only 56%, and the description adds no parameter meaning at all. With 9 overlapping selectors (track, track_contains, target_track_guid, use_selected_track, fx_guid, fx_index, fx_scope, fx_name_contains) plus dry_run, the agent gets no help on precedence or which combinations are valid.

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

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

States a specific verb (Read) and resource (loaded FX host preset name, index and count), which cleanly separates it from the sibling set_fx_preset. It does not, however, distinguish itself from get_fx_parameters or scan_fx, which an agent might reasonably confuse it with.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives such as get_fx_parameters or set_fx_preset. The agent must infer usage entirely from the name.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'List' implies a read-only operation, but the description never confirms it, and the schema's dry_run and fx_* parameters suggest mutation capability, muddying the picture rather than clarifying it.

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, which is appropriate for a simple listing operation. It is arguably too terse given the nine-parameter schema, but nothing in it is wasted.

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

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

With nine parameters, no annotations, and no output schema, a one-line description is not sufficient. An agent cannot tell whether the parameters affect the result, whether the call is safe, or what form the returned device list takes.

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

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

Schema description coverage is only 56%, and the description mentions none of the nine parameters. Worse, most parameters (track, fx_guid, fx_scope, target_track_guid) appear unrelated to listing MIDI inputs, and the description does nothing to explain how or whether they apply.

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: list MIDI input device names and indices. An agent immediately knows what it returns. However, it does not distinguish itself from the sibling configure_midi_input, leaving the listing-vs-configuring boundary to inference.

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

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

There is no guidance on when to use this versus alternatives such as configure_midi_input, nor any prerequisite context (e.g., whether REAPER must be running or a project open). The one sentence implies a discovery use case but states nothing explicitly.

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

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

With no annotations, the description must carry the behavioral burden. It discloses that reads are bounded-paged and includes instantaneous peak meters, but doesn't cover the read-only nature, permission requirements, or what happens when a target GUID/name matches nothing. Adequate but incomplete for a no-annotation tool.

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

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

Two tight sentences; the first front-loads the full resource list and the second provides the routing guidance. No wasted words.

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

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

For a five-parameter, no-output-schema, no-annotation reader, the description covers the high-level shape but leaves parameter semantics and return format undefined. The 'one hop' snapshot concept is conveyed, yet an agent still lacks enough to invoke correctly without guessing parameter meaning.

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

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

Schema description coverage is 0% and the description does not explain any of the five parameters: limit, offset, max_params, target_track_guid, target_track_name. The word 'bounded page' hints at limit/offset but gives no format, defaults, or semantics for the identifier 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 specific verb ('Read') and enumerates the resources returned (tracks, master, GUIDs, routing, FX, parameter values, peak meters), which is much richer than a tautology. It distinguishes itself from many siblings by being a snapshot reader, though the sibling 'measure' it names is not in the provided list, so the differentiation is only partially verifiable.

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 explicitly routes to 'measure' for integrated audio evidence, a clear when-to-use-this-other-tool condition. However, it doesn't state when NOT to use this tool beyond that one pointer, and the referenced alternative isn't among the listed siblings.

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

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

With no annotations, the description carries the full burden, and it does disclose real behavioral traits: this is a liveness/health probe that also reports whether risk-level-3 operations (audio capture) are permitted. That gating semantics is meaningful context an agent could not infer. It does not explicitly state read-only/no-side-effects, but 'Check' plus the heartbeat framing makes that clear enough.

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 purpose-plus-contents sentence is front-loaded and the imperative directive follows. No filler, nothing redundant.

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

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

There is no output schema, so the description must hint at returns, and it does by listing heartbeat, open project, and risk-level enablement. It omits the response shape/format, which is a minor gap for a no-param status probe.

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 tool takes zero parameters, so there is nothing to document and the baseline is 4. The description correctly implies a no-argument invocation.

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

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

States a specific verb ('Check') and resource ('the bridge is alive inside REAPER') and enumerates what the check covers: heartbeat, open project, and whether risk-level-3 commands such as audio capture are enabled. This clearly separates it from siblings like get_context (project context) and capture_track_audio (the gated operation).

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?

'Call this first' gives an explicit ordering directive, which is strong usage guidance for a preflight tool. It stops short of naming when not to call it or an alternative, so it does not reach the top of the scale.

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

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

No annotations are provided, so the description carries the full disclosure burden. It does declare 'Read-only', which is a genuine safety signal for a tool whose name could suggest a write ('routing'). But it says nothing about error behavior, what happens with zero target arguments, or the shape of the returned routing data. Adequate but thin for an annotation-free tool.

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

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

One tight sentence listing the returned fields plus a two-word safety tag. Front-loaded with the verb and resource, and nothing is padded.

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

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

No output schema, so the description's field enumeration is the only clue to the return value — and it does list them. However, for a read tool with no annotations and no guidance on target selection or mutual exclusivity among track/track_contains/target_track_guid/use_selected_track, an agent is left to guess which selector wins when more than one is supplied.

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 four targeting parameters are fully documented in the schema itself, including the useful 'errors if it matches more than one track' note on track_contains and the 'preferred when available' note on target_track_guid. The description adds nothing about parameters. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Read a track's routing') and enumerates exactly which routing properties are returned: sends, receives, parent bus, volume, pan, phase, automation mode. That is unusually concrete. It doesn't differentiate from siblings like get_mix_snapshot or get_context, which likely overlap in track-level information.

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

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

No when-to-use guidance at all. With 38 sibling tools and multiple read-oriented ones (get_status, get_context, get_mix_snapshot, analyze_track, compare_tracks, profile_track), an agent has no basis for choosing this over them. It also doesn't warn that no target parameter is required, even though 0 of 4 params are required — so calling it with no arguments is legal but its behavior is undefined here.

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

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

With no annotations, the description carries the full burden and does so: it discloses that the tool MUTATES the project, that the pass is undo-block wrapped (one Ctrl/Cmd+Z reverts it), that dry_run previews without writing, that the contour is always applied and amount only scales spread/looseness, and the enforced no-repeat-velocity rule. That is unusually complete behavioral disclosure.

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?

Core purpose and the in-place mechanism are front-loaded, and every sentence adds information (mechanism, contour/amount relationship, follow_lead, dry_run, mutation). It is dense and long-winded in places, but little is wasted.

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

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

For an 8-parameter mutation tool with no annotations and no output schema, the description covers safety (undo wrap), preview path, the follow_lead alternative and its failure mode, and the amount/contour contract. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: it clarifies that amount scales only the random spread on top of an always-applied contour, and that example_through_bar's auto-detect ties to follow_lead's flat-bar requirement. It stops short of documenting seed/map/item_index interactions, so not a 5.

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

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

States a specific verb+resource (humanize an already-on-track drum take) and describes the mechanism: read, plan, write back in place via index-addressed note edits. It is clearly distinguishable from siblings like insert_groove, insert_riff, or apply_automation_transaction, which create or transform differently.

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

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

Gives explicit routing: use follow_lead only when the user hand-humanized the opening bars, and it fails if no flat region remains; otherwise the shared taste model applies. It also directs the agent to prefer dry_run first, naming both when-to-use and the failure condition.

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

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

No annotations are provided, so the description carries the full burden and delivers: MUTATES the project but is undo-block wrapped (one Ctrl/Cmd+Z reverts), dry_run is available, failure is fast and pre-generation when the bridge is dead, and the rendered .mid is kept under rendered-midi/ because REAPER imports MIDI by reference (deleting it yields an empty take). Error behavior (DSL_ERROR carrying the engine's message) is also 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?

Front-loaded with the core action and the mutate/undo caveat immediately after. Sentences are dense and largely earn their place, though the parenthetical asides and the long precedence chains make it heavier to parse than necessary for a 10-parameter tool.

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

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

For a 10-parameter mutation tool with no annotations and no output schema, the description covers mutation semantics, undo, dry_run, refusal conditions, deterministic seeding, target resolution, and error return shape. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds precedence semantics the schema does not fully carry: kit-map resolution order (DSL @map > map arg > drum-config.json > GM Standard) and track resolution order (named track > drum-config default > REAPER selected track). Mutual exclusivity of dsl_text/dsl_path and seed determinism are also restated, so the net add is real but partially duplicative.

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

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

States a specific verb chain and resource: 'Render a drum DSL to MIDI and insert it on a track in ONE call.' It is clearly distinguishable from siblings like insert_midi_file (which consumes an existing .mid) and insert_midi_events, because it names the DSL as the input format and the render step explicitly.

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

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

Gives concrete routing rules: DSL either inline via dsl_text or via dsl_path, 'never both', and points at insert_midi_file for the position object shape. It also states when the tool refuses (dead bridge heartbeat) and supports dry_run for preview. It stops short of explicitly naming the alternative tool to use when the agent already has MIDI, so it is not a full when-not/alternatives treatment.

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

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

With no annotations, the description carries the full burden: it discloses the time reference frame (seconds relative to item start) and channel range (0..15), which are genuine behavioral facts. It does not say whether this mutates existing items, what permissions are needed, or what a dry_run returns, leaving meaningful gaps for an unannotated write tool.

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

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

Three tight sentences, none wasted, with the core action front-loaded. The 'drum-apparatus goldenrule' phrase is terse to the point of being cryptic, but the overall density is appropriate.

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

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

For a 12-parameter mutation tool with no annotations, no output schema, and an events array typed only as bare objects, the description does not supply enough to call it correctly. The critical unknown, the shape of each event object, is left entirely to the agent while the rest of the surface is 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 42%, so the description must compensate, and it partially does: it defines the time basis for start_seconds/length_seconds and enumerates the event kinds for the completely undocumented events array. It adds nothing for fx_guid, fx_index, fx_scope, fx_name_contains, or track selection, and the events item structure remains opaque.

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

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

States a specific verb and resource ('Create a MIDI item') plus the content types it accepts (notes, CC, pitch bend, program changes), which implicitly separates it from insert_midi_file and insert_groove. It never names a sibling, so an agent must infer the boundary rather than being told it.

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

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

The only conditional guidance is 'For drums, enforce drum-apparatus goldenrule before sending,' which is a narrow precondition and refers to an unnamed external concept. There is no statement of when to use this tool instead of insert_midi_file, insert_groove, or insert_riff.

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

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

With no annotations, the description carries the full burden and does disclose one meaningful behavioral trait: it 'Never overwrites existing items unless replace_existing_in_range is true', which is not derivable from the bare boolean schema. It omits other mutation-relevant behavior such as error handling on ambiguous track names, permission/save-state requirements, and what a dry_run returns.

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

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

Three short sentences, front-loaded with the core action and followed by the precondition and the destructive-behavior guard. Nothing is padded, though the middle sentence ('Write the MIDI yourself, then insert') is slightly awkward advice rather than 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 10-parameter mutating tool with nested objects, no annotations, and no output schema, the description covers purpose, precondition, and the one destructive toggle. It still leaves gaps around error behavior, interaction with dry_run, and the fact that only one parameter is required, so it is adequate but not 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 already 80% and most params (track, position, length, midi_path) are self-documenting, so the baseline would be 3. The description adds real value by explaining the semantics of replace_existing_in_range (the only way items in range get destroyed), which the schema leaves as a bare boolean.

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

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

States a specific verb and resource ('Insert a .mid file from disk onto a track at a position'), plus the source and destination, so the agent knows exactly what the call does. It does not, however, explicitly distinguish itself from close siblings such as insert_midi_events, insert_riff, or insert_groove, which an agent must infer from the file-on-disk framing.

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?

'Write the MIDI yourself, then insert' implies the required precondition (a .mid file already exists on disk and is passed via midi_path). That is useful context, but there is no statement of when to choose this over insert_midi_events or how it relates to dry_run/verify_change, so routing guidance is only implied.

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

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

No annotations are provided, so the description carries the full behavioral burden. It warns that MIDI success does not prove controller response and advises a separate audition project, which is useful behavioral context. But it does not disclose whether this modifies the target project, side effects, or what the inserted content is (MIDI clip vs audio).

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

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

Two sentences, front-loaded with the core action and then the workflow guidance. No wasted words, though the parenthetical list of dimensions and the terse warning could be structured more clearly.

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

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

For a 4-parameter mutation tool with no annotations, no output schema, and only 25% parameter coverage, the description is under-specified. It omits parameter semantics, side effects on the project, and how it differs from closely related insert tools, leaving the agent without enough information to call it confidently.

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

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

Schema coverage is 25% – only dry_run has a description – so the description must compensate. It mentions nothing about pitch, start_seconds, or target_track_guid; the only parameter meaning conveyed is indirectly via '13-second melodic test'. This leaves three undocumented parameters, including the required target_track_guid.

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 (insert a 15-second melodic test) and enumerates what it exercises (expression, modulation, sustain, octave range). It is clear what the tool does, though it doesn't explicitly contrast with siblings like insert_riff or insert_groove beyond the audition 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?

It says to use a separate audition project and render with capture_track_audio and audition, which gives some workflow context. However, it doesn't state when to use this versus the many other insert tools (insert_riff, insert_groove, insert_midi_events), and no exclusions are given.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the project MUTATES, that it is undo-block wrapped and reverts with one Ctrl/Cmd+Z, that it refuses in ~0s when the bridge heartbeat is dead, and that the rendered .mid is retained even on a dry run because REAPER holds it by reference.

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

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

Front-loaded with purpose then format, mutation and failure behavior. Dense but every sentence earns its place; the retained-.mid note is slightly peripheral but relevant to dry_run.

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

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

For a 12-parameter mutation tool with no output schema, the description covers format, mode selection, undo behavior and refusal conditions. Minor gaps remain around return shape and the replace/position interaction, but nothing critical for correct invocation is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuinely non-redundant meaning: the step alphabet legend, the case-sensitivity rule for power chords vs single notes, and the seed semantics for distinct double-tracked performances.

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

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

States a specific verb+resource scope: 'Render ONE humanized guitar or bass part and insert it on a track'. The 'ONE ... part' scope and the guitar/bass engine distinction let an agent separate it from generic siblings like insert_midi_file or riff_grid.

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

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

Gives explicit selection rules among its own inputs — bars_text XOR bars_file, omit both for 'demo' — and states the double-tracking workflow (call twice with different seeds). It does not name sibling alternatives such as insert_groove or riff_grid, so it stops short of full routing guidance.

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

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

No annotations are provided, so the description carries the full burden. It does add one genuinely useful behavioral caveat: results don't prove plugins load or samples are available. But it doesn't state whether this is a read-only scan, whether the cache can be refreshed/invalidated, or how large/unbounded a result set may be. That's thin for a discovery tool with zero annotation coverage.

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

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

Two short sentences, front-loaded with the core action, with no filler. The caveat is the single most valuable sentence and it's included without bloat.

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

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

With no annotations, no output schema, no enum hints, and 0% parameter description coverage, the description should be doing significantly more heavy lifting than two sentences. It omits return structure, default behavior for content_roots, and query semantics — important gaps for a discovery tool with three undocumented options.

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 0% — the three parameters (limit, query, content_roots) are completely undocumented in both the schema and the description. The description does not name a single parameter, explain pagination via limit, describe query matching semantics, or clarify that content_roots overrides default search locations. This is the opposite of the compensation a 0%-coverage schema requires.

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 verb and resource ('Discover plugin cache entries and local preset files'), which is clearer than a tautology. However, it's somewhat abstract and, given the sibling tools are almost entirely DAW/reaper-adjacent operations, it isn't clear how this tool relates to (or differs from) get_fx_preset or set_fx_preset. A capable agent can guess the purpose, but the scope is fuzzy.

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's no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named despite 'get_fx_preset' being an obvious sibling. The caveat sentence hints at a limitation ('do not prove plugins load'), which is diagnostic context but not usage routing.

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

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

With no annotations provided, the description must carry the full behavioral burden, but it does not state whether the project is mutated, what permissions are required, whether the mapping is reversible, or how the verification works. It mentions readback verification but gives no operational side-effect 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, which is structurally appropriate. However, it is extremely terse relative to the tool's complexity, so it is concise without being fully adequate.

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 14 parameters, no output schema, and no annotations, the description is incomplete. It omits parameter targeting mechanics, dry_run behavior, error conditions, and what the readback verification actually returns, leaving the agent without needed operational context.

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

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

Schema description coverage is only 36% across 14 parameters. The description implies that 'controller' is a MIDI CC and 'param_index' selects the FX parameter, but it leaves the other 12 parameters—including fx_guid, fx_index, fx_scope, track, scale, offset, and dry_run—unexplained and does not compensate for the low schema coverage.

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

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

The description states a specific verb and resource: 'Map MIDI CC to a scanned FX parameter and verify native parameter-link readback.' It is clear what the tool does, though it does not explicitly differentiate itself from siblings like set_fx_param or configure_midi_input.

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 such as fx, set_fx_param, or configure_midi_input. It also lacks any mention of prerequisites, exclusions, or the dry_run mode already present in 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 are absent, so the description carries the full behavioral burden. It says 'add or delete' but never mentions mutation effects, permission requirements, reversibility, or the dry_run preview capability that exists in the schema. For a destructive-capable tool with only one sentence, this is far too thin.

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

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

It is concise and front-loaded, but the brevity is under-specification rather than efficiency — one sentence cannot carry the needed context for a 10-parameter tool.

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

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

For a 10-parameter mutation tool with no annotations and no output schema, this description is drastically incomplete. It omits parameter guidance, behavior, usage context, and return information — essentially everything beyond a bare action list.

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

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

Schema coverage is only 50%, and the description explicitly names only three of the ten parameters (implicitly via action enum). Key parameters like start/end/position, color, length_bars, marker_index, is_region, and dry_run get no explanation in the description, and several lack schema descriptions too.

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 the resource (markers and regions) and lists the actions available via the enum, giving an agent enough to know it's a marker/region CRUD tool. However, it provides no scope, no distinction from siblings, and the one-liner is too terse to fully separate it from other editing 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?

No when-to-use guidance is given — no preconditions, no indication of when this should be preferred over raw_command or other editing tools. The agent gets no routing help.

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

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

With no annotations, the description carries the full burden, and it does disclose two real behavioral facts: the original tab is restored and media is excluded. It omits what a 'recipe' file contains, what dry_run does, and whether rebuild overwrites anything — meaningful gaps for a mutation-capable tool.

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

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

Two tight sentences, front-loaded with the three operations and followed by the two behavioral caveats. No padding, though the clause order puts the caveats after the action list rather than attaching them to the relevant actions.

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

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

No annotations, no output schema, and 0% parameter coverage — the description must do all the work but only partially does. It never says what a capture/diff/rebuild returns, what the path points to, or what dry_run changes, leaving an agent unable to call this reliably beyond the action name.

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 0%, so the description must compensate. It usefully disambiguates the three action enum values against their operations, but leaves 'path' (recipe file? project path?) and 'dry_run' entirely unexplained in both schema and description.

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

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

The description names a specific resource (a 'mix recipe') and enumerates the three operations — capture, compare, rebuild — which map cleanly onto the action enum. It is distinguishable from siblings like get_mix_snapshot and compare_tracks, though 'mix recipe' itself is never defined, so the resource remains slightly abstract.

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 three actions imply their own usage contexts, but the description never says when to choose this over the nearby alternatives (get_mix_snapshot, compare_tracks, verify_change) or what prerequisites a recipe path requires. Usage is inferable from the enum, not stated.

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

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

With no annotations, the description carries the full burden and does so: it discloses that it reads the saved .rpp on disk (stale on dirty projects), that the result repeats this caveat, that it is slow (up to 600s), and that it returns numbers rather than verdicts. These are exactly the behavioral traits an agent needs before invoking.

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

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

Front-loads purpose before caveats and parameters, and every sentence carries information. It is dense and slightly long, but nothing reads as filler given the complexity of the tool.

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

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

For a 5-param tool with no annotations and no output schema, the description covers purpose, the disk-vs-live caveat, the relay instruction, the numbers-not-verdicts contract, track selection, and the timeout window. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the windowing relationship between bars, start_bar and max_seconds, and the DI preference for the track parameter. It adds usage intent beyond the schema without restating syntax.

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

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

States a specific verb and resource ('profile a guitar stem bar by bar to plan drums') and enumerates the exact outputs produced (onset density, IOI regularity, decay ratio, accent grid, section boundaries). An agent can distinguish this from generic analysis siblings like analyze_track without opening the schema.

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

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

Gives clear operating context: point it at the DI track not the amped stem, and window the slow run with bars/start_bar/max_seconds. It does not explicitly name an alternative sibling or state when NOT to use it, so it stops short of full routing guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden, and for an arbitrary-command escape hatch that burden is heavy. It does not say whether commands mutate the project, whether dry_run is the safe path, what auth/permissions are needed, or what happens when an unknown type is sent. The 'escape hatch' framing implies risk but discloses none of it.

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

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

Two sentences, zero filler, and the critical framing ('Escape hatch') is front-loaded so the agent understands the tool's role immediately. The reference pointer is packed into the same sentence rather than a separate paragraph.

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 open-ended, unannotated command-execution tool with no output schema and a nested payload, the description is thin — it says nothing about mutation risk, return shape, or failure modes. The pointer to bridge/command_schema.md partially compensates by acknowledging the command space is defined elsewhere, which keeps it from being inadequate.

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

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

Schema description coverage is only 25% (dry_run alone is documented), so the description must compensate. It names the two core inputs (type + payload) and points to bridge/command_schema.md for the full command reference, which adds real value. However timeout_ms is never mentioned and the payload's nested structure is left entirely to the external doc.

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 action and resource — 'send any bridge command by type + payload' — and explicitly frames itself as the escape hatch. The line 'Use when no dedicated tool covers it' clearly differentiates it from the long list of specific siblings. The only mild vagueness is what a 'bridge command' actually is, which is deferred to an external reference.

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

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

It gives a direct when-to-use rule: only when no dedicated tool covers the task. That is exactly the routing condition an agent needs to avoid reaching for this over a specialized tool like transport or fx. It stops short of stating when NOT to use it (e.g., never for known operations) or any fallback behavior on failure.

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

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

With no annotations, the description carries the full behavioral burden and does so richly: it reads the saved .rpp file rather than Reaper's live project, carries the same stale-material caveat as profile_track, returns a proposal rather than an auto-beat, explains the percentile rows as attack-strength heuristics, and warns that the grid can read a 16th early if the stem is offset.

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

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

The purpose is front-loaded in the first sentence, and the remaining sentences all add useful caveats, limitations, or workflow routing. The paragraph is dense and long, but nearly every sentence earns its place given the absence of annotations and output schema.

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

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

For a complex, unannotated, no-output-schema tool, the description supplies the workflow position, file-reading behavior, proposal-vs-automation expectation, row semantics, timing risk, and next step. It omits little that an agent would need to invoke and use the result 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%, so the schema already documents all four parameters. The description adds contextual meaning about what 'track' and 'project' represent (a guitar stem and a saved .rpp file), but it does not add per-parameter syntax or format details 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 states a specific verb and resource: 'read a guitar stem's transients into a proposed KICK GRID.' It also positions the tool as 'Step 1 of the drum workflow' and explicitly distinguishes its proposal role from auto-beat generators and from the downstream insert_groove step.

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 places the tool in a workflow ('Step 1'), says the user must correct the proposal, and names the next action ('Transcribe the row the user picks into a DSL, then insert_groove'). It does not spell out when not to use the tool or name an alternative for the same job, 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?

With no annotations, the description carries the full burden, and it does add real value: overwrite protection ('Existing files are refused'), the media-free nature of .RTrackTemplate exports, and a gate precondition. It stops well short of describing what the fx_* and track-targeting parameters actually mutate, and gives no auth/permission or response detail.

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

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

Three short sentences, front-loaded with the two outcome modes, then the safety constraint and precondition. Every clause earns its place with no filler.

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

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

For a 12-parameter mutation tool with no annotations and no output schema, the description covers the core modes and one safety rule but leaves too many parameters and mode interactions (fx targeting, dry_run behavior, template toggling) to inference.

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

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

Schema description coverage is only 42% across 12 parameters, so the description needs to compensate. It clarifies that 'path' must be new/absolute and that tracks are 'explicitly named', but leaves fx_guid, fx_index, fx_scope, template, track_guids and use_selected_track essentially unexplained beyond their bare schema entries.

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

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

States a specific verb and two distinct resource outcomes ('Save to a NEW absolute .rpp path' vs 'export explicitly named tracks as a media-free .RTrackTemplate'), which lets an agent tell it apart from generic save tools. It is slightly clouded by the presence of fx_guid/fx_index/fx_scope parameters that the description never ties into either mode.

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 'or export...' phrasing implies the two selection modes, and 'Requires project save gate' names a precondition. However, no sibling alternative is named and no guidance is given on when to prefer a plain project save versus a template export, or when the fx_* parameters apply.

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

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

No annotations are provided, so the description carries the full burden and does disclose key traits: read-only, restricted to FX already loaded rather than the plugin library, and an explicit anti-pattern to avoid. It does not describe reply size or failure behavior beyond what the schema already covers (track_contains erroring on multiple matches), which keeps it short of a 5.

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

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

Three short sentences, front-loaded with the core action and scope, then safety, then the exclusion. Every clause earns its place with no redundancy.

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

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

For a read-only enumeration tool with no annotations and no output schema, the description covers action, scope, and the key misuse case adequately. It stops short of describing the return shape or how the much-larger include_values reply is structured, which is a minor gap given no output schema exists.

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

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

Schema description coverage is 100% with five well-documented parameters, so the baseline is 3. The description only adds one semantic point — omitting the track selector means the whole project — and says nothing about include_values, target_track_guid, or use_selected_track beyond what the schema already states.

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

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

States a specific verb (enumerate) plus resource (FX and their parameters) and scope (one track or the whole project). It also distinguishes itself from the installed-plugin library and from the fx add resolver, so an agent can place it among siblings like get_fx_parameters and fx without opening schemas.

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

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

Gives an explicit when (enumerate loaded FX), a how (omit the track selector for the whole project), and a hard when-not with the named alternative: 'Never use it to check whether a plugin exists before adding one — that is the fx add resolver's job.' Nothing is left to inference.

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

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

With no annotations, the description carries the burden and does well: it discloses that writes are undo-block wrapped, that dry_run previews without mutating, and that formatted_value triggers a binary search on the display string. Auth requirements and error/failure behavior are still undisclosed.

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?

Terse, front-loaded, and every clause earns its place: purpose, the three value modes with examples, the scan-first routing, and the undo/dry_run traits, all in four compact sentences.

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

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

For a 13-parameter mutation tool with no annotations and no output schema, the description covers the critical value semantics and mutation safety, but leaves the targeting parameters (fx_index, fx_scope, name matching) and error/output behavior unexplained.

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

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

Schema coverage is only 38% across 13 params. The description adds real meaning for the three value parameters (0-1 range, display-string examples, relative syntax) and hints at param_index preference, but fx_index, fx_scope, param_name_contains, and fx_name_contains remain undocumented in both schema and description.

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

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

States a specific verb+resource ('Set one FX parameter') and clearly delineates itself from the read-side sibling by instructing the agent to scan with get_fx_parameters first. It does not distinguish itself from nearby write siblings like set_fx_preset, tune_param, or write_automation, 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?

Gives an explicit prerequisite and alternative ('Scan with get_fx_parameters first and prefer param_index'), plus three concrete input modes (normalized, formatted, relative). No when-not-to-use guidance against sibling mutation tools, so not a 5.

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

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

No annotations are provided, so the description carries the full burden, and it does disclose two useful traits: exact-name matching and a post-load readback verification, plus a plugin-UI limitation. It is silent on mutation side effects, permissions, and failure behavior when the preset name doesn't exist.

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

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

Two tightly packed sentences, with the core action front-loaded and the caveat/alternative following. No filler.

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

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

For a 10-parameter mutation tool with no annotations and no output schema, the description covers the core action and its alternative but leaves targeting/selection and error conditions unexplained. The readback note partially substitutes for an output schema.

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

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

Schema coverage is 50% and 10 parameters exist, so the description should compensate more than it does. It clarifies the required 'name' semantics (must be exact match to a host preset name), but says nothing about the targeting parameters (track, fx_guid, fx_index, fx_scope, use_selected_track).

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

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

States a specific verb+resource: loading a named REAPER host preset with a readback check. It also names a contrasting sibling (add_fx_chain for saved chains), though it doesn't explicitly contrast with get_fx_preset, which is the obvious inverse operation in the sibling list.

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

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

Gives an explicit exclusion: proprietary preset files may require plugin UI, and saved chains should go through add_fx_chain instead. This is real routing guidance, though it stops short of describing prerequisites (e.g. FX must already exist on the target track).

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

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

No annotations are provided, so the description carries full burden. It discloses important behavioral traits: every mutation runs in a REAPER undo block (encompassing undo-ability), supports dry_run for previewing changes, and warns that delete is destructive and requires confirmation. However, it doesn't mention required permissions, rate limits, or the effect of operations on selected tracks beyond the 'exclusive' parameter.

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

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

The description is extremely concise: one line listing actions, one line for behavioral notes, and one warning. It front-loads the action list and then key behaviors, with no wasted words. Each sentence serves a purpose.

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 (17 parameters, no annotations, no output schema), the description is only partially complete. It covers the actions and some critical behaviors (undo, dry_run, destructive delete), but omits guidance on targeting tracks (e.g., which parameters are mutually exclusive), error handling, or output. An agent would need to consult the schema heavily to use it correctly.

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

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

Schema description coverage is 53%, so about half of the 17 parameters lack schema documentation. The description adds meaning for some parameters: set_volume (dB), set_pan (-1..1), and mentions dry_run, but doesn't explain others like track, track_contains, target_track_guid, use_selected_track, or exclusive in detail. The schema itself does provide descriptions for about half, so the description partially compensates but leaves 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 enumerates the operations (add, delete, rename, select, set_volume, set_pan, mute, solo, arm, set_color), which are the exact enum values from the schema. It states a specific resource ('track') and verb set, making the tool's scope clear. However, it doesn't explicitly distinguish itself from siblings like mix_recipe or raw_command, though none of the listed siblings appear to overlap directly with basic track operations.

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 alternatives. It mentions dry_run and confirms delete intent, but there's no indication of when this tool is preferable over raw_command, batch, or other track-related tools. An agent would have to infer usage from the action list 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?

With no annotations, the description must carry the full burden of behavioral disclosure. It does add valuable context: 'Mutations run in an undo block (Ctrl/Cmd+Z reverts).' This tells the agent that changes are reversible. However, it fails to disclose other important traits: whether play/stop are read-only or state-changing, if record requires special permissions, what happens to existing selections, or any rate limits or side effects. The undo note is a positive but insufficient for full transparency.

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

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

The description is a single sentence listing actions and a brief note about undo. It is front-loaded with the tool's purpose and the list of actions, then adds a crucial behavioral note. It is efficient with no wasted words. Could be slightly more structured (e.g., separate sentences) but overall concise.

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 complexity (8 parameters, nested objects, no output schema, no annotations), the description is only partially complete. It lists the actions but does not explain how to use the parameters (e.g., what position, start, end mean in the context of each action), nor does it cover return values or error conditions. The undo note is helpful but not enough to fully guide an agent in all use cases.

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 50%, meaning half of the 8 parameters lack descriptions in the schema. The description itself does not document any parameters beyond listing the action names. For parameters like bpm, end, start, position, seek_play, length_bars, the schema provides some descriptions for end, clear, start, position, but bpm, seek_play, and length_bars have no description. The description does not compensate for these gaps. Baseline 3 is appropriate given moderate coverage and no added meaning.

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

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

The description states a specific verb+resource: 'Transport and project timing' with a clear enumeration of actions (play, stop, pause, record, set_cursor, set_time_selection, set_tempo). This is much clearer than the many sibling tools that deal with FX, automation, MIDI, etc. However, it does not explicitly differentiate from siblings like raw_command or get_status, leaving some ambiguity about when exactly to use this multi-action tool instead of others.

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 listing the available actions, but provides no explicit guidance on when to use this tool versus alternatives (e.g., raw_command). It also lacks prerequisites or conditions for each action. The presence of siblings that might overlap (e.g., get_status for transport state) makes this omission more noticeable.

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

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

With no annotations, the description carries the full burden and does so richly: it discloses the monotonicity assumption and NON_MONOTONE restore-on-violation behavior, the cost profile (baseline plus up to 5 blocking renders), undo-point granularity, and the exact post-failure state (best-observed stays applied, final carries the read-back live value). This is exactly the behavioral detail an agent needs before invoking a destructive, slow tool.

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

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

Front-loaded with the core purpose, and nearly every sentence carries a distinct operational fact. It is dense and slightly run-on, but there is little filler to cut.

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 nested-object tool with no output schema and no annotations, the description still covers the outcome semantics, failure states, reset behavior, and the reported result contents, leaving nothing an agent needs before calling it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond it: delta is relative to the baseline measurement, band_hz requires a prior Post Mortem, tolerance is the convergence window, and the selector combination rule (ONE of fx_name_contains/fx_index AND one of param_index/param_name_contains) is stated. That pairing logic is not obvious from the schema alone.

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

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

States a specific verb and resource: iteratively set ONE FX parameter and re-measure until a target audio outcome is hit, then report the measured result. This clearly distinguishes it from the sibling set_fx_param, which sets a value directly rather than searching toward an outcome.

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

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

Gives strong operational context: it is outcome-driven, ASSUMES monotonic movement, stops on non-monotone, and is expensive enough to warn the user first. Preconditions (allow_audio_writes, one FX selector and one parameter selector) are explicit. It stops short of naming a sibling alternative for the simple non-search case, so 4 rather than 5.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses that it REALLY mutates, that it is undo-block wrapped (one Ctrl/Cmd+Z reverts), that it costs TWO renders blocking the REAPER UI, and that it needs allow_audio_writes. It defines all three terminal statuses including the dangerous UNVERIFIED case (possible partial change, not rolled back).

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

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

It is long, but front-loads the core mechanism and mutation warning, then the status taxonomy, with no filler sentences. Every clause conveys distinct, decision-relevant information for a genuinely complex operation, though the density is near the upper bound.

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

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

There is no output schema, so the description must explain returns — and it does, enumerating the reported audio deltas (LUFS-I always; spectrum/peak/stereo with Post Mortem) and status semantics. Given the operation's complexity and reversibility stakes, nothing an agent needs for a correct call is missing.

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

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

Schema coverage is 100%, so each parameter is already documented. The description adds only light context (track pinned by GUID, payload 'as for raw_command') and does not supply syntax or format details beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb+resource with its distinguishing mechanism: 'Run ONE mutating bridge command with MEASURED proof' via before/after capture. This clearly differentiates it from the raw_command sibling, which applies changes without proof. An agent can select it without opening any schema.

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

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

Explicitly names when to use it (need measured proof of a mutation's effect), when to confirm intent first (destructive command types: delete_track, delete_items_in_range, remove_fx), and when NOT to retry (UNVERIFIED outcomes). It also routes to capture_track_audio for the allow_audio_writes prerequisite.

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

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

With no annotations provided, the description carries the full burden and does well: it discloses snapshotting, reread confirmation, and automatic rollback on any failure, plus the critical destructive semantic that a declared range means replacement rather than merge. It omits permission requirements and what happens to envelope data outside the declared range, keeping it short of a 5.

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

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

Two dense sentences with the transactional guarantee front-loaded and the range-replacement caveat last. No filler, every clause adds information.

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

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

For a 13-parameter mutation tool with no annotations and no output schema, the description covers the safety model well but leaves parameter usage, targeting precedence (GUID vs name vs selection), and sibling differentiation unexplained. Adequate but with clear gaps.

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

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

Schema coverage is only 54% across 13 parameters, so the description should compensate more than it does. It clarifies the semantics of ranges/replacement and implicitly the dry_run-vs-write distinction, but leaves many targeting parameters (fx_index, param_index, fx_scope, param_name_contains) relying on sparse schema text.

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

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

States a specific verb and resource: writing one FX-parameter envelope transactionally, with named sub-behaviors (snapshot, range replacement, reread, rollback). However it does not distinguish itself from the close sibling apply_automation_transaction, which an agent could easily confuse it with.

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

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

The rule 'A declared range always means replacement' implies when the range parameter applies, but there is no explicit guidance on when to choose this tool over apply_automation_transaction, set_fx_param, or get_fx_param_automation. Usage is only weakly implied.

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