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 discloses the algorithm (onset cross-correlation) and that the result is a lag value applied elsewhere, implying a non-destructive read. It does not state permissions, cost, or explicitly that it mutates nothing, leaving meaningful 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?

Two sentences, front-loaded with the core purpose followed by the actionable workflow. No wasted words, though the inline example is slightly dense.

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

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

An output schema exists, so return values need not be described. However, with 5 parameters at 0% schema coverage and no annotations, the description leaves the agent guessing on bars and project, making it only partially complete for correct invocation.

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

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

Schema description coverage is 0% across 5 parameters, so the description must compensate. It explains band with a concrete example ('sub' for kicks) and implies a/b are the two sources, but bars and the required project parameter are entirely unexplained, leaving most parameters opaque.

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

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

The description states a specific computation ('timing lag between two sources (onset cross-correlation)') with a concrete verb+resource, and the parenthetical explains the method. It is clear enough to distinguish from generic analysis siblings like compare or cmp_*, though it never explicitly names 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?

It gives an explicit workflow: compute the lag, then apply it via project_set(offset_sec = offset_sec + lag). That tells the agent exactly when and how to use the result. It stops short of stating when NOT to use it or naming alternatives, so it is not 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?

No annotations are provided, so the description carries the full disclosure burden, and it only partially meets it. It does surface one genuine behavioral trait not present in the schema: results are capped at 32 bars, which signals truncation. It says nothing about read-only safety, permissions, cost, or whether analysis has side effects.

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

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

A single dense sentence that front-loads the key noun ('Per-bar table') and the cap, then lists the columns. No filler, though it is telegraphic to the point of omitting necessary context.

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

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

An output schema exists, so the enumerated columns are somewhat redundant and return values needn't be explained here. But with zero schema coverage on inputs and no usage guidance among a crowded analyze_* family, the definition leaves an agent unable to determine parameters or selection criteria.

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 three parameters (project, bars, source) are entirely undocumented in the schema. The description only obliquely touches the bars parameter via 'max 32 bars' (an output cap, not input semantics) and says nothing about what 'source' selects or what form 'project' takes. It fails to compensate for the coverage gap.

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

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

The description names a concrete artifact (a per-bar feature table) and enumerates its columns, so the agent knows what comes back. However, it never states the action performed (no verb) or the input it operates on, and it gives no differentiation from the many sibling analyzers (analyze_grid, analyze_sections, analyze_overview, analyze_timbre). Purpose is inferable but not sharply defined.

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 at all: nothing says when to pick analyze_bars over analyze_grid, analyze_sections, or cmp_bars, nor what prerequisites (e.g. a project must exist, bars must be defined) apply. The agent must guess 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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose one useful constraint (max 32 bars), but says nothing about whether analysis is read-only, what permissions the project requires, or how the source parameter affects behavior. For an unannotated tool this is a thin 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?

It is a single short sentence, so nothing is wasted, but it is arguably over-terse to the point of ambiguity rather than genuinely concise. The core information is front-loaded but opaque.

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

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

An output schema exists so return values need not be described, but with 0% parameter coverage, no annotations, and a cryptic one-liner, the definition leaves too much for the agent to infer about a four-parameter analysis tool.

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

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

Schema description coverage is 0% with four parameters. The description loosely maps to 'bars' and 'per_bar', but the required 'project' parameter and the 'source' parameter are never explained. It compensates only partially for the total absence of schema descriptions.

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

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

The description names a specific resource (chords + bass note) which does distinguish it from many analyze_* siblings like analyze_key or analyze_melody. However, the phrasing 'per 1/per_bar of a bar' is cryptic and the intended verb is only implied by the name. It states what is analyzed but not clearly enough to confidently separate it from adjacent analyzers.

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

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

There is no statement of when to use this tool versus the many other analyze_* siblings, no prerequisites, and no alternatives named. An agent must infer usage entirely from the name.

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

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: output granularity (3 band lanes, 16-bar cap), the false-positive risk on mixed sources where non-drum elements register as hits, and the downstream use (paste into pattern_write). It omits sensitivity/source-authorization details, but the false-positive warning is genuine behavioral insight.

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 output format, then workflow integration, then source guidance. Four sentences with no filler, though the 'Paste into pattern_write' and source hints could be slightly tighter.

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

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

Output schema exists so return format is covered, and the source/mix caveat is strong. However, with five params at 0% schema coverage and no annotations, the total absence of any explanation for `sens` and `steps_per_beat` leaves the definition incomplete 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 0%, so the description must compensate. It clarifies the `source` parameter ('track:<drum track>', 'ref:drums', 'render', 'ref') and the 16-bar cap tied to `bars`, but leaves `sens` and `steps_per_beat` entirely undocumented in both schema and description.

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

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

States a specific verb+resource and precise output: 'Drum hits as step strings per bar in 3 lanes (low/snare/hat bands), max 16 bars.' This clearly separates it from sibling analyzers like analyze_grid, analyze_structure, or analyze_bars without needing the schema.

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

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

Gives concrete when-to-use conditions ('Best on an isolated drum source: track:<drum track> after render(stems=True), or ref:drums') and a when-not/degraded case ('On a full mix the lanes are band activity, so bass, pads and leads also register as hits'). It doesn't name an alternative tool, but the source-selection guidance is explicit enough to steer invocation.

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 hints at the result shape ('digits 0-9, max 8 bars') but says nothing about side effects, permissions, cost, or what the tool actually returns as a whole, leaving the safety and behavior profile unexplained.

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, front-loaded with the input encoding then the payoff. Dense and essentially waste-free, though the 'Level per step as digits' phrasing is terse enough to be slightly cryptic.

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

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

An output schema exists so return values need not be spelled out, but with 5 parameters at 0% schema coverage and no annotations, the description leaves most inputs (source, project, bars, steps_per_beat) and the tool's behavioral profile undocumented.

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

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

Schema description coverage is 0% across 5 parameters. The description only clarifies 'band' (sub|bass|lowmid|mid|himid|air) and marginally bounds 'bars' (max 8); 'source', 'project', and 'steps_per_beat' remain entirely undocumented in both places.

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 tells the agent this tool derives an amplitude envelope ('Level per step as digits 0-9') and what it surfaces ('sidechain pumping, gating, note rhythm'), which is a clear specific activity. It differentiates loosely from other analyze_* siblings by naming the phenomenon it detects, but it never explicitly names 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?

There is no when-to-use vs when-not-to-use guidance and no mention of any sibling such as analyze_drums, analyze_bars, or analyze_swing. The stated outputs imply a use case but the agent must infer when this tool is preferred over the many other analysis 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?

With no annotations, the description carries the full burden. It does disclose real behavioral traits: the LPC method, per-step resolution, and a hard cap of 8 bars. However, it says nothing about read-only vs mutating behavior, whether it needs rendered audio, or what the defaults do — significant gaps for a zero-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 dense sentences with the output shape front-loaded and usage second; every clause carries information. The opening "Vowel view of a voice" is slightly colloquial but quickly resolves into concrete detail.

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

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

An output schema exists, so return values need not be re-explained, and the description's framing of the analysis is adequate for selection. But with 0% schema coverage on four parameters, the definition leaves too much about inputs unspecified to be 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?

Schema description coverage is 0% across 4 parameters, so the description must compensate. It hints at the bars limit ("max 8 bars") and per-step resolution ("per step"), but never explains the `source` ref format, `project`, or the structure of the `bars` array, leaving most parameters opaque.

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

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

The description names a specific analysis output (LPC formants F1/F2/F3 per step plus nearest vowel), which is a concrete verb+resource and clearly distinct from siblings like analyze_spectrum or analyze_timbre. It stops short of explicitly naming the alternatives it is not.

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

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

"Use it to see what a vocal part is saying/singing and to match a vocoder / formant sound to it" gives clear context for when the tool applies. It offers no exclusions or named alternatives, but the use case is unambiguous.

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

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

