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

Beyond the annotations (which only say non-readonly, non-idempotent), the description discloses the credit cost, that the prompt is fixed server-side, and precisely what preview:true suppresses (no job, no credit spend, no provider call). It also names the three fields returned by the dry run, which is the key behavioral contract for a billing-sensitive tool.

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 sentences, front-loaded with the highest-risk fact (credit spend) in caps, then the fixed-prompt constraint, then the preview escape hatch, then the return contract. Nothing is repeated from the schema verbatim and no sentence is filler.

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?

With no output schema, it correctly describes the preview return fields — but says nothing about what a paid render returns (job id? how to poll via get_generation/story_get_job?), which is the natural next question after submitting. For an 8-param, credit-spending, open-world tool that is a meaningful remaining gap, though the billing and dry-run guidance is otherwise complete.

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 100%, so baseline is 3; the description adds real value by scoping the creative inputs to effect/photo/duration and by restating preview's cost semantics in operational terms. It does not clarify run_id, project, workspace, or user_request — those rely entirely on their schema text, and "same rule as render_video" in the schema is a cross-tool dependency the description never resolves.

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?

"Render a one-photo video effect from list_effects — SPENDS CREDITS" gives a specific verb + resource + scope, and immediately distinguishes this from render_video (multi-scene video), render_image (still), and preview_render (generic preview). The source of the `slug` (list_effects) is named in the first sentence.

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 explicitly prescribes the workflow — call with preview:true before any paid render — and gives a hard stop condition: "if `sufficientCredit` is false, do not submit the paid render." It also states what the caller does and does not control ("you only choose the effect, the photo and the duration"), so no when-to-use decision is left to inference.

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