Analyze Silence

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 does well on output behavior (start/end times and bars, a terminal PASS or FAIL 'and what to do') and on scalability ('read in blocks', 'a whole assembly of hours'). However it never states that the tool is read-only with no side effects, nor anything about cost or permissions for long sources, leaving a real gap for a no-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?

Nearly every clause carries information, and the detection criteria are front-loaded, so there is little filler. But the text is a dense, semicolon-chained run-on with nested parentheses and pipe-delimited enums, which makes it slow to scan for a calling agent. Structure is the weak point rather than size.

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 description still usefully summarizes the verdict line. Given the tool is a read-only analysis over potentially huge sources, coverage of criteria, source forms, verdict semantics, and sibling alternatives is nearly complete. What is missing is only the side-effect/permission profile and an explicit note on the project parameter.

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

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

With 0% schema coverage, the description must carry all five parameters, and it explains four well: min_s and floor_db with defaults and units, source with an enumerated set of forms (render | ref | track:<name> | sound:<name> | file path), and planned as [[start_s, end_s]] pairs reported as planned rather than failed. The extra detail that rms is measured per 100 ms is meaning the schema cannot convey. The project parameter is only implied ('a file needs no project'), so it is not fully documented.

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 precisely defines what is detected: 'every stretch of min_s seconds or more (default 3) whose rms per 100 ms stays under floor_db (default -50 dBFS)', which is far more specific than the name alone. It also distinguishes itself from analyze_bars and analyze_envelope by noting they read levels on the bar grid, while this one reports silent stretches. It stops short of a clean verb-first statement ('Detects silent stretches...'), starting instead with a noun fragment, but the intent 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?

The description gives concrete deployment guidance ('Run it on every rendered chapter and on a whole assembly before anyone reviews it') and names alternatives with their distinct behavior: onair_check adds source levels and a rules check, analyze_bars/analyze_envelope work on the bar grid. There is no explicit 'do not use this when...' exclusion, which keeps it from a 5.

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