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

Beyond what annotations provide, the description discloses two cost-relevant behaviors: 'Spends AI credits' flags the resource expense, and 'returns a job to poll' flags asynchronous execution rather than a direct return. These complement the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) without contradicting them, and the idempotency key in the schema aligns with idempotentHint.

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 sentences with zero filler: the first fronts the purpose and pipeline components, the second packs the two most decision-relevant behaviors (credit cost and async job polling). Every phrase earns its place, and the critical scoping word 'full' is positioned early.

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 16-parameter orchestrator with an output schema and annotations, the description conveys the essentials: full-pipeline scope, credit cost, and the follow-up polling path via generation_jobs_get. Combined with 100% schema coverage and the output schema, an agent has enough to invoke and supervise the job; only expected runtime duration is left implied.

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 100%, so the baseline of 3 applies — the schema fully documents all 16 parameters. The description only previews pipeline features (voiceover, captions, music, sound) that map to boolean flags, without adding parameter-level detail beyond the schema. It does not compensate further, but it does not need to given the complete schema.

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 states a specific transformation — 'Turn a script into a full faceless video project' — and enumerates the pipeline components (scene plan, generated visuals, optional voiceover, captions, music, sound). This clearly distinguishes it from single-step siblings like generation_video_create and generation_image_create, which produce one asset rather than an end-to-end project.

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 trigger condition is clear: when you have a script and want a complete faceless video, this is the tool. It also closes the loop by telling the caller to 'poll with generation_jobs_get' for the result. However, it never names alternatives or exclusion cases (e.g., 'for a single scene use generation_video_create'), so routing guidance is implied rather than explicit.

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