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

Annotations declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so safety basics are covered; the description adds real behavioral context beyond them — the validation failure mode ('indexes do not match ... rejected and nothing is stored') and the cost profile ('Costs no credits'). It does not disclose what happens to a previously stored beat sheet for the same upload, which is the one gap the destructive hint implies.

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?

Four short sentences, front-loaded with the action and the prerequisite, then the validation rule, then prompt semantics, then cost. No sentence is redundant and the failure condition is stated before an agent would construct the payload.

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 values need not be described, and the annotations carry the safety profile. The description supplies the prerequisite, the validation rule and prompt intent, leaving only the overwrite/destructive semantics of a repeat save unstated for a tool annotated destructiveHint=true.

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 carry the semantic load. It does explain the critical constraint on shot.index alignment and the intended meaning of image_prompt/motion_prompt, but the majority of nested fields (format_summary, hook, structure, tags, beats.role/title/intent/shot_indexes, setting, narration, sound, on_screen_text) get no interpretation beyond their enums.

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 a specific verb+resource: 'Store your beat sheet for an analysed video.' It clearly positions the tool against its read counterpart by naming get_video_analysis_bundle, so an agent can distinguish this write from the analysis-retrieval siblings without opening a schema.

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 an explicit ordering prerequisite ('Read get_video_analysis_bundle first') and a hard precondition for success (one shot object per measured shot, same index, or the write is rejected). That is strong 'when to use' guidance, but it never states when not to use it or what the alternative is if the bundle is unavailable.

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