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

Annotations already establish that this is a non-read-only, non-destructive, closed-world mutation. The description adds the important behavioral constraint that a song can have 16 instruments, but it does not explain what happens if that limit is reached or what the operation returns.

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

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

Two short sentences, front-loaded with the core action and followed immediately by the key capacity constraint. There is no wasted text.

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

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

For a simple mutation tool with full schema coverage and annotations covering its safety profile, the description is largely complete. It could be stronger if it noted the behavior at the 16-instrument limit, but that is a minor omission.

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

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

Schema description coverage is 100%, so the input schema already fully documents voice, cutoff, volume, and resonance. The description adds no parameter-level meaning beyond the schema, which is the expected baseline when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: adds an instrument to the song. It also gives a capacity constraint. It does not differentiate the tool from siblings such as update_instrument or remove_instrument, which keeps it from a 5.

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

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

The description does not say when to use this tool versus update_instrument, remove_instrument, or list_voices. Usage is only implied by the operation name and the 16-instrument limit.

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

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

Annotations already declare this is a non-read-only, non-destructive, closed-world mutation. The description adds meaningful behavioral context beyond that: it returns the new pattern's index, the pattern is silent until used in the arrangement, and notes are absolute pitches constrained by key and scale.

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

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

The description is three tight sentences with the core action and return value front-loaded. Every sentence carries useful information 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 moderate-complexity tool with full schema coverage and no output schema, the description covers the return value, workflow implication, and key note constraints. It leaves out sibling alternatives and drumkit-specific handling, which the schema covers but an agent comparing tools might still want in the description.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds value by explaining that notes are absolute pitches, that key and scale do not transpose them, and that notes must fit the selected key and scale.

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

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

The description clearly states the verb and resource: it adds a pattern and returns its index. It does not explicitly differentiate itself from the very similar sibling clone_pattern, so it falls short of a 5.

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

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

The line 'It won't play until the arrangement uses it' hints at the workflow after adding a pattern, but the description never states when to use add_pattern instead of clone_pattern, import_midi, or other creation paths. Usage is implied rather than explicitly guided.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds genuinely new content by disclosing the returned fields and the non-starting behavior. It stops short of describing failure behavior when the app is down, which is the main remaining unknown.

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

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

Two sentences, front-loaded with purpose and capped by the key exclusion. No filler or restatement of the title.

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

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

With no output schema, the description carries the burden of explaining returns, and it enumerates version, song summary, and playback/export state, which is adequate for a status probe. 'Song summary' and 'export state' remain slightly under-specified (what fields, what states), keeping it below a 5.

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 the baseline is 4; there is no parameter semantics to explain and the description correctly says nothing about inputs.

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 ('Reports') and resource ('whether Bosca Ceoil Blue is running') and enumerates exactly what comes back: version, song summary, playback and export state. This clearly separates it from siblings like launch_app, quit_app, and export_status.

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 clause 'Doesn't start the app' explicitly excludes the most likely confusion and implicitly routes the agent to launch_app for that need. However, it doesn't state the positive trigger conditions (e.g., 'call before any operation to confirm the app is up') or what happens if the app is not running.

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

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

Annotations already indicate the tool is mutating (readOnlyHint=false) but non-destructive. The description adds that a new index is created and that the copy is meant as a starting point for variation, but it does not explain what is returned, such as the new pattern index, which matters because there is no 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?

The description is a single front-loaded sentence with no wasted words. It immediately communicates the action and destination.

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 tool with no output schema, the description covers the basic action but omits important context such as how to identify the source pattern and what the caller gets back after cloning. It is minimally adequate but leaves meaningful gaps.

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

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

Schema coverage is 0%, so the description must compensate for the bare "pattern" integer parameter. The description only says a pattern is copied; it does not clarify whether the parameter is the source pattern index, its valid range, or how patterns are identified.

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: "Copies a pattern to a new index." This clearly distinguishes the core action from update_pattern or remove_pattern, though it does not explicitly name those siblings as alternatives.

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

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

