AI Photo Animator

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

Annotations only declare readOnly=false and openWorld=true; the description adds the context an agent actually needs: the call costs credits, it is asynchronous and returns a task_id rather than a video, and the caller must poll get_video with a typical 1–5 minute turnaround. That is real behavioral disclosure beyond the structured fields, with no contradiction.

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?

Four short sentences, front-loaded with the action, then mode selection, then cost, then the result-handling contract. No sentence is redundant and the polling instruction is placed last where an agent needs it.

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 3-parameter async generation tool with no output schema, the description covers everything an agent must know to call it and handle the result: cost, task_id return, poll target, and expected latency. Remaining details (credit amount, failure/refund behavior) are marginal against a 100%-covered schema and present annotations.

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 coverage is 100%, so the baseline is 3, but the description adds the semantic relationship between the two optional params: `effect` overrides motion and `prompt` becomes supplementary instructions, or `prompt` alone drives a free-form animation. It still does not clarify multi-image ordering or the 1–4 image limit, which stays entirely in the schema.

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 ('Turn photo(s) into a short video'), and the two-mode framing (effect-driven vs prompt-driven) makes clear what the tool actually produces. It never names create_video as the text-to-video counterpart, so differentiation from the closest sibling is left implicit 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?

It gives a clear decision rule for the two invocation modes ('With `effect` ... the effect decides the motion; without it ... following `prompt`') and routes the agent to list_effects for valid effect ids and to get_video for results. What is missing is an explicit exclusion — e.g., when to prefer create_video or restore_photo over this tool.

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 cover safety (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds genuinely new behavior: the model/quality ('Nano Banana 2 at 1K'), that it consumes credits, and the synchronous-vs-pending return pattern. It stops short of saying what happens on failure or how many credits are consumed.

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 tight sentences, front-loaded with the primary capability, then cost, then return semantics. No filler or redundancy.

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?

With no output schema, the description correctly explains the return shape (direct image or pending + get_image) and discloses credit cost, which is what an agent needs to plan a call. Error handling and credit quantities are the remaining gaps.

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 all three parameters are already documented with constraints and enum values. The description implies the prompt/image_urls relationship but adds no syntax, ordering, or format guidance beyond the schema, which is the expected baseline 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?

Names specific verbs (generate, edit) and the resource (image), and enumerates concrete edit types (background, outfit, style, lighting, combine). An agent can distinguish this from create_video or animate_photo without opening the 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 a clear usage fork ('omit image_urls to generate from text only') and an explicit follow-up path ('if status is pending, call get_image later'). It does not route against near-siblings like restore_photo or animate_photo, so selection between those remains inferred.

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 readOnlyHint=false, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: it costs credits, output is fixed at 5s/720p/audio, and the call is asynchronous, returning a task_id to poll with get_video. Missing only failure/timeout behavior or expected generation latency.

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 compact sentences, zero filler. The output spec and the text-only constraint are front-loaded, with the cost and the task_id/poll pattern trailing as secondary but essential facts.

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 2-parameter tool with a fully documented schema, this covers everything an agent needs: what it produces, what it costs, that it is async, and which tool continues the flow. No output schema exists, yet the description still explains the return value (task_id).

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 coverage is 100%, with prompt and aspect_ratio both fully described including the enum meanings, so the schema does the heavy lifting. The description adds only an implicit constraint ('text description only') and no syntax, length, or format detail beyond what the schema states. Baseline 3 applies.

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?

Names a specific verb and resource ('Generate a short video') and pins down the output envelope (5 seconds, 720p, with sound) plus the input modality ('from a text description only, no photo needed'). The 'no photo needed' clause directly separates it from the sibling animate_photo, so an agent can route without opening schemas.

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 clear conditions: use text only, no photo required, and expect a credit cost. It also names the follow-up path ('poll get_video'), which tells the agent this is step one of a two-call flow. It stops short of naming alternatives like create_image or animate_photo as explicit exclusions, or pointing to get_credits before spending.

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 declare non-read-only, open-world, non-destructive; the description goes well beyond by disclosing the credit cost model (scaled by clip length), the hard input constraints (MP4, 15s, 50MB), and the asynchronous contract (returns task_id, poll get_video). These are exactly the facts an agent needs before committing to a paid, long-running call.

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 the operation and its hard limits, then the cost and async contract. Every clause carries operational information—no restatement of the name or title.

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?

With no output schema, the description correctly covers the return path (task_id then get_video) and supplies the cost and size limits an agent would otherwise lack. Nothing needed to invoke this correctly is missing.

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 the schema already explains prompt, video_url and the image 1/image 2 reference convention for image_urls. The description's mention of 'the person from a photo' loosely reinforces image_urls but adds no constraint or syntax the schema doesn't already supply, so the baseline 3 applies.

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?

Specific verb + resource (edit an existing video clip), plus the input format, duration and size envelope, and the exact class of edits supported (outfit, style, background, scene) while preserving motion and timing. An agent can distinguish this from create_video or animate_photo 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?

It makes clear this operates on an existing clip with instructions and explicitly routes the agent to get_video for polling the result. It does not, however, contrast this with create_video or animate_photo as alternatives for non-editing generation, so the when-not branch is left implicit.

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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description's added value is naming what comes back (remaining credits and plan) and that it applies to the connected account's credentials, but it gives no detail on units, staleness, or error behavior when unauthenticated.

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?

A single terse clause with no filler and the payoff front-loaded. It is arguably one verb short of fully self-explanatory, which keeps it off a 5.

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 zero-param read with no output schema, an agent still doesn't know the shape of the response — whether plan is a name or object, whether credits are numeric, or what happens with an unauthenticated account. Adequate, but a sentence short of complete.

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?

Zero parameters, so the schema carries no semantic load and the description needs none. Baseline 4 applies.

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?

Names the specific resource returned (remaining credits and plan) and scopes it to the connected account, which cleanly distinguishes it from the media-generation siblings. It is a noun phrase rather than a verb phrase, but the intent is unmistakable.

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?

No explicit when-to-use, prerequisites, or alternatives are stated; usage is only implied by the zero-parameter read shape. For a self-evident account-status lookup that is arguably adequate, but it never says anything like 'use before generating media to check quota'.

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 cover the safety profile (readOnlyHint=true, destructiveHint=false), so the description's added value is the state machine: pending, success with image_url ready, or failed with credits refunded. The refund-on-failure detail is real behavioral context an agent could not infer from structured fields. It omits whether repeated polling is expected or whether task_ids expire.

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 short sentences, front-loaded with the operation and followed by the outcome states. Every clause carries information; nothing is padding.

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 one-parameter polling tool with annotations covering safety and no output schema, the description supplies the essential missing piece: the possible statuses and their meanings including the credit refund. Only the polling/expiry behavior is left unstated.

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 coverage is 100%, and the single parameter's schema description already says it is the task_id returned by create_image or restore_photo, which the prose merely echoes. No additional format or lifetime guidance is provided, so the baseline 3 applies.

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 names a specific verb ("Check") tied to a specific resource ("an image task"), and scopes it to tasks produced by create_image or restore_photo. That implicitly separates it from get_video and the creation tools, but it never states the contrast outright.

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?

"Check an image task from create_image or restore_photo" gives a clear usage context: call this after starting one of those two jobs. There is no explicit when-not guidance or named alternative (e.g. get_video for video jobs), so it falls short of a 5.

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?

The description adds useful behavioral context beyond the annotations: status is pending, success, or failed, and a failed task has credits refunded. With readOnlyHint and destructiveHint=false already covering the safety profile, this is a solid disclosure of outcome semantics.

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 two short sentences with the purpose first and the status details second. Every sentence contributes directly to understanding the tool.

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 simple read-only status tool, the description covers the important return states and what happens on failure. The task_id source is handled by the schema, so the only modest gap is the lack of explicit routing against sibling status tools.

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%, and the task_id schema already explains that the value comes from animate_photo, create_video, or edit_video. The description does not add parameter-level detail, so the baseline score of 3 is appropriate.

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 action as checking a generation task and clarifies the possible status outcomes, including video_url on success and credits refunded on failure. It is clear enough to identify the tool, though it does not explicitly distinguish video tasks from the sibling get_image status tool.

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 only implied by 'Check a generation task' and the status lifecycle. It does not explicitly say to call this after create_video/animate_photo/edit_video, nor does it mention alternatives such as get_image or list_my_videos.

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 cover the safety profile (readOnly, non-destructive, closed-world), so the description's added value is describing returned fields: an `effect` id and a `photos` count. That is useful output context beyond the annotations, though it doesn't fully describe the item shape.

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 purpose, then downstream usage, then a field note. Every sentence carries distinct information and nothing is repeated from the schema or title.

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?

With no output schema, the description does part of the job by naming two returned fields and the consumer tool. It leaves the rest of the result shape undescribed, but for a simple zero-parameter list tool this is close to sufficient.

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 the baseline is 4. The description's mention of `effect` and `photos` refers to returned fields rather than inputs, which adds minor clarity without any parameter ambiguity to resolve.

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 (List) and resource (video effect templates) and illustrates scope with concrete examples (dance, sports, meme scenes). It also differentiates itself by naming the sibling that consumes its output (animate_photo).

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?

Explicitly tells the agent this is the discovery step whose `effect` id is then passed to animate_photo, which is clear usage context. It does not state any when-not conditions or exclusions, keeping it just short of a 5.

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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds ordering ('newest first'), which is genuinely useful behavior the annotations don't carry. It stops short of saying how many are returned by default, whether 'most recent' means a fixed window, or what each entry contains.

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?

One front-loaded sentence with no padding, and the ordering is stated first. It's efficient, though the leanness is partly under-specification rather than discipline.

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?

With no output schema, a 0%-documented parameter, and no annotations explaining return shape, the description should say what comes back and what the limit does. Neither is covered, so an agent cannot predict the result size or default behavior.

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% and the description never mentions the single 'limit' parameter. The agent is left without a documented default, an explanation of the 1-30 range, or whether omitting it returns everything or a capped slice — exactly what the description should compensate for at zero coverage.

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?

It names the resource (the user's video generations) and its ordering, which distinguishes it from get_video and list_effects, but it never states the operation as a verb — 'The user's most recent video generations' only implies a listing. An agent can guess it's a list call, but the description reads closer to a caption than a definition of what the tool does.

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?

There is no when-to-use guidance and no routing to alternatives. Nothing tells the agent when to call list_my_videos versus get_video for a specific video, or create_video to make a new one.

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 declare the safety profile (not read-only, not destructive, open-world); the description adds substantive behavior: it costs credits, it may return a pending state requiring get_image, and it preserves subjects' identity ('keep everyone exactly as they are'). Credit amounts and failure modes are not covered, keeping it below 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?

The core action is front-loaded, followed by the optional colorize flag, cost note, return/pending semantics, and a chained-next-step tip. Dense with zero filler 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?

With no output schema, the description steps in to explain what comes back (restored image, or pending routed to get_image) and what it costs. For a two-parameter tool with annotations covering safety, nothing material is missing for correct invocation.

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 both parameters are already documented, including colorize's default of false. The description's mention of optional colorization for black-and-white photos restates rather than extends the schema, which is the baseline-3 case.

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?

Names a specific verb and resource (repair an old or damaged photo) and enumerates the exact defects handled: scratches, dust, creases, fading, soft faces. This is clearly a restoration tool, distinct from siblings like create_image or edit_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?

The description establishes context (old/damaged photos, scans or print photos per the schema), notes the optional colorize path, and explicitly routes the agent onward: 'animate the result with animate_photo afterwards' and 'pending → get_image'. It doesn't state explicit exclusions versus create_image, but the intended use case is unambiguous.

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