Video from references

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

With no annotations, the description carries the full burden and does reasonably well: it discloses the output format (mp4), the async behavior ('long jobs come back as a generation_id'), the model default, and the cost-check workflow via ideogram_quote. It omits permission/auth requirements and any rate or concurrency limits, but the core behavioral profile is disclosed.

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 purpose is front-loaded in the first clause, followed by constraints, outputs, and the pricing pointer — a sensible order for a 13-parameter tool. It is dense with parenthetical per-model details, which slows reading slightly, but almost every clause carries information an agent needs.

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 13-parameter generation tool with no annotations and no output schema, the description covers the essentials: supported inputs, model variants and default, minimum reference requirement, output format, async result shape, and the quote-first cost workflow. Remaining parameter detail is handled by the schema's own 100% description coverage, and return values are addressed via the mp4/generation_id statement.

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 100%, so baseline is 3. The description still adds value beyond the schema: it establishes the model ordering and default, the 'at least one reference image or video' constraint that the schema does not state as a rule, the per-model audio duration limits, and the prompt-order semantics for references. It is additive rather than redundant.

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 states the resource and scope precisely: a video guided by reference images, audio clips, and Ideogram-stored videos, with a clear model ordering (Seedance 2.5 default, then Seedance 2, MiniMax H3). An agent can tell this is reference-to-video rather than a plain image-to-video tool. It stops short of naming the sibling it must not be confused with (ideogram_video_image / ideogram_video_text), so it is clear but not fully differentiated.

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?

Usage is implied through prerequisites ('at least one reference image or video') and a workflow hint ('ideogram_quote prices a call first'), which is genuinely useful. However, there is no explicit statement of when to choose this over ideogram_video_image, ideogram_video_text, or the other video siblings. Guidance exists but must be inferred.

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