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

Annotations already declare the write/destructive/open-world/non-idempotent profile, so the description's job is the rest. It adds genuinely useful behavior: the call returns tracked tasks and the caller must poll get_production_status, and the output is an editable project rather than a finished render. It does not explain cost implications or why destructiveHint is set for a create operation.

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-loads the core capability, then branches per mode, and closes with the async polling note. Every clause is informative, though the middle section is dense enough that the three modes run together.

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?

Covers the modes, prerequisites, and the async return path, which is important given there is no output schema. For a nested-schema, four-parameter creation tool with zero parameter descriptions in the schema, however, key invocation details (valid model strings, type/resolution/aspectRatio behavior, workspace scoping) remain undocumented.

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 0% across four parameters (including a nested `definition` object), so the description carries the burden. It clarifies intent for `referenceImages` (product ads) and `parameters` (localization target language) and the authored shot prompts, but says nothing about `workspaceId`, `model` values, `type`, `aspectRatio`, or shot duration limits.

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 and enumerates the three supported modes (product ad, 3-5 shot story, localized creative), which map directly to the `kind` enum. It does not, however, contrast itself against closely-related siblings like run_production_template or create_edit, so an agent must infer the boundary.

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 when-to-use context: product ads require passing the real product image as a reference and using extract_product_image or an upload first; localization requires the original creative, target language as a parameter, and preservation instructions. No explicit when-not-to-use or named alternative (e.g., run_production_template) is supplied.

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