"As a starting point for a variation" gives an implied use case for cloning rather than creating or editing. However, it gives no explicit guidance on when to choose clone_pattern over add_pattern or update_pattern, nor any prerequisites.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description still adds real value by disclosing the replacement behavior and the exact fallback state when instruments/patterns are omitted (one Grand Piano, one empty pattern on bar 0). It omits that replacing a song with unsaved changes requires discard_changes=true, which the schema carries instead.

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

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

Three short sentences, front-loaded with the destructive replacement, then the construction capability, then the default outcome. Every sentence carries information; a slightly crisper ordering could have put the default-behavior note before the sales pitch, but nothing is wasted.

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

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

For a 12-parameter destructive constructor with no output schema, the description covers what the tool replaces and what an empty call produces, and annotations cover the destruction risk. The main remaining gap is the unsaved-changes/discard_changes interaction, which is documented only in the schema.

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

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

Schema description coverage is 100%, so per-parameter meaning is already fully documented, including defaults, ranges and the discard_changes guard. The description only groups the parameters conceptually ('settings, instruments, patterns and an arrangement') without adding syntax or constraints beyond the schema, which matches the baseline of 3.

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

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

States a specific verb and resource ('Replaces the open song with a new one') plus the optional one-shot construction from settings, instruments, patterns and arrangement. It does not name a sibling it is not (e.g. update_song, open_song), so differentiation is left to inference, but the destructive 'replace' framing is unambiguous.

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

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

'This is the quickest way to write a song' is a weak usage cue rather than an explicit when-to-use rule. Nothing tells the agent when to prefer update_song for modifying an existing song, or open_song for loading one; usage is only implied by the destructive replacement semantics.

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

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

Adds real behavior beyond the annotations: writes are whole-bar starting at at_bar, other bars are untouched, and an omitted loop defaults to the whole song. However it never warns that replace_all clears the remainder of the timeline, which matters for a tool annotated destructiveHint=false.

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

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

Four short sentences, purpose front-loaded, no filler. The channel explanation is slightly redundant with the bars schema description but is justified as orientation for a nested 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?

Covers the core write model for a mutation tool with no output schema, but omits whether edits are undoable and does not flag the destructive potential of replace_all or how out-of-range pattern indices are handled.

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

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

Schema coverage is already 80%, and the description still adds meaning the schema does not: the default loop span covering the whole song clarifies loop_start/loop_end as a pair, and 'leaving other bars alone' clarifies the write boundary around at_bar.

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

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

Opens with a specific verb+resource ('Places patterns on the timeline') and immediately explains the arrangement model (bars, up to 8 channels per bar). That distinguishes it from pattern-level siblings like add_pattern/update_pattern, though no sibling is named explicitly.

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

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

There is no statement of when to reach for this tool versus update_pattern or create_song, and no prerequisites or exclusions. The sentences about whole-bar writes and loop coverage describe mechanics rather than guiding 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?

Annotations declare destructiveHint=true and the description sensibly adds behavior beyond them: render latency roughly proportional to playback length, the possibility of a non-final "rendering" state, and the duration/peak/RMS metrics a finished WAV reports for catching silent or clipped output. It doesn't explicitly restate the overwrite hazard, but the schema already carries that and there is no contradiction.

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

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

Three tight sentences, front-loaded with what is exported and the format enum, followed by the async caveat and the verification signal. No filler and no repetition of 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?

With no output schema, the description usefully discloses the "rendering" state and the WAV result metrics, which is the key return-value knowledge. It does not describe what a completed mid/mml/xm export returns, but the essential call-time and follow-up behavior is covered.

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 83% and every parameter is described there, so the baseline is 3. The description only implicitly touches wait_seconds (via the render-speed caveat) and says nothing about from_bar/to_bar range semantics, adding little beyond the schema.

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

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

