scan_dialogue_coverage

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

No annotations exist, so the description carries the full burden — and it delivers extensively: discloses zero-charge read-only default, that rescan consumes compute and is non-instantaneous, that TTS shots are out of scope, and the never_audited caveat ('not tested ≠ no problem'). It even surfaces empirical context (21% of sufficient-length shots still incomplete) that prevents misuse. No contradiction with annotations since none exist.

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 long — a multi-topic wall of text with ★ markers for structure. Every sentence earns its place (trigger condition, category semantics, corrective routes, rescan tradeoff, exclusions, sibling routing), and the primary decision guidance is front-loaded. Slightly heavier than strictly necessary, but organized well enough that no content feels 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?

Complete for a complex analysis tool with no output schema: it defines all five result categories, flags never_audited as the key column, names rescan_skipped_by_limit as a response field, excludes TTS shots, and routes to the relevant sibling for a related but distinct problem. An agent can invoke it correctly and interpret results without further lookups.

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 already documents limit and rescan well (67% coverage), so the baseline is near-full. The description adds usage nuance beyond the schema: it explains that rescan is a deliberate opt-in costing compute, that limit controls the per-run cap, and that episode_id drives the per-episode scan scope implied throughout. Marginal but real added value over the schema's 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?

States a specific verb and resource ('scan dialogue coverage'), and precisely defines the operation: word-level comparison of each original-voice shot's audio track against its script. It enumerates the exact output categories (truncated/off_script/extra_speech/minor_gap/ok), which fully disambiguates it from the sibling scan_intra_shot_cuts, named explicitly for the separate 'too-fast cuts' problem.

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 an explicit trigger condition ('customer reports words cut off / half-read'), states the default read-only/zero-cost mode, and routes decision-making: truncated/off_script → regenerate_shot_video, repeated off_script → switch engine, and 'too-fast cuts' → scan_intra_shot_cuts. It also instructs when to add rescan=true (catch-up on never-tested shots), leaving nothing to inference.

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