读取剧本分集分镜

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

The annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: it verifies project ownership (核项目归属) before reading, returns active_tasks, and attaches per-entity fingerprints. The explicit 'no media generation' disclaimer prevents a common false assumption, though error behavior on missing episodes is unstated.

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?

Two dense sentences with no filler; the read scope is front-loaded and the run_stage caveat closes the description. The phrasing is jargon-heavy (核项目归属, _mcp_fingerprints) but every clause carries information an agent needs.

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?

An output schema exists, so return structure need not be described, yet the description still summarizes the payload (segments, scenes, shots, active_tasks, fingerprints), which is a bonus. For a two-parameter read tool with full annotation coverage, the only real gap is the undocumented episode_id semantics and empty-storyboard behavior.

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% for both parameters, so the description must compensate and largely does not. '核项目归属' hints that project_id drives an ownership check, but episode_id is never explained, nor is the expected ID format or what happens when the two do not match. An agent must guess at the episode parameter's role.

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 gives a specific verb (读取/read) and enumerates exactly what is returned: native segments (段落), scenes (场景), shots (镜头), active_tasks, plus _mcp_fingerprints.storyboard. It also implicitly distinguishes itself from the mutation siblings (update_storyboard, create_storyboard_shot) by framing the fingerprints as input for later editing. It stops short of naming those siblings explicitly, so it is clear but not maximally differentiated.

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 an explicit when-not rule: generating a storyboard requires a separate call to run_stage and this tool will not auto-produce images or video. It also signals the intended use case (fetch fingerprints so entities can be edited). It does not spell out prerequisites such as whether the episode must already have a storyboard, which keeps it from a 5.

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