With no annotations, the description carries the full burden. It usefully discloses conditional behavior (swing is only computed when a reference drum stem is supplied) and the internal voting heuristic for bar 1 (kick, harmony, section changes, snare on 2/4). It does not state that the operation is read-only, whether it mutates project state, or its cost/expense profile.

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

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

A single dense sentence listing outputs followed by a short directive sentence; front-loaded with the core purpose and free of filler. The parenthetical voting detail is somewhat crammed but still earns its place by explaining bar-1 estimation.

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

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

An output schema exists, so return values need not be re-explained, and the description covers what is estimated plus the follow-up workflow. It nevertheless leaves gaps around the required project parameter, bpm_hint, and the read-only/cost profile that an un-annotated tool should disclose.

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% for 3 parameters, so the description must compensate. It implicitly maps 'reference drum stem' to the source parameter, but never mentions the required project parameter or the bpm_hint parameter at all. The bpm_hint omission is especially costly for a tempo-estimation tool where a hint plausibly changes behavior.

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 (Estimate) and enumerates concrete outputs: tempo, bar-1 position, A440 tuning offset, and swing. It partly distinguishes itself from siblings by scoping swing detection to the presence of a reference drum stem. However, it does not clearly separate itself from near-neighbors like analyze_swing, analyze_bars, or analyze_structure, so an agent must still infer the boundary.

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

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

'Use the result in project_new/project_set' gives a downstream workflow hint, implying this is a preparatory analysis step before setting up a project. But there is no explicit when-to-use vs analyze_swing/analyze_bars, and no stated prerequisites or exclusions. Usage is only implied.

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

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

With no annotations, the description carries the full behavioral burden but discloses little: it names the Krumhansl estimation method but says nothing about permissions, read-only nature, side effects, or defaults. It adds the algorithm detail but leaves the operational profile unspecified.

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; scope and method are packed efficiently with zero filler.

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

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

An output schema exists, so return values need not be explained. However, with no annotations and 0% parameter description coverage, the terse sentence leaves gaps: the required 'project' parameter and any permission/default behavior are undocumented.

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

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

Schema coverage is 0%, so the description must compensate. It does add meaning for two parameters: 'source' (the whole source to analyze) and 'bars' (a range given as [a, b]), but the required 'project' parameter is never mentioned.

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 ('Key estimate') and scopes it to 'the whole source or bars [a, b]', naming the Krumhansl algorithm. This clearly differentiates it from other analyze_* siblings in intent, though it does not explicitly name a sibling 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 only implied via the scope clause 'over the whole source or bars [a, b]', which tells the agent it can target either the full source or a bar range. There is no when-to-use/when-not guidance and no alternative tool named.

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

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

With no annotations, the description carries the full burden and does well: it discloses that audio files are written to <project>/analysis/kit/comp_<n>.wav, the folding/print format of the analysis, and the constraint not to use the outputs in a render. It stops short of stating compute cost or whether the source audio is modified, so it is strong but not exhaustive.

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 verb and mechanism, and the tuning guidance and sibling comparison each add value rather than padding. The second and third sentences are dense run-ons with stacked parentheticals, which slightly hurts readability, 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?

The tool is analytically complex, yet the description covers the mechanism, side effects, output locations, and tuning guidance; and since an output schema exists, return-value detail is not required. The main gap is the under-explained source and bars inputs, which leaves a small hole 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 0%, so the description must compensate. It conveys real meaning for k (number of components, with a stopping heuristic) and cycle (the loop length in bars the hit pattern folds over), but source (default ref:drums), bars, and the exact indexing of cycle are left unexplained, leaving roughly half the parameters undocumented in both places.

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 ("Discover the pieces of a drum kit") and names the NMF mechanism (splits into k components, each a spectrum + hit time) plus the concrete artifact produced (comp_<n>.wav). It also explicitly contrasts with the sibling analyze_drums ("shows 3 band lanes and hides pieces"), so an agent can separate the two without opening either 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 a concrete tuning rule for when to stop ("Raise k until new components are only fragments (< 2% energy, or a copy of another's pattern)") and names alternatives by pointing output at sound_import/instrument_fit while warning it is "never in the render." The conditions for choosing this tool over analyze_drums are stated outright.

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

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

With no annotations, the description carries the full burden. It does disclose the output format and a hard 16-bar limit, plus the input-material requirement, which is real behavioral context. It says nothing about permissions, reversibility, or what happens on non-monophonic input.

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 fragments, front-loaded with the core transformation and no wasted words. Brevity is a virtue here, though it verges on under-specification given the parameter load.

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

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

An output schema exists, so return values need not be explained. But for a 7-parameter tool with zero schema coverage and no annotations, the description leaves most parameters and all failure/permission behavior undocumented, which is 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 0% across 7 parameters, so the description must compensate and largely does not. Only the bar limit (relating to 'bars') is hinted at; fmin, fmax, quant, source, min_conf, and project are never explained.

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 transformation: monophonic pitch becomes a note list in notes_write format, capped at 16 bars. That is a clear verb+resource+output mapping. It does not, however, distinguish itself from closely named siblings like analyze_pitches or analyze_notes.

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

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

"Best on a stem or a soloed line" gives an implied precondition and, by implication, a failure condition on polyphonic material. It names no explicit alternative tool, so the agent is left to infer routing among analyze_pitches/analyze_notes/notes_from_audio.

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 discloses only a bar cap (max 16) and threshold behavior. It does not say whether existing notes are overwritten, whether it writes anything at all or just returns data, what permissions are needed, or how the result is delivered. The '-> notes_write format' phrasing leaves the read/write nature genuinely ambiguous.

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

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

It is very short and front-loads the core function, which is good, but the arrow notation and fragments read as under-specification rather than disciplined brevity. Every word is load-bearing only because so little is said.

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

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

An output schema exists, so return values need not be explained. However, for a 7-parameter audio-analysis tool with no annotations, the description is far too thin: it omits what the tool consumes (audio source), how 'source' is interpreted, and how it relates to sibling analysis tools. It is not complete enough to call correctly without trial and error.

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?

Seven parameters at 0% schema coverage, yet the description addresses only 'threshold' (with useful semantics: raise it to drop weak/ghost notes). bars, fmin, quant, source, project, and max_poly are undocumented in both schema and description, so an agent must guess at units, formats, and defaults.

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 resource (notes) and an output target ('notes_write format'), plus a constraint (max 16 bars), so the agent can roughly tell it produces note data. But 'Polyphonic note estimate' is jargon rather than a clear verb+resource statement, and it never distinguishes itself from siblings like notes_from_audio, notes_from_audio_loop, analyze_pitches, or analyze_melody. Purpose is implied rather than stated.

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

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

The only guidance is a parameter hint ('Raise threshold to drop weak/ghost notes'), which is not a when-to-use rule. There is no indication of when this tool should be chosen over the many sibling analyze_* or notes_from_audio* tools, nor any prerequisite or exclusion.

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, yet it only lists output contents. It does not state that the operation is read-only/non-destructive, whether analysis is expensive or time-consuming, or what happens when 'source' is omitted (the schema default is null). 'Analyze' weakly implies a safe read, but nothing is disclosed explicitly.

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 no filler and the resource named up front. It is efficient, though it is a noun fragment rather than a front-loaded statement of purpose and action.

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

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

An output schema exists, so return values need not be re-explained, but for a two-parameter tool with 0% schema coverage and no annotations, the description leaves key gaps: the meaning of 'source' and its default behavior, and any indication of when to prefer this over the specialized analyze_* siblings.

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

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

Schema description coverage is 0% for both parameters, so the description must compensate and does not. Neither 'source' (optional, defaults to null) nor 'project' (required) is mentioned or explained; 'on the project grid' gestures vaguely at project scope but leaves unclear what an audio source is (file, track, clip) or what the default source is.

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 concrete outputs (loudness, key, section map with bars, level, dominant bands, chroma) of an audio source, so the resource is identifiable, but it uses no verb and gives no indication of how this overview differs from heavily overlapping siblings such as analyze_key, analyze_bars, analyze_sections, or analyze_structure. An agent can guess it is a combined summary but cannot confidently route to it over the specialized 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?

