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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true and idempotentHint=false, so the mutation profile is covered. The description goes beyond that with a meaningful time cost ("about a minute") and the full billing behavior (first storyboard free, re-plans cost `replan_credits`, missing `credits` yields `price_confirmation_required` with nothing charged). That is real added value, but it stops short of disclosing failure modes or what happens to an existing storyboard when a re-plan overwrites it, so it sits just above adequate rather than at the top.

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 purpose, then inputs, then outputs, then pricing — a sensible order with almost no filler. The final pricing/routing paragraph is long and slightly tangled (free re-plan vs. paid re-plan vs. free edits), costing some readability, but every clause carries decision-relevant information.

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 9-parameter generative tool with no output schema, the description fully compensates: it enumerates the return shape (`picture_storyboard.frames` with `t`, `title`, `note`, `image_url`, plus `sheets`, `replan_credits`, `redos_left`, and `button`), states latency, and spells out the payment gate. Nothing an agent needs to call this correctly and explain the outcome to a user is missing.

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 earns an extra point by explaining behavior the schema cannot, notably that `idea` accepts the script's own idea via "own", that omitted `shape`/`music`/`captions` fall back to "our guesses", and that `credits` only belongs on a same-idea re-plan. It still does not say how `feedback` interacts with `credits` (does a free edit path exist here?), which keeps it off a 5.

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 ("Draw the PICTURE STORYBOARD for one of the film's ideas") and immediately scopes what it produces: 14–20 timed key frames in one look. It also anchors the input to the sibling that produces the ideas (studio_video_ideas), so an agent can distinguish it from edit_studio_video_storyboard and edit_studio_video_board.

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?

Explicitly routes between siblings: small changes go to edit_studio_video_board (free), and make_studio_video should only be invoked once the user is happy. It also states the preconditions and the price-confirmation loop (say the price, get a yes, pass `credits`), which is exactly the when/when-not guidance an agent needs.

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