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

No annotations exist, so the description carries the full burden and it largely succeeds. It discloses that this is a separate CLI, requires installation and enabled capture, refuses full-mix fallbacks, and requires the edit cursor to be parked at the playing track. This gives the agent important behavioral expectations beyond the schema. It stops short of describing error behavior for missing prerequisites, but the gating reference partially covers that.

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

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

The description is dense but efficient, front-loading the core purpose before prerequisites and caveats. The parenthetical about Post Mortem is a bit heavy, yet every clause earns its place by covering identity, output content, gating, fallback behavior, and setup requirement. It is not bloated, though it could be slightly tightened.

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

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

Given there is no output schema, the description compensates by enumerating the returned measurement categories (FX chain, LUFS, true peak, spectrum, stereo image, silence fraction). It also supplies prerequisites, installation gating, fallback refusal, and an operational instruction about cursor placement. This is sufficient for a narrow diagnostic tool, though it leaves minor gaps around failure modes when prerequisites are unmet.

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 both parameters (track name and seconds default 10). The description adds context about the track needing to be verified-isolated and playing, which relates to the track parameter, but it does not add meaningful syntax or format details beyond the schema. A baseline 3 is appropriate since the structured schema carries the weight.

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 tool ('Post Mortem'), a specific action ('capture one verified-isolated track'), and a concrete output ('MEASURED mix data ... for YOU to diagnose'). It clearly distinguishes itself from siblings by emphasizing it is a separate CLI that returns measured analysis, not a generic track operation. No ambiguity remains about what this tool does.

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

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

The description provides clear context: it is for isolated-track measurement and diagnosis, requires Post Mortem installed and capture enabled, and explicitly refuses full-mix fallbacks. It references capture_track_audio for gating, which orients the agent toward the prerequisite flow. It does not explicitly contrast against all alternatives like profile_track or scan_fx, but the usage conditions are strong.

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 provided, the description carries the full behavioral burden and does so thoroughly. It discloses transactional semantics, failure stopping behavior, partial results, return shape, the no-rollback caveat, and that an undo block is created. This is exemplary transparency.

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

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

The description is dense and front-loaded, with the core purpose stated first. The return-object and failure-mode explanation is lengthy but necessary for a tool with no output schema. It is efficient overall, though it could be slightly better organized to avoid the run-on sentence structure.

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 batch tool with no output schema and no annotations, the description covers the essential context: return values, error behavior, partial results, rollback semantics, and undo behavior. An agent has enough information to invoke the tool correctly and interpret failures.

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

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

Schema coverage is high (80%), so the baseline is 3. The description adds meaningful value beyond the schema by explaining the commands array structure, the multi-step intent, nested batch refusal, and the detailed interaction between stop_on_error and return_partial_results. It does not explain undo_label, but the schema mostly carries the parameter docs.

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

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

The description clearly states what the tool does: it runs several bridge commands as one undo block and one round-trip. It is immediately distinguishable from sibling single-command tools because it emphasizes batching, atomic undo grouping, and the multi-step use case.

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 says to use the tool for multi-step edits and gives a concrete example (several set_fx_param calls). It also states a clear exclusion: nested batches are refused. It does not explicitly name the alternative for single-step commands, but the usage guidance is strong enough that an agent can infer when batch is appropriate.

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

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