There is no when-to-use guidance, no prerequisites, and no named alternatives despite a large family of sibling analyze_* tools. The only contextual hint is the phrase 'on the project grid', which does not tell the agent 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses a real constraint (max 16 bars) and the output ordering (loudest first with dB), which is useful, but it says nothing about how the analysis is sourced, whether it is a safe read-only operation, or any performance/authorization considerations.

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, front-loading what the tool returns before the usage guidance, with essentially no filler. Minor awkwardness in the opening clause slightly hurts readability 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?

An output schema exists, so the return format needn't be explained, and the description covers scope, ordering, and best-fit use cases. However, for a 7-parameter analysis tool with no annotations and 0% schema coverage, the near-total silence on most parameter meanings leaves the definition thinner than it should be.

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% across 7 parameters, so the description must compensate, and it only clarifies per_bar (subdivisions of a bar) and the bars cap. Key parameters like fmin, source, floor_db, and max_notes receive no explanation, leaving most of the schema opaque.

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

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

The description states a specific resource and output shape: pitches sounding per 1/per_bar subdivision, ordered loudest first with dB, capped at 16 bars. It is distinguishable from analyze_melody, though the phrasing ('Pitches sounding in each 1/per_bar of a bar') is grammatically awkward and omits an explicit verb.

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 clear when-to-use guidance ('Best view for pads, drones, sustained basses and chords') and names the alternative ('use analyze_melody for fast monophonic lines') with the condition that selects it. It does not address overlap with other sibling analyzers such as analyze_chords or analyze_notes, so it falls 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 behavioral burden. It discloses the output structure and the dual mode (ASCII grid vs. notes_write list), which is useful. However it never states that this is a read-only analysis operation, nor any constraints on cost, scope, or side effects, so it only partially fulfills the burden.

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 main purpose is front-loaded, but the prose is dense and occasionally ungrammatical ('from the same step features the comparisons score'), forcing re-reading. It is reasonably sized for a 10-param tool but not cleanly structured.

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

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

An output schema exists, so return values need not be explained, yet the description helpfully details the grid encoding anyway. The gap is on the input side: for a 10-parameter tool with zero schema coverage, several parameters remain unexplained, so the definition is not fully complete for correct invocation.

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

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

Schema description coverage is 0% across 10 parameters, so the description must compensate. It explains low/high (pitch range for splitting bass/chords/lead), rel_db (threshold under the loudest note), floor_db (absolute floor), and as_notes, but leaves source, bars, project, max_bars, and min_steps entirely 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 states a specific verb and resource: rendering a piano-roll comparison score of a source, with an explicit output encoding ('#' note starts, '=' sustains). It distinguishes itself within the crowded analyze_* family by describing a grid/score output rather than pitch, chord, or melody summaries, though it never names a sibling directly.

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 a hint of a workflow ('as_notes=True returns a notes_write list ... write it, then cmp to verify'), but no explicit guidance on when to choose this over analyze_notes, analyze_pitches, analyze_melody, or analyze_grid. The agent is left to infer the selection condition from the output format alone.

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

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

With no annotations, the description carries the full burden. It does disclose the computed metrics, the section-indexing semantics, the default blocking behavior, and the exact flagging thresholds (2 dB average drop, 3 dB peak proximity), which is meaningful behavioral detail. It omits anything about cost or side effects despite source defaulting to 'render'.

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 output content is front-loaded, which is good, but the whole definition is a single dense paragraph and the trailing parenthetical about the build never arriving is editorial rather than operational. Every clause is informative, yet the structure makes it harder to scan than it needs to be.

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

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

An output schema exists, so the description need not explain return values, yet it is otherwise reasonably complete for a nested-object analysis tool: it covers the sections format and flag semantics. The unexplained `source` parameter, which governs whether audio is rendered, is a real gap for an agent deciding how to invoke 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 description coverage is 0%, so the description must compensate. It explains the `sections` object format with a concrete example and the bars-inclusive convention, and ties an omitted value to the `block` parameter. However, `project` and `source` (default 'render') receive no explanation at all.

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 precise statement of what is computed per section (rms, peak, loudest/quietest 400 ms, dynamic range), which is far more specific than the tool name. It does not, however, explicitly distinguish itself from nearby siblings like analyze_structure, analyze_bars, or cmp_sections, so an agent must infer the boundary.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no named alternative, despite a crowded field of analyze_* and cmp_* siblings. The build/climax flag narrative hints at a diagnostic use case but never states it as 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 describes output content but says nothing about the operation being read-only/non-destructive, whether it can mutate state, or any permission or cost considerations, leaving the safety profile unstated.

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

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

Two sentences, front-loaded with what the tool returns, then the window-format rules. The window sentence is dense but every clause earns its place by disambiguating span versus t0/t1 semantics.

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

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

The output schema means return values needn't be described, yet the params remain half-documented (0% coverage, source/project missing) and the safety profile is absent. It is adequate for basic invocation but has clear gaps for a five-parameter 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 0%, so the description must explain all five params. It clearly defines span (fractional bars, end-exclusive) and t0/t1 (seconds) with worked examples, but leaves 'source' and 'project' completely unexplained and even references a 'bars' parameter that does not exist in 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 first sentence states a specific analysis and its output (1/3-octave levels + strongest peaks with note names), which distinguishes it from siblings like spectrogram or analyze_timbre. It never names an alternative tool directly, but the content mapping is clear enough for an agent to pick it correctly.

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 guidance, and no sibling alternative is named among the many analyze_* tools. The only hint is the parenthetical 'like the other analysis tools,' which implies a convention rather than telling the agent 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 burden and does disclose real behavior: the output shape (bands + stems, one char per bar), that sections are lettered by similar material, that repeats and loop length are reported, and critically the default source resolution ('reference if the project has one, else your render'). It omits any statement of read-only nature or cost, but for an analysis tool this is meaningfully 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?

Two sentences, front-loaded with the core purpose before the source-mode detail. Dense but every clause carries information; no filler or repetition.

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

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

An output schema exists so return values need not be spelled out, yet the description still summarizes them usefully. For a 3-param analysis tool with no annotations, the main residual gap is the undocumented project parameter and absent sibling routing, but the core invocation context 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 0%, so the description must compensate. It explains the source parameter well (ref vs render + default logic) and implies the stems boolean through 'bands + stems', but the project parameter is entirely undocumented and the stems behavior is only inferable, not stated.

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 ('Analyze Structure' → macro view of a whole song) and enumerates the concrete outputs: arrangement map, sections lettered by material, repeats, loop length. It clarifies scope ('whole song', macro view) but never names the closely related siblings (analyze_sections, analyze_bars) to differentiate.

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 via 'macro view of a whole song', suggesting it is the high-level counterpart to bar/section analyzers, and it explains the source-mode choice (ref vs render with default resolution). However, it never says when to prefer this over analyze_sections or analyze_bars, nor gives any explicit when-to-use trigger.

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 behavior: the default source resolution chain (reference drum stem if present, else reference/render), the meaning of the returned value, and that straight timing yields 0. It does not state read-only/safety characteristics or latency, but for a read-oriented analysis tool this is solid 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?

Front-loaded with the core measurement, then usage, with no filler sentences. The 16ths/8ths parenthetical is dense but earns its place by defining the metric. Slightly packed but efficient.

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

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

An output schema exists so return-value documentation is rightly omitted, and the description covers purpose, timing semantics, default source, and workflow. The only real gap is the unexplained required `project` parameter and no safety indication, which keeps it from 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?

Schema coverage is 0%, so the description must compensate. It does explain the `source` parameter's default and value syntax ('track:<hats>', reference stem), which is valuable. However the required `project` parameter gets no explanation at all, so compensation is only partial.

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 measurement: how late swung hi-hats land, reported in beats and ms, with clear unit semantics (16ths vs 8ths) and 'Straight = 0'. This is far more specific than a tautology and implicitly distinguishes it from generic analyzers like analyze_grid or analyze_notes, though it never names a sibling to route against.

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 when-to-use guidance: 'on a reference before writing swung notes, and on track:<hats> to check yours.' This is concrete workflow context. It lacks a when-not or an explicit alternative-tool pointer, so it falls just short of 5.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses what the analysis computes, and the presence of an output schema covers the return value, but it never states that the tool is read-only/non-destructive or what the 'source' selection implies. Adequate but incomplete for an unannotated 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?

