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 it does disclose the important traits: windowed output of at most max_rows (cap 1000), start-frame pagination with the next-window pointer on the last line, 'bars up to 64', and '-' meaning unvoiced. It does not say whether only the window is analysed at a cost, how long analysis takes, or anything about project scope/permissions, so the behavioral picture is good but not complete.

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 first clause and every sentence carries information (output fields, alternative tool, windowing, tuning advice). The first sentence is a long enumeration that is dense to parse, but nothing is filler.

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

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

For a complex analysis tool it covers scope, output shape, pagination caps and the key tuning lever; the existence of an output schema means it did not need to spell out return structure as thoroughly as it did. The remaining gap is the unexplained project/source parameters and whether unvoiced frames are retained in the window.

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 8 parameters, so the description must compensate; it gives real meaning to hop_ms, start, max_rows, fmin/fmax and partially bars. However the required 'project' parameter and the opaque 'source' (default 'ref:other') are never mentioned, leaving two parameters with no semantics 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 ('pitch contour of a monophonic line') and enumerates the exact output columns (time, bar, beat, f0 Hz, float MIDI, nearest note + cents, voicing probability). It also explicitly separates itself from the nearest sibling: 'for a pitch per note use analyze_melody(cents=True)'.

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?

Names the concrete tasks it serves (slides, vibrato, ornaments, intonation incl. quarter-tone maqam steps) and the alternative for a different need. It adds a practical exclusion-avoidance hint: 'Narrow fmin/fmax around the line when a backing or an octave error pulls the reading.'

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?

No annotations are provided, so the description carries the behavioral burden, and it does disclose measurement windows, band defaults, per_beat subdivisions, printed columns, reference-comparison output, and beats it could not follow. It does not explicitly state read-only/no-side-effect behavior, though the analysis framing strongly implies it.

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

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

The purpose is front-loaded, but the description is a dense, run-on paragraph with nested parentheticals that is hard to scan. Most details earn their place for a complex analysis tool, but the structure is not concise.

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

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

For a 7-parameter analysis tool with no annotations and no schema descriptions, the description gives enough measurement and output behavior to invoke it correctly, and the output schema covers return values. Minor gaps remain around the project parameter and an explicit no-mutation statement.

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

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

With schema description coverage at 0%, the description compensates well by explaining band defaults, window_ms, per_beat values, source formats such as render and track:<name>, against='ref', and bars slots. It leaves project unexplained and gives only an approximate format for the bars array.

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 identifies a specific analysis target—per-note feel—and enumerates timing and level metrics such as timing spread, offbeat placement, and level by metric position. It distinguishes the reference-comparison mode and feel_from_ref check, but does not explicitly differentiate itself from nearby siblings like analyze_swing or analyze_grid.

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

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

It explicitly says to reach for the tool when a draft sounds MIDI-like, mechanical, robotic, stiff, or quantized against a reference, or to check feel_from_ref's result. It also advises reading a stem when the part shares its band, but does not give explicit when-not conditions or a full list of alternatives.

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

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

With no annotations, the description carries 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 and does useful work: it discloses the thumb band (55-190 Hz) vs finger band (1.5-6 kHz) cross-check, reports disagreement and a likely-beat verdict, and gives the 3-3-2 bossa pitfall. What's missing is any statement that this is a read-only/non-destructive analysis and roughly what it costs or requires.

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?

Outputs are front-loaded in the first sentence, with downstream use and the band cross-check following. The closing bossa-guitar example (122 BPM for 92) is illustrative but verbose for the space it occupies.

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 the behavioral narrative is strong. However, with zero annotation coverage and 0% schema description coverage on three parameters, the definition leaves the agent guessing about inputs and safety profile.

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 explain the three parameters and it largely does not. 'Reference drum stem' loosely gestures at the source parameter but never names it, and bpm_hint — a meaningful input that changes behavior — is entirely unaddressed.

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 time, tuning offset from A440, and swing. That is far more than a restatement of 'Analyze Grid'. It stops short of distinguishing itself from siblings like analyze_swing, analyze_tuning, or analyze_bars, which it partially overlaps.

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 downstream context, and 'with a reference drum stem' implies a precondition for the swing metric. But there is no explicit when-to-use/when-not guidance relative to analyze_swing, analyze_tuning, or analyze_bars, so the agent must infer 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 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 behavioral burden and discloses that the tool prints pitch region, energy share and hit pattern, and writes component audio files under <project>/analysis/kit/. It also warns not to use the outputs in the render. It does not mention overwrite behavior or computational cost, which keeps it from a perfect score.

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 operation and then layers in sibling differentiation, output behavior, tuning guidance and usage context. It is dense and long, but nearly every clause contributes useful information.

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

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

