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

Goes well beyond the annotations by disclosing that the operation 'costs no credits' (consistent with readOnlyHint=true) and by spelling out the OAuth/API-key sign-in requirement — something annotations cannot convey. The ordering constraint relative to estimate_ad_cost and generate_ad is also behavioral context not present in structured fields.

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 purpose and the output shape, then workflow, then auth. Every sentence carries information, though the auth block is verbose and could be tightened. No wasted preamble.

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?

An output schema exists, so return values need no explanation. The description nonetheless covers the output shape, cost implications, sign-in prerequisites, and the surrounding tool chain, which is complete for a nested-object input with no enums.

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% and the single 'brief' object is fully documented with field names, ranges (1-8 valueProps, 2-5 shotCount, 6-20 totalDurationSec) and enum-like options. The description adds only '2-5 shots' which duplicates the schema, so the baseline 3 for high coverage applies.

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 ('Turn an ad brief into a storyboard') and immediately enumerates the concrete output ('2-5 shots with framing, the spoken line, the caption and the duration of each'). This clearly distinguishes it from sibling generation tools like generate_ad or estimate_ad_cost, which it explicitly names as downstream steps.

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?

Provides an explicit ordered workflow: produce the storyboard, show it to the person, edit if needed, then price with estimate_ad_cost and submit with generate_ad. It also states when auth is needed and how to satisfy it. This is about as complete as usage guidance gets.

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