edit_video_shot

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

With no annotations, the description fully carries the behavioral disclosure burden, and it does so thoroughly. It reveals that the tool mutates the shot in place, requires prior user confirmation, has model-specific cost/billing implications, may extend the environment per instruction with WAN models, and returns a 400 error for unsupported interval parameters on H3/WAN. This is unusually 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?

The description is dense but well-organized: main purpose first, then model options and constraints, then the mandatory quote confirmation flow. Every sentence adds actionable information, and the warning about H3/WAN interval unsupported is positioned effectively. It is appropriately sized for the complexity of the tool.

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?

For a 9-parameter mutation tool with no annotations and no output schema, the description covers the essential prerequisites, model selection, interval constraints, and the critical quote-before-edit process. It does not describe the return value or follow-up status behavior, and it lacks explicit routing against alternative shot-editing tools, but an agent can call it correctly with the information provided.

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 description adds meaningful semantics beyond the schema, especially for the model parameter, explaining tradeoffs like 'hailuo-3=MiniMax H3 强保真编辑约1/3成本' and 'wan3.0...强语义编辑约4折'. It also clarifies the behavior of start_sec/end_sec and the quote_id workflow. With schema coverage at 67%, the description compensates for most gaps, though storyboard_id and reference list limits remain underexplained.

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 '确认后就地编辑某镜视频' and clearly states the core action: edit a shot video by instruction, optionally with reference assets or interval replacement using start_sec/end_sec. This identifies a specific verb and resource, but it does not explicitly distinguish itself from related sibling tools like trim_shot, split_shot, or regenerate_shot_video.

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 explicit workflow guidance: call the corresponding quote_* tool first, relay estimated_points to the user, obtain explicit consent, and only then call this tool with the returned quote_id. It also warns against passing start_sec/end_sec with H3/WAN models. However, it does not discuss when to use this tool instead of sibling alternatives like regenerate_shot_video or split_shot.

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