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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds real behavioral context beyond that by disclosing the shape of the result ('Ends with `issues`: plain-language problems ranked by severity') and a runtime cost knob. It stops short of noting limits such as supported formats, file-size constraints, or expected runtime.

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 long capability list is dense rather than padded, every clause names a distinct measurement, and the core purpose leads the sentence. It is on the verbose side but no sentence is wasted.

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

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

With no output schema, the description carries the return-value burden and does so partially, naming the `issues` summary and the category of measurements returned. For a 5-parameter analysis tool it is close to complete, lacking only parameter units and format/limit caveats.

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 carry the burden. It does explain two parameters meaningfully – `start`/`end` as the analyzed section and `pitch`/`rhythm` as speed-vs-depth toggles – but it never states the units for start/end (seconds?) and says nothing about `path` beyond the obvious.

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

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

States a concrete verb (measure) and resource (an audio file or its start..end section), then enumerates the exact measurement families produced: loudness, clipping, DC offset, silence/noise floor, stereo field, spectral balance, pitch, onsets/tempo, loop-seam quality. That enumeration makes it easy to separate from siblings like audio_info (metadata) or audio_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?

The only actionable guidance is the performance tradeoff 'Set pitch/rhythm to false to run faster,' plus the implicit scoping note about analyzing a start..end section. There is no explicit when-to-use versus audio_info, audio_check_delivery, or audio_compare, so usage is only implied.

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

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

Annotations already establish this is a non-read-only, non-destructive, closed-world write. The description adds real behavioral detail beyond them: same relative output names, refusal to write into the input folder without overwrite=true, and subtype validation happening before any file is written. It stops short of describing partial-failure behavior when one file in a batch fails.

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 contract (one chain, every file, output naming), then safety, then a compact example, then subtype notes. Dense but every paragraph carries information; the subtype sentence is slightly run-on but still earns its place.

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

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

For a 6-param mutating tool with no output schema and no schema descriptions, the description covers the essentials: what is processed, where output lands, the overwrite safeguard, and operations format. Gaps remain around pattern/target semantics and per-file error handling, but an agent can 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 coverage is 0%, so the description has to carry the load. It explains subtype (with concrete values), the overwrite safety gate, the operations chain format via example, and output_dir semantics, but leaves target (folder vs list) and pattern interpretation largely implicit, so half the params remain under-specified.

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

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

States a specific verb and scope: apply one operations chain to every file in a folder or list, writing results into output_dir. The batch framing clearly distinguishes it from the sibling audio_process (single-file) and audio_batch_survey (inspection rather than processing).

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?

Makes the when-to-use condition clear through the batch framing and a concrete example (normalize a set of sound effects), and adds a critical usage constraint: it refuses to write into the input folder unless overwrite=true. It does not explicitly name audio_process as the alternative for single files, but the batch/single split is strongly implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: it discloses the return contents (issues list, per-file table, suggested_fixes with ready-to-use operations) and that recursion is applied, though it says nothing about cost or large-folder behavior.

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

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

A single dense sentence with the primary verb and resource front-loaded, followed by the report contents and the audio_batch_process handoff. Every clause carries information; only the parenthetical examples make it slightly heavier than needed.

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

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

With no output schema, the description carries the burden of describing returns and does so adequately (consistency findings, per-file table, suggested_fixes). For a 2-parameter read-only tool this is essentially complete, missing only corpus-size or performance caveats.

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: it explains target accepts a folder OR a list of files, and that pattern is a glob (e.g. "*.wav", "footstep*") used to filter. It omits the explicit default "*", which the schema still supplies.

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 (analyze/report) and resource (a folder of audio files or a list of files) with the exact scope of analysis: loudness, sample rates/channels/formats, and leading silence. It also implicitly distinguishes itself from the sibling audio_batch_process by being the read-only consistency survey whose suggested_fixes feed that tool.

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

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

The description makes the use case clear (checking batch consistency before processing) and explicitly names the downstream tool audio_batch_process, which routes the agent within the sibling set. It stops short of stating when NOT to use it, so no exclusions are given.

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

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

