Create a video for my brand

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

The 'one-shot' framing signals it is a single end-to-end call, and the description discloses the brand-resolution dependency and its failure precondition. However, it says nothing about credit cost, job/async behavior when wait=false, or what happens if the saved brand lacks assets — meaningful gaps for a non-read-only generator. Annotations only cover the readOnly/destructive basics, so this is modest added value.

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?

Three short sentences, front-loaded with the core action, then the brand-defaulting rule, then the prerequisite. No filler and nothing repeated from the schema or annotations.

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?

The critical brand prerequisite is covered, and an output schema exists so return values need not be explained. But for a seven-parameter, seven-value generation tool with 29% schema coverage, the missing guidance on duration units, valid platform values, aspect ratio defaults, and async behavior leaves real holes.

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 29%, so the description must compensate, and it does clarify the brandId/brandSlug semantics and default-brand fallback. But duration, platform, aspectRatio, and wait are left entirely to sparse or absent schema text, leaving five of seven parameters without meaningful explanation.

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?

States a specific verb and resource: generates a UGC ad video grounded in the user's saved brand assets. The brand-grounding phrase implicitly separates it from generic siblings like generate_video and generate_ugc_video, but it never names those alternatives explicitly, so the differentiation is inferred rather than stated.

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?

Gives concrete routing logic: use the default saved brand unless brandId/brandSlug is supplied, and call create_brand first if no brand exists. There is no explicit instruction about when to prefer this over generate_ugc_video or generate_video, so the alternative-selection guidance is incomplete.

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