capcut_add_bg_music_with_ducking

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

No annotations provided, so the description carries the full behavioral burden. It explains the ducking concept but omits whether this mutates the draft, requires a rendered timeline, affects existing tracks, or what audio processing happens. For a mutation tool with zero annotation coverage, this is a significant gap.

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?

Front-loaded with the core action, then a compact bulleted list of key params. Efficient overall, though the bullets duplicate schema defaults rather than adding new information.

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 described, and the ducking concept is explained. However, with 7 params at 0% coverage and no annotations, the description leaves several parameters and the mutation semantics unexplained, which is thin for this complexity.

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. It documents three of seven params (speech_intervals_json with a format example, duck_volume, normal_volume with defaults), which is genuinely useful, but leaves draft_name, music_path, start_ms, and track_index unexplained.

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 (add), resource (background music), and a distinctive mechanism (automatic volume ducking under speech). It clearly distinguishes from sibling capcut_add_audio_clip by naming the ducking behavior, though it doesn't explicitly name the alternative.

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 implies usage (you need speech intervals to duck under) but never states when to use this vs capcut_add_audio_clip or capcut_improve_audio. No prerequisites or exclusions are given, leaving usage to inference.

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