preview_mix

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

No annotations exist, so the description carries the full burden. It discloses meaningful behavior: ffmpeg sidechaincompress for ducking, a synthesized CC0 demo bed for seed tracks without audio, and path/command/spec returns. It does not state whether original assets are modified, but for a preview operation the named behaviors are adequately transparent.

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?

Three compact paragraphs front-load the action, then the output contract, then edge-case behavior. Every sentence adds a new fact; there is no filler or redundancy.

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?

The description covers outputs, intentional audio-processing details, and an offline fallback, so an agent can form a good mental model. It is less complete on parameter semantics and selection criteria, and never points the agent to which sibling supplies asset_id/track_id – a notable gap at 0% schema coverage.

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 coverage is 0% and the description adds almost no parameter-level meaning. It implies the ducking boolean and mentions 'BGM' and 'speech', but does not explain bgm_db/voice_db units or values, nor clarify asset_id/track_id beyond their names.

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 'Mix BGM under the video' – a specific verb and resource – and expands with hook trim, looping, ducking, and returned artifacts. This clearly distinguishes it from nearby siblings like export_mix_spec or generate_bed.

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?

No explicit when-to-use/when-not-to-use statement appears. The 'preview' nature is implied by the name and the returned preview mp3/mp4, but the description never contrasts with export_mix_spec or explains when an agent should choose it over another sibling.

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