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

With destructiveHint=true and idempotentHint=false already declared, the description still adds substantial context the annotations cannot: AI credits consumed, monthly narration-character quota with graceful stop-and-report, drafts saved before generation, unchanged clips skipped, and identical inputs reusing earlier clips for free. That is exactly the cost/side-effect/partial-failure information an agent needs before spending quota.

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-loaded with the outcome, then parameter effects, then cost/publish consequences — a logical order with no filler sentences. It is a dense single paragraph that runs long and packs several ideas per clause, which slightly hurts scanability.

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 6-parameter, nested-object, quota-consuming mutation with no output schema, the description covers permissions, cost, partial-completion behavior, and the downstream publish step. The only gap is the shape of the result ('reports what was done' is vague) and error behavior when a target id is invalid.

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 schema already documents all six parameters and the baseline would be 3. The description still adds sequencing semantics the schema lacks: `scripts` is persisted to the draft first, `writeMissing` burns 1 AI credit per 20, and `voice` is drawn from list_voices.

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+resource: 'Gives a demo spoken narration' per step (guided) or screen (clickable), with captions — an agent knows exactly what artifact is produced. It does not, however, distinguish itself from the sibling generate_video_voiceovers, so the reader must infer the demo-vs-video split from the name alone.

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?

Explains the workflow clearly: pass `scripts` to set copy, `writeMissing` to draft with AI, optionally `voice`, then clips are made only where missing or stale. It also carves out an exclusion ('Translations' narration is generated in the editor') and points to publish_demo for going live. No explicit routing against generate_video_voiceovers, which keeps it from a 5.

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