With no annotations present, the description carries full behavioral burden and does excellently: it discloses synchronous blocking, the read-once flag behavior, the full_mix fallback, and the rights NOT needed (save_project or preference rights. This is far beyond a bare action statement and adds significant behavioral context.

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

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

The description is dense but front-loaded with the core purpose. The gating sentence is long and contains many parentheticals, making it somewhat hard to parse, but every sentence earns its place by carrying essential prerequisites or behavioral caveats. It could be better structured as bullets, but it is not padded.

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

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

Given the tool's complexity—gating, fallback behavior, synchronous blocking, and no output schema—the description covers most critical operational facts. The main gap is the shape/format of the 'evidence scope' return value, but the description already provides substantial context despite no output schema.

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

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

Schema description coverage is 86%, so the schema already documents most parameters. The description does not add parameter-level semantics beyond the schema, so the baseline of 3 applies. It adds no syntax or format guidance for start_seconds, duration_seconds, or track selectors.

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

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

The description opens with a specific verb and resource: 'Render a track capture to WAV and return its evidence scope.' This clearly states the tool's action and output. The isolation_verified nuance further distinguishes it from generic audio/snapshot tools 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?

The description gives concrete usage context: it only delivers true per-track audio when isolation_verified=true, and item-based tracks may degrade to a full_mix fallback. It also states explicit gating prerequisites and the reload/relaunch requirement, which tells an agent when the tool is callable. It does not name alternative tools, but the context is clear enough for selection.

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

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

With no annotations provided, the description must disclose behavior. It reveals that full-mix fallbacks are refused, returns spectra and a masking table for the user to diagnose (not automated fixing), and references the same requirements as analyze_track. It does not explicitly state read-only nature or permission needs, but the 'for YOU to diagnose' phrasing implies analysis without modification. Some behavioral context is added beyond the schema.

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

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

The description is efficiently written with no filler. It front-loads the purpose, then states a key behavioral constraint (full-mix fallback refusal), and ends with routing to the sibling. Every sentence contributes distinct value.

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

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

For a tool with no output schema and no annotations, the description covers the essentials: what it does, what it returns, constraints, and when to use it. The only gap is that 'same requirements as analyze_track' requires the agent to look up another tool's requirements, but since analyze_track is a sibling, this is acceptable. It does not explain output format details, but the mention of 'spectra' and 'masking table' is sufficient for an agent to understand the result.

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

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

Schema coverage is 100% for both parameters (tracks and seconds), so the schema already documents them. The description adds critical semantics: tracks must be 2+ and verified-isolated, which is a meaningful constraint beyond the schema's generic 'Two or more track names.' It also implicitly ties 'seconds' to capture length, but that is already in the schema. Overall, the description enhances parameter understanding.

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

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

The description clearly states a specific action (cross-track masking analysis) on a specific resource (2+ verified-isolated tracks) and explicitly differentiates from the sibling analyze_track by stating when each is appropriate. The purpose is unambiguous and not a tautology.

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 names analyze_track as the alternative and gives the exact condition for choosing this tool: 'use this when two parts fight for the same frequencies.' It also notes the requirement of verified-isolated tracks and the refusal of full-mix fallbacks, providing clear when-to-use and when-not-to-use guidance.

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

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

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?

With no annotations, the description carries the full burden of disclosing behavior. It states that the record input is always set even when other fields are omitted, that the operation is undoable, that values are read back, and it enumerates the exact error codes. It also explains the I_RECINPUT encoding, which is valuable non-obvious behavior.

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

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

The description is dense but every sentence earns its place: the core action, the omission/default behavior, the return shape, the error list, the undo property, and the prerequisite. It is compact, front-loaded, and contains 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?

This is a complex 9-parameter tool with no annotations and no output schema. The description compensates by specifying the return object shape, the exact encoding formula, all relevant error cases, and the undo behavior, while the schema fully documents parameter semantics. An agent has enough context to select and call the tool correctly.

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

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

The input schema already covers all 9 parameters at 100% coverage, including defaults and 'leave as is' semantics. The description adds a small amount of cross-parameter meaning ('the record input is always set') and a tool prerequisite, but most parameter-level meaning is already in the schema, so the baseline of 3 is appropriate.

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

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

The description names the exact action—'Set one track's record input to a MIDI device and channel'—and adds the optional arm/monitor behavior plus a read-back of the resulting state. This is specific enough to distinguish the tool from siblings like get_midi_inputs, which is referenced as a prerequisite rather than a substitute.

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

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

The description gives an explicit prerequisite ('Use get_midi_inputs first to find the device index') and explains the default/omission behavior for arm, monitor, device, and channel. It does not explicitly list alternative tools or state when not to use configure_midi_input, so it falls just short of a full 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 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 of behavioral disclosure. It explicitly states the tool is destructive, that it is wrapped in an undo block (implying reversibility), and that it supports dry_run. This is significant and valuable, though it does not detail exact consequences or any permission requirements. It covers the most critical behavioral aspects.

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

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

The description is a single, well-structured sentence that front-loads the action and then delivers key behavioral notes. Every phrase earns its place; there is no redundancy or filler. It is an excellent example of concise, effective communication.

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

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

For a tool with 9 parameters, no output schema, and no annotations, the description is too brief. It does not explain return values, error conditions, or how the many track selectors interact (though the schema covers some). The destructive nature warrants more cautionary guidance, such as what happens on success or how dry_run results are returned. Significant gaps remain.

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%, which is moderate. The description adds some parameter context by mentioning dry_run and all_tracks, but it does not elaborate on range semantics, track selection precedence, or length parameters. It provides marginal value beyond the schema, not fully compensating for the undocumented 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 clearly states the action (delete), the resource (media items), and the scope (time range on a track or all tracks). It is specific enough to distinguish from most sibling tools, though it does not explicitly contrast with similar deletion tools like cut_band. The verb+resource+scope pattern is strong.

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 some usage guidance: it flags the operation as destructive, advises confirming intent, and mentions dry_run for preview. However, it does not explicitly state when to use this tool versus alternatives or when not to use it. The guidance is implicit rather than explicit, leaving the agent to infer context.

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

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

With no annotations, the description carries full burden and does so well: it explicitly warns that REAPER is never changed, no model is invoked, no winner is selected, and comparisons measure structural similarity rather than musical quality. It also discloses the preparation prerequisite for evaluate. This is unusually transparent.

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

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

The description is compact and action-oriented, with key caveats front-loaded in the first two sentences. Some domain terms (candidate.dsl, intent.json, wildcard requests) are unexplained jargon, but no sentence is wasted.

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

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

It covers workflow constraints and safety well, but because there is no output schema it leaves return behavior unspecified, and 'export MIDI' has no corresponding action value. The description also doesn't state what feedback does after it records explicit user input. These gaps matter for correct invocation.

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

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

Schema coverage is 75%, so parameters are mostly self-documenting. The description adds meaning by clarifying what actions imply (candidates, intent.json, structural-similarity comparison, audition feedback) and by defining the workshop-folder flow, going beyond the bare 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?

The description states specific capabilities: preparing composition requests, comparing drum DSL candidates, exporting MIDI, and recording feedback. However, it lists 'export MIDI' as an action while the action enum only exposes prepare/evaluate/feedback, leaving that capability unmapped and slightly muddying the tool's boundaries.

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 useful procedural context, such as 'The calling agent writes candidate.dsl and intent.json before evaluate' and 'Local files only; never changes REAPER,' which implies a safe offline workflow. It never names alternatives among the many sibling tools like insert_performance_audition or transcribe_drums, so an agent must infer when this tool is the right choice.

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

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

With no annotations, the description carries the full disclosure burden and does so thoroughly: it states undo-block wrapping, dry_run behavior, the exact dry_run add exception, and the installed-plugin-cache-as-validation model. This prevents an agent from incorrectly treating an absent plugin as an error, which is a non-obvious behavioral trait.

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 longer than average, but nearly every sentence carries operational weight, especially the warnings about scan_fx and live recording. The repeated negative directives ('do NOT precheck... do NOT hedge... do NOT narrate') are emphatic rather than informational, so it is not perfectly concise, but it is front-loaded and well-organized.

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, the description covers the critical add workflow, dry_run exception, track targeting, and sibling routing. It leaves some context unspecified, such as what a successful call returns and the detailed selection semantics for move/bypass, but these are either inferable from the schema or less critical to a first correct call.

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

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

Beyond the 69% schema coverage, the description adds meaningful semantics for key parameters: fx_name is a fuzzy query, dry_run add requires an exact fx_name with no fuzzy resolution, and track accepts 'master' as a special target. It does not narrate per-action parameter combinations for remove/bypass/move, but the schema largely covers those selectors.

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 opening line states the exact resource ('FX chain operations') and enumerates the four distinct verbs: add, remove, bypass, move. It further narrows 'add' semantics with fuzzy plugin-name resolution, making the tool distinguishable from siblings like set_fx_param and scan_fx without inspecting the schema.

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

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

The description gives explicit routing: 'To change a parameter on an FX already in the chain use set_fx_param' and 'Do NOT precheck with scan_fx.' It also prescribes the exact call pattern for adding ('JUST RUN add IN ONE CALL') and for targeting the master track ('track:"master"').

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?

readOnlyHint already marks this as read-only; the description adds concrete context by enumerating what is read (progress, failure, output files, insertion receipt) and explicitly states the tool does not insert into REAPER. This goes beyond the annotation without contradicting 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 short sentences that front-load the read action and then clarify a key side-effect fact. No filler or repetition of schema 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 one-parameter read-only tool, the description covers what the tool reports and its non-mutating behavior. It could add a hint that job_id comes from transcribe_drums, but the core calling context is otherwise 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?

With schema coverage at 0%, the description must carry parameter meaning. It only refers to 'a drum transcription job' without explaining job_id's format, source, or relationship to transcribe_drums, so the agent is left to infer the obvious identifier role.

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 ('a drum transcription job's progress, failure, output files and insertion receipt'). The second sentence explicitly distinguishes it from insertion tools by noting no REAPER insertion occurs, so an agent can separate this from transcribe_drums/insert_drum_transcription.

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 makes the use case clear: retrieve status, errors, outputs, and receipt for a transcription job. It does not explicitly name alternatives or when-not-to-use, though the 'has not inserted anything into REAPER' clause implies it is a read-side check before any insertion step.

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 of behavioral disclosure. It explicitly states that the tool does not create or arm automation, and lists the rich set of returned information (points, neighbors, automation items, duplicate times, content hash). This is valuable non-obvious context beyond what the name conveys.

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

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

Two sentences with no filler. The first sentence states the action and its key non-destructive constraint; the second lists the return payload. 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?

Despite a complex 13-parameter schema, no output schema, and zero annotations, the description leaves considerable gaps: it does not explain how track/fx/parameter selection resolves, what errors might occur, whether results are ordered, or the exact shape of returned data. It gives an overview but not enough detail for correct invocation.

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

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

Schema coverage is only 31% (4 of 13 parameters have descriptions), and the tool description does not compensate for the gap. It mentions 'inclusive-range points' which hints at start_time/end_time, but it does not explain track selectors, fx_guid, param_index, fx_scope, or any of the other parameters. An agent would struggle to build a valid call without opening the schema.

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

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

The description names a specific verb ('Read') and resource ('existing FX-parameter envelope'), and adds the key constraining behavior 'without creating or arming it.' This clearly separates it from write-oriented operations like write_automation or set_fx_param, though it never names a sibling explicitly.

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

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

The phrase 'without creating or arming it' implies a read-only use case, and the returned data hints at inspecting envelopes. However, there is no explicit guidance on when to choose this over get_fx_parameters, get_fx_preset, or apply_automation_transaction, and no stated exclusions or alternatives.

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

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

With no annotations, the description carries full disclosure burden. It adds useful behavioral information: auto-pagination, complete one-FX result set, and the returned value types. It implies a read-only scan operation but does not explicitly state side effects, permissions, or error behaviors.

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 front-loaded sentences: the first establishes operation and output; the second gives actionable usage guidance. 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-oriented list tool with a partially descriptive schema, the description supplies the key missing facts: the result covers one FX, is auto-paginated, and returns specific value fields. It does not address error cases, but the schema covers track-selection edge 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 only 56%, and the description adds little direct parameter detail. It does signal that param_index is the preferred identifier over name matching, but it does not explain fx_scope, fx_name_contains, or param_name_contains semantics beyond the schema.

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

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

States a specific action and scope: 'Full parameter list for ONE FX', and enumerates return fields (index, name, normalized value, formatted display value). This distinguishes it from sibling scanners like scan_fx and mutators like set_fx_param.

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 instructs to 'Scan before setting parameters' and to prefer param_index over name matching, giving the agent a clear use context. It does not name alternative tools or state when not to use it, so it stops short of a 5.

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

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

The description goes far beyond the readOnlyHint annotation: it discloses the exact return shape ({name, valid, index, count, scope}), the semantics of `valid` when no named preset exists, the selector fallback order, and the complete list of error codes. This level of behavioral detail is exemplary and removes guesswork for the agent.

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

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

Every sentence carries essential information: the operation, selector rules, return contract, domain boundary, errors, and the sibling write tool. There is no filler or repetition; the description is dense yet immediately scannable with a front-loaded purpose statement.

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

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

Given 8 parameters, 0 required, and no output schema, the description covers all essential context: how to disambiguate track/FX selection, what the response contains, when `valid` is false, which error conditions to expect, and the limitation to host presets. An agent can invoke this tool correctly and interpret its result without needing additional help.

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

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

The input schema already documents all parameters at 100% coverage, so the baseline is 3. The description adds value by consolidating the selector precedence ('fx_guid, else fx_index + fx_scope, else fx_name_contains') and by tying parameters to the returned `scope` field, which gives a working model of how the parameters interact rather than just enumerating them.

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

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

The description opens with a specific verb-resource pair ('Read-only: report which REAPER host preset is loaded on one FX') and clearly scopes the tool to a single FX. It even distinguishes itself from plugin-preset browsers and names the sibling set_fx_preset for the write counterpart, making the purpose unmistakable.

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

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

It says when to use it (read-only reporting), gives explicit selector precedence for both track and FX, and names the alternative tool for mutation ('Use set_fx_preset to change it'). It also states a boundary condition ('Only sees REAPER host presets, not a plugin's own preset browser'), which helps an agent decide whether this tool is appropriate.

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

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

Annotations already provide readOnlyHint=true, and the description reinforces that with 'Read-only.' It goes beyond the annotation by disclosing the exact return shape, the fixed magic numbers 63 and 62, and the behavioral meaning of configurable=false for high indices. This gives the agent concrete expectations without requiring an output schema.

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

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

Three sentences, each earning its place: purpose and read-only nature, return shape, and the actionable relationship to configure_midi_input. It front-loads the key behavior and packs important constraints into a compact, readable definition.

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

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

Despite having no output schema, the description fully specifies the return value structure and the special index semantics. It covers how the result should be used with a sibling tool, which is the main context needed for a zero-argument read-only listing tool. Nothing an agent needs to call this 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?

The tool takes zero parameters, and the input schema is already empty. The description explicitly states 'Takes no arguments,' which removes any doubt about parameter semantics. With 100% schema coverage and no parameters to explain, the description adds appropriate confirmation without needing more.

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: list the MIDI input devices REAPER can see. Clearly distinguishes itself from the sibling configure_midi_input by framing itself as the read-only lookup step and explicitly noting the device-index contract. Even without opening the schema, an agent knows exactly what this tool does.

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

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

Explicitly instructs when to call the tool: 'Call this before configure_midi_input to find a device index.' It also provides a constraint on usage by explaining that configurable is false above index 63 and that configure_midi_input cannot set those. This is clear routing guidance with no ambiguity.

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 burden. It does state 'Read-only' which is a behavioral trait. However, it doesn't disclose error behaviors beyond what the schema already says (e.g., errors on ambiguous names, errors on nothing selected). The schema already documents those error conditions, so the description adds only the read-only trait. It doesn't mention what happens if the track doesn't exist, or whether the returned data has any particular structure. A 3 is appropriate – minimal but not misleading.

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

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

One sentence with zero waste. The core purpose is front-loaded ('Read a track's routing'), followed by a compact field list, and the read-only trait is stated at the end. Every word earns its place.

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

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

For a read-only query tool with 100% schema coverage, the description is nearly complete. The only gap is that it doesn't describe the return format or how the routing data is structured, but with no output schema, a brief note on what the response contains would help. However, the field list in the description partially covers this. The tool is simple enough that this is a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters thoroughly, including precedence rules and error conditions. The description adds no parameter-specific information beyond what the schema provides. Baseline 3 is correct when the schema does the heavy lifting.

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

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

The description states a specific verb ('Read') and resource ('a track's routing'), and enumerates the exact fields returned (sends, receives, parent bus, volume, pan, phase, automation mode). It also explicitly declares 'Read-only', which distinguishes it from mutation tools like write_automation or set_fx_param. This is a clear, specific 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?

The description says 'Read-only' and the tool name clearly indicates a read operation, which implies when to use it (when you need routing info) versus mutation tools. However, it doesn't explicitly name alternatives or state when not to use it. The sibling list includes get_mix_snapshot and profile_track which could overlap, but the description doesn't address that distinction. Clear context but no explicit exclusions.

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

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

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?

With no annotations present, the description carries the full burden and covers it thoroughly: writes are conditional on dry_run, source changes and duplicates are refused, original audio/mute/tempo are preserved, and one undo reverts the insertion. These behavioral guarantees go far beyond the schema and explain what an agent can expect and what it cannot do.

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 dense sentences, each carrying information: purpose, prerequisites, refusals, validation mode, non-destructive guarantees, undo. It is front-loaded with the main function and contains no filler.

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

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

For a complex mutation tool with no annotations and no output schema, the description is unusually complete about constraints and side effects. It still leaves some gaps — the return/result format and the exact meaning of job_id/track are not stated — but the behavioral guarantees and dry_run escape hatch make it sufficient for most invocation decisions.

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 25%, so the description must compensate; it does add meaning for dry_run ('validates without writing') and map_name ('catalog map_name'), but it never explains job_id or track, which are the two required parameters. The phrase 'original source item' hints at context but does not explicitly map parameters to their roles.

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 opening clause uses a specific verb and resource — 'Map a completed transcription to a drum kit and insert verified notes into REAPER' — and the rest of the description adds distinctive scope (verified notes, original source item, empty destination range). This differentiates it from generic insert_* siblings like insert_midi_events or insert_groove without requiring schema inspection.

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 states clear prerequisites ('Requires the original source item and an empty destination range') and explicit refusal conditions ('Refuses source changes, duplicate jobs and active transport'). It doesn't explicitly name sibling alternatives or say 'use this instead of X', so it stops short of a 5.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly. It discloses that the tool MUTATES the project, wraps changes in an undo block, preserves rendered .mid files because REAPER imports by reference, refuses when the bridge heartbeat is dead, and explains the kit-map precedence chain.

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

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

The description is dense but front-loaded with the core action, then organizes constraints and precedence into connected clauses. Every sentence adds operational value: mutation safety, dry-run, render persistence, kit-map resolution, track selection, and error handling. Nothing 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 10-parameter, mutation-heavy tool with no output schema, the description is remarkably complete: it covers failure modes, render persistence, track resolution, and precedence. The only notable gap is the success return shape; the agent knows errors return DSL_ERROR but not what a successful insertion returns.

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?

Although schema coverage is 100%, the description adds critical semantics: dsl_text and dsl_path are mutually exclusive, same seed plus same DSL produces identical MIDI, target_track_guid wins over other selectors, and use_selected_track is ignored when another selector is present. These details go well beyond the raw parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Render a drum DSL to MIDI and insert it on a track in ONE call.' This clearly distinguishes the tool from siblings like insert_midi_file and insert_midi_events, which operate on already-existing MIDI or event data rather than a drum DSL.

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

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

The description gives clear operational context: DSL must be provided either inline or via file, 'never both'; dry_run is supported; track selection precedence is spelled out; and errors like DSL_ERROR are explained. It does not explicitly contrast this tool against sibling insertion tools, but the DSL-specificity and reference to insert_midi_file for position semantics provide enough 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 present, the description carries the full burden and succeeds: it states there is no humanizing, explains event timing, gives the drum velocity rule, lists the return shape, details error conditions and their side effects (nothing written on BAD_PAYLOAD, item deleted on INSERT_FAILED/VERIFY_FAILED), and notes the operation is undoable.

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?

Although dense, every sentence earns its place: purpose, sibling routing, timing clarification, domain rule, return shape, error behavior, and undoability. It is front-loaded with the core action and does not repeat the schema's parameter-by-parameter details.

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

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

For a complex tool with 8 parameters, no annotations, and no output schema, the description is remarkably complete. It covers the return value, error semantics, rollback behavior, and selection criteria, while the fully-covered schema handles parameter-level detail.

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

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

Schema description coverage is 100%, so the schema already documents every parameter thoroughly. The description mostly restates event-time semantics already present in the schema and adds no new per-parameter meaning beyond that, meeting the baseline for full schema coverage.

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

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

The description opens with a specific verb and resource: 'Create a new MIDI item on one track from a list of raw events.' It also explicitly names what this tool is not for by distinguishing itself from insert_midi_file, insert_groove, insert_riff, and cut_band, so an agent can clearly differentiate it from siblings.

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

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

The description provides direct when-to-use guidance: 'Use this for exact, hand-specified MIDI' and then lists the exact alternative tool for each other scenario (.mid exists, humanized drums, humanized guitar/bass, four-track jam). This leaves no ambiguity about tool selection.

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

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

With no annotations, the description carries the behavioral burden and it discloses the most important side effect: existing items are never overwritten unless replace_existing_in_range is true. It also clarifies that the tool inserts rather than generates MIDI. It does not describe return values or error cases, so it is not a perfect 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, each purposeful: the action, the overwrite caveat, and the routing to alternatives. The most important guidance is front-loaded before the sibling list.

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

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

For a 10-parameter tool with no annotations and no output schema, the description is concise but covers the core call path, the safety behavior, and sibling selection. It leaves some details, such as default position and return value, to the schema or inference, but the essential decisions an agent must make are all represented.

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

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

Schema description coverage is 80%, so the schema carries most parameter documentation; the description adds value by clarifying replace_existing_in_range, which otherwise lacks a schema description. It does not explain loop or default behavior for position, but the high schema coverage keeps this at baseline 3.

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

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

States a specific action and object: inserting an existing .mid file from disk onto a track at a position. It also differentiates from siblings by noting the file must already exist ('Write the MIDI yourself') and by naming alternative tools for generated, humanized, or guitar/bass content.

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

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

Explicitly tells the agent when to choose this tool: when a .mid file already exists on disk. It names insert_midi_events, insert_groove, and insert_riff as alternatives with their exact conditions, leaving no ambiguity about 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?

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, the description carries the full behavioral burden. It mentions a verification readback, which is helpful, but it does not disclose that linking modifies project state, whether it is destructive, or what else happens beyond verification. The presence of dry_run in the schema hints at mutation, but the description does not state 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?

One tight sentence with no filler; the action and verification outcome are front-loaded. It is concise rather than under-specified.

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

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

For a 14-parameter mutating tool with no annotations, no output schema, and rich sibling context, a single sentence is not enough. It omits side effects, prerequisites, selection precedence, and return/verification details.

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

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

The description adds meaning to the two required params (controller = MIDI CC, param_index = scanned FX parameter), which lack schema descriptions. However, it does not clarify scale, offset, channel, or the track/FX selection semantics, and schema coverage at 64% leaves several params underdocumented.

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 ('Map MIDI CC to a scanned FX parameter') and adds a distinct verification behavior ('verify native parameter-link readback'). It clearly differentiates the tool from value-setting siblings like set_fx_param, though it does not explicitly name an alternative.

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

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

The phrase 'scanned FX parameter' implies that the intended workflow is linking after a scan, and it is clear the tool is for MIDI-CC mapping rather than generic parameter editing. But there is no explicit when-to-use guidance, preconditions, or named alternatives among the many FX/MIDI sibling tools.

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

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

Annotations 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 provided, the description carries the full burden, and it does disclose meaningful behavioral constraints: existing files are refused, the export is media-free, and a project save gate is required. However, it does not cover side effects, failure modes, return behavior, or what the save gate entails, leaving notable gaps for a 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?

The description is two concise sentences, front-loading the two main modes and then immediately stating the key constraint about existing files. Every sentence earns its place, with no filler or repetition of schema content.

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

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

For a 12-parameter tool with no annotations and no output schema, the description covers core constraints but is not fully complete. It omits the meaning of the save gate, what dry_run returns, how template selection interacts with track selectors, and overall expected behavior in edge cases. The rich schema descriptions compensate somewhat, but the global workflow is still underspecified.

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

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

Schema description coverage is 75%, so most parameters are already documented. The description adds a high-level distinction between .rpp and .RTrackTemplate modes, but it does not explain the undocumented parameters (template, track_guids, path) or clarify how they relate to the two modes beyond what the schema already says.

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

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

The description clearly states two concrete operations: saving to a new absolute .rpp path and exporting explicitly named tracks as a media-free .RTrackTemplate. It further distinguishes itself by noting that existing files are refused, making the tool's core purpose and scope unambiguous relative to sibling tools.

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

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

The description provides no guidance on when to choose this tool vs alternative siblings, and does not name or contrast any alternatives. While it mentions a prerequisite (project save gate) and the two modes, it leaves the agent to infer the appropriate context for invoking the tool.

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

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

With no annotations, the description carries the full burden, and it does disclose the key behavior: the tool is read-only and lists only FX already loaded, not the plugin library. It leaves response shape and error behavior to inference, but those are less critical for a simple read-only enumeration.

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 tightly written sentences with the purpose front-loaded. Every clause adds a distinct constraint or routing fact, and there is no filler.

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

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

For a read-only scan tool, the description plus detailed schema covers the important decisions: scope, selector precedence, and the loaded-versus-library distinction. The absence of an output schema leaves the exact reply structure unspecified, but that is a minor gap for this tool.

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

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

Schema coverage is 100% and every parameter already has detailed semantics: matching rules, selector precedence, and error conditions. The description adds the 'whole project when selector omitted' default, which is helpful, but the schema carries most of the parameter burden.

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

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

The verb 'enumerate' plus the resource 'FX and their parameters' and the scope 'one track or the whole project' are specific and unambiguous. It clearly rules out the installed-plugin library, but it does not differentiate itself from the similarly named sibling get_fx_parameters, so sibling distinction is incomplete.

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

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

The description gives an explicit when-not: never use it to check plugin existence before adding, and names the alternative as the 'fx add resolver'. It also tells how to select scope by omitting the track selector, providing clear 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?

With no annotations, the description carries the full behavioral disclosure burden. It usefully discloses undo-block wrapping, dry_run support, and the bridge's binary-search behavior for formatted_value matching. It does not describe conflict/error behavior when multiple value modes are provided, but the transparency is still strong.

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

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

The description is compact and front-loaded: it states the action, then the value modes with concrete examples, then the workflow and safety features. Every sentence carries useful information with no repetition or filler.

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

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

For a 13-parameter polymorphic tool with no output schema and no annotations, the description gives the core semantics and workflow but leaves important gaps. It does not explain how to select the target FX via fx_index/fx_scope/fx_name_contains, nor what happens if multiple value or selector modes are provided, so an agent may still need to infer or experiment.

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 38%, so the description must compensate for sparse parameter documentation. It adds meaningful semantics for normalized_value, formatted_value, relative, and param_index. However, key FX-targeting parameters such as fx_index, fx_scope, fx_name_contains, and param_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?

The description opens with 'Set one FX parameter,' a specific verb and resource. It also names the companion workflow tool, get_fx_parameters, and clearly distinguishes the action from scanning or preset-level 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?

It gives explicit operational guidance: 'Scan with get_fx_parameters first and prefer param_index' and explains the three value-supply modes. It does not enumerate when-not-to-use alternatives like tune_param or set_fx_preset, but the intended workflow is clear.

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

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

With no annotations, the description must carry the behavioral burden. It discloses verification behavior and a plugin-UI dependency, but it does not state whether the operation mutates the project, what happens on failed readback, or whether it is reversible.

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

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

Two short sentences front-load the primary action and include a high-value caveat and sibling route without filler.

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

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

For a 10-parameter tool with no annotations or output schema, the description is thin on overall behavior: it hints at 'verify readback' but not the return value, mutation/safety profile, or failure semantics. The rich schema covers parameters, so the description is minimally viable but leaves notable 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 90%, so the parameter descriptions in the schema already carry most semantic weight. The description adds only 'exact' matching and the saved-chain distinction; it contributes no additional parameter-level detail.

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

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

States a specific action ('Load an exact REAPER host preset name') and an observable outcome ('verify readback'), which clearly distinguishes it from get-oriented and chain-insertion siblings. It also names add_fx_chain as the tool for saved chains, reinforcing scope.

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

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

The description gives a concrete exclusion ('saved chains use add_fx_chain') and a caveat for proprietary preset files, which helps an agent route to an alternative. It does not explicitly spell out when to prefer this over get_fx_preset, but set vs. get is clear 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 present, so the description carries the full disclosure burden. It usefully states that all mutations run in a REAPER undo block, supports dry_run, and that delete is destructive. These are valuable behavioral traits that would not be obvious from the schema. However, it omits other side effects (e.g., whether select changes the current project selection) and what the tool returns, leaving some transparency gaps.

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

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

The description is two sentences long, front-loads the list of supported operations, and follows with the most critical behavioral warnings. Every sentence 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 tool with 17 parameters, one enum, and no output schema or annotations, this description is too minimal. It does not map actions to their required parameters (e.g., rename needs name and new_name; set_color needs a track selector and color object), nor does it explain the precedence among the five track-selection parameters. The schema covers some of this, but the description should summarize the selection rules and per-action parameter usage to make the tool reliably callable.

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

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

The schema only describes about half of the parameters, so the description needs to compensate. It does add units for volume (dB) and range for pan (-1..1), which are absent from the schema. But it does not explain the semantics of new_name, mute, solo, armed, select, or how parameters map to actions, leaving significant gaps for a polymorphic tool.

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

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

The description clearly identifies the tool as handling track operations, listing the specific actions it can perform (add, delete, rename, select, set_volume, set_pan, mute, solo, arm, set_color). This differentiates it from sibling tools focused on mixing, transport, FX, or markers. However, it is phrased as a domain label rather than a verb+resource statement, leaving a small ambiguity about the exact effect on tracks.

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

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

The description gives two usage cautions (dry_run for preview, delete destructive) but does not explain when to choose this tool over siblings such as batch or raw_command, nor does it state prerequisites like needing a target track identifier. There is no explicit guidance about which operations to use for which scenario, so the agent must infer usage from the schema.

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

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

With no annotations provided, the description carries the full burden and does so well. It discloses async background execution, possible model-weight downloads on first use, local-only audio handling, no project mutation, and the fact that tom and cymbal articulations are estimates. This is rich, honest behavioral context beyond a simple one-line summary.

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?

Six sentences, each earning its place: the main action is front-loaded, followed by source selection, workflow, prerequisites, side effects, and a quality caveat. There is no redundancy or filler.

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

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

For a tool with no output schema and no annotations, the description covers the key workflow, return value, prerequisites, and safety profile. The main gap is parameter semantics: device, threads, and separate are not explained, and source-parameter precedence is unclear. Still, the description is substantially complete for invoking the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the source-selection concept ('one selected audio item or a named source track/item') but does not describe the semantics of device, threads, or separate, nor which source parameter takes precedence. The agent is left guessing about meaningful options like cuda vs cpu, thread count, and what 'separate' actually controls.

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: starting a local audio-to-drum-MIDI analysis in a background worker using an audio item or named source track/item. It clearly distinguishes itself from the related get_drum_transcription and insert_drum_transcription tools by framing itself as the initiation 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 provides clear context: use a selected audio item or named source track/item, expect a job_id, poll get_drum_transcription, then insert_drum_transcription. It also names prerequisites like the transcription environment and ffmpeg. However, it does not explicitly say when not to use this tool or compare it with alternative analysis tools such as analyze_track or compare_tracks.

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, the description carries the full burden and does substantial work: it discloses snapshotting, inclusive-range replacement, reread confirmation, automatic rollback on failure, and the key invariant that declared ranges always mean replacement. This is strong behavioral disclosure, though it omits details like permission needs or undo behavior.

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

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

Two sentences with no redundant wording. The core action and transactional guarantees are front-loaded, and the key range-replacement rule is stated as a crisp closing guideline.

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 output schema, a two-sentence description is insufficient on its own. The schema helps, but the description does not cover selection precedence, dry_run, fx_scope semantics, or expected return values. It provides the core transactional contract but leaves meaningful gaps for safe invocation.

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

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

Schema coverage is 54%, slightly above the low threshold, so baseline is 3. The description clarifies the meaning of 'ranges' by stating that a declared range always means replacement, adding some value beyond the schema. However, it does not explain the shape or interaction of points, clear_existing_in_range, or fx_scope, leaving parameter semantics under-specified.

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

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

The description uses a specific verb ('Write') with a clear resource ('one FX-parameter envelope') and distinct transactional semantics. This differentiates it from siblings like apply_automation_transaction, which likely handles broader automation changes.

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 transactional framing implies this tool is intended for safe, rollback-protected automation writes, but it never explicitly states when to prefer it over alternatives like set_fx_param, get_fx_param_automation, or apply_automation_transaction. No exclusions or alternative routing are provided.

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