detect_silence

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

With no annotations, the description carries the full burden of behavioral disclosure, and it does a solid job. It reveals that execution happens locally via child_process with ffmpeg, requires ffmpeg on PATH, returns an explicit error if ffmpeg is missing, and is non-destructive. It does not specify the exact shape of the returned intervals, but it covers the most important behavioral and operational traits.

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 four sentences, each earning its place: clear action, execution/reason, safety, and follow-up usage. It is front-loaded with the core purpose and avoids redundant rephrasing of the schema. No filler or unnecessary detail.

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 no output schema and no annotations, the description covers the key contextual needs: external dependency (ffmpeg), failure behavior, non-destructive nature, and how to act on the results. It could be more explicit about the interval format (e.g., start/end times and units), but it is otherwise complete enough for an agent to select and invoke the tool.

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?

The input schema already documents all four parameters with descriptions, defaults, and examples, so schema coverage is 100%. The description adds little parameter-specific meaning beyond noting the use of the silencedetect filter and pointing to the returned intervals. This matches the baseline expectation for high schema coverage.

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 opens with a specific verb and resource: 'Analyzes a media file's audio for silent stretches using ffmpeg's silencedetect filter.' It clearly distinguishes this tool from editing/destructive siblings by stating 'This is DETECTION ONLY -- it does not cut or modify anything,' and even notes why Premiere's scripting API cannot do this. This makes the tool's purpose unmistakable and well differentiated.

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 clear context for when to use the tool (to detect silence) and explicitly rules out Premiere's scripting API as an alternative. It recommends follow-up tools (split_clip/ripple_delete/razor_timeline_at_time) for removing detected silence. While it doesn't enumerate exhaustive when-not-to-use scenarios, the intended usage and downstream workflow are clearly stated.

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