States a specific verb (exports) and resource (the song) and enumerates the four output formats with one-line glosses (wav rendered audio, mid MIDI, mml SiON MML, xm FastTracker). An agent can immediately tell this apart from export_status or save_song 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 context for the asynchronous path: a WAV renders at about playback speed or slower, so a long one returns state "rendering" and must be followed up with export_status. It does not state when to prefer save_song or when a non-WAV format is the right choice, so differentiation from siblings is only partially covered.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful behavioral context by noting that the song cannot be edited while rendering and that status falls back to the most recent export.

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 purpose. There is no wasted language.

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 simple, zero-parameter, read-only status tool with no output schema, the description supplies the core semantics and the render-lock behavior. It omits the specific status values or fields returned, which 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?

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameters that do not exist.

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

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

The description uses a specific verb and resource: 'Reports how the current or most recent WAV export is going.' The temporal scope is clear, though it does not explicitly name the sibling tool export_song as the 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?

Usage is implied: an agent should call this to check export progress. However, there is no explicit guidance on when to use this versus export_song, or what to do if no export exists.

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

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

Annotations declare readOnlyHint=false with destructiveHint=false, so the agent knows this mutates non-destructively, but the description adds nothing about what state changes (UI focus/selection), whether pattern and instrument indices must already exist, or what happens when no parameter is supplied. No mention of preconditions such as the app being launched.

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

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

A single compact sentence with the three modes front-loaded. The only waste is the vague opener 'Shows something in the app's window', which could be dropped without loss.

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

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

With 0% schema description coverage, three parameters, no output schema and no annotation explaining effects, the description is too thin: an agent cannot confidently decide between passing 'pattern', 'instrument' or 'view', or know the effect of passing several.

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 carry the burden, yet it only loosely maps names to actions and explains nothing about index semantics for 'pattern'/'instrument', valid ranges, zero-based indexing, or whether the three parameters are mutually exclusive 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 names three concrete actions (select pattern, select instrument, switch view) that map directly to the parameters, so an agent can tell what the tool does. The opening phrase 'Shows something in the app's window' is vague, and nothing distinguishes this from siblings like screenshot_app or app_status.

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

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

Usage is only implied: selecting a pattern or instrument, or switching views, is the condition for calling it. There is no statement about when not to use it, whether multiple params may be combined, or which sibling (screenshot_app, get_song) to prefer for inspection instead.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is clear. The description adds semantic context about what the returned items represent in a drumkit pattern, but does not discuss pagination, error behavior, or other operational details.

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

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

The description is two concise sentences with zero waste. The core action is front-loaded, and the second sentence usefully clarifies the domain concept without padding.

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

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

For a simple read-only tool with one fully described parameter and clear annotations, the description is largely complete. It does not describe the return shape in detail, but the tool's simplicity makes that a minor gap rather than a blocking omission.

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

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

Schema description coverage is 100%, and the voice parameter already includes an example format. The description adds no parameter-specific syntax or constraints beyond what the schema provides, so the baseline of 3 applies.

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

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

The description states a specific verb, resource, and scope: it lists the items of a drumkit voice. It also clarifies that drumkit pattern notes are these items rather than pitches. It does not explicitly differentiate from sibling tools such as list_voices, keeping it below a 5.

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

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

Usage is implied by the explanation of drumkit pattern notes, but there is no explicit when-to-use guidance, no exclusions, and no named alternatives among the siblings. An agent can infer the context but is not routed decisively.

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 readOnlyHint annotation already covers the safety profile, and the description adds real behavioral value beyond it: the exact scope of what is returned and, importantly, that notes use the same representation the editing tools accept, implying round-trip compatibility. It omits any warning about payload size or cost for large songs, which keeps it from a 5.

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

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

Two short sentences with no filler; the payload contents come first and the interoperable note format second, both earning their place.

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

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

With no output schema, the description carries the burden of describing the return shape, and it does so at a useful level of detail for a whole-document reader. A note on response size or the summary mode would make it fully 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 a single parameter at 100% schema description coverage, the schema already explains include_notes fully. The description never mentions the flag, but given full coverage the baseline of 3 is appropriate.

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

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

