capcut_add_animation

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 the default dry-run plan mode and notes the segment/resource targeting, but does not cover permissions, reversibility, ordering, or what a write actually mutates. The 'CapCut must be closed' constraint lives only in the schema, not the description.

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 verb and resource, followed by the target and dry-run note. Two sentences cover a lot without filler; the parenthetical examples are dense but earn their space as lookup aids.

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?

Adequate for the core call, but with 8 parameters at 50% schema coverage, no annotations, and no output schema, several parameters (track, name, and the duration_s semantics) rely entirely on the schema. The description is serviceable but leaves the agent relying on structured fields for a mutation 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?

Adds genuine meaning beyond the schema: it maps kind values to element types (text/sticker for loop, combo for group) and gives concrete resource_id examples tying numeric IDs to animation names. With only 50% schema coverage this partially compensates, though name, track, and duration_s get no description-level explanation.

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 ('Add an in / out / loop / group animation'), the target ('segment at start_s by resource_id'), and the key operating mode ('Dry-run by default'). An agent can distinguish it from capcut_add_effect or capcut_add_transition by the animation construct alone, though no sibling is named.

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 'Dry-run by default' note hints at the intended safe workflow, and the kind parentheticals (text, sticker, combo) imply which animation type applies to which element. But there is no explicit when-to-use, no when-not, and no mention of alternatives among the many add_* siblings.

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