新增分镜片段

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

Annotations already establish that this is a non-destructive (destructiveHint=false), write (readOnlyHint=false), idempotent operation, so the baseline is lower. The description still adds real value beyond that: it requires the latest storyboard fingerprint (concurrency control via expected_sha256), states that it preserves existing order and media and does not copy or delete shots, and describes read-back behavior (new object, official default scene shot, new fingerprint). These are concrete side-effect details annotations cannot express.

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 text is dense but front-loaded: the endpoint and the core add-only invariant come first, followed by prerequisites, side effects, and the split caveat. Every clause carries operational meaning with no filler, though the compressed phrasing makes a few clauses (e.g., '回读返回新增对象、官网默认场景镜头及新指纹') harder to parse on first read.

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?

This tool is a mutation, but annotations cover its safety profile and an output schema exists, so return values need not be explained. The remaining gap is parameter coverage: two of the five required parameters (project_id, operation_id) are undocumented anywhere, which matters for a write tool with 0% schema coverage. The core behavior is otherwise adequately framed.

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 0%, so the description must compensate for all five parameters. It implicitly covers episode_id (episodes/{id}), display_order ('指定排序'), and expected_sha256 ('最新storyboard指纹'), but leaves project_id and operation_id (the idempotency key) unexplained, even though idempotentHint implies the latter. Partial compensation warrants a middle score.

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 states a specific verb+resource: it adds (新增) a storyboard segment at a specified ordering, mapped to POST episodes/{id}/segments. It also bounds the operation ('不复制或删除原镜头', does not copy or delete existing shots), which distinguishes it from pavo_script_delete_storyboard_segment and pavo_script_delete_storyboard_shot. It does not explicitly contrast with pavo_script_create_storyboard_shot, so sibling differentiation is partial rather than complete.

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?

It gives procedural guidance for the split workflow: copy/save and verify first, then explicitly delete migrated old shots, and it states that the tool does not auto-generate content. However, it never states directly when an agent should pick this tool versus pavo_script_create_storyboard_shot or pavo_script_update_storyboard; the choice must be inferred from the 'segment' vs 'shot' naming.

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