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

Annotations already flag non-readOnly and destructiveHint=true, but the description adds genuinely non-redundant behavior: the job is queued and priced (costs money, returns an ID rather than a finished asset), and it shares the UGC pipeline. What it does not do is explain what the destructiveHint encompasses or what happens to prior renders.

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 front-loaded with the action and the bracketed tags are efficient metadata, and there is little outright filler. But the single run-on sentence with deeply nested parentheticals makes the key constraints hard to parse, and much of the nested-field detail arguably belongs in the schema rather than the description.

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 7-parameter, nested-object, no-output-schema write tool, the description covers the core payload and the returned IDs, which is more than most. It is still incomplete for a required nested argument (video_render_target) and for the six supporting parameters, leaving the agent unable to assemble a fully valid invocation from this definition alone.

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 coverage is 0%, so the description carries the full burden; it does a strong job on video_ugc, enumerating nested keys, constraints (6000 chars, 30-120s default 60, 1-12 scenes) and even the backing enums. But video_title, video_output, video_keywords, video_language, video_description and especially the REQUIRED video_render_target receive no shape or meaning at all, which is a hard blocker for constructing a valid call.

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?

States a specific verb and resource ('Create a film from characters and a scenario') and identifies the pipeline relationship ('same pipeline as the UGC video'), which orients the agent among create_ugc_video/create_video siblings. It also states the return identifiers (video_id, video_uuid). It stops short of telling the agent when to pick a film over a UGC video or a plain video, so differentiation is only implicit.

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 '[write, queued, priced]' tags and the reference to plan_film_storyboard as the upstream producer of storyboard scenes imply a workflow and its ordering. However, there is no explicit 'use this instead of X when...' guidance against the several sibling video-creation tools, and no prerequisites (e.g., character must be READY) beyond a passing parenthetical.

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