Purpose is front-loaded, followed by usage then window syntax; every sentence carries information. The window-selection sentence is long and dense but each example earns its place.

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

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

With an output schema present, return values need no explanation, and the window semantics are well covered. However, for a 5-parameter, 0%-coverage, unannotated tool, the unexplained 'source' parameter (which sound is analyzed) and the phantom 'bars' option leave real gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It thoroughly documents the window selectors (span/end-exclusive with worked examples, t0/t1 in seconds), which is high value, but leaves 'source' and 'project' entirely unexplained and references a 'bars' parameter that does not exist in the schema, creating mild confusion.

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 ('Describe the sound') plus the exact output dimensions (envelope, pitch, harmonic profile, waveform guess, brightness/filter, noisiness, stereo width). This clearly differentiates it from siblings like analyze_spectrum, analyze_envelope, and analyze_formants.

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 use context: 'Use on isolated sounds (stems, sound bank, soloed tracks) for sound design.' It implies when this tool is appropriate but does not explicitly rule out the noisy/mixed-material cases handled by other analysis tools, so it stops just short of naming an alternative.

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 implies a mutation (creating a clip) but says nothing about undo/reversibility, permissions, or what happens if a clip already exists at the target bar. For a write operation with zero annotation coverage, this is a significant 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?

A single front-loaded sentence with no wasted words. It is efficient, though its brevity is partly a symptom of under-specification rather than disciplined concision.

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

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

An output schema exists, so return values need not be explained. But with 7 parameters at 0% coverage, no annotations, and no usage guidance, the description leaves an agent without enough context to invoke a placement/mutation 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% across 7 parameters. The description only clarifies `bar` semantics ('fractional ok'), leaving gain_db, offset_sec, length_beats, and the exact track/sound/project references completely undocumented in both the schema and the description. It does not compensate for the coverage gap.

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

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

States a clear verb (place), resource (bank sound), and target (track timeline as an audio clip), which distinguishes it from note-writing siblings like notes_write and from creation siblings like sound_make. However, it does not explicitly name an alternative tool to route the agent, 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?

There is no explicit when-to-use or when-not-to-use guidance, and no named alternatives among the many siblings (sound_import, sound_list, notes_write). The phrase 'bank sound' implies the sound must already exist in the bank, but this prerequisite is never 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?

With no annotations, the description carries the full burden. It usefully discloses a non-obvious behavioral trait: passing param=None clears all automation. However, it says nothing about reversibility, undo support (a sibling undo exists), permissions, or what the destructive 'remove all' path actually affects.

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

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

A single sentence with zero waste, front-loading the action and immediately clarifying the special None case. Nothing extraneous and nothing 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?

An output schema exists, so return values need not be described. But for an unannotated destructive operation, the description omits the safety context (irreversibility, undo, permissions) that would make it complete enough to call 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 description coverage is 0%, so the description must compensate. It adds real meaning for param (None means all), but project and track are left entirely undocumented beyond their self-evident names, leaving a partial gap in the three-parameter surface.

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

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

The description states a specific verb (remove) and resource (automation) plus the scope of the operation (one param, or all). It is clearly distinguishable from automation_set and automation_read by name and intent, though it never explicitly 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: clear automation rather than set or read it. There is no explicit statement of when this should be preferred over automation_set (which might also overwrite/remove) or any prerequisite conditions, so the agent must infer the selection rule.

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

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

With no annotations, the description carries the full burden. It usefully discloses the return shape ('[bar, value] points') and the special track identifiers ('master', 'bus:<name>'), but says nothing about auth/permissions, pagination, ordering, or behavior on an empty lane. Some value added beyond structured fields, but significant behavioral gaps remain.

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

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

A single tight sentence with the operation front-loaded and the special-case detail parenthetically attached. 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?

