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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds two pieces of context beyond that: 'Does not spend' (no credits) and the shape of returned data (kinds with slug/name/line; brand_id adds saved recipes with id/title/kind/scenes/seconds). Useful, though pagination/size behavior is unstated.

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?

Content is dense and every clause carries information, but the sentence is a run-on with heavy parenthetical asides and em-dashes, making it harder to parse quickly. The evocative opening is not maximally front-loaded for selection.

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?

With no output schema, the description usefully documents the return shape (kinds, formats, brand recipes and their fields) and the downstream workflow to create_motion_project. Two optional params and closed-world read scope are adequately covered, though list size/pagination is not addressed.

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 adds real semantic value: it explains that supplying brand_id surfaces the brand's own saved recipes ('make another like this one') with a specific field set, which meaningfully clarifies the parameter's effect beyond the schema's 'Brand workspace id from list_brands'.

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 communicates that this lists the starting-point templates for video creation, enumerating kinds (ad, reel, explainer, talking_head, polish) and their formats, which lets an agent distinguish it from creation siblings like create_motion_project or make_studio_video. It leans on the metaphor 'What a film can start from' rather than an explicit verb, so it is clear but not maximally direct.

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?

'Pass the choice to create_motion_project' and 'as on the Video tool's start screen' frame this as the selection step that feeds the creation tool, giving clear usage context. No explicit when-not-to-use or named alternatives beyond the downstream call, so it stops short of a 5.

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