Make a motion graphics video

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

Annotations only say readOnly=false and openWorld=true; the description supplies what they cannot: credit cost at each stage, that the first call is free and returns a quote with the spec in structuredContent, that preview costs 1 credit, runtime (~a minute) and output (1080p MP4), plus a hard content constraint ('never invent a claim, number or review'). That is exactly the behavioral context an agent needs before spending a user's credits.

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?

Front-loads purpose, then trigger phrases, then recipes, then the step machine — a sensible order for a 17-parameter tool. It is dense but nearly every clause carries new information; the only waste is mild redundancy in the opening caps ('MOTION GRAPHICS and ANIMATED VIDEO') and a packed run of recipe glosses that could be bulleted.

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 complex, nested-spec, no-output-schema tool, it covers the workflow, cost, runtime, format and the content-safety rule. The remaining unknown is what a successful preview/confirm response actually contains (asset URL vs. job id vs. structuredContent fields), which the agent must discover by calling — a small but real gap given no output schema exists.

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 only 53%, and several bare params (recipe, preview, confirm, projectUrl, help, spec, size) have no schema description at all. The description compensates well by defining every recipe value, the spec/help:true escape hatch, and the preview/confirm/projectUrl semantics. It leaves size, mood and theme to the schema, which already documents them, so the gap is minor.

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+resource ('MOTION GRAPHICS and ANIMATED VIDEO... made in code with no video model') and enumerates the concrete artifacts it produces (kinetic typography, logo intro, launch film, social cut). This clearly separates it from generate_video, make_explainer and product_sizzle by declaring it is code-rendered rather than model-generated, and by listing the trigger phrases an agent should match.

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?

Gives explicit selection triggers ('Pick it for "animated video", "motion graphics", "kinetic text"...'), describes what each recipe is for, and lays out the escalation path: no flags = free quote, preview:true = 1-credit contact sheet, confirm:true = render. It also names an alternate entry point (projectUrl re-edits an existing spec), so the agent knows when to reuse rather than start fresh.

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