Add Visual Effect to CapCut Draft

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

The description adds useful details like the time range behavior and that the effect is applied over a range, plus a return confirmation. However, it does not disclose whether the draft must be explicitly saved afterward (a sibling capcut_save_draft exists) or whether adding an effect overwrites existing ones. This is notable for a mutation tool without annotation hints.

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 front-loads a clear purpose but then includes a full Args list that duplicates the input schema, which is unnecessary and inflates length. The return line is brief, but the redundant parameter enumeration wastes tokens and reduces conciseness.

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 provides a basic return statement but omits important context about draft persistence (especially given capcut_save_draft) and effect layering or ordering. The rich schema covers parameters well, but the description is not fully complete for effective tool usage.

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 100%, and the description's Args section largely repeats the schema's property descriptions without adding new meaning. It does mention that params use null for defaults, but this is already in the schema. Thus it adds minimal value beyond the structured schema.

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 clearly states 'Apply a visual effect or filter to an existing draft over a given time range,' which specifies the exact action, resource, and scope. It also distinguishes itself from sibling add_* tools by focusing on visual effects/filters and time ranges.

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 its usage context ('existing draft') and mentions a relationship with capcut_create_draft, but it does not explicitly state when to prefer this tool over similar siblings like capcut_add_text or capcut_add_video_keyframe. No alternative names or exclusionary guidance is provided.

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