States a specific verb and resource ("Returns the whole song") and enumerates the payload contents: settings, instruments, patterns with notes, and the arrangement. It is not explicitly differentiated from nearby readers like open_song or screenshot_app, so it stops short of a 5.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternative is named. The clause about notes matching the editing tools' format implies the intended workflow (read state, then edit), but the agent must infer it.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral context — that Bosca is a step sequencer and complex MIDI timing may be lost on import — which is exactly the kind of expectation-setting annotations can't convey.

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

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

Two tight sentences: the operation is front-loaded and the caveat follows immediately. Nothing is wasted and nothing is buried.

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, three-parameter mutation with no output schema, the description covers what the tool does and its main fidelity caveat, while the schema carries the parameter rules. It stops short of stating that unsaved changes will block the call unless discard_changes is set, but that is documented in the schema.

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

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

Schema description coverage is 100%, with path, pattern_size (including the 0/absent auto-detect behavior) and discard_changes all documented in the schema. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Replaces the open song with one imported from a MIDI file'), making clear this is an import-and-overwrite operation rather than a plain open. It implicitly distinguishes itself from open_song/create_song by noting replacement of the current song, though it never names those 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?

Usage is implied by 'replaces the open song', but there is no explicit guidance on when to choose this over open_song or create_song, nor any mention of prerequisites such as the unsaved-changes guard. The agent must infer the 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful fact that launching is implicitly deferrable, but it does not say what happens if the app is already running (idempotency) or whether an explicit launch changes session state. The headless data-loss caveat lives in the schema, not the description.

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, zero filler, with the most decision-relevant information (you usually don't need this) front-loaded right after the purpose.

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

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

For a one-optional-boolean launch tool with no output schema and good annotation coverage, the description covers purpose, necessity, and alternatives. The only real gap is behavior when the app is already running, which matters for a mutate-session tool but is a minor omission.

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 carries a detailed description including the song-loss caveat, so the schema does the heavy lifting. The description only alludes to the parameter via "choose the mode," adding no format or default detail beyond what the schema already says. 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?

"Starts Bosca Ceoil Blue" gives a specific verb and resource, and the following clause explains the tool's role relative to the rest of the toolset. An agent immediately knows this is the app-launch tool and not a general-purpose action.

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

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

Explicitly states that other tools launch the app on demand, so this is only needed "to choose the mode or to open the window before working." Both the trigger condition and the redundant case are named, which is stronger guidance than most definitions provide.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the result set is large (300+ entries) and the full list is long, which warns the agent to narrow the query. It omits what a voice record contains or any pagination behavior, keeping it below a 5.

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

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

Two tight sentences with no filler. The resource and its scale are front-loaded, and the filtering advice follows immediately.

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 list tool with two optional params and no output schema, the description covers what it returns at a high level (voices) and how to keep results manageable. A brief note on what fields a voice entry exposes would close the remaining gap left by the absent 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 100%, so both parameters (query, category) are already documented with examples in the schema. The description only says 'filter them' generically and adds no syntax, matching rules, or interaction between query and category, so the baseline 3 applies.

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

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

States a specific verb and resource ('Lists the app's voices') and adds scale and purpose ('over 300', 'to pick from when adding an instrument'), which implicitly distinguishes it from mutation siblings like add_instrument. It stops short of naming an explicit alternative or contrasting tool, so it lands at 4 rather than 5.

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

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

'Filter them, since the full list is long' gives implied usage guidance (use the filters when the full list would be unwieldy) but never states when not to call it or which sibling to use instead. There are no prerequisites or exclusions, so the agent must infer the workflow.

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

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

Annotations flag destructiveHint=true, so the agent knows this is potentially destructive, but the description adds no context about what is destroyed (the currently open song) or the safeguard required (discard_changes). For a mutation tool that can discard unsaved work, the description should disclose this rather than relying solely on the hint.

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

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

A single, front-loaded sentence with no filler. It is efficient, though its brevity leaves behavioral gaps rather than 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 destructive, state-replacing operation with no output schema and several related sibling tools, the description omits the critical caveat about unsaved changes and the discard_changes requirement. The agent must infer the destructive consequence from annotations alone.

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

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

Schema coverage is 100% and both parameters are documented in the schema, including the important discard_changes semantics. The description adds nothing beyond the schema, so baseline 3 applies.

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

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

States a specific verb ('Opens') and resource ('.ceol song file'), which is clear enough to distinguish it from create_song or import_midi by file type. However, it does not explicitly contrast with those siblings (e.g., whether opening loads a project vs. creating a new one).

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

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

No guidance on when to use this versus create_song, import_midi, or get_song. Critically, there is no mention that opening a song may replace the currently loaded song or that unsaved work may be lost, which is the main decision point for an agent choosing this tool.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation-without-destruction profile is covered. The description adds the useful state detail that playback position is retained, but does not say whether subsequent play resumes from that point or what the transport state becomes — the main behavioral question an agent would have.

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

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

A single six-word sentence, front-loaded with the action and immediately followed by the one distinguishing qualifier. Nothing wasted, nothing padding.

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

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

For a parameterless transport control with no output schema and adequate annotations, the description covers the essentials. The only remaining gap is whether play resumes from the paused position, which is minor but relevant for correct chaining.

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 for the description to disambiguate beyond what the empty schema shows. Baseline 4 applies.

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

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

States a specific verb and resource ('Pauses playback') and adds the scope qualifier 'keeping the position', which implicitly separates it from the sibling 'stop' that likely resets position. It stops short of naming that sibling explicitly, so it lands at 4 rather than 5.

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

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

The phrase 'keeping the position' implies when to choose this over stop (temporary halt vs. full stop), but no alternative is named and no prerequisites or follow-up (e.g., resume via play) are stated. Usage is inferable rather than spelled out.

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

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

Annotations only declare the generic mutation profile (readOnly=false, destructive=false, openWorld=false). The description adds genuinely new behavior: audio is emitted to physical speakers, playback loops indefinitely until stopped, and the agent cannot perceive the result. It does not say whether playback restarts from the beginning or resumes from a current position, which matters for a play 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 short sentences with zero filler, and the core behavior (plays through speakers, loops until stopped) is front-loaded before the usage hint.

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

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

For a single-optional-parameter, non-destructive playback tool with no output schema, the description covers what an agent most needs: audio is produced, the agent cannot verify it, and playback continues until stopped. Only the resume-vs-restart and from_bar default behavior are left unstated.

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

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

There is a single optional parameter (from_bar) with 100% schema description coverage, so the schema already carries the semantics and the baseline is 3. The description's mention of looping loosely connects to the schema note that the bar must be inside the loop, but adds no default or format guidance.

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

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

States a specific verb (plays) and resource (the song) plus the output destination (user's speakers). The looping-until-stopped clause distinguishes it from the pause and stop siblings without needing to name them.

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

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

"Use this when the user wants to listen" gives a clear positive selection condition, and "looping until stopped" implicitly points at stop/pause as the terminating tools. It stops short of explicitly naming the alternatives or stating when not to use it.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the risk profile is known. The description adds nothing beyond that: it does not say whether unsaved changes block or prompt termination, whether the quit is graceful, or what happens to the session state on failure.

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

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

A single short sentence with zero filler — appropriately sized and front-loaded. It errs toward under-specification rather than verbosity, which is not penalized here.

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 destructive tool, annotations cover the risk flag and the schema fully documents discard_changes. Still missing is the crucial operational detail of what happens when unsaved changes exist and discard_changes is omitted, which is exactly the ambiguity an agent would face.

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 discard_changes parameter is fully documented in the schema, so the description is not required to explain it. Baseline 3 applies since the description contributes no additional meaning about the parameter.

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

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

The description names a specific verb (closes) and the exact resource (Bosca Ceoil Blue), so an agent can tell this is an app-termination tool. It is not differentiated from siblings, but none of the listed siblings (launch_app, stop, pause) could be confused with quitting the application entirely.

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

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

There is no guidance on when to call this versus stop/pause or save_song first, and no mention of prerequisites such as saving pending work. The agent must infer that this terminates the whole app rather than playback.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false. The description adds only the scope 'last undone edit' and does not disclose behavioral details such as what happens when there is no undone edit, whether the redo is reversible, or any error conditions.

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

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

A single, front-loaded sentence with no wasted words. For a zero-parameter tool, this is appropriately sized and clear.

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 low complexity, zero parameters, and annotations covering safety, the description is nearly complete. It states the core action, though it could mention stack behavior or failure modes for full completeness.

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 are no parameter semantics to explain. The baseline for a parameterless tool is 4.

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

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

The description states a specific verb and resource: 'Redoes the last undone edit.' It is immediately clear what the tool does, though it does not explicitly differentiate itself from the sibling 'undo' tool beyond the obvious inverse relationship.

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

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

Usage is implied by the phrase 'last undone edit' – an agent can infer it should be used after an undo – but there is no explicit guidance on when to use it versus alternatives, no prerequisites, and no exclusion conditions.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds genuine beyond-schema behavior: later instruments shift down one index and dependent patterns are reassigned to instrument 0. That is exactly the side-effect disclosure an agent needs before a destructive call; it stops short of stating irreversibility or whether undo applies.

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, with the core action front-loaded and consequences following immediately. Nothing could be cut without losing 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?

Side effects are well covered for a destructive one-parameter tool with no output schema, but the missing parameter format and the absence of any note on reversibility/undo leave meaningful gaps for an irreversible operation.

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

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

Schema coverage is 0% and the description never explains the single parameter: it is unclear whether "instrument" is a zero-based index, a name, or an ID, despite the description itself discussing indices. This ambiguity matters because the index-shifting behavior means stale indices are a real hazard.

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 ("Removes an instrument") that is immediately distinguishable from the sibling add_instrument and update_instrument. It does not explicitly name those siblings, but the operation is unambiguous.

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

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

No statement of when to use this versus alternatives (e.g., update_instrument to reassign, or remove_pattern), and no preconditions such as whether the instrument must be empty or whether removal is reversible. The agent must infer usage from the name alone.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so safety is covered. The description earns credit for the non-obvious side effect that later patterns shift down one index, which directly affects any subsequent index-based calls. It stops short of saying whether the removal is undoable or what happens with an out-of-range index.

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 operation and immediately followed by the consequence. Zero filler.

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

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

For a single-parameter destructive mutation with no output schema, the critical missing pieces are the index base/bounds and undo semantics; the description covers consequence but not validity. Adequate but with a clear gap for a tool whose only input is ambiguous.

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 only parameter is a bare integer with a meaningless ±9e15 range. The phrase 'later patterns move down one index' hints the value is a positional index, but neither the base (0 or 1) nor the valid bounds are stated, so the agent still cannot construct a correct value with confidence.

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+resource: 'Removes a pattern'. Easily distinguished from add_pattern, update_pattern, and remove_instrument by the resource noun. Sibling differentiation is implicit rather than stated, keeping it just below a 5.

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

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

No statement of when to use this versus update_pattern (which might also alter arrangement) or when removal is the wrong call. No prerequisites, no mention of the undo sibling as the recovery path. The agent must infer all usage context from the name alone.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=false, so the safety profile is covered. The description adds the useful context that songs are not autosaved and that the output is a .ceol file, but it does not elaborate on overwrite behavior or other destructive implications beyond what the schema states.

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

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

The description is two short sentences with zero waste, and the primary action is front-loaded. The autosave caveat is directly relevant and appropriately brief.

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 simple two-parameter save tool with full schema coverage and annotations, the description covers the essential facts: what it does, the file format, and that persistence is manual. The main remaining gap is sibling routing against tools like export_song, but nothing critical to 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 description coverage is 100%, so both parameters are already documented by the schema: path indicates where to save, and overwrite indicates whether replacement is allowed. The description adds no parameter-specific meaning beyond the file format, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: it saves the song, and it specifies the output as a .ceol file. It does not differentiate this tool from siblings such as export_song or create_song, but the core purpose is clear.

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

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

The line 'Songs aren't saved automatically' implies that this tool is needed to persist work, but it does not explicitly say when to use save_song versus export_song, open_song, or other related tools. Usage is inferable rather than clearly guided.

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

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

readOnlyHint=true is consistent with a capture operation. The description adds a real behavioral constraint not present in annotations: the tool will not work when no window exists. It omits details such as image format, resolution, or how the failure manifests, which keeps it short of a 5.

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

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

Two short sentences, with the purpose front-loaded and the caveat second. Nothing is redundant or padded.

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

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

For a parameterless read-only capture tool with no output schema, the description covers what it returns (an image of the window) and the one condition under which it fails. It could say slightly more about the resulting image or error behavior when no window exists.

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

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

The tool takes zero parameters, so the schema imposes no semantic burden and the baseline is 4. Nothing in the description is needed to explain inputs.

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 — capturing the app's window as an image — and adds the intent (to check what the user is seeing). No sibling tool does anything similar, so it is trivially distinguishable from the arrangement/playback/instrument tools listed.

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?

"To check what the user is seeing" gives a clear condition for use, and "Not available without a window" states a precondition. No exclusion or named alternative is given, but no sibling is a plausible substitute for visual capture.

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

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

Annotations already declare that this is a non-read-only, non-destructive operation. The description adds the important behavioral detail that playback returns to the loop start, but it does not clarify whether playback must be active, whether the reset discards any state, or whether the action 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?

The description is a single, front-loaded sentence with no wasted words. It efficiently conveys both the primary action and the reset behavior.

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

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

For a simple transport control with no parameters and no output schema, the description covers the core effect well. Minor gaps remain around prerequisites and exact loop/song semantics, but the essential behavior is present.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain. The baseline score for a parameterless tool is 4.

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

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

The description states a specific verb ('Stops') and resource ('playback'), and adds the reset-to-start behavior. This implicitly differentiates it from the sibling 'pause' tool, though it does not name the alternative explicitly.

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

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

Usage is only implied by the described effect: an agent can infer that 'stop' should be used when playback should halt and reposition to the loop start. It does not explicitly state when to use this versus 'pause' or 'play', nor does it mention prerequisites or exclusions.

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

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

Beyond the annotations, the description discloses how much history is available (40 steps) and that opening or creating a song clears that history. It does not explain edge cases such as undo with no prior edit, but it adds meaningful behavioral context for a simple mutation tool.

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

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

The description is two concise sentences with the core action stated first and the history constraints immediately after. Every sentence contributes useful information, with no wasted wording.

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

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

For a zero-parameter tool with no output schema, the description is complete enough to call correctly. It covers the action, scope, history limit, and the key condition that clears undo history.

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 has zero parameters, so there are no parameter semantics to clarify. The baseline score of 4 applies, and the description does not need to add parameter detail.

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

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

The description states a specific verb and resource: it undoes the last edit, whether made by the user or a tool. This clearly identifies the operation, but it does not explicitly distinguish it from the sibling redo tool.

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

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

The description gives useful context for when the tool applies by noting it undoes the last edit from either a user or a tool. It also clarifies the history constraints, though it stops short of explicitly naming redo as the alternative or stating when not to use undo.

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?

This goes beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false) by disclosing a cross-entity side effect — every pattern using the instrument changes — and a real data-loss hazard when switching to a drumkit. That is exactly the kind of consequence hints cannot express. It is docked one point for not saying whether the change is reversible (an undo sibling exists) or what happens when only the instrument index is supplied with no settings.

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, zero filler, and the edit's scope is front-loaded before the caveats. Each sentence carries distinct information: action, blast radius, failure mode.

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-parameter mutation tool with full schema descriptions, no output schema, and existing annotations, this covers what changes, what else it affects, and the main hazard. Only the reversibility question and the no-op case (instrument index alone) are left open.

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; each parameter already carries a range, default, and cross-reference to list_voices. The description's "voice or settings" loosely maps to voice/cutoff/volume/resonance but adds no format, default, or interaction detail beyond the schema.

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

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

"Changes an instrument's voice or settings" pairs a specific verb with a specific resource and even names the mutable facets, so an agent knows this is a mutator on an existing instrument rather than a creator/remover. It stops short of explicitly distinguishing itself from siblings like add_instrument or update_pattern, but the model is unambiguous.

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

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

Usage is implied rather than stated: the propagation and drumkit notes give context for what happens when you call it, but the description never says when to prefer this over update_pattern or add_instrument, nor that instrument (index) must identify an existing instrument. Useful signal, no explicit routing.

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

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

Annotations only declare the generic readOnly=false/destructive=false profile; the description meaningfully adds that all edits land as "one undo step" (atomicity) and, critically, that changing the scale removes notes that don't fit — a data-loss behavior the destructiveHint=false flag alone would not prepare an agent for. It stops short of covering how notes_mode replace interacts with existing notes or what happens to notes when the instrument changes.

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, zero padding, with the operation and its scope front-loaded and the two surprising side effects immediately following. Every sentence carries distinct information.

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

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

For a nine-parameter mutation tool with no output schema, the description plus the fully-covered schema gives an agent enough to call it correctly, including the undo atomicity and the lossy scale behavior. It is slightly thin on how the parameters combine (e.g. notes plus instrument change, or notes_mode interaction with transpose_with_key).

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

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

Schema coverage is 100%, so the schema already documents all nine parameters in detail, including key formats, scale list, and notes_mode defaults — that sets the baseline at 3. The description adds real semantic value for two of them (key causes transposition, scale prunes non-conforming notes) but says nothing beyond the schema for pattern, instrument, filter_steps, or record_filter.

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 ("Edits") and resource (a pattern), then enumerates exactly which facets are mutable: notes, key, scale, instrument, filter automation. That enumeration cleanly separates it from siblings like update_song, update_instrument, add_pattern, and clone_pattern without needing to name them.

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

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

Usage is only implied — an agent infers this is for modifying an existing pattern, but the description never says when to prefer it over clone_pattern + edit, nor does it state prerequisites like recording being stopped. What it does give is consequence guidance (key transposes, scale prunes notes), which is useful but is effect-of-use rather than when-to-use.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the mutation/safety profile is known. The description adds a genuinely useful behavioral fact beyond the annotations: changes apply live, including during playback. It does not say whether unspecified settings are preserved, whether changes are undoable, or what is returned, so it remains a modest addition rather than rich 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?

Two short sentences with no filler. The core purpose is front-loaded and the live-apply behavior follows immediately.

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 6-parameter tool with zero required parameters and full schema description coverage, the schema carries the parameter burden, and the description supplies the one non-obvious behavioral trait (immediate application during playback). No output schema exists, so return-value details are not required, though stating whether omitted settings stay unchanged would close the remaining 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%, and each parameter has explicit bounds, defaults, and units (bpm default 120, swing -10 to 10, bar_size purely visual, etc.). The description adds no parameter-level meaning beyond 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 gives a specific verb+resource: "Changes song settings." This clearly separates it from update_pattern and update_instrument implied by the resource, though it never names those siblings or enumerates the settings it can change. The schema carries the field list, so an agent can still identify the tool's purpose without opening anything else.

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

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

There is no when-to-use guidance, no prerequisites, and no explicit alternative named among the many sibling tools (update_pattern, update_instrument, create_song, etc.). "Takes effect immediately, even during playback" describes effect timing, not when the agent should choose this tool over alternatives.

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