An output schema exists, so return values need not be explained in depth (the description's brief format note is a bonus). However, for a tool with zero annotation and zero schema-description coverage, it leaves the 'project' parameter and read-operation safety profile undocumented, which is a noticeable 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 0%, so the description must compensate. It clarifies the accepted values for 'track' (including 'master' and 'bus:<name>'), which is genuinely useful, but never mentions the required 'project' parameter nor the format of ordinary track names. Partial compensation only.

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

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

The description gives a specific verb ('List') and resource ('automation lanes on a track'), and adds scope detail by noting that 'master' and 'bus:<name>' are also valid targets. It is clearly a read operation, distinguishable from automation_set/automation_clear by name and verb, though it never explicitly names 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?

There is no explicit guidance on when to use this tool versus automation_set or automation_clear, nor any prerequisites (e.g., a project must be open). The read-only intent is only inferable from the verb 'List', so usage is implied rather than stated.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses interpolation behavior (linear between points, log for Hz params, held before/after) and explains that mode='merge' preserves existing points outside the new span, implying the default 'replace' overwrites. It omits auth/permission needs and does not explicitly state what replace destroys, but the curve semantics are unusually well covered.

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

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

The main purpose is front-loaded before the dense parenthetical examples, and given the genuine complexity the length is justified. However, the single run-on paragraph with stacked parentheticals is harder to scan than a structured breakdown would be.

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

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

An output schema exists, so return values need not be explained. For a 5-parameter, 0%-coverage mutation tool the description supplies nearly everything an agent needs (points format, interpolation, param syntax, mode), with the only real gap being explicit precedence/overwrite behavior in replace mode.

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, and it does: it defines track formats ('master', 'bus:<name>'), points structure ([[bar, value], ...] with fractional bars), mode semantics, and the full range of param values including dB-offset behavior and inst/fx paths. Only 'project' is left undocumented, which is self-evident.

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, 'Automate a parameter over time', and immediately clarifies the scope (master, bus, or inst automation). An agent can tell it writes/creates automation curves rather than reading or clearing them, though it never names the sibling tools automation_read/automation_clear 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 implied through the detailed how-to content (track formats, param syntax, mode semantics), but there is no explicit when-to-use guidance, no exclusion conditions, and no routing to alternatives such as automation_clear or automation_read. The agent must infer when this tool is appropriate.

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

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

With no annotations, the description carries the full burden, and it does disclose a meaningful trait: mutations are atomic with rollback to the pre-batch state on failure, plus ordered execution and per-op output. However it says nothing about error surfacing, permissions, or how the stop_on_error parameter changes behavior relative to the always-atomic guarantee.

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 the call format and atomicity guarantee front-loaded. The example earns its place by showing the op object shape; nothing is redundant, though the prose is quite compressed.

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

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

An output schema exists, so return values need not be spelled out, and atomicity is covered. The remaining gap is the undocumented stop_on_error parameter and the unresolved question of how it interacts with the unconditional rollback described — an agent cannot predict behavior when an op fails.

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 partially does: the ops array format is illustrated with a concrete example and 'project is implied' clarifies the project parameter. But stop_on_error (default true) is never explained, leaving one of three parameters 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 gives a clear verb and resource ('Run many ops in order'), and the inline example of an op object makes the nature of the tool concrete. It does not name any sibling or explicitly contrast with the many single-op tools (notes_write, track_set, etc.), so an agent must infer that this is the batching 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?

There is no statement of when to prefer batching over calling individual op tools repeatedly, nor any exclusion or prerequisite. The only guidance is implicit in the format example, which shows how ops are shaped but not why or when to use 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?

No annotations exist, so the description carries the full behavioral burden. It says nothing about the defaults (volume_db=0, fx=null), what an effect-return bus does to the project state, whether it persists, or what permissions are needed. For a mutation tool with zero annotation coverage this is a substantial 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?

Two tight sentences: purpose first, follow-on routing second. Every clause earns its place and nothing is padded.

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

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

An output schema exists, so return values need not be described, which lightens the load. However, with four parameters at 0% schema coverage and no annotations, the description leaves key calling details undocumented.

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

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

Schema description coverage is 0%, so the description must compensate and largely does not. Only 'name' is referenced (via the sends/output syntax); project, fx, and volume_db are never explained, and the sends=-12 example is ambiguous about which parameter it maps to.

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 ('Add an effect-return bus') and gives a concrete example ('reverb'), so the agent knows exactly what is created. It does not distinguish itself from related siblings such as live_bus, which is the only gap.

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 how to use the created bus afterward: route via track_set(sends={name: -12}) or track_set(output=name). This is actionable operational guidance. It stops short of saying when to prefer bus_add over alternative routing approaches, so it is not 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?

No annotations exist, so the description carries the full burden. It usefully discloses the output format (one char per bar, per stem, yourself vs reference), but says nothing about whether the operation is read-only, its cost, or any side effects. For an apparent analysis tool this is adequate but 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?

A single compact sentence, front-loaded with the tool's function and ending with the payoff ('macro structure at a glance'). Nothing is wasted, though the terse phrasing borders on cryptic.

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

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

An output schema exists, so return values need not be explained, and the description adds useful framing about the map format. However, with no annotations and zero parameter documentation, the definition leaves real gaps for an agent deciding how to call 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 description coverage is 0% for two parameters, so the description must compensate and largely does not. It never mentions 'project' or 'id' by name; only the implicit 'yours vs reference' framing loosely maps to 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 names a specific resource and action: it produces arrangement maps comparing 'yours vs reference, per stem' with 'one char per bar'. This distinguishes it reasonably from siblings like cmp_summary and cmp_sections, though it does not explicitly contrast itself with 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?

It hints at a use case ('the macro structure at a glance') but gives no when-to-use instruction, no prerequisites, and no guidance on choosing this over cmp_sections, cmp_bars, or cmp_summary. The agent must infer the 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, and it only discloses pagination ('32 bars per page'). It says nothing about what metrics are returned, whether any state is mutated, permissions required, or how the comparison is scoped.

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 scope and pagination front-loaded and no filler. It is terse rather than bloated, though the brevity borders on cryptic.

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

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

An output schema exists, so return values need not be explained, which lightens the burden. Still, for a 4-parameter analysis tool with 0% schema coverage the description leaves too much (metrics definition, 'id'/'project' roles) unstated.

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

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

Schema description coverage is 0% across 4 parameters. The description hints at the 'bars' range syntax (bars=[a, b]) and implies the 'stem' selector, but leaves 'id' and 'project' entirely undocumented, so it only partially compensates for the coverage gap.

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

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

The phrase 'Per-bar metrics for one stem' identifies the resource (bar-level metrics) and scoping (single stem), which does loosely separate it from cmp_sections and cmp_worst. But there is no verb and no statement of what is being compared or measured, so an agent cannot fully tell what 'cmp' computes without inspecting the output 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?

There is no when-to-use guidance and no mention of any alternative among the many cmp_* siblings (cmp_worst, cmp_sections, cmp_zoom, cmp_summary). The pagination note is not usage guidance, so 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 burden alone. It does disclose two behavioral traits beyond the schema: the result is exhaustive ('All stored comparisons') and sorted oldest-first, which supports trend reading. It says nothing about whether the call is read-only or how the required project scopes the result.

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 tightly-packed sentence with the key facts (scope, payload, ordering, purpose) front-loaded and no filler. It is terse rather than padded, though the compressed phrasing costs some precision.

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

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

An output schema exists so return shape need not be explained, but for a tool whose only required parameter is undocumented, and with no annotations and no differentiation from five sibling cmp_* tools, the description leaves too much for the agent to infer before calling.

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 sole required parameter 'project' is never mentioned in the description. Because 'All stored comparisons' suggests an unfiltered list, the description arguably obscures whether project is a filter or a container, leaving the parameter's meaning to guesswork.

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 resource (all stored comparisons) plus the ordering (oldest first) and content (closeness per stem), which tells an agent this is the historical list rather than a single-run comparison. It stops short of naming how it differs from siblings like cmp_summary or cmp_worst.

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 trailing phrase 'progress over time' hints at the intended use case, but there is no explicit when-to-use versus cmp_summary, cmp_worst, or cmp_run, and no prerequisites or exclusions are 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 provided, the description carries the full behavioral burden. It discloses key behavioral traits: the tool stores the comparison ('store a full comparison'), requires a full render with stems for the 'tracks' option, notes that 'demucs' is slower, and returns summary vs ceiling/floor baselines. It does not mention authentication, rate limits, or whether the stored comparison persists across sessions, but the core operation and its requirements are well described.

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

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

The description is front-loaded with the core action and scope, then efficiently lists enum options and routing to related tools. It packs a lot of information into a few sentences without repetition. The only minor inefficiency is the implicit assumption that the agent understands 'stem_map' and 'render(stems=True)' from context, which requires prior knowledge but is not wasted verbiage.

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 (4 parameters, no schema descriptions, no annotations, but an output schema exists), the description is quite complete. It explains the comparison scope, the stems behavior, the return summary, and how to drill down. It does not explain the 'label' or 'b' parameters in detail, but the presence of an output schema reduces the need to describe return values. It covers what an agent needs to invoke the tool correctly in most scenarios.

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 does so by explaining the semantics of the 'stems' parameter with all three enum values and their requirements ('tracks' needs a full render, 'demucs' uses the reference's model and is slower, 'none' is mix only). It also implies the 'b' parameter is the reference and 'project' is the target. The 'label' parameter is not explained, but the critical parameter receives detailed treatment, substantially adding value beyond the bare 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 uses a specific verb+resource: 'Build and store a full comparison of your latest render (A) vs the reference (B)'. It clearly distinguishes the tool from the many siblings by naming the exact scope (every stem, bar, 16th step) and positioning it as the top-level comparison entry point. It does not explicitly name the sibling it is not, but the level of detail is sufficient for an agent to identify its role.

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 explicitly states when to use this tool versus alternatives. It lists the valid enum values for the 'stems' parameter and explains the condition that selects each: 'tracks' needs a full render(stems=True), 'demucs' is apples to apples but slower, 'none' is mix only. It also routes the agent to drill-down tools (cmp_sections, cmp_bars, cmp_worst, cmp_zoom, cmp_arrangement) and to cmp_list for progress. This is comprehensive guidance for invocation and follow-up.

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 it delivers almost nothing. It implies a read-only analysis result, but never states that, nor what 'metrics' are computed, how they relate to the reference, or what happens with the default stem='mix'. For a tool with zero annotation coverage this is a substantial 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?

It is a single short, front-loaded sentence with no filler, which is structurally clean. However, it is terse to the point of being uninformative rather than genuinely concise — the brevity comes from omitting content, not from editing it down.

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

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

An output schema exists, so return values need not be described, but everything else is missing: no annotations, no parameter documentation, and no differentiation from the crowded cmp_* family. An agent cannot confidently select or invoke this tool from the description alone.

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

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

Schema description coverage is 0%, so the description must compensate for all three parameters and does not. 'one stem' loosely maps to the stem parameter (which silently defaults to 'mix'), but id and project are never explained, and no format, valid values, or defaults are given.

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 sentence names no verb at all — it describes a return value ('metrics per reference section') rather than an action, leaving the agent to guess that this computes or fetches comparison metrics. 'Metrics' and 'reference section' are undefined jargon, and the phrasing gives no way to tell it apart from cmp_bars, cmp_summary, or cmp_zoom in the sibling set.

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 mention of any alternative tool despite a dense cluster of cmp_* siblings that clearly overlap. The agent is left entirely on its own to decide whether cmp_sections or cmp_bars is the right call.

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 implies a read-only summary but never states that explicitly, nor does it disclose permission requirements, whether anything is mutated, or what the baselines represent.

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 key noun phrase front-loaded and no filler. It is dense but appropriately sized for the operation.

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

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

An output schema exists, so return values need not be described, but with no annotations and 0% schema description coverage the description leaves behavioral and parameter gaps. The baseline terms 'ceiling/floor' are undefined, so an agent lacks context to interpret the summary.

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% for 2 parameters. The '(default latest)' clause adds meaning for the id parameter, but the required project parameter is entirely unaddressed in the description, leaving the coverage gap only partially compensated.

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

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

States a specific resource and operation: a summary of a stored comparison, scoped to per-stem metrics against ceiling/floor baselines. It is distinguishable from sibling list/view tools (cmp_list, cmp_sections), though the jargon-heavy phrasing leaves the exact output shape unclear without 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 only guidance is the parenthetical '(default latest)', which concerns parameter defaults rather than when to use this tool over alternatives. No when-to-use condition or named alternative (e.g., cmp_list, cmp_worst) is provided.

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

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

With no annotations, the description carries full behavioral burden. It implies a read-only analysis returning a bounded ranking ('n worst'), which is reasonable, but it never explicitly states it is non-mutating, describes paging/limits, or notes anything about cost. Adequate but thin for an un-annotated 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?

A single front-loaded sentence with no filler. The inline metric enumeration is dense but earns its place since the schema provides no enums for that parameter.

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

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

An output schema exists, so return values need not be described. The metric options are covered, but for a 5-parameter tool the required 'project' and optional 'id' remain opaque, and there is no routing against sibling comparison tools.

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 explains n ('n worst'), stem ('of a stem'), and metric, even enumerating the valid metric values (note_f1, pc_f1, etc.) that have no enums in the schema. However, the required 'project' and the 'id' parameters are entirely unexplained, leaving a real gap.

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

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

States a specific verb+resource combination ('the n worst bars of a stem') with a clear ranking scope and lists the metric dimension. An agent can tell what it returns, though it never differentiates itself from the closely-named sibling cmp_bars or compare.

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 and no exclusions. The availability of an 'overall or by one metric' mode hints at a use case, but nothing tells the agent when to reach for cmp_worst versus cmp_bars, cmp_summary, or compare.

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 it is thin: it never states whether this is read-only, whether it requires a loaded reference, what happens with missing/invalid bars, or performance/rate characteristics. It does disclose output semantics (the b/r/y/UPPERCASE legend), which is genuine added context, earning it above the minimum.

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

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

It is a single compact sentence, which is appropriately sized, but it is heavily jargon-dense and not front-loaded from a newcomer's perspective. The legend (b/r/y/UPPERCASE) and layer info are packed together without structural separation, slightly hurting readability despite brevity.

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 six parameters at 0% schema coverage, no annotations, and output schema present (justifying omission of return values), the description is still too sparse. It leaves project, stem, and id semantics unexplained and provides no usage context versus the many comparison siblings, so an agent cannot reliably invoke it correctly.

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

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

Schema description coverage is 0% for six parameters, so the description must compensate. It only partially covers bar/bars ('bar..bar+bars-1') and layers ('level bands hits notes'), leaving project, stem (default 'mix'), and id completely unexplained. The critical 'stem' default and its meaning versus 'project' are unaddressed, which is a significant gap for an A/B comparison 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 says it performs a 'Step-level A vs B' comparison over a bar range ('bar..bar+bars-1'), which identifies a specific verb (compare) and resource (step-level note data across bars). However, it uses cryptic shorthand (b, r, y, UPPERCASE markers) that assumes domain familiarity, and it does not clearly distinguish itself from siblings like cmp_bars, cmp_worst, cmp_sections, compare, or sound_compare.

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 statement of when to use this tool versus the many comparison siblings (cmp_* family, compare, sound_compare, cmp_run). The description only explains what output looks like, not when this tool is the right choice. Usage must be inferred entirely from the name and terse content.

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 load; it discloses that output covers similarity metrics, worst bars, and advice, which tells the agent the shape of the analysis. It says nothing about whether comparison is non-destructive, cost, or alignment implications of offset_b, leaving real behavioral 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?

Two tight sentences with the core compare action front-loaded, followed by a compact metric list. Slightly dense with unexplained jargon terms, but 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?

The presence of an output schema excuses explaining return values, and the description does enumerate the scoring dimensions. But with six undocumented parameters, no annotations, and heavy sibling overlap, it stops short of what an agent needs to invoke this correctly.

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

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

Schema coverage is 0%, so the description must define all six parameters. It only illuminates 'a' and 'b' (defaults plus the 'track:bass'/'ref:bass' stem syntax); 'bars', 'detail', 'offset_b', and 'project' are never explained, so the agent is left guessing at scope, granularity, and alignment offset.

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 ('compare two sources bar by bar on the project grid') and clarifies the default operands (your render vs the reference). However, it does not distinguish itself from the many sibling comparison tools (cmp_run, cmp_bars, cmp_summary, sound_compare), so an agent cannot tell which comparator to pick.

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 through the named default case (render vs reference) and the stem-comparison example, which shows a concrete invocation pattern. But there are no when-to-use/when-not statements and no routing relative to the cmp_* or sound_compare 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 does so well: it discloses the render step, the 1/3-octave comparison, the octave-centre EQ band range (63 Hz..16 kHz), the +-max_db gain clip, that it replaces an earlier eq_match EQ, and that it writes a level difference to the fader. It stops short of explaining what apply=false does or any permission/undo implications, leaving some behavioral gaps for a 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 core sentence is long and clause-dense but front-loads the purpose and every clause adds operational detail rather than filler. The trailing usage sentence is efficient. It could be split for readability but wastes little.

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

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

An output schema exists, so return values need not be described. For a mutation tool with zero annotations the description supplies rich effect/destruction context, but the missing explanation of apply semantics leaves a meaningful gap given the 0% parameter coverage.

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% across 6 parameters, so the description must compensate. It meaningfully explains bars ([a,b]), max_db (gain clipping bound), and level (fader write), but leaves apply and the project/track identifiers unaddressed, and apply in particular has non-obvious dry-run semantics.

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 precise verb+resource+mechanism: it matches a track's long-term spectrum to a reference stem and writes a peaking EQ as fx 0. It is clearly distinguishable from siblings like levels_from_ref or compare, which do not describe this specific render-and-EQ-write pipeline.

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 concrete applicability condition ('Best where that track dominates its stem in the window (e.g. a pad in an intro)'), which tells the agent when this is the right choice. However, it names no alternatives or exclusions (e.g. when to prefer levels_from_ref or fx_set instead), so the routing is contextual rather than explicit.

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

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

With no annotations, the description carries the full burden, yet it discloses only target syntax and chain-index placement. It says nothing about mutation semantics, required permissions, reversibility, or failure conditions for what is clearly a state-changing operation.

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

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

Two tight sentences, front-loaded with the core action and followed by the two clarifying details; no filler. Slightly terse on project/fx, but structurally efficient.

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

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

An output schema exists, so return values need not be described, and target/index are covered. But for a 4-parameter mutating tool with 0% schema coverage and no annotations, leaving 'project' and the fx field's structure undocumented (even by reference) is a real gap.

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

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

Schema description coverage is 0%, so the description must compensate. It usefully documents target (with a literal grammar for track/bus/master) and index (default end), but leaves 'project' unexplained and defers the fx object's contents entirely to fx_help.

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 ('Add an effect') and the target scope ('<track>', 'bus:<name>' or 'master'), so an agent knows exactly what the tool does. It does not explicitly distinguish itself from siblings like fx_set or fx_remove, 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?

It routes the agent to fx_help for the fx payload and explains the index default, which implies usage. However, it never says when to use fx_add versus fx_set/fx_remove, nor any prerequisite or exclusion, so guidance is only implied.

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

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

No annotations are provided, so the description carries the full burden. It conveys the informational nature of the tool and adds that automatable params are listed per type, but never explicitly states it is non-mutating or side-effect-free. For a help tool the risk is low, so a middle score is appropriate.

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

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

Two terse clauses, front-loaded with the primary behavior and followed by the filter clause. No wasted words, though the extreme brevity borders on under-specification rather than pure conciseness.

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

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

An output schema exists, so return values need not be explained. However, with zero annotation coverage and 0% schema description coverage, the description does not fully cover the project parameter or clarify list-vs-detail behavior, leaving gaps for a 2-parameter 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 0%, so the description must compensate. It explains the type parameter's purpose and syntax (type=<name> returns a single entry), but the project parameter is left completely undocumented in both schema and description.

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

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

States a specific resource (effect types) and what it returns (default params, automatable params per type). Combined with the name fx_help, an agent can tell this is a reference/lookup tool distinct from mutators like fx_add, fx_set, and fx_remove. The telegraphic phrasing keeps it from being fully explicit about being a help 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?

"type=<name> for one" gives an implied usage pattern (omit type to list all, supply it to get one), but there is no explicit when-to-use vs alternatives and no when-not guidance. The routing intent is inferable but 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 disclose a real side effect: automation on later fx indices is re-pointed automatically. That is meaningful behavioral context an agent could not derive from the schema. It stops short of covering permissions, invalid-index errors, or reversibility.

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, front-loaded sentences with zero filler; the purpose comes first and the side-effect caveat second.

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

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

An output schema exists so return values needn't be explained, and the key index-shifting behavior is covered. However, for an annotation-free mutation the description omits the 'project' parameter's role and any error behavior, leaving gaps for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies 'index' as an effect index and 'target' as the effect host, but says nothing about the required 'project' parameter or valid index ranges. Partial compensation for the coverage gap.

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

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

States a specific verb+resource ('Remove effect #index from target') that clearly distinguishes it from fx_add and fx_set. It does not name siblings explicitly, 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 when-to-use guidance, no prerequisites, and no mention of alternatives such as fx_set for modifying an effect instead of removing it. Usage is only inferable from the verb.

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. '(merge)' does signal non-replacement semantics, which is useful. But there is no mention of permissions, reversibility, error behavior if the index is invalid, or what parts of the effect state are preserved – all important for a 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 single sentence is front-loaded and wastes no words. It is terse to the point of under-specification, but the sentence structure itself is efficient.

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

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

For a 4-param required mutation tool with no annotations, zero schema description coverage, and nested objects, this description is far too thin. The presence of an output schema means return values need not be explained, but parameter meaning and usage context are 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 0% and the description mentions none of the four parameters by name (project, target, index, params). 'effect #index on target' only loosely gestures at index and target, leaving project and params entirely unexplained at zero schema coverage. This is a severe gap.

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

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

States a verb (Update) and a resource (params of effect #index on target), but 'fx' and 'index' are cryptic without domain context and no sibling is named to differentiate (fx_add vs fx_remove vs fx_set). The 'effect #index on target' phrasing implies a hierarchy but doesn't explain it.

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

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

No guidance on when to use this versus fx_add or fx_help. The '(merge)' hint implies it updates a subset of params, but no explicit conditions, prerequisites, or alternatives are 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?

No annotations are provided, so the description carries the full burden. It usefully discloses the guide's content (workflow, conventions, tool routing), which is meaningful for a reference tool, but it never states that it is side-effect-free/read-only or that its content is static and authoritative. Adequate but thin 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?

A single tight sentence, front-loaded with the imperative 'Read this first' and then the content scope. Every clause earns its place with no filler.

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

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

An output schema exists, so return values need no explanation, and for a simple one-parameter orientation tool the description covers purpose and content well. The only real gap is the undocumented 'project' parameter.

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 single 'project' parameter has 0% schema description coverage, and the description never mentions it—so neither the field's meaning nor whether it scopes the guide's content is documented anywhere. The description fails to compensate for the coverage gap.

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

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

States a specific role: the onboarding/meta-guide for using the DAW as an agent, with the scope enumerated (workflow, conventions, tool routing). It clearly frames itself as the top-level orientation tool. It does not explicitly distinguish itself from sibling help tools (voice_help, instrument_help, fx_help), 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?

'Read this first' is an explicit, front-loaded when-to-use instruction that tells the agent to consult this before acting. It gives clear context but names no exclusions or alternatives, so it doesn't reach the when/when-not/alternatives bar of a 5.

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

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

With no annotations, the description carries the full burden. It usefully discloses the matching dimensions (spectrum + envelope + width), the fmin/fmax spectral-window rationale, and the side effects ('Saves the result as sound save_as and/or sets it on apply_to_track'). But it omits determinism/cost behavior around seed and iters (80 default), and does not state auth/permission or runtime expectations for an iterative search.

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 lines are dense, information-bearing parameter hints. Some parenthetical asides are terse, but little is wasted given 14 undocumented parameters.

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

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

An output schema exists, so return values needn't be explained, and the primary mutation targets (save_as, apply_to_track) are covered. However, for a 14-parameter, 4-required, iterative fitting tool with zero schema descriptions and no annotations, six parameters (including seed/iters controlling reproducibility) remain unexplained, leaving clear completeness gaps.

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

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

Schema description coverage is 0% and there are 14 parameters, so the description must compensate. It documents target, instrument, params (with concrete syntax examples like {"tone_hz": [100, 250]}), notes, fmin, fmax, save_as, and apply_to_track — a substantial majority. It leaves project, fx, seed, iters, length_sec, and target_window undocumented, so not fully compensating.

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: 'Search instrument parameters so its sound matches a target (spectrum + envelope + width).' An agent can understand this is a parameter-fitting search tool. However, it never distinguishes itself from close siblings like track_fit, eq_match, or ref_retune, which appear to do analogous matching work.

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 workflow hints: the target 'source like sound:refsnare (cut one first with sound_import)' gives a prerequisite, and the description says how to seed params and instrument. But there is no explicit when-to-use versus the sibling match/fit tools, and no exclusions or mode-selection guidance beyond the inline hints.

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. 'Help' strongly implies a read-only, side-effect-free lookup, and it discloses the returned content (parameter reference with defaults), but it never states read-only semantics explicitly nor explains the role of the 'project' parameter. Reasonable but not thorough for an unannotated 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?

A single front-loaded sentence with no filler: the resource and content type come first, followed by the value enumeration. The long inline list is dense but each element earns its place as it defines valid inputs.

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

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

An output schema exists, so the description need not explain return values, and the tool is low-complexity. It conveys what it returns and which types are valid, which is most of what an agent needs. The only real gap is the undocumented 'project' parameter and the absence of any read-only confirmation.

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 does add real value for 'type' by enumerating the accepted values and the synth=sprite alias (which the schema does not encode as an enum). However, the 'project' parameter is entirely unexplained in both schema and description, leaving half the parameters undocumented.

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

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

The description states a specific verb+resource: it returns the 'full parameter reference (with defaults)' for an instrument type. That is clear enough for an agent to know this is a reference/help lookup rather than a mutation. It does not explicitly contrast with siblings like instrument_show, voice_help, or fx_help, 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?

Usage is implied: you call it to learn the valid parameters for a given instrument type. There is no explicit when-to-use/when-not guidance and no mention of alternatives such as instrument_show or voice_help, which cover adjacent concerns. Adequate but leaves routing to inference.

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

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

No annotations are provided, so the description carries the full burden and does deliver substantive mutation semantics: merge=True deep-merges keys while replacing the oscs list whole, merge=False replaces outright. It still omits side effects like undo coverage, failure modes for bad presets, and whether the change 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?

Roughly two dense sentences, front-loaded with the core action and followed by the merge distinction. The awkward mid-sentence line break and the un-explained parenthetical about oscs cost it a point, but nothing is wasteful.

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

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

An output schema exists, so return values need not be described, and the merge behavior is the key unknown the description resolves. For a mutation tool with zero annotations it should still say more about permissions, error behavior, or reversibility to be fully self-sufficient.

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 does compensate partially by explaining merge (default behavior and its two modes) and the 'preset:<name>' form of instrument. It says nothing about project or track, leaving two of four parameters undocumented anywhere.

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 ('Set a track's instrument'), which cleanly separates it from siblings like instrument_show, instrument_help, and instrument_fit. It lacks any explicit reference to those siblings, but the purpose itself 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?

There is no when-to-use guidance, no prerequisites, and no naming of alternatives such as instrument_show for inspection. The merge semantics explain how the call behaves but not when an agent should reach for 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?

No annotations exist, so the description carries the full behavioral burden. It implies a read ("Show") but discloses nothing else: no permissions, no side effects, no note about what happens when the track has no instrument. The full/default note is parameter behavior, not 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?

A single, front-loaded sentence with no wasted words. Terse to the point of under-specification, but efficient as written.

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

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

An output schema exists, so return-format detail is not required. For a simple read tool that is adequate, but with 0% param coverage and no annotations, the description leaves the two required parameters unexplained.

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

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

Schema description coverage is 0%, so the description must compensate, yet it only addresses one of three parameters (full=True includes all defaults). The required project and track parameters are left entirely undocumented in both schema and description.

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

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

States a specific verb ("Show") and resource ("a track's instrument JSON"), which clearly distinguishes it from sibling mutators like instrument_set and from instrument_help/instrument_fit. It does not explicitly name a sibling, but the noun scope communicates the read purpose unambiguously.

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 and no reference to alternatives. With siblings like instrument_set, instrument_help, and instrument_fit present, the agent gets no signal about when viewing raw instrument JSON is the right call versus editing or getting 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 does disclose significant behavior: apply=True writes fader changes, the proposed change is uniform per stem, and downstream processors alter levels after application. It does not detail permissions, reversibility, or error conditions, which leaves some 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 core purpose and apply behavior are front-loaded, but the second clause about comparing sums is dense, and the prerequisite and re-render advice make the paragraph long and somewhat run-on. It is informative but could be tighter.

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

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

An output schema exists, so return values need no explanation. However, for a tool with a destructive side effect (apply=True), unknown bars semantics, and no annotations, the description is adequate but not fully complete on parameter behavior and error/permission conditions.

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 should explain the three parameters. It documents apply=True well and implies a project/reference context, but it does not explain the bars parameter at all, leaving one of three parameters 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 states a specific verb and resource: it compares per-stem levels against a reference and proposes fader changes, with apply=True writing them. This is clearly distinguishable from siblings like separate or stem_map_set, though the 'sum of the mapped stems' phrasing is slightly dense.

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 states prerequisites: needs stem_map_set, separate(source='ref') and render(stems=True) over the same bars. It also advises re-rendering and re-checking after applying because compressors and the limiter move levels. It does not, however, name an alternative tool or explicitly say 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?

With no annotations, the description carries the full burden. It does disclose result ordering ('best matches first') and that results include a 'whether the change worked' signal, which is useful behavioral context. However it does not state that this is a read-only operation, nor any permission or rate considerations, leaving the safety profile unstated.

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

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

Purpose is front-loaded in the opening clause, followed by the two directional examples. The parentheticals are informative rather than filler, though the phrasing is slightly dense.

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

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

An output schema exists, so return values need not be explained. But with no annotations and 0% schema description coverage across three parameters, two of which ('who', 'project') are entirely undocumented, the definition is only partially complete 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 0%, so the description must compensate. It explains the 'text' parameter well via the example text='high shelf', but the 'who' and 'project' parameters are documented nowhere in either the schema or the description, so only one of three parameters gains meaning.

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

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

States a specific verb+resource: a bidirectional lookup between a person's vocabulary and system terms, with a concrete example ('crisp', 'high shelf'). It does not explicitly name or distinguish itself from the nearby siblings lexicon_note and lexicon_view, so the agent must infer the read-vs-write split from names alone.

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

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

Usage is implied by the motivating examples ('what did X mean last time', 'so you can say it their way'), which convey why an agent would call it. There is no explicit when-not guidance and no reference to lexicon_note/lexicon_view as alternatives for writing or viewing entries.

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 file is local and shared by every session (writes are globally visible), that updates mutate only means/craft/outcome/why while 'said' is immutable, and what the tool returns. It omits any permissions/rate-limit or concurrency caveats, keeping it short of a 5.

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

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

Purpose is front-loaded and the body is organized as field:meaning pairs with concrete examples that earn their place. It is dense and reads as one long run-on paragraph, with some parenthetical examples that could be trimmed, but little is genuinely 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?

For a nine-parameter tool with no annotations and 0% schema coverage, the description covers the core fields, allowed values, constraints, update semantics, and shared-file behavior. The output schema exists so return values need not be spelled out (it still notes them), and the undefined who/where/project params are the main residual gap.

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

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

Schema coverage is 0%, so the description must compensate, and it documents six of nine params in detail: said (verbatim words), means (mapped system terms), craft (with a full enumerated role list absent from the schema), outcome (open|worked|partly|missed), id, and why. Only who, where, and project are left undefined, so it substantially but not fully closes the gap.

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

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

States a specific verb and resource: 'Record what the person called something, and what it means.' The record-a-lexicon-entry purpose is clear. However it does not differentiate itself from the sibling lexicon_find/lexicon_view tools, leaving the agent to infer the boundary.

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

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

Gives a clear update mode ('Update an entry with id=...; the words themselves never change') and an explicit exclusion ('Words about the work only: never record emotion, mood or health'). It even points at lexicon_view for locating the file. It stops short of saying when to record vs. when to look up, so it is not a full when/when-not/alternatives statement.

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 implies a safe read ('view', 'readout', 'Read it') and discloses the 'since' scoping constraint, but says nothing about permissions, rate limits, or whether the aggregate readout is cached/live.

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

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

Purpose is front-loaded, but the middle is a dense run-on enumerating readout sections with parentheticals, making it hard to scan. Several clauses could be tightened without losing meaning.

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

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

An output schema exists, so return values need not be described and the content enumeration is a bonus. However, three of four input parameters are undocumented, which is a real gap for an agent trying to filter the readout.

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% for 4 parameters. The description explains only 'since' (with an example) and leaves 'who', 'craft', and 'project' entirely undefined in both schema and text, so it does not compensate for the coverage gap.

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

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

The description enumerates what the readout contains (entries by craft/outcome, share of trade words by month, new entries per week, unmapped entries, newest ten), which conveys the resource. But it never states a clean verb+scope ('view the lexicon'), relies on the poetic 'vocabulary as a readout,' and gives no hint it differs from lexicon_find or lexicon_note.

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?

'Read it at the start of a session to speak the person's language' is explicit timing guidance for when to invoke it. It stops short of naming alternatives or when-not-to-use (e.g. vs lexicon_find), so it is clear context without 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 delivers real behavioral context: wet-only signal behavior for reverb/delay unless 'dry' is given, that a replaced chain's tail rings out, and that remove=True destroys both the bus and the sends into it. It does not mention permissions, rate limits, or throttling, and avoids return-format detail (an output schema exists), so it is strong but not exhaustive.

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

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

Front-loads the core purpose before diving into fx and remove semantics, and every sentence carries information. It is dense and parenthetical-heavy, but 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?

For a mutation tool with no annotations, an output schema (so return values need not be described), and 0% schema coverage, the description covers the destructive semantics and fx grammar but leaves 'at' and 'volume_db' unaddressed. Adequate but with a clear gap in the parameter surface.

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 across 6 params. It explains fx thoroughly (list, or 'bus:<name>'/'track:<name>' copy syntax from project.json) and clarifies remove=True, but says nothing about 'at' (default 'now') or 'volume_db', leaving two parameters entirely undocumented in both schema and text.

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

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

States a specific verb+resource ('Create or change a send bus') and immediately defines the concept with a concrete example ('one hall for many tracks'). An agent can distinguish it from generic siblings like bus_add and fx_add. It stops short of explicitly contrasting itself with the similarly-named bus_add sibling, so 5 is not warranted.

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 shows the intended integration path ('tracks feed it with live_track(sends={bus: dB})') and notes remove=True deletes it, which implies usage. However, it never states when to prefer this over the sibling bus_add or when not to use it, leaving the routing decision to inference.

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