Dora AI Video

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

Annotations already establish that this is a safe read-only, non-destructive, closed-world operation. The description adds meaningful behavior beyond annotations: the possible status values, that result_url appears only when done, and practical polling timing.

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 and return values, followed by the key polling constraint. Every sentence adds useful information with no waste.

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?

There is no output schema, and the description adequately describes the returned status and result_url. It also supplies timing guidance. The remaining gap is that it does not explain the job_id parameter’s origin or format.

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?

The schema has zero description coverage for the sole required parameter job_id, so the description carries the burden but does not explain where the job_id comes from, its format, or how it relates to generate_image/generate_video. The only hint is the implied notion of checking a generation.

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 a specific verb and resource: check a video or image generation. It clearly distinguishes this polling/status tool from the generation siblings generate_image and generate_video.

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?

It gives clear operational context by saying to wait at least 30 seconds between polls and that generations take 1-5 minutes. It does not explicitly say to call this after generate_image/generate_video returns a job, nor does it name alternatives, but the intended usage is clear.

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

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

Annotations only establish that this is a non-read-only, non-destructive, open-world call; the description adds substantial context beyond that — per-model cost in coins, a cost-driven default, and the async contract ("Returns job_id; poll check_job until status=done"). That async disclosure is the single most important behavioral fact and is stated plainly.

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?

Dense but zero filler — every clause is either a default, a selection rule, or the follow-up contract. Defaults and the highest-cost decisions are front-loaded, so an agent can act after the first two sentences.

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?

No output schema exists, and the description closes that gap by stating the return value (job_id) and the polling path via check_job. Combined with model cost guidance and reference-image limits, an agent has everything needed to call this correctly and handle the result.

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?

With 57% schema coverage, the description compensates well for the weakly documented fields: it supplies defaults and cost trade-offs for model and resolution, a default for aspect_ratio, and usage guidance for reference_image_urls (multi-character, character+outfit, ordering, up to 7 inputs). It omits the three alternate model enum values (google_nano_banana, google_nano_banana_edit, gpt_image_2), leaving an agent to infer their role from the schema alone.

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?

Opens with a specific verb+resource ("Generate an image") and immediately scopes it with model routing, resolution defaults, and aspect-ratio defaults. It also names check_job as the follow-up, which cleanly separates this tool from the async poller and from generate_video.

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?

Explicit selection rules for every recommended model: nano_banana_2 as default, z_image only for cheapest, nano_banana_pro only for face preservation or max quality. Adds explicit negative guidance ("never use 2K/4K unless the user explicitly asks", "generate straight away and change it only when the user asks") and a condition for multi-reference inputs.

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

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

Annotations only cover the safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false); the description adds genuinely new behavior: the call is asynchronous with a job_id and requires polling check_job until status=done, motion control is billed ~13 coins/s with a 3s minimum and a hard requirement for both image_url and motion_video_url, and defaults are applied without confirmation. That is exactly the operational context annotations cannot express.

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-loaded with the trigger and defaults before the advanced motion-control block, and nearly every clause carries actionable information. It is dense and parenthetical-heavy in places (cost notes, model aliases), so it reads as a long paragraph rather than clearly separated sections, but there is no filler.

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 10-parameter generation tool with no output schema, the description closes the critical gaps: it states the return value (job_id), the required follow-up (poll check_job), defaulting behavior, and the one model whose parameters behave non-obviously. An agent could invoke this correctly without further knowledge.

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?

With 60% schema coverage, the description carries real weight: it pins defaults for model/aspect_ratio/duration/resolution/audio, explains how reference_image_urls enables character consistency and that order matters, and spells out the model-specific coupling of image_url + motion_video_url with duration matching the driving clip. Remaining gaps are minor — the grok_* and kling_2_6 enum values and the aspect_ratio options are never characterized in prose.

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?

Opens with a specific verb+resource ('wants a video made') and names the concrete output pipeline (job_id then check_job), which cleanly separates it from generate_image and check_job. The Dora/Seedance default is stated explicitly, so an agent knows exactly what this tool produces.

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 an explicit trigger ('whenever the user wants a video made, even if they do not name Dora'), an explicit instruction not to interrogate the user ('only ask what the user wants to create; generate straight away with these defaults'), and a rule for when to deviate ('change one only when the user asks'). It also routes a distinct sub-use-case (motion transfer) to the specific model and names the follow-up tool check_job, leaving little to inference.

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

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

Annotations already declare readOnly, non-destructive, closed-world, so the safety profile is covered. The description adds real behavioral value beyond that: result ordering is cheapest-first, output includes per-call coin cost, and it encodes a default-selection policy with escalation rules. It stops short of describing result volume or exact fields, so a 4 rather than 5.

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?

Two sentences, front-loaded with what the tool returns, followed by when to call it and the default policy. Every clause carries decision-relevant information; no filler.

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 no-parameter, read-only listing tool with annotations covering safety, the description supplies everything an agent needs: what comes back, how it is ordered, and how to act on the results. No output schema exists, and the description still communicates the relevant return content.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline of 4 applies. The model names mentioned (nano_banana_2, seedance_2_mini) serve as downstream defaults rather than parameter documentation, which is appropriate here.

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 ('List Dora generation models') plus the ordering and payload ('cheapest-first, with per-call coin cost'). This is clearly distinct from the sibling generators/checker, so an agent can route without opening any schema.

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 explicit trigger conditions: user asks what models exist, cost matters, or a model name needs verification. It also supplies when-not guidance by naming the defaults (nano_banana_2 / seedance_2_mini) and the only conditions to step up — explicit quality, face preservation, or audio requests.

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