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

The description adds substantial behavior beyond annotations: reference-based generation conditions on actual pixels and preserves faces; character-system alternatives drift; generate_image silently ignores external references; and the result should be retrieved through check_job. Annotations already cover mutation/idempotence/safety, but this enriches the operational picture significantly.

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?

The description is long, but each section earns its place: core definition, parameter encoding detail, routing guidance, workaround, and project scoping. The 'confirmed live' and 'same-day testing' material is verbose yet directly supports tool selection and prevents known failures. It is front-loaded with the primary purpose, though it could be tightened.

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?

Despite having no output schema, the description tells the agent how to follow through—via check_job and first_frame_path—and gives enough context for selection and invocation. It does not explicitly explain the full return flow or all parameters, but defaults and enums lower the risk. Overall, it is near-complete for a tool with this much sibling confusion.

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%, so the description carries the parameter-semantics burden. It adds genuinely useful detail for reference_images_base64 (raw base64, no data URI, max 3) and project_id (must be from create_project), but it leaves prompt, aspect, include_preview, and video_model_key unexplained beyond schema defaults/enums. Compensation is partial, not complete.

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 opening sentence states a specific verb and resource: 'Generate a video using up to 3 reference images (r2v)'. It also clarifies the distinguishing purpose—consistent character/subject preservation—and explicitly separates it from i2v start-image generation. This clearly differentiates it from siblings like generate_video_from_image and generate_video_between_frames.

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?

The description is unusually explicit about when to choose this tool: it is 'THE RECOMMENDED WAY' for real-person likeness preservation, and it names concrete alternatives (generate_character_image, generate_character_turnaround, generate_image) while explaining why they fail. It also gives a workaround for still-image output, plus the mutual exclusivity constraint with i2v.

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