rewrite_video_subtitles

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

With no annotations provided, the description carries the full burden and exceeds it: it discloses real billing, the non-committing first call returning 409 with data.userPrompt and data.confirmToken, the binding of the token to order + subtitle texts with 15-minute expiry, and the caveat that pre-rewrite links remain valid but must not be presented as final. This is exceptional behavioral disclosure for a mutating, billing-affecting tool.

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?

It is a dense wall of text, but every sentence carries critical operational information for a billing-affecting tool: the two-step protocol, token semantics, prerequisites, and follow-up routing. The billing warning and two-step requirement are front-loaded. A structured step list would improve scannability, but no sentence is wasted.

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?

Despite having no output schema and no annotations, the description covers prerequisites, the exact 409 error contract, token lifecycle, the returned data.videoTranslateRewriteOrderNo field, the correct progress-checking tool, and the post-rewrite product retrieval flow. Nothing an agent needs to invoke this tool correctly and safely is missing for a tool of 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 100%, so the baseline is 3. The description adds workflow-level meaning beyond the schema: it explains how confirm_token is obtained (from the prior 409 response), when it must be omitted vs. supplied, and that editing even one subtitle line invalidates prior consent — tying source_subtitles_txt and target_subtitles_txt to the confirmation semantics.

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 opening phrase '用编辑后的字幕重新生成视频' states a specific verb (rewrite/regenerate) plus resource (video) plus input (edited subtitles). It is immediately distinguishable from siblings: translate_video creates the original translation, get_video_subtitles fetches subtitles, and get_video_rewrite_status only checks progress.

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 exhaustive usage guidance: the original task must be status 2, the first call must omit confirm_token, the second call must include it after user consent, progress is checked via get_video_rewrite_status, and final products are re-fetched via wait_for_video_translation or get_video_translation_status. Every relevant sibling and its role is named explicitly.

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