update_shot

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

With no annotations, the description carries the full burden and succeeds thoroughly. It discloses: dialogue edits invalidate existing TTS and subtitles; text edits do not auto-regenerate images/videos; original-sound shots get flagged with '待重生' and compose_episode emits advisory 'stale_video_after_edit'; character_ids and prompt bodies are full-overwrite; deleting @char/@scene markers causes identity drift. These go far beyond what the schema could convey.

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 long but well-structured with ★ markers and a clear order: core purpose, editing rule, dialogue side-effects, video staleness, prompt-editing warnings, and verification route. Every section carries a distinct operational consequence; minor redundancy with the schema's parameter notes is acceptable given the tool's complexity.

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 16-parameter mutation tool with no output schema, the description is effectively complete: it explains the edit model, cost (免费/纯文本写库), side-effects, required pre-reads, post-edit verification via get_storyboards, and the exact handling of stale videos before compose_episode. An agent has everything needed to invoke it correctly and handle downstream states.

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 94% and individual parameter descriptions already carry substantial semantics (e.g., dialogue's TTS invalidation, image_prompt's @char/@scene warnings, character_ids' overwrite behavior). The tool description adds cross-cutting usage rules ('只传要改的字段、其余不动') and reinforces the prompt-reading prerequisite, providing meaningful value above the schema but with some redundancy.

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 line states a specific verb and resource: '逐镜编辑:改单个分镜的文本内容...与角色绑定' — editing a single storyboard shot's text and character binding. It also differentiates from sibling operations by explicitly referencing get_storyboards, regenerate_shot_video, and compose_episode as separate follow-up/replacement steps, so an agent understands this is the text-edit tool, not the regeneration or query tool.

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 usage rules: '只传要改的字段、其余不动' (only pass fields to change), prerequisites ('改前先用 get_shot_prompts 读现值,别凭空覆盖'), and clear when-to-use-alternatives guidance ('改文本不会自动重出图/视频...改完再 regen 对应镜'; '正确处置是先 regenerate_shot_video 再终拼'). This is a fully actionable guide.

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