An output schema exists, so return values need not be described. The description still covers the analysis method, printed diagnostics, file outputs and intended downstream uses. The main gap is that one input parameter (bars) and the exact source parameter format are not explained anywhere.

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 k as the number of NMF components, cycle as the loop length in bars, source as the drum source, and project as the output root. It does not explain the bars parameter or give exact source syntax, so coverage is incomplete.

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

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

The description uses a specific verb and resource: it discovers drum-kit pieces by splitting a drum source with NMF into k components. It also explicitly distinguishes itself from the sibling analyze_drums, which shows only 3 band lanes and hides pieces.

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 ('when a snare, kick or hat sounds dated, generic or not the genre's'), names the alternative analyze_drums, and says the exported WAVs should be used as sound_import/instrument_fit targets but never in the render. It even provides a stopping heuristic for choosing k.

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

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

With no annotations, the description carries the behavioral burden and does well: it discloses the confidence output, warning conditions when another pitch is within 6 dB, cents output shape, vibrato averaging behavior, and full-mix behavior. It does not explicitly state that the operation is side-effect-free, but the analysis framing and output description imply a non-mutating 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?

The description is dense but front-loaded with the core transformation and output format. Some sentences are long and parenthetical, but the technical detail is mostly necessary and no obvious filler is present.

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 9 parameters, no annotations, and 0% schema description coverage, the description is only partially complete. It covers the most unusual musical parameters well, but omits meaning for source, quant, min_conf, and project, which an agent may need in order to call the tool correctly.

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

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

Schema coverage is 0%, so the description must compensate. It explains fmin/fmax restrictions, cents output, vibrato_ms, and the 16-bar limit, but does not explain project, source, quant, or min_conf, leaving several 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 converts monophonic pitch into a note list in notes_write format, with a 16-bar limit. It clearly distinguishes the tool from analyze_contour, analyze_roll, and full-mix use by explaining that contour is for pitch movement inside a note and roll is for ornaments.

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

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

It explicitly says to use this on a stem or soloed line, and that on a full mix the loudest line wins, usually the bass. It names analyze_contour for slides/vibrato/ornaments and analyze_roll for cases where an ornament matters, giving clear alternatives and conditions.

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

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

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 provided, the description carries the full burden and does a substantial job: it discloses the build-detection rule (a pre-climax section 2 dB or more quieter on average but peaking within 3 dB), the vanishing-quiet-section flag, the path resolution order (working directory then project), and the stems prerequisite. It does not state cost, runtime, or whether anything is written, but for a measurement tool the disclosed heuristics are the more valuable information.

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 content is front-loaded with the metrics, which is good, but the prose collapses into run-ons and nested parentheticals; the closing sentence about stems, buses, and parts routed to master versus a bus is nearly unparseable on first read. Editorial asides ('the climax will not arrive, and this only showed up here') crowd out operational detail and hurt scannability for an agent parsing the text.

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

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

An output schema exists, so return values need not be described, and the description instead covers segmentation defaults, flag semantics, path resolution, and the stems prerequisite — the things the schema cannot express. The remaining gap is that it never states the acceptable values of `source`, which matters for a 4-parameter tool with 0% schema 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 description coverage is 0%, so the description must compensate, and it does for the hardest parameter: the `sections` map format is spelled out with a concrete example ('{"intro": [1, 4], ...} (bars inclusive)') and its default behavior when omitted. `block` is explained as the fallback block size in bars, `project` via the path lookup rule, and `source` only obliquely (render vs reference implied by the stems sentence) — the missing piece is the allowed values for `source`.

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

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

The opening clause 'Loudness per section: rms, peak, loudest and quietest 400 ms, and the song's dynamic range' names the exact measurement set and the unit of analysis, so an agent knows precisely what it gets. It does not, however, distinguish itself from close siblings such as analyze_overview, analyze_structure, or cmp_sections, leaving the choice between section-level loudness and whole-song structure analysis to inference.

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

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

Usage conditions are implied rather than stated: 'omitted = blocks of `block` bars' tells the agent the default segmentation, and the stems sentence reveals the prerequisite that a render with stems=True (or a separated reference) must already exist for part-level output. There is no explicit 'use this when X, use analyze_overview when Y', so selection against siblings is left to inference.

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

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

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 does substantial work: default source resolution order, per-step output contents (hits, accents, median offset, most-played 16-step strings), pluck detection logic via threshold against the 95th percentile peak, and drift reporting above 3%. It never states that the operation is read-only/non-destructive or what permissions/project state it requires, which is the remaining gap 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?

The purpose is front-loaded in the first sentence and almost every clause adds operational information rather than filler. The cost is density: a single ~70-word sentence covers all of follow mode, and undefined/elliptical references ('reads X', 'the thumb') make parts harder to parse than necessary.

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

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

For a five-parameter analysis tool with an output schema (so return format needn't be re-explained) and no annotations, the description covers sources, modes, thresholds, band defaults and the fixed-grid caveat — enough to call it correctly in normal cases. It omits any statement of safety/read-only nature or what 'project' expects, which keeps it from being 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% across five params, and the description compensates for most of them: source default resolution and 'track:<hats>' syntax, follow semantics at length, band_hz defaults per material ([1500,6000] plucks, [6000,16000] hats), and threshold's meaning plus a suggested value (0.5). Only 'project' is left implicit, and the threshold guidance contains an undefined placeholder ('reads X on every step'), which blunts precision.

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

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

The opening sentence states a precise measurement — how late swung hi-hats land, in beats and milliseconds — and anchors the scale with 'Straight = 0' and the 16th/8th reference points, so the resource and output semantics are unambiguous. It never names a sibling (e.g. analyze_grid, analyze_roll) to explicitly delimit scope, though the closing mention of 'the fixed grid smears the offsets' implicitly contrasts grid-based timing with this beat-line reading.

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 two concrete usage scenarios: 'Use it on a reference before writing swung notes, and on track:<hats> to check yours.' It also states the condition that selects follow=True (a record that drifts, played without a click). There is no explicit when-not or named alternative tool, so it stops short of a 5.

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

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

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?

With no annotations, the description carries the full behavioral burden and does so thoroughly: it explains the pitch-reading method, skip_ms fallback behavior, attack-only handling, what is skipped and never flagged, grid and key defaults, verdict categories, and error recovery steps. This is far beyond what the schema and annotations provide.

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 and the detailed sections are structured by concern: reads, per-note method, grid, returns, verdicts, errors. It is dense and long, with some illustrative details that border on excessive, but most sentences contribute useful operational context for a complex analysis tool.

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

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

The tool has 9 parameters, no annotations, a complex DSP-based behavior, and an output schema. The description covers prerequisites, error paths, skipped-part handling, return structure, and interpretation guidance, leaving no significant gap 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, and it largely does: it enumerates source modes ('render', 'ref', 'track:<name>', 'ref:<stem>', 'sound:<name>', 'render:mix', 'ref:mix'), explains stems and bars filtering, defines skip_ms behavior, describes tuning_cents and key defaults, and explains tol_cents and worst. Only 'project' is left implicit, which is minor.

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: 'Check every part of a render against the song's tuning grid (12-TET) and key, and flag notes more than tol_cents off.' That is enough to distinguish it from neighboring analysis tools like analyze_key or analyze_pitches.

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 clear trigger: 'Run it after the first render of a song with pitched percussion or a voice playing in a new register, and before any exam.' It does not name an explicit alternative tool to use instead, but the usage context is concrete enough to guide selection.

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

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

With no annotations, the description carries the full burden and does it well: it discloses the hidden prerequisite that it reads the last render(stems=True), defines exactly what counts as 'the rest' (other track stems to master plus bus stems, bus counted without the voice), specifies the frame gate (within 30 dB of the voice's loudest), and names the band split. It also bounds expectations by stating no speech server or transcription is assumed.

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 question, the trigger, the data source, the computation, and the verdict arrive in a logical order with little redundancy. It is dense but nearly every clause supplies operative detail; the closing 'Built in a song and proven there' is the one line that does not directly help an agent call it.

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 verdict format need not be restated, and the description correctly stops at describing inputs and computation. The render(stems=True) prerequisite is covered. Remaining gap is edge behavior: what happens when no stems render is present, and the unstated meaning of 'project'.

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

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

Schema coverage is 0%, so the description must carry parameter meaning, and it only partly does: bars is explained as an inclusive [a, b] range, and voice is characterized as the voice's track stem. 'project' is never mentioned, and the accepted form of the voice value (track name, stem id, or path) is left ambiguous.

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: voice level versus the summed other stems, in per-band dB, ending in a masking verdict. It is clearly distinct from generic siblings like analyze_overview or cmp_bars, though it never names a competitor to sharpen the contrast. 'Is the voice heard over the mix?' front-loads the question but the actual verb+resource is only spelled out in the following sentences.

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 concrete trigger conditions ('a narrator under a drop, a vocal fighting a lead') and timing relative to another action ('before asking the person whether they can make out the words'). That is a clear use context. What's missing is a when-not or an explicit alternative (e.g., a generic spectrum/level tool) for cases where stems are unavailable.

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, so the description carries the full burden and does: it discloses the decision rules (queue, refuse for queue-length/too-soon/too-long/closed, near-duplicate counted as vote), rate limiting one vote/love per viewer per reward_s seconds, that `!love` produces no reply, and that a line is acted on once regardless of repeated handoff. These are exactly the side-effect/idempotency facts an agent needs.

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 commands and their outcomes, then usage trigger, then input/return semantics. Dense and mostly earned, though the refusals and vote-counting are packed into a long clause chain that takes a second read.

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?

Return shape is spelled out ({replies, handled, left}) and the follow-up action for each reply is given, so the agent can close the loop. Referenced dependencies (venue_rules, request_next, reward_s) are named with their role. Nothing material is missing for a one-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% and the single parameter is untyped in the schema, but the description compensates by explaining `lines` accepts chat_watch's JSON as-is or just its lines array. That is the critical semantic; it stops short of a formal shape example but is sufficient.

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 (handle chat's `!request`, `!vote`, `!love`) and enumerates the exact command syntax it owns. Sibling tools chat_watch/chat_say are functionally distinguished: this tool consumes chat_watch output and defers speaking to chat_say.

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?

Explicit trigger: reach for it when chat_watch returns lines with commands in them. Explicit handoffs: replies go out via chat_say(text, reply_to=...), and undecided commands come back in `left`. No ambiguity about when this tool applies vs alternatives.

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

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

With no annotations, the description carries the full burden and delivers real behavioral detail: messages are returned newest-first bounded by limit/since, filtering to venue/user means only those, and records with ok=false were refused and are never shown. It omits what happens on empty results or errors, and doesn't confirm whether history is bounded in any other way.

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 and ordering rule come first, then the record shape, then the usage and handoff — a sensible front-loaded order with no filler sentences. The 'kind said, with by and ok' fragment is dense shorthand that costs some readability but packs genuine information.

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

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

An output schema exists, so return values need not be described, yet the description still sketches the record shape (kind/with/by/ok) helpfully. For a 4-parameter read tool it covers scope, ordering, filtering, and the follow-up workflow; only edge-case behavior (empty history, since out of range) is unaddressed.

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 address all four parameters: limit (newest N lines), since (a position after which to read, clarified by 'since=<its last>' implying a last-seen position), and venue/user (restrict to only those). The venue/user phrasing is terse and it never clarifies that since is an integer line index rather than a timestamp, so the compensation is good but not complete.

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 ('Chat history from the log') plus the exact ordering and scope rule ('newest limit lines after since'). It goes further by naming the sibling chat_watch and differentiating the read-from-log role from the live-watch role, so an agent can tell them apart 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 two concrete use cases ('catch up after a gap', 'see what was already answered') and an explicit follow-up handoff: chat_watch(who, since=<its last>) so nothing is answered twice. The only gap is that it never states an explicit 'do not use this when...' exclusion; the live-vs-history split is only implied by the handoff.

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

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

With no annotations present, the description carries the behavioral load and does it well: it spells out platform-dependent reply threading (Twitch/Kick threaded vs '@name' on YouTube) and the three refusal conditions (over-length, duplicate line within 30 s, venue rate-limiting). That is real operational context an agent cannot get from the bare schema. It stops short of 5 because it never states what a successful post looks like operationally (e.g. what the null venue/who defaults resolve to) or what happens to the line after posting.

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

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

Front-loaded with the action, then trigger conditions, then parameter semantics, then failure modes — a sensible ordering with no filler sentences. The middle is slightly dense and run-on (the reply_to parenthetical spans two platform behaviors in one breath), but nothing is 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 an unannotated 4-parameter mutation tool this covers the essentials: when to call it, what each parameter does, and the concrete refusal cases. The output schema is present so return values need not be described. The remaining gap is the meaning of null defaults for venue and who, which an agent may need to reason about before omitting them.

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 all meaning must come from the prose, and it delivers: reply_to is explained as a chat line's number with per-platform rendering, venue is explained in both forms ('<name>' for one venue, 'all' for every reading venue), and who is described as the role logged with the line. Every one of the four parameters gets semantics beyond its bare JSON type.

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 gives a concrete verb and resource ("Say one line in chat") and the following clause frames the intent (reply to a viewer, answer someone, greet the room), so an agent can picture the action immediately. It is not explicitly contrasted with near-siblings like phone_say or stage_say, but "in chat" plus the venue/reply_to discussion makes the target channel 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?

"Reach for it when you reply to a viewer, answer someone in chat, or greet the room" is an explicit positive trigger set rather than an implied one. There are no exclusion rules or named alternatives (e.g. when to use chat_read first to find a line number), which keeps it short of a 5.

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

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

With no annotations, the description carries the full burden and does so richly: it discloses blocking behavior, place-remembering, burst gathering with a 3-second second look, filtering of own echoes by default, and the wait_min timeout returning {alive: true}. These are exactly the behavioral traits an agent needs to invoke and re-arm it correctly.

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 purpose and operational behavior, and most sentences carry useful information. It is dense and somewhat run-on, and it repeats return-shape details despite an output schema, but it avoids empty filler.

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

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

For a complex blocking watcher with no annotations and no schema parameter descriptions, the description covers the key behavioral contract, return shape, re-arm loop, timeout, and self-echo filtering. The main remaining gap is parameter documentation for who, since, and venues, but the operational picture is otherwise fairly 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%, so the description must define all parameters. It explains wait_min and include_self well, and implies who via the `who=MC` example, but it does not clearly define `who`, explain the input meaning of `since`, or clarify the `venues` filter beyond the vague phrase 'only these'.

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: a standing chat watcher that blocks until chat arrives, returns it, and remembers its place. The blocking and re-arm behavior clearly distinguishes it from a passive chat read, even without naming chat_read 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?

It gives clear operational guidance: reach for it when reading a stream's chat, run it in the background, act on returned lines, and re-arm it first after every wake. It also directs replies to chat_say(text, reply_to=<its n>), though it does not explicitly contrast with chat_read or state when not to use this watcher.

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 at all, the description must carry the full behavioral burden. It does disclose what the tool computes (chroma_sim, rhythm_corr, band dB deltas, log-mel L1, worst bars, advice) and hints at staleness via render's last-run reply, but it never states that this is a read-only analysis that does not alter the project, render, or reference. For a no-annotation tool, that omission is a real gap even though the name implies non-destructiveness.

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?

Dense but purposeful: purpose, output scores, stem syntax, and usage conditions are all front-loaded in roughly two sentences. The phrase 'render's reply says when it last ran' is slightly oblique and the 'plus the worst bars and advice' clause jams return detail in, but there is no filler and every clause contributes.

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 still outlines them helpfully. The unresolved gaps are the undocumented bars, detail, and offset_b parameters and the lack of any explicit statement about side effects or permissions. For a 6-parameter, 0%-schema-coverage tool, that leaves an agent with meaningful uncertainty before calling it.

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

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

Schema description coverage is 0%, so the description must compensate, and it does add genuine meaning for the two most important parameters: a and b default to 'render' and 'ref', and stem targeting is shown with a='track:bass', b='ref:bass'. However, three of six parameters — bars, detail (default 8), and offset_b (default 0) — receive no mention at all, leaving their semantics 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 verb and resource: 'Compare two sources bar by bar on the project grid', with the default comparison pair (render vs reference) spelled out. It does not name the cmp_* siblings, so an agent must infer that this is the general bar-level comparator rather than the summary/section/bars variants, but the core action 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?

Gives explicit triggers: use when a reference is set (as target or inspiration) and a draft is about to go to the person, or when feedback says it does not match the reference. It also notes that 'render's reply says when it last ran', which supports deciding whether to re-run. No explicit exclusions or named alternatives (cmp_summary, cmp_sections, cmp_worst) are given, so it stops short of full routing guidance.

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

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

With no annotations, the description carries the full burden and does well: it discloses what no-args returns (every setting, one line each, grouped), what key mode returns (value, source among settings file/env var/default, accepted values, and restart semantics), and what group mode returns. It never explicitly states that the operation is read-only and side-effect free, but the 'get' framing and contrast with config_set make that clear in practice.

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

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

It front-loads the modes correctly and every sentence contributes information, but the opening inventory of settings and the informal 'ismail's settings' framing are slightly verbose. The prose is dense and list-like rather than elegant, though still readable and free of filler.

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

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

For a zero-required-parameter read tool with an output schema, the description is nearly complete: it covers all three modes, the source-of-value and restart metadata, and sibling routing. It does not explicitly state whether key and group can be combined or that they are mutually exclusive, which is the one small 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, and it does: it gives example key values ('songs', 'ffmpeg', 'live.trim_db') including dotted nesting, example group values ('paths', 'tools', 'live'), and explains the behavior of each mode including the no-argument default. It adds substantial meaning the bare schema lacks.

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 (retrieving settings) and immediately enumerates its three modes, no-args, key, and group, with concrete examples like 'live.trim_db' and 'paths'. It is clearly distinguishable from config_set and config_unset, which it names and contrasts.

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

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

Explicitly says when to reach for it ('when you need to know where songs are saved, which ffmpeg or Blender ismail uses, or why a folder is where it is') and clarifies the division of labor with config_set ('changes one') and config_unset ('returns one to its default'). That is explicit when-to-use plus alternatives.

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

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

With no annotations, the description carries the full burden and does so: value validation against the setting's declared type and range, persistence to a named file, and — unusually valuable — that the reply reports old vs new value, immediate-vs-restart applicability, and environment-variable precedence. Reversibility is covered by pointing at config_unset.

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

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

Front-loaded with the action and its consequences, then usage triggers, then per-parameter semantics, then siblings — a sensible order with no filler. The sentences are long and dense, which slightly hurts scanability, but every clause carries information.

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

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

An output schema exists, so return shape needn't be spelled out, and the description still usefully previews what the reply contains (old/new value, restart behavior, env precedence). For a two-parameter mutation tool with no annotations, nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: key is defined by reference to config_get's listing with dotted examples ('songs', 'ffmpeg', 'live.trim_db'), and value carries concrete typed examples ('D:/music', -3, true, ['dj','mc']) backed by the earlier type enumeration. The key set itself is not enumerated, which keeps it short of a 5.

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

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

A specific verb ('Change') plus resource ('one of ismail's settings') with the full effect chain (type-checked, written to ~/.ismail/config.json) stated up front. It explicitly contrasts itself with the sibling readers/writers config_get and config_unset, so an agent can place it without opening a schema.

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

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

It gives concrete when-to-use triggers ('songs in another folder', 'ffmpeg, Blender or browser it did not find', 'live master's trim or cap changed') and names the alternatives with their roles: config_get(key) reads it back, config_unset(key) returns it to the default.

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

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

With no annotations, the description carries the burden and does reasonably: it discloses the mutation's concrete effect ('its line leaves the settings file') and that the reply reports the effective value and when it applies. It omits error behavior for unknown keys and whether the removal is reversible, which keeps it short of a 5.

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

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

Three short sentences, front-loaded with the core effect and with zero filler. The clause about when the value applies is slightly oblique but plausibly meaningful for a live settings system.

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, yet the description still summarizes what the reply contains. For a one-parameter mutation with no annotations this is nearly complete; the remaining gap is failure behavior for unknown or non-existent keys.

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

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

Schema coverage is 0% – the single `key` parameter is an undescribed string. The description implies the key names a setting and references `config_get(key)` to establish the read/write pairing, but gives no format, casing, or valid-key guidance to compensate for 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 states a specific action on a specific resource: return a named setting to its default by removing its line from the settings file. It also implicitly distinguishes itself from config_set/config_get by naming config_get as the read counterpart. It is clear, though the phrasing 'one of ismail's settings' leans on project-specific naming rather than a generic resource noun.

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: you use this when you want a setting back at its default rather than set to a value. It points to config_get as the read-back path, which helps orient the agent, but never says when to prefer this over config_set to a default value, nor what happens for keys that are already default or unknown.

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 load and does so: it explains file creation, overwrite risk ('may have been edited by hand'), footer's write-nothing behavior, and that uncredited ref/ files are listed in the reply. This is rich behavioral context beyond what the schema provides.

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 write operation and each clause adds operational detail, but the single dense paragraph is longer than necessary and includes layered caveats. Still structured and mostly earns its length.

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

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

For a 5-parameter, no-annotation, output-schema-bearing tool, the description supplies enough context to call it safely, including side effects, exclusions, and footer return. The only minor gap is the lack of an explicit project parameter definition.

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 the parameters. It covers out, overwrite, format='footer', and consulted=True, but does not explicitly define the required 'project' parameter; hence 4.

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

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

States a specific verb ('Write') and resource ('the piece's credits / CREDITS.md at the song root') and describes the inputs it draws from. It is clear, but it never explicitly differentiates from the sibling request_credits, so 4 rather than 5.

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

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

Gives a concrete trigger for footer mode ('Reach for it whenever you build a listening page or post by hand') and a caution ('Review the file before it goes public'). It does not name alternatives or state when not to use it, so no 5.

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

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

With no annotations, the description carries the full burden and does so: it states that nothing is played and no engine is touched, that results are machine-state-dependent ('a busy machine reads slower'), and that `wait` queues the call when the machine is busy. That is meaningful non-obvious behavioral context that no structured field provides.

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 body is a dense run-on packed with parentheticals and semicolon-linked clauses. Most content earns its place, yet the same ideas (offline render, machine-dependent numbers) are restated, and the prose could be tightened substantially without losing signal.

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

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

For a five-parameter diagnostic tool with no annotations, the description covers what it measures, why it matters, and how the numbers should be interpreted. An output schema exists, so the lengthy enumeration of report fields is largely redundant, but nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 0%, so the description must compensate, and it covers all five parameters: project ('the song's project folder, as live_load takes it'), bars ('the deck window live_load will get, first bar measured'), bpm ('the house tempo, default the song's'), workers (render workers, live_start's default), and wait ('stand in line this long when the machine is busy'). Only the string format of `wait` (e.g. '10m') and the shape of `bars` beyond a two-element window are left implicit.

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

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

The description states a specific action and scope: an offline render of the song's first bar, timed the way the live engine renders it, with no playback. It distinguishes itself from live_start/live_load by emphasizing 'nothing played, no engine touched,' though the opening clause is wordy enough that the core purpose takes a few reads to land.

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 trigger ('Reach for it when planning a set or a reset'), a concrete question it answers ('which deck leaves a silent gap after live_load, how long, and which track makes it'), and names the follow-up alternatives (load heavier decks earlier, pick a lighter section, or track_freeze). Explicit exclusions are absent but the usage context is clear.

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