Annotations only declare readOnlyHint and openWorldHint, so the description usefully adds that the fix is an ordered operation list 'simulated on this file' (fix.verified) and enumerates what cannot be fixed (clipping, unfixable noise floor, wrong length). It also notes each result cites sources and check dates. It does not clarify write behavior beyond the simulation hint or any cost/latency characteristics.

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 purpose and return shape, then spec list, then the cross-tool follow-up. Dense but nearly every clause carries information; only the parenthetical source/date note is marginal.

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

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

With no output schema, the description carries the full burden of describing returns, and it does so well (verdict levels, per-criterion fields, fix/fix.verified, cannot_fix). For a read-only check tool this is close to complete, though the unexplained start/end parameters leave a 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 schema gives no parameter meaning, but the description compensates for `spec` by enumerating the valid spec values (apple_podcasts, spotify, youtube, ebu_r128, atsc_a85, acx_audiobook, game_sfx). However path, start, and end — the latter two presumably a time window — are never explained, leaving half the parameters undocumented.

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

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

States a specific verb (check) and resource (a file against a delivery spec) and immediately characterizes the output shape (verdict, per-criterion entries, fix list). It is clearly distinguishable from siblings like audio_analyze or audio_info, which don't target named delivery specs.

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

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

Gives clear usage context: check a file against one of the named specs, use spec="list" to enumerate them, and after a denoise fix verify words with audio_transcribe. It never explicitly says when to prefer a sibling (e.g. audio_analyze) instead, 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?

Annotations already establish readOnlyHint=true and openWorldHint=false, and the description reinforces this ('Read-only: never modifies the project'). It adds real behavioral context beyond annotations: truncation limits (at most max_files files, first max_seconds each), the loop-seam exception using real loop points, and the res:// path semantics.

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

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

