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

Annotations only say readOnlyHint=false and destructiveHint=true; the description supplies the real behavioral burden — per-character cost in two charged parts, the ElevenLabs ~4x premium, the 6000-character dialogue cap with no auto-cut, the start_confirmed:false recovery path (do not re-create, watch it), and the idempotency_key replay semantics. These are exactly the failure modes an agent needs before spending.

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?

Structure is front-loaded and logical: what it makes, who writes the script, what happens after, cost, exclusions, spending gate, idempotency. It is long and repeats the cost warning in both the description and voice_provider_left, and heavy ALL-CAPS shouting costs some readability, but for a 15-parameter token-spending tool nearly every sentence carries load.

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?

Covers the full lifecycle despite having no output schema: it states the response carries the price split and renders_automatically:true, that wait_for_generation is the wait step, and that get_video yields the file url. Combined with the cost gate, size limit and unoffered-features list, an agent has everything needed to call it safely.

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 the baseline is 3; the description goes beyond by linking parameters across fields — changing voice_provider_* invalidates an older estimate, a longer script costs more, and estimate_only:true must be run before quoting. It does not restate per-parameter syntax, which the schema already owns, so it stays additive rather than redundant.

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?

Opens with a specific verb and a precise artifact: 'CREATES a fake-text video: a phone chat conversation that types itself out over a gameplay or green-screen background, every line read aloud.' That is distinguishable at a glance from generate_story_video, generate_image_story and generate_audio without opening any 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?

Names the routing cases explicitly: 'YOU WRITE THE SCRIPT: there is no writer behind this endpoint,' show it as plain text first because 'iterating costs nothing', then 'one call makes the finished video ... no fire or render step' (ruling out fire_story_video/render_story_video), plus wait_for_generation and get_video for the terminal url. It also lists an explicit NOT OFFERED set (music, gameplay clips, in-chat images, contact photos, promotions, second chat, cantina skin) so the agent knows what to refuse rather than approximate.

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