Silence

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

Annotations declare readOnlyHint=false and destructiveHint=false but say nothing about what the tool actually touches; the description fills that gap by asserting no audio is deleted and that the selection is restored. It further discloses that results are 'capped regions plus the total count' and that mute/gain/envelope state affects rendered silence — behavior an agent could not infer from annotations. It stops short of stating permissions or whether it blocks on a running Audacity instance.

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

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

Front-loaded with the core purpose and the non-destructive guarantee, and every subsequent sentence adds distinct information (scan modes, time bases, return shape, mute/gain caveat). A few clauses are compressed to near-opacity, e.g. 'rendered tracks/currentSelection with selection restored', which costs readability.

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

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

For a 9-parameter, zero-schema-documentation, read-but-state-touching tool, the description covers purpose, scan modes, time semantics, and result shape, and an output schema exists so return values need not be spelled out. The remaining gap is per-parameter detail for maxRegions and trackCount, plus no note on prerequisites such as an active Audacity session.

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 9 parameters, so the description carries the full burden and largely meets it: it explains thresholdDb, minimumSeconds, file, track, currentSelection, and the absolute-vs-file seconds distinction for start/end. It only gestures at maxRegions ('capped regions') and never disambiguates trackCount from track, leaving two of nine parameters 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 resource ('Find quiet regions') plus the exact predicate ('every channel must stay below thresholdDb for minimumSeconds'), and immediately distinguishes itself from a destructive sibling operation with 'without deleting audio'. An agent knows this is a detection/analysis tool, not a silence-removal tool, without consulting any schema.

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

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

Gives clear operational context: it can scan an optional file, or rendered tracks/currentSelection, and it notes that selection is restored afterwards. It also warns that current mute/gain/envelopes influence rendered results, which is a real usage caveat. It does not name any sibling tool or state an explicit when-not, so it falls 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.