suggest_handoff_cut_tool

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 key behavior: it keeps about retain_sec of air, snaps onto RMS silence islands rather than transcript gaps, uses timeline seconds, and returns use_inaudible_opt: false. It stops short of explicitly stating that the tool is non-destructive, though 'propose' and 'lock those bounds on ripple_delete_tool' strongly imply 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 description is compact and front-loaded with the core purpose, followed by use conditions, exclusions, and algorithmic detail. Every sentence adds value, and the formatting makes the caveats easy to scan.

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 has an output schema, the description need not explain return values. It supplies enough context for selecting and using the tool, including units, algorithm behavior, and downstream tool. The main gap is that several optional tuning parameters are not explained in context, but the defaults and explanatory names mitigate this.

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 undocumented parameters. It clarifies retain_sec and the timeline-seconds unit, and it indirectly explains quiet_db/min_island_sec through 'RMS silence islands.' However, hop_ms, speaker, track_id, and several other parameters receive no direct semantic explanation beyond their titles 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 states a specific verb and resource: 'Propose retain-then-snap ripple bounds for a narrative handoff.' It also explicitly distinguishes itself from preview_inaudible_cut_tool and from word-timestamp cutting, so the agent can differentiate it from close 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?

The description gives concrete when-to-use scenarios ('cleaning up a transition, leaving a beat, or punchline-to-pivot') and explicit when-not-to-use guidance ('not word timestamps and not preview_inaudible_cut_tool'). It also tells the agent what to do with the result: 'lock those bounds on ripple_delete_tool.'

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