Front-loaded with purpose, then progressively adds detail, return shape, then behavioral constraints. It is dense with parenthetical clauses and reads as a long run-on, but nearly every clause carries distinct information needed to call the tool correctly.

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, non-destructive audit tool with four parameters and no output schema, the description covers the return structure (summary, per-category categories stats, issues sorted problem > warning > info, each with res:// file and fix), the parameter semantics, and the runtime limits. An agent has everything needed to invoke and interpret 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 largely does: it explains the 'categories' override with glob examples ({"audio/stingers": "music", "*/click_*": "ui"}), and defines max_files/max_seconds as sampling limits, plus identifies project_dir via 'the folder with project.godot'. It stops short of a formal per-parameter enumeration, so 4 rather than 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?

Specific verb and resource: 'Audit the audio of a Godot 4 project (the folder with project.godot)'. The scope is enumerated precisely (inventory, import settings, loudness consistency, per-file problems, res:// references), so an agent can distinguish it from generic analyzers like audio_analyze or audio_info without opening a schema.

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

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

Gives clear context for when to use it (auditing a whole Godot 4 project's audio) and routes the agent downstream by emitting 'suggested_batch' for audio_batch_process and 'fix' entries as audio_process operations. It does not compare itself to audio_check_delivery or state exclusions, so no 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral detail beyond that: the null test aligns and subtracts, and its verdict categories (identical, gain-changed, lightly or heavily changed) tell the agent what conclusions the tool can reach. It does not disclose format support or behavior on mismatched lengths/rate, which keeps it at 4.

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 'A/B two files' before the output enumeration, and the usage directive lands at the end. The long parenthetical output list is dense but each item is substantive rather than filler, so it earns its space without being wasteful.

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

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

There is no output schema, so the description must carry the return-value burden, and it does so thoroughly by enumerating the report components. Combined with read-only annotations, safety is covered. The remaining gap is the totally undocumented pair of path parameters and unsupported edge cases (mismatched durations/sample rates), which leaves it just short of 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% and the two properties carry only boilerplate titles ('Path A'/'Path B'). The description's 'A/B two files' wording implies path_a is the reference and path_b the candidate, which is mild added meaning, but it never specifies path format, required presence, or supported file types, so it only partially compensates.

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

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

States a specific verb+resource ('A/B two files') and then enumerates concretely what the comparison surfaces (metric deltas, per-band levels, spectral similarity, null test). An agent can distinguish this from siblings like audio_analyze or audio_info because the paired-file comparison and null-test framing are unique to this tool.

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

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

Explicitly gives context: 'Use after audio_process to verify an edit did what you intended and nothing else.' That is a clear when-to-use signal tied to a workflow. It stops short of naming alternatives (e.g., when to reach for audio_analyze instead) or stating exclusions, so it is a strong 4 rather than 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: an adaptive threshold that adjusts to background level, an example output line format, and mention of spacing regularity and pitch sequences. Not exhaustive (no cost/limit notes) but well above the annotation baseline.

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 action and the returned attributes, then folds parameter behavior into the same tight paragraph with a concrete example line. Dense but every sentence carries information; only the stray 'as_text' reference adds mild confusion.

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

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

With no output schema, the description carries the return-value burden and does so convincingly via the attribute list, example line, and regularity/pitch reporting. The remaining gap is undocumented start/end semantics on a 5-parameter tool, a minor omission given the otherwise rich output description.

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

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

With 0% schema description coverage, the description must compensate and it partially does: threshold_db (dBFS override) and split_on_onsets are explained with their effect. But path, start, and end are never described, and 'as_text' is referenced as if it were a parameter though it does not appear in the schema, so half the parameters remain semantically opaque.

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

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

States a specific verb+resource ('split the audio into distinct sound events') and enumerates the per-event attributes produced, so the agent knows exactly what it yields. It does not explicitly differentiate itself from near siblings like audio_melody or audio_analyze, which limits it below a 5.

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

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

Offers conditional guidance for two parameters (override threshold_db; set split_on_onsets=false to keep continuous sounds as one event), which implies usage contexts. However, it never states when to pick this tool over alternatives such as audio_melody or audio_analyze, so routing 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?

Goes well beyond the annotations (readOnlyHint/openWorldHint), which only cover the safety profile. It discloses the FFmpeg dependency, the concrete failure mode and message when FFmpeg is absent, how formats map to format/subtype/decoded_via, and that a directory path triggers recursive listing.

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

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

Front-loaded with the core value ('Fast metadata without decoding'), followed by concrete detail. Slightly dense in the FFmpeg/container/codec sentence, but every clause carries information an agent needs; nothing is padding.

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

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

With no output schema, the description carries the return-value burden and does a fair job by naming the reported fields and the decoded_via/format/subtype semantics, plus the directory-listing variant. It stops short of specifying ordering or how many files a directory listing returns.

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

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

Schema description coverage is 0% for the single `path` parameter, so the description must compensate. It does: `path` is documented as accepting either a file or a directory, with recursive enumeration behavior on directories, which is meaningfully more than the bare string schema.

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

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

States a specific verb (read/report metadata) and an explicit scope: 'Fast metadata without decoding: format, sample rate, channels, duration.' The 'without decoding' qualifier and the enumerated fields clearly distinguish it from heavier siblings like audio_analyze or audio_transcribe.

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

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

Usage is implied rather than stated: the 'without decoding' framing and the directory behavior hint at when this cheap metadata call is the right choice, but no sibling is named and there is no explicit when-not guidance (e.g. 'use audio_analyze if you need spectral 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the result contents: notes with start times, durations, note names, cents deviation, and a compact text form, which matters since no output schema exists.

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 and output format, followed by actionable tuning advice. No filler, though the parenthetical source list is slightly long for its information content.

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

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

For a read-only analysis tool with no output schema, the description adequately conveys what is produced and how to tune the frequency bounds. The main gap is the unexplained start/end time-window parameters, but overall an agent has enough to 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% across 5 parameters, so the description must carry the load. It partially compensates by explaining fmin/fmax and giving concrete ranges (bass 40-400, voice 80-1000), but path, start, and end are left entirely undocumented.

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

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

States a specific verb (Transcribe) and a narrowly-scoped resource (monophonic line) and enumerates the applicable sources (voice, whistle, solo instrument, synth lead, SFX pitch). The 'monophonic' constraint implicitly separates it from the broader audio_transcribe sibling, but no sibling is named or contrasted explicitly.

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

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

Gives tuning guidance for fmin/fmax with concrete ranges, which is useful operating advice, but never states when to choose this tool over audio_transcribe or audio_analyze. Usage context is only implied by the monophonic-signal constraint.

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

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

Annotations only state non-readonly, non-destructive, closed-world. The description adds substantial context on top: input is never modified by default, the one override path (output==path with overwrite=true), default output path naming, and M4A/video inputs defaulting to WAV. It also discloses the return payload (before/after levels and warnings).

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 most safety-critical fact (a new file is written; input untouched) is front-loaded before the op catalog. The op listing is long but dense and non-redundant, since there is no structured documentation of the operations array elsewhere; minor tightening is possible but every line informs a caller.

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

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

Despite no output schema and 0% schema coverage, the description covers defaults, format conversion, overwrite semantics, the full operation catalog, output subtype values, and the shape of the return value. An agent has everything needed to invoke this five-parameter tool correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so well: it enumerates every operation name with its parameters and defaults (gain, normalize_*, denoise, fade, crop, resample, etc.), documents the operations object format with an example, explains output defaults, and lists valid subtype values like PCM_16/FLOAT/PCM_U8 for WAV.

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: 'Apply operations in order and write a NEW file', with concrete default naming and format-conversion behavior. It clearly conveys what the tool does, but it never names an alternative sibling (e.g. audio_batch_process for multi-file work), so an agent must infer the single-file vs batch split.

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

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

Usage is implied rather than stated: process one file with an ordered op list, and 'verify speech afterwards with audio_transcribe' hints at a follow-up step. There is no explicit when-to-use/when-not guidance or comparison to sibling tools like audio_batch_process or audio_analyze, leaving routing to inference.

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

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

Annotations already declare readOnly=false, destructive=false, openWorld=false, so the safety profile is covered. The description adds useful spec-level behavior (pink/brown loop seamlessly, dc is a constant offset), but says nothing about the file-write behavior, overwrite handling, or error cases that the output/overwrite params imply.

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 before the examples and the schema reference. The inline schema is long but largely earns its place given 0% schema coverage; it is dense rather than padded.

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

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

For a nested-spec synthesis tool with no output schema, the spec itself is thoroughly covered, but the definition omits what 'output' should contain (path/format), how 'overwrite' behaves, and what the tool returns, leaving real gaps for correct invocation.

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

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

Schema coverage is 0%, so the description carries the burden, and it documents the complex nested spec object exhaustively (wave enums, freq/freq_end, envelope, vibrato, tremolo, filters, sequence) with worked examples. It leaves the 'output' and 'overwrite' parameters entirely unexplained, which keeps it from 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?

The first sentence names a specific verb (Generate) and resource (audio) and enumerates the synthesis primitives (tones, sweeps, chords, noise, melodies, layered effects). It is highly specific, but it never differentiates from siblings like audio_melody or audio_process, which plausibly overlap.

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 explicit when-to-use, when-not, or named alternatives are given. The laser-zap and melody examples implicitly convey intended use cases, which is why this is not a 2, but the agent gets no routing guidance against the many audio_* siblings.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it streams the file, so it works on recordings of any length without loading everything into memory. It stops short of describing pagination or sparkline resolution.

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

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

Two tightly written sentences, front-loaded with what the tool returns and followed by the operational constraint. Nothing is redundant and every clause adds information.

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

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

With no output schema and 0% parameter coverage across four parameters, the description should do more work. It usefully sketches the return shape (per-segment RMS, peak, brightness, sparkline), but leaves the start/end windowing semantics undocumented, which matters for a tool that claims to handle files of any length.

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 carries the burden for path, start, end, and segments. 'Per-segment' loosely hints at the segments parameter, but start/end ranges (units, whether seconds or samples) and the default of 24 segments are never explained, leaving half the parameters 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 names the resource (audio timeline) and enumerates the specific outputs (per-segment RMS, peak, brightness, loudness sparkline), which is far more informative than the bare name. It does not, however, contrast itself with the many audio siblings like audio_analyze, audio_info, or audio_events, so an agent must infer the distinction.

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 one concrete use case, 'use it to find where to zoom in', which implies the tool is for coarse temporal scanning rather than detailed analysis. There is no guidance on when to prefer audio_analyze or audio_events instead, and no exclusions, so usage remains largely implied.

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

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

Annotations declare readOnlyHint and openWorldHint, but the description adds traits they don't cover: local execution (no cloud API call) and the first-use model download, which is a real latency/network side effect an agent should anticipate. It also discloses the return envelope in detail (segments, per-word confidence, detected language, pauses, uncertain_words).

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 a five-word lead, then parameter hints are packed into dense, colon-delimited clauses with no filler. It is slightly compressed, but every clause carries information an agent would otherwise have to guess.

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 tool with no output schema, the description covers the important behavioral facts and most parameters, and its return-value enumeration substitutes for the missing output schema. Remaining gaps are minor: what `path` accepts (local file vs URL) and whether timings are seconds or offsets.

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 model parameter has no enum, so the description carries the load: it enumerates valid model values (tiny/base/small/medium/large-v3/turbo) with a size-versus-speed tradeoff, and explains model, language, initial_prompt, start and end. Only path is left undefined, and word_timestamps is only implied via the mention of per-word timings.

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

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

Opens with a specific verb+resource ("Speech to text") plus the engine (Whisper) and an execution constraint (runs locally), so an agent immediately knows what this does and how it differs from audio_synthesize or audio_analyze. It also enumerates the outputs it produces, removing any ambiguity about scope.

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

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

It gives per-parameter usage hints ("Use start/end to transcribe part of a long recording", "language: ISO code like \"en\" to skip detection") which is genuine decision guidance at the argument level. However, it never says when to pick this tool over siblings such as audio_batch_process for multi-file work or audio_analyze, so tool-level selection is only implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds real behavioral value beyond that: the on-canvas semantics (horizontal lines = harmonics, vertical stripes = transients, haze = noise), the red 0 dBFS clipping markers, and the fact that save_to writes a PNG to disk. The disk write is the one detail an agent should reconcile with readOnlyHint, but it is a requested new artifact rather than a mutation of source data, so no contradiction is claimed.

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

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

Front-loaded with the core purpose, then kind options, then an interpretation legend. Nearly every sentence carries information an agent needs to read the rendered image or set parameters, though the spectrogram-reading tutorial is on the verbose side for a tool description.

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?

Against 8 parameters with zero schema descriptions and no output schema, the description supplies the render semantics, the interpretation legend, and most parameter behavior, so an agent can invoke it correctly and understand the returned image. The unexplained max_freq/freq_scale/path params are the only meaningful omission, and they have usable defaults.

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 carries the whole burden and does substantial work: it enumerates the kind values, explains start/end as zoom bounds, defines pitch_overlay, and notes save_to's side effect. Gaps remain for max_freq, freq_scale (default 'log') and path, which are completely undocumented in both the schema and the 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 opening clause states a specific verb and resource: render a picture of the sound, then enumerates the three render kinds ('both', 'waveform', 'spectrogram'). This clearly separates it in spirit from data-oriented siblings like audio_analyze, audio_melody or audio_transcribe, but no sibling is named, so routing is inferred rather than explicit.

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

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

Usage mechanics are covered well ('Zoom with start/end', 'pitch_overlay draws the detected f0 in cyan', 'save_to optionally also writes the PNG to disk'), which tells the agent how to shape the output. However there is no guidance on when to choose audio_view over audio_analyze, audio_info or audio_events, and no stated prerequisites (file must exist locally, supported formats).

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