Magic Hour

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

Annotations already cover safety (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds genuinely new behavior: it runs as a background job, it consumes credits, and it returns a project id. It stops short of saying anything about job duration or failure handling, so not a 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, zero filler, with the core action front-loaded and the cost/async consequence trailing. Nothing could be cut without losing information.

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?

Output schema exists, so return-value explanation is not required, and the description still links the job to wait_for_video_project. The one gap is not flagging the overlap with translate_video for a tool that sits among many similar video generators.

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 style enum, custom_config requirements, and asset path rules are all documented in the schema itself. The description only echoes the preset-vs-custom choice, adding no new format or constraint detail, so 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?

States a specific verb and resource ('Adds automatically generated subtitles to a supplied video segment') plus the two styling modes, which is enough to separate it from generic siblings like edit_video or restyle_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 names the follow-up tool (wait_for_video_project) and flags that the job costs credits, but never says when to pick this over a close alternative such as translate_video, which also produces subtitles. Usage is therefore implied rather than guided.

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 safety (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the description's extra value is the credit cost (25), the asynchronous job model, and the project-id handoff. These are exactly the behavioral traits an agent needs before invoking. It doesn't state failure modes or turnaround expectations, which keeps it below a 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 tight paragraphs with zero filler; the behavioral line (what it does, cost, async handoff) is front-loaded in the second sentence. The safety policy leads the description rather than trailing it, which is defensible but slightly delays the core purpose statement.

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?

Given a rich nested schema, full coverage, an output schema that already describes return values, and annotations covering the safety profile, the description supplies everything remaining: the credit cost, async workflow, follow-up tool, and usage restrictions.

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 documents person_file_path, garment_file_path, garment_type, and name in detail. The description only implicitly references the person and garment inputs and adds no syntax or format guidance beyond what the schema provides, so 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?

States a specific verb+resource: changes clothing in a person photo using a supplied garment reference image. This clearly distinguishes it from siblings like edit_face_in_photo, swap_face_in_photo, and generate_headshot, which manipulate other aspects of a person 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?

The description gives explicit policy constraints (only the user's own likeness or authorized content; never impersonation, deception, sexual content, or minors) and the correct downstream flow: it starts a background job and the returned project id should be passed to wait_for_image_project. This names the follow-up tool directly.

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 give generic hints (readOnlyHint=false, destructiveHint=false, openWorldHint=true); the description adds two non-obvious behaviors: credit cost and asynchronous project-id return. Doesn't mention failure modes or file format constraints, but that's in the schema.

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, front-loaded sentences; cost and next-step routing are packed in without 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?

Output schema exists so return values needn't be explained, and the async workflow handoff is stated. Missing only a note on input image requirements or failure cases, which is minor.

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 detailed descriptions for name and image_file_path, so baseline 3 applies; the description adds no param-level detail beyond what the schema already provides.

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: colorizes a black-and-white or faded photo. It also states the input constraint (grayscale/faded), distinguishing it from edit_image or generate_image.

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?

States the cost (10 credits) and explicitly says it returns a project id for wait_for_image_project, which directs the agent's next step. No explicit when-not-to-use or sibling exclusions, but the input condition narrows applicability well.

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 the safety profile (readOnly=false, destructive=false, openWorld=true), so the bar is lower, and the description adds genuinely useful context: credit cost scales with frame rate and duration, and it returns a project id to poll via wait_for_video_project. It doesn't mention auth or approval requirements, but the async chain and cost warning are real added value.

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 tight sentences, front-loaded with the verb and resource, followed by capability and cost/return facts. 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?

Given an output schema exists, return values needn't be described, yet the description helpfully flags the project id and the wait_for_video_project hand-off. With 7 parameters, nested objects, and conditional enums, the description could say slightly more about required inputs (e.g., that audio/assets drive prompt_type), but overall it is sufficient 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 coverage is 100%, so the schema already documents every parameter including the enums, nested style object, and conditional requirements. The description only loosely maps 'art and camera settings' and 'initial image and audio' to those fields, adding little beyond the schema — baseline 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?

States a specific verb and resource ('Creates a stylized animated video') and enumerates the two prompt modes plus optional image/audio inputs. It doesn't explicitly contrast itself with near-neighbors like create_video_from_image or create_video_from_audio, so sibling differentiation is only implied by the 'animated video with art styles' framing.

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?

Mentions the audio-derived prompt mode constraint only indirectly ('custom prompt or an audio-derived prompt mode'), and names wait_for_video_project as the follow-up, which implies an async workflow. However, it never says when to pick this tool over the many other video-creation siblings, leaving selection 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=false and destructive=false, so the bar is lower, and the description still adds real behavioral context: a fixed 50-credit cost and asynchronous background-job semantics. The non-obvious detail that the job is awaited via wait_for_image_project rather than wait_for_video_project is exactly the kind of trap this field should catch; only refund/failure behavior is missing.

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 clauses with zero filler: capability first, cost second, async/return contract last. Everything an agent needs to act is front-loaded.

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 an output schema present, return-value explanation is optional, yet the description still supplies the key chaining fact (project id → wait tool) plus cost. The nested style.prompt object and the sibling-overlap question are the only remaining gaps for a paid async tool.

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 67%, and the schema already documents prompt (max 500), output_format enum, and the name default. The description restates the three formats and the text-prompt nature without adding format-level meaning such as aspect ratio, duration, or motion guidance, so it is baseline rather than compensatory.

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 — generating a short animation from a text prompt — plus the concrete outputs (GIF, MP4, WebM). It is clear on its own, but it never distinguishes itself from close siblings like create_animation or create_video_from_text, so an agent cannot route between them from this text alone.

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 by the output-format scope, and the description does supply a workflow pointer ('returns a project id for wait_for_image_project'), which is genuinely helpful. However, it gives no when-to-use vs when-not guidance against the many other animation/video-from-text siblings.

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 annotations already declare this is a non-read-only, open-world operation, but the description adds substantive behavioral context: it starts a background job, costs credits, and returns a project id for polling. The authorization and content-policy constraints are also disclosed, which 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?

The description is compact and front-loaded with the safety restriction, then the core operation, the sibling alternative, and the async lifecycle. Every sentence provides actionable information.

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?

Although an output schema exists, the description still adds necessary operational context about the background job and the project id. Combined with the rich input schema and annotations, an agent has everything needed to select and invoke the tool correctly.

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 every parameter and nested field is already documented in the schema, including video_source, start_seconds, end_seconds, style.generation_mode, and max_fps_limit. The description adds no parameter-level detail beyond that, so the baseline 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 a specific verb and resource: adjusting an existing video's lip movements to match replacement audio. It explicitly distinguishes this from create_talking_photo, which handles still portraits rather than existing 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 explicit when-to-use and when-not-to-use guidance, including authorized likeness restrictions and prohibited uses such as impersonation and minors. It also routes still-image cases to create_talking_photo and tells the agent to follow up with wait_for_video_project using the returned project id.

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 a non-read-only, open-world, non-destructive operation, so the bar is lower. The description adds genuinely non-structured context: a 10-credit cost and the fact that execution is asynchronous returning a project id, both of which materially affect how an agent invokes it.

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, each carrying a distinct fact (what it does, cost, async return/next step). Front-loaded with the purpose and 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?

An output schema exists so return-value detail is unnecessary, and the description covers cost plus the async handoff. It is somewhat thin on the nested style options and the optional `name`, but an agent has enough to call it correctly.

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 50% on a nested object; the description only restates that topic and template drive the result and never mentions the optional `name` or `searchWeb` fields. Enum (template = "Random") is already in the schema, so no credit there. Adequate but not compensating for the coverage gap.

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 ("Creates a meme") plus the two inputs that shape the output (topic, template). It is clearly distinct from generic siblings like generate_image or create_gif_or_short_video by virtue of the meme/template framing, though it never explicitly names an alternative.

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 routing information for the follow-up step: the tool starts a background job and returns a project id to hand to wait_for_image_project. It doesn't state when *not* to use this versus generate_image or other image tools, but the async workflow guidance 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 already declare readOnlyHint=false and destructiveHint=false, and the description adds genuinely new behavior: the operation is currently 0 credits and is asynchronous, returning a project id rather than a finished asset. That async/credit context is the key thing an agent can't infer from annotations.

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, zero waste, with the core action stated first and the cost/async behavior front-loaded before the follow-up hint.

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?

An output schema exists, so return values need no explanation, and the description links to the correct polling sibling. Minor gap: nothing about the style template list or failure behavior, but the essentials for a correct invocation are present.

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 67%, and the description only restates that content is 'text or a URL' and style is an 'art-style description' — the schema already says this. It adds no constraints on the nested art_style object or the name parameter, so baseline 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?

States a specific verb and resource (creates a stylized QR code) plus the two inputs that drive it (text/URL and an art-style description). This is clearly distinguishable from sibling image generators like generate_image or create_meme.

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 operational context: it starts a background job and returns a project id to pass to wait_for_image_project, which tells the agent exactly what to do next. It does not name when to prefer this over e.g. generate_image, so no exclusions/alternatives are covered.

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?

Adds real behavioral context beyond the annotations: it discloses that this starts a background job, that it costs credits, and that it returns a project id meant for wait_for_video_project. It does not cover plan/auth constraints or failure behavior, but the cost and async nature are the highest-value disclosures here.

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 with zero filler; the core action, the usage trigger, and the cost/async warning are all front-loaded in that order.

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 an output schema present, return values needn't be described, yet the description still flags the project id and the wait_for_video_project handoff. Combined with annotations covering the safety profile and a rich schema, nothing an agent needs to call 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 80%, so per-parameter meaning (model defaults, script character limits, end_seconds ranges, file path format) is already fully documented in the schema. The description only echoes that an image and script are needed, adding no syntax or constraint detail beyond it. 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?

States a specific verb and resource ('Creates a creator-style spoken ad video') and names both required inputs (prepared image, text script), which distinguishes it from siblings like create_video_from_image and create_talking_photo that lack the script-driven dialogue element.

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 activation condition ('Use when the image is ready and the dialogue should be generated from text') and routes the follow-up to wait_for_video_project. It stops short of naming an explicit alternative or a when-not-to-use case, so it lands just below the top band.

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 mark it as non-read-only, open-world, and non-destructive, and the description adds important behavior beyond them: it starts a background job, costs credits, and returns a project id intended for wait_for_video_project. It also discloses authorization and content-safety constraints. There is no contradiction with the annotations.

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 compact and front-loads the most important constraint, then states the purpose, input requirements, and async cost/return behavior. Every sentence carries useful information with 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?

Given the rich input schema, full parameter description coverage, and an output schema, the description is complete enough for an agent to select and invoke the tool correctly. It covers the key functional scope, safety constraints, required asset types, cost/background-job behavior, and next step for retrieving results.

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 parameters such as assets, resolution, start_seconds, end_seconds, style, and generation_mode. The description reinforces that a portrait photo and audio file are required and that text alone is not accepted, but it does not add much detail about the nested style, resolution, or timing parameters beyond what the schema provides.

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 action and resource: it animates a still portrait so it speaks an existing audio recording. It also distinguishes the tool from text-only generation and speech synthesis by explicitly saying text alone is not accepted and it does not synthesize speech.

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?

Provides clear usage context and exclusions: use only with the user's own likeness or authorized content, and do not use for impersonation, deception, sexual content, or minors. It also clarifies that a portrait photo and audio file are required, though it does not explicitly route the agent to a named sibling alternative for lip-sync or audio-to-video cases.

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?

Goes well beyond the annotations by disclosing that the call only enqueues a background job, that it consumes credits, and that completion requires polling wait_for_video_project. Those are exactly the behavioral facts an agent needs and are not derivable from readOnlyHint/destructiveHint/openWorldHint.

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 core purpose is front-loaded and the operational note (cost, background job, polling tool) is appended, which is the right ordering for an agent scanning for what to call next.

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?

An output schema exists so return values need not be explained, and the async lifecycle is covered. Minor omissions remain: no indication of typical job duration or that the 1080p/720p resolution may depend on account tier (only implied via the schema's resolution note).

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 every parameter (including the nested style.prompt and assets.image_file_path) is already documented in the schema. The description only restates that the audio track is required and the image is optional, adding no format or constraint detail beyond the schema — baseline 3.

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 ('Generates an audio-guided video from a supplied audio track') plus the two modifiers that distinguish it from the other create_video_* siblings: audio track input, optional starting image and visual prompt. An agent can tell it apart from create_video_from_image/create_video_from_text 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?

It names the follow-up tool ('returns a project id for wait_for_video_project'), which is the key routing instruction for an async operation. It does not explicitly say when to prefer this over create_video_from_text or create_video_from_image, so it stops short of full when/when-not guidance.

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 a non-read-only, non-destructive, open-world operation, so the description's added note that it starts a background job and costs credits is real value beyond structured fields. It does not cover failure modes or credit-amount variability across models, which is the remaining gap.

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 tight sentences with the core action first and the async/cost caveat second. Nothing is redundant with the title or schema, and every clause carries information.

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 7-parameter, nested, async generation tool with an output schema and rich schema descriptions, the description covers the essential calling contract: image input, async job, credit cost, and the project-id handoff. Only the sibling differentiation for create_animation 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?

With 100% schema description coverage, the schema already documents every parameter, including the extensive per-model duration/resolution/audio tables. The description adds only the general notion of 'motion instructions and available model options' and does not clarify parameter syntax beyond the schema, so 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?

States a specific verb and resource: animates a supplied image into a video, with motion instructions and model options. This cleanly separates it from create_video_from_text and create_gif_or_short_video, though it doesn't explicitly name the nearby sibling create_animation, which could also involve still-image input.

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 sentence 'returns a project id for wait_for_video_project' gives a useful follow-up cue, but there is no guidance on when to choose this over create_animation or create_video_from_text, nor any prerequisites or exclusions. Usage is implied by the resource rather than stated.

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 mutability and open-world traits; the description adds genuinely new behavior: it is asynchronous ('Starts a background job'), it consumes credits, and it returns a project id that must be polled. That is the crucial operational context for a write tool. It stops short of covering failure/refund behavior or cancellation.

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: what it does, when to pick the sibling instead, then the async/cost consequence and next step. Front-loaded and free of repetition of schema content.

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 an 8-parameter, nested-schema, enum-heavy tool with an output schema present, the description supplies exactly the non-schema essentials: purpose, sibling routing, asynchronous job semantics, credit cost, and the follow-up tool. Nothing needed to invoke it 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 88%, with detailed per-model constraints on audio, model, resolution, end_seconds, aspect_ratio and references. The description only alludes vaguely to 'optional supported reference inputs and model settings' and adds no meaning the schema doesn't already carry, 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?

States a specific verb and resource ('Generates a video from a text prompt') plus the scope of optional inputs and model settings. It explicitly distinguishes itself from create_video_from_image, so an agent can route between the two without opening either 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 selection rule ('To animate an existing starting image, use create_video_from_image') and names the required follow-up (wait_for_video_project). It does not address the many other video-producing siblings (create_video_from_audio, create_animation, edit_video), but the primary branching decision is covered.

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 destructiveHint=true, so the description must add beyond that — and it does: output artifacts are also removed, the deletion is best-effort ('attempts to'), and the action is irreversible with a confirmation requirement. Minor gap: no mention of behavior when the ID doesn't exist or when output deletion fails.

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, the scope of deletion first, then the irreversibility and confirmation warning. No filler; every clause carries operational weight.

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 single-parameter delete with no output schema, this covers what an agent needs: what gets destroyed (including derived output), that it's permanent, and that user confirmation is required. Only the error/not-found case is unaddressed.

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 id property already documents its meaning and origin (returned by POST create APIs). The description mentions no parameter details, so it adds nothing beyond the schema — 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?

States a specific verb (deletes) and resource (audio project), and adds that it also removes the completed output, which distinguishes it from a mere record cleanup. The 'audio' qualifier separates it from delete_image_project and delete_video_project, though it doesn't name them.

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 precondition: 'confirm with the user first', which is the key gating instruction for an irreversible action. It does not name alternatives or say when-not to use it, but no real substitute exists among the siblings for removing an audio project.

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 flag destructiveHint=true, but the description adds genuinely new context: the output deletion is only "attempted" (best-effort, may not fully succeed) and the action "cannot be undone." That nuance about partial deletion is not derivable from any structured field.

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 action and its consequence before the safety instruction. 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 single-parameter destructive tool with no output schema, the essentials are covered: irreversibility, best-effort output cleanup, and user confirmation. Minor gap: nothing about what happens if the project is still processing or whether an error is returned when the output can't be deleted.

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?

Only one parameter, and the schema describes it at 100% coverage including provenance ("returned by all of the POST APIs that create an image"). The description adds nothing about the id, so 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?

States a specific verb and resource ("Deletes the image project") plus a secondary effect (deleting completed output). The name and description make the media type unambiguous relative to delete_audio_project and delete_video_project, though it never explicitly names them.

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?

Provides one useful precondition, "confirm with the user first," which is real when-to-use guidance. It gives no alternatives or exclusions, e.g. no routing to get_image_project to verify the target, and no mention of how to find the id beyond the schema.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds genuinely new behavioral context: the deletion is irreversible and the attempt to remove the completed output may be partial ('attempts to'), which warns the agent that leftover artifacts are possible.

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, zero waste. The irreversible consequence is front-loaded ahead of the confirmation instruction, so the most important warning lands first.

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, so the description could say what a delete call returns or whether it is idempotent if the project is already gone. Still, for a one-parameter destructive tool it covers the essentials: effect, irreversibility, and user confirmation.

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 100% schema description coverage, the single 'id' parameter is already documented, including its origin from POST creation APIs. The description adds no further parameter semantics, so the baseline of 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?

States a specific verb ('Deletes') and resource ('the video project'), plus an additional effect on its completed output. This clearly distinguishes it from the sibling delete_audio_project and delete_image_project, which share the same verb but operate on different resources.

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 precondition — 'confirm with the user first' — which is exactly the right guidance for a destructive operation. It does not, however, point to alternatives or prerequisites such as verifying the project with get_video_project before deleting, so no exclusions are stated.

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 meaningful behavior beyond the annotations: the task is asynchronous, returns an id and charge information, and currently has a free pricing caveat that may change. It does not cover auth or rate limits, but with annotations declaring non-destructive and open-world behavior, this is sufficiently transparent.

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 three short sentences, front-loads the core operation, and includes only relevant context about async behavior, next-step retrieval, and pricing. There is no wasted wording.

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?

Given the output schema, full input-schema coverage, and annotations, the description provides the key flow an agent needs: this is an async task, results are retrieved with get_face_detection_results, and charge information is returned. Nothing essential for correct invocation 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 fully documents the nested asset path and confidence_score parameters. The description only implies image or video input and does not add parameter-level detail beyond the schema, making the baseline score of 3 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 a specific verb and resource: it starts an asynchronous face-detection task for an image or video and returns an id plus charge information. It also differentiates the tool from its retrieval sibling, get_face_detection_results, so an agent can identify its role 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?

The description gives explicit usage context: use before a selected-face swap, then retrieve results with get_face_detection_results. It does not list cases where detection should be skipped, but it clearly names the relevant workflow and the follow-up 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 already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds genuinely new behavior: 1 credit per edit, output size tied to subscription tier, and asynchronous execution returning a project id. It stops short of failure modes or what happens if no face is detected, which keeps it off a 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?

Three short sentences, front-loaded with what the tool does, then cost, then the async return contract. Every sentence carries information an agent needs and none repeats structured fields.

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?

Given an output schema exists, the description needn't explain return values, and it correctly limits itself to cost, tier-dependent sizing and the follow-up call. For a nested 3-parameter generation tool this is nearly complete; only the input asset expectations and failure handling are left implicit.

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 every style field carries its range, increment and meaning in the schema itself. The description's 'numeric controls' framing adds a little orientation but no semantics beyond what the schema documents, 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?

States a specific verb ('adjusts'), resource ('facial expression, pose and gaze in a supplied photo') and mechanism ('numeric controls'). This clearly separates it from identity-swapping siblings like swap_face_in_photo or change_clothes_in_photo without needing to open a 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?

The description gives workflow context ('Starts a background job; returns a project id for wait_for_image_project'), which is useful, but never states when to choose this over edit_image, swap_face_in_photo, or swap_head_in_photo. Usage is implied by the verb rather than guided.

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?

Adds real context beyond annotations: credit consumption, an async-style project id consumed by wait_for_image_project, and plan-gated model availability including the default model. It stops short of stating what happens on failure, whether credits are refunded, or how long the project takes.

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 core action and the sibling contrast, then cost, then follow-up tool, then plan caveat. No sentence is wasted.

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 an output schema, full annotations, and 86% parameter coverage, the description covers the agent-critical gaps: cost, the async handoff tool, and plan-dependent model choice. The missing piece is guidance on how this general editor relates to the specialized edit_* siblings.

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 86% and the model/resolution enums already document tier availability and per-model resolution limits, so the schema carries the parameter burden. The description's note that the default model is not on every plan adds a little meaning but largely restates the schema's tier lists.

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 ('Edits one or more supplied images using a text prompt') and immediately contrasts with the closest sibling, generate_image, for prompt-only creation. An agent can tell this apart from generate_image without reading either 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?

Explicitly routes prompt-only work to generate_image and points to wait_for_image_project as the follow-up. It does not say when to prefer this general editor over the many specialized siblings (edit_face_in_photo, change_clothes_in_photo, remove_image_background, upscale_image), leaving that boundary 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 readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds material context beyond that: it is a background job, it costs credits, and it emits a project id consumed by wait_for_video_project. Only failure/retry and rate-limit behavior are left unstated.

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, no filler, with the core action stated first and the operational consequences (credits, async job, follow-up tool) second. 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?

With 7 params including nested objects, an output schema, and full annotations, the description covers the main operational concerns: cost, async lifecycle, and the companion wait tool. The remaining gap is sibling disambiguation against restyle_video and replace_character_in_video, which matters given how many near-identical video tools exist.

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 high (86%), so the schema already documents model tier defaults, resolution constraints, and end_seconds duration limits per model. The description only echoes the required inputs at a high level and adds no meaning about start_seconds, model selection tradeoffs, or the assets path format.

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 and resource ('Edits the appearance or content of a supplied video segment using a text prompt'), which is far more informative than the title 'Edit video'. However, it never distinguishes this tool from close siblings like restyle_video, replace_character_in_video, or translate_video, whose scopes overlap with 'appearance or content'.

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 second sentence ('Use with a source video, the requested changes and the clip end time') restates the required inputs rather than saying when to reach for this tool instead of a sibling. The one genuine routing hint is that it 'returns a project id for wait_for_video_project', which is a useful workflow step but not a use-case exclusion.

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 read-only/non-destructive; the description adds real context: the 8 MiB ceiling, the smaller max_bytes option, and the HTTPS-at-media-host prerequisite. It does not describe failure behavior when the host or URL is wrong, so it is not a 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?

Four short sentences, front-loaded with the capability, then the URL requirement, then the size limit and fallback. Nothing is repeated from the 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 say the return is inline MCP audio content, and it covers the size limit, URL form, and transport requirement. A mention of what happens when the project isn't finished would make it 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?

Schema coverage is 0%, so the description must carry both parameters, and it does: download_url must be the exact signed URL including query parameters, and max_bytes is framed as a size cap against the 8 MiB default. Neither param is left to guesswork.

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+resource: fetch a completed project's audio as inline MCP audio content. That distinguishes it cleanly from the image/video download siblings by the resource type, though it never names those siblings explicitly.

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 usable conditions: works for compatible clients, needs HTTPS on the configured media host, and explicitly says to use the signed URL directly for files larger than the cap. It stops short of stating when not to use it versus fetch_image_download/fetch_video_download, but those are obvious.

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?

Adds meaningful behavior beyond the annotations: HTTPS media-host requirement, inline-content delivery, an 8 MiB cap or smaller max_bytes, and a fallback for larger files. These constraints materially affect whether the tool can be used successfully.

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 primary action, then constraints and fallback. No sentence is wasted.

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, so the description appropriately explains the return as inline MCP image content. Combined with annotations covering safety and the description covering usage limits and parameters, an agent has everything needed to call it correctly.

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 0% schema description coverage, the description carries the full burden and does so effectively: download_url must be the exact signed URL including query parameters, and max_bytes controls a cap no larger than 8 MiB. Both parameters gain actionable meaning beyond their bare schema types.

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 ('Fetch a completed project's image') and specifies the mechanism ('inline MCP image content'). This clearly distinguishes it from fetch_video_download and fetch_audio_download without naming them.

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 operational guidance: use the exact signed URL including query parameters, and use the URL directly for files larger than the inline limit. It does not explicitly name sibling alternatives, but the when-to-use conditions are sufficiently 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 already declare readOnlyHint, destructiveHint=false and openWorldHint=false, so the description's added context is what earns credit: the HTTPS/Magic Hour media host requirement and the 8 MiB ceiling with fallback. It does not mention auth requirements beyond the signed URL or failure modes for expired signatures.

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 what the tool returns, then how to call it, then constraints, then the escape hatch. No sentence is redundant with another.

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 two-parameter fetch tool with no output schema, the description covers return shape (embedded binary resource), host/transport requirement, and size limit. Only the error/expiry behavior is left implicit, which is a small gap.

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 burden and does so for both parameters: download_url must be the exact signed URL including query parameters, and max_bytes caps the payload below the 8 MiB default. Minor gap: no guidance on what happens if max_bytes exceeds the actual file size or on URL expiry.

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 ('Fetch a completed project's video') plus the delivery mechanism ('embedded MCP binary resource for compatible clients'), which distinguishes it from sibling fetchers like fetch_image_download and fetch_audio_download. An agent can tell what it gets back 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 concrete invocation guidance ('Use the exact signed download URL, including query parameters') and an explicit alternative for the oversized case ('Use the signed URL directly for larger files'), plus a client-compatibility caveat. It stops short of naming sibling tools or stating preconditions such as project completion state.

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 it is a non-read-only but non-destructive, open-world operation; the description adds material context beyond that: a 50-credit cost, asynchronous execution, and the single-face precondition that causes failures. It does not cover failure modes beyond the face constraint or credit-refund behavior, 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?

Two short sentences, zero filler, with the core action and input constraint front-loaded and cost plus async follow-up in the second sentence.

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?

An output schema exists, so return values needn't be detailed, yet the description still flags the project id and the wait_for_image_project follow-up, plus cost and the async model. Complete enough to invoke correctly; only failure/error handling is unaddressed.

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 67%, so most parameter meaning already comes from structured fields. The description reinforces the one-face requirement on assets and gestures at 'optional appearance instructions' (the style.prompt object) but doesn't name parameters or clarify the default naming behavior, adding only marginal value over 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?

States a specific verb and resource ('Creates a headshot') plus the key input constraint ('from a supplied photo containing one detectable face') and the optional style customization. That distinguishes it from generic siblings like generate_image or edit_image without naming them, so it stops just short of a 5.

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 context for use plus a concrete routing instruction: it starts a background job and returns a project id 'for wait_for_image_project', which tells the agent exactly which sibling to chain. It does not say when to prefer a sibling such as swap_head_in_photo or edit_face_in_photo instead, so no explicit exclusions.

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 and destructiveHint=false, so the safety profile is covered, and the description adds two genuinely new facts: the operation consumes credits and it is asynchronous, returning a project id to poll. It stops short of covering tier requirements or failure behavior, but that is a modest gap.

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, both front-loaded with the highest-value facts (what it makes, what it costs, what it returns) and no redundant restatement of the schema.

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 an output schema present and a fully documented parameter schema, the description only needs to cover cost and the async handoff, both of which it does. Nothing an agent needs to call it 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 coverage is 100%, with the model, resolution, and style enums exhaustively documented in the schema itself. The description only summarizes ("model, output size and image count options") without adding syntax or trade-off detail beyond the schema, which is the expected baseline.

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 opens with a specific verb+resource ("Generates one or more images from a text prompt") and the phrase "from a text prompt" implicitly separates it from sibling editing tools like edit_image and upscale_image. It also names the downstream sibling wait_for_image_project, so an agent understands the tool's position in the pipeline.

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 supplies useful context ("Costs credits", follow-up via wait_for_image_project) but gives no explicit when-not-to-use guidance or mentions of overlapping siblings such as generate_headshot or create_meme. Usage is implied rather than stated.

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 the mutation/safety profile (readOnlyHint=false, destructiveHint=false), and the description adds genuinely new context: a credit cost of 1 per requested second and that the call is asynchronous, returning a project id. It does not say whether a failed generation still burns credits or how long generation typically takes, which keeps it from a 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 compact sentences that front-load the purpose, then cost and the next-step tool. Every clause carries information an agent would otherwise have to guess.

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?

An output schema exists, so return shape need not be spelled out; the description covers capability, cost, output mode, and the natural next call. For a 3-parameter nested tool with annotations, nothing essential to correct invocation 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 coverage is 67% and the description adds real meaning beyond the fields: it clarifies the credit-per-second relationship to duration and reinforces the lyrics/instrumental interaction. It leaves the nested `style` object's structure and duration bounds to the schema, so it complements rather than substitutes.

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 ('Generates music') plus the input modality ('from a description') and the two output modes (custom lyrics vs instrumental-only). This clearly separates it from the many image/video siblings and aligns with the audio-project siblings like wait_for_audio_project and get_audio_project.

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 explicitly routes the agent to the follow-up tool ('returns a project id for wait_for_audio_project'), which is genuine when-to-use-next guidance. It stops short of naming when to prefer a sibling (e.g., create_video_from_audio for reuse of existing audio), so it falls shy of full alternatives coverage.

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 description's "Read-only" restates rather than adds. It contributes the useful negative scoping but says nothing about auth requirements, failure modes, or whether the balance is live versus cached.

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 tight sentences: the first front-loads what is returned, the second carries usage and exclusions. No filler, no repetition of the 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 an output schema present, the description needn't enumerate return fields, and with zero parameters the call surface is trivially complete. A brief note on authentication state or staleness of the balance would make it fully self-contained.

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 and the baseline of 4 applies. The text correctly implies a no-argument call scoped implicitly to the connected account.

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 (returns) with the exact resources: credit balance and subscription details for the connected account. It also explicitly delimits scope by ruling out a cost quote or model-eligibility check, which separates it from any lookalike accounting 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?

Gives a concrete when-to-use ("inspect account information before generation") and explicit when-not ("not a request-specific cost quote or model-eligibility check"). It stops short of naming the sibling tool an agent should call instead for a cost quote, leaving that inference to the caller.

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 establish that the tool is read-only, non-destructive, and closed-world. The description adds useful behavioral detail by explaining that the response includes status and, only once complete, download URLs, though it repeats the read-only fact and omits error or polling behavior.

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 with no wasted words. The return behavior is front-loaded, followed by the usage context and safety reminder.

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 one fully described parameter, rich annotations, and an output schema, the description is largely complete for an agent to invoke the tool correctly. The main missing context is how this tool relates to the closely named wait_for_audio_project and fetch_audio_download siblings.

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 schema already explains that id is the unique audio project ID returned by audio-creating POST APIs. The description's mention of the id from an audio create tool adds only slight emphasis beyond the schema, so the baseline 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 a specific verb and resource: it returns an audio project's status and, once complete, download URLs. It is clear what the tool does, but it does not explicitly distinguish itself from the sibling wait_for_audio_project or fetch_audio_download tools.

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 says to use the tool to check progress with the id from an audio create tool, giving clear usage context. However, it does not state when to prefer wait_for_audio_project or fetch_audio_download instead, so alternatives remain 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 and destructiveHint=false, so the safety profile is covered upstream. The description still adds genuine behavioral context beyond them: results are eventually consistent ("faces may populate while processing"), which implies an agent may need to re-poll rather than trust an empty first response.

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, zero filler. The resource and return shape come first, the workflow and consistency caveat second, which is the right ordering for an agent scanning for relevance.

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?

Single-parameter read tool with an output schema, so return-value detail is correctly omitted, and annotations cover safety. The description covers the remaining essentials: where the id comes from, what the call is for, and that results may still be populating.

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 an example and a linked doc, so the schema already does the heavy lifting and the baseline is 3. The description earns one above baseline by tying the id's provenance to the sibling tool detect_faces, making the origin of the value actionable rather than just documented.

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?

"Returns a face-detection job's status and detected faces" gives a specific verb (returns) plus two concrete resources (job status, detected faces). It is clearly distinguishable from the sibling detect_faces (which starts the job) and from the swap tools that consume its output.

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 states the prerequisite chain explicitly: use the id from detect_faces, and use it to inspect progress before a selected-face swap. That is strong when-to-use guidance tied to a real workflow. It stops short of naming any when-not-to-use case or an alternative tool for the same result, so not 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 cover the safety profile, yet the description still adds useful behavior: the response carries status, and download URLs only appear once the project completes. That conditional-result detail is not obvious from the schema. The closing 'Read-only' merely repeats readOnlyHint.

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 return behavior and followed by the usage cue. The trailing 'Read-only.' is wasted space given the annotations.

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?

An output schema exists, so return values need no explanation, and the description still flags the conditional availability of download URLs. What's missing is only the polling-versus-blocking guidance relative to its wait_ sibling.

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 there is a single required id, so the schema already documents it fully. The phrase 'id from an image create tool' restates what the schema property description already says about POST APIs returning the value.

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 ('Returns an image project's status') and the payload once complete. It implicitly distinguishes the polling tool from the blocking sibling, but never names wait_for_image_project or fetch_image_download, so an agent must infer the split.

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?

'Use to check progress with the id from an image create tool' gives a clear context of use and identifies where the id comes from. It stops short of the key routing decision — when to poll this versus blocking on wait_for_image_project.

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?

With readOnlyHint=false and destructiveHint=false the annotations only say 'write, but safe'; the description adds the crucial nuance that no bytes are uploaded and no generation starts here, so the agent understands the actual side effect is only URL generation. It doesn't mention presigned-URL expiry or upload constraints (size, content-type enforcement), which would be the remaining behavioral gaps.

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 action, followed by the when-to-use and the exclusion. Every sentence carries distinct information; no repetition of the title or schema.

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?

An output schema exists, so return values need not be spelled out, and the description still names the two key outputs (upload_url, file_path). Combined with the workflow guidance and the non-mutation clarification, an agent has everything needed to call this correctly.

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 per-field descriptions, enum values, extension pattern and the ordering guarantee all documented in the schema. The description adds only the general notion of 'file-path pairs' and does not extend parameter meaning, so 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?

States a specific verb and resource ('Creates presigned upload URL and file-path pairs for local media') and immediately distinguishes the tool from the many create_* siblings by naming what it does not do ('Does not upload file bytes or start a generation'). An agent can place it correctly 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 an explicit trigger ('Use when a generation needs a file the user has locally'), concrete next steps (upload raw bytes to upload_url, then pass file_path to the create tool), and a negative condition ruling out the most likely misuse. Nothing is left to inference about when to pick this over create_video_from_image or similar.

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 trailing "Read-only." sentence is pure restatement of structured data and earns no credit. What the description does add — that the response carries status first and download URLs only once the job completes — is genuinely useful behavioral context not expressed by annotations, but it's thin for a status/polling tool.

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 what is returned, then how to use it, then a safety tag. Nothing is padded and no sentence is wasted, aside from the redundant read-only line.

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?

This is a simple one-parameter read with full schema coverage and an output schema, so return values need not be explained. The description covers the essentials, though for a status-checking tool it could note whether the call blocks or returns immediately, which is what would separate it from wait_for_video_project.

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 single `id` property is already well documented, including its provenance from the create APIs. The description repeats that provenance ("the id from a video create tool") but adds no format, validation, or failure-mode detail beyond the schema, so 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 states a specific verb and resource ("Returns a video project's status ... download URLs") and clarifies the staged nature of the response. It implicitly positions itself against fetch_video_download (URLs vs. the actual download) and wait_for_video_project, but never names those siblings, so a caller still has to infer the split.

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?

"Use to check progress with the id from a video create tool" gives clear context and even names the source of the required id. It stops short of the 5 bar because it offers no exclusions — notably it never says when to use wait_for_video_project instead of repeatedly polling 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 already declare readOnly/closed-world/non-destructive, and the description adds genuinely new context the agent could not infer: authentication is required, and no eligibility check or credit spend occurs. It does not cover caching or whether the guide content varies over time, but the safety and side-effect profile is fully clear.

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, zero filler. The return payload is front-loaded and the usage rule follows immediately, so an agent gets the gist in the first clause.

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?

An output schema exists, so return structure need not be re-explained; the description only summarizes it. Authentication and non-billing behavior are covered. The one remaining gap is how the returned guide connects back to the sibling execution tools, which the reader must infer.

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 must carry the load for the single `workflow` param. It says 'eight supported Magic Hour workflows', which matches the 8-value enum, but never explains what each choice selects or how to choose between, e.g., 'image-to-video' and 'video-generator' — the enum values themselves are the only guidance.

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 (returns inputs/steps/examples/criteria for eight Magic Hour workflows) and states the scope explicitly as a planning artifact. The clause 'Use when planning a generation, not to run one' cleanly separates it from every create_*/generate_* sibling in the list.

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?

'Use when planning a generation, not to run one' gives an explicit when and when-not with the exclusion stated directly. It stops short of naming the concrete siblings to call afterwards (e.g. create_video_from_text), so the routing is implied rather than spelled out.

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 and destructiveHint=false, so the description does not need to restate safety; instead it adds real behavioral value the annotations lack — the newest-first ordering and the distinction between durable 'assets[].file_path' and 'temporary signed URLs' for preview/download, which signals URL expiry. It stops short of saying how long URLs live.

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 sentences, all load-bearing: scope and ordering first, output-shape guidance second, pagination/safety last. No filler or restatement of the 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?

An output schema exists, so return values needn't be spelled out, yet the description still notes where reusable file paths live and that signed URLs are temporary — exactly the practical details an agent would otherwise get wrong. Nothing needed to call 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 coverage is 100%, so the baseline is 3; the description earns a bump by documenting the cross-field relationship between the response's next_cursor and the cursor parameter, which the schema alone does not convey.

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 (lists) and resource (saved items), enumerates the five item types returned, and specifies ordering ('newest first'). No sibling tool lists saved items, so this is unambiguous against the surrounding generate/edit/fetch tools.

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 operating context: read-only, newest-first, and explicitly how to paginate ('pass next_cursor as cursor for the next page'). It does not name an alternative tool or state when-not to use this one, which keeps it below 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 and destructiveHint=false, and "makes no media or project changes" reinforces that without contradicting it. The genuinely additive content is the negative scoping: it does not verify credentials or account access, which no annotation conveys.

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, both front-loaded with the core purpose first and the caveat second. Nothing padded and nothing repeated beyond the single reinforcing clause about no changes.

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-parameter health check with full annotation coverage and an output schema, the description covers purpose, the when-to-use case, and the key limitation (no auth validation). Nothing an agent needs in order to call it 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?

Zero parameters, so the schema has nothing to document and the baseline of 4 applies. The description correctly says nothing about parameters, which 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?

States a specific verb and resource: checks server reachability. Against a sibling list that is entirely media-generation/management tools, this is unmistakably a health-check utility, so no sibling confusion is possible even without naming alternatives.

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?

"Use for connectivity troubleshooting" gives a clear when-to-use condition, and "does not validate API credentials or account access" rules out a plausible misuse. It stops short of naming the correct alternative (e.g., get_account_info) for credential checks, leaving the agent to infer it.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real context beyond that: credit cost scales with resolution (from 50 credits at 640px) and the call returns a project id rather than a finished image, implying asynchronous work. It does not mention rate limits or failure modes, which keeps it from a 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 tight paragraphs with no waste. The compliance restrictions are front-loaded before the operational description, which is defensible for a tool with likeness/consent risk, though an agent scanning for 'what does this do' has to read past them first.

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 nested-parameter, enum-bearing tool with an output schema, the description covers what it does, the cost implication of one required parameter, the async handoff to wait_for_image_project, and the policy constraints. The only soft spot is the absence of any hint about what the resulting image contains or how assets are uploaded, though the schema's file-path docs handle the latter.

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. The description earns an extra point by explaining that resolution drives credit cost, which is decision-relevant meaning the schema does not convey. It says nothing extra about the assets or name parameters, but the schema already documents them thoroughly.

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 gives a specific verb and resource: it places a person from one supplied photo into a supplied scene image, and notes the project id it returns. That is concrete enough to separate it from edit_face_in_photo or change_clothes_in_photo by implication, though it never names those siblings directly.

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 context for use (own likeness or authorized content) plus explicit exclusions for impersonation, deception, sexual content, and minors. It also names the follow-up step, wait_for_image_project, which tells the agent how to continue. It stops short of pointing at alternative tools for other editing needs, so it is not a full when-to-use/when-not guide.

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 the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds genuinely new behavioral facts: a 5-credit cost and asynchronous job semantics with a follow-up wait tool. It omits what happens on failure or whether credits are refunded, but the value-add over annotations is substantial.

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 in a tight purpose → cost → next-step order. Every sentence carries an independent, actionable fact with 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?

With an output schema present, the description needn't explain return values, and cost plus the async handoff to wait_for_image_project are the facts an agent most needs. The description is nearly sufficient, though it could note the required image_file_path vs optional background image relationship more explicitly.

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 nested parameters are already fully documented including accepted URL/file_path formats. The phrase "optionally replacing it with another supplied image" usefully signals that background_image_file_path is not required, but adds nothing about format or sizing beyond what the schema states.

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 and resource ("Removes an image's background") and adds the optional replacement behavior, which is more than a restatement of the title. It does not explicitly distinguish itself from adjacent siblings such as edit_image or generate_image, 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?

It gives clear operational context — this kicks off an asynchronous job and hands back a project id for wait_for_image_project — which effectively tells the agent the correct follow-up call. It stops short of stating when to prefer this over generic image-editing siblings or any preconditions on input assets.

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?

Beyond the annotations (readOnly=false, destructive=false, openWorld=true), the description discloses that this is an asynchronous background job, that it consumes credits, and that it returns a project id to poll with wait_for_video_project. That is meaningful context the annotations do not carry; it only lacks detail on failure/validation behavior.

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 sentences, no filler, and the mechanical workflow statement is tight. The safety policy leads the description, which slightly defers the core 'what it does' statement rather than front-loading it, but nothing is wasted.

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 7-param, nested-schema, credit-consuming async tool with an output schema available, the description covers purpose, safety constraints, and the follow-up polling step. Model/point compatibility rules live in the schema and need not be repeated; only alternative-tool routing is absent.

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 documents all 7 parameters, including the model-specific replace/animate constraints. The description adds no parameter-level detail beyond what the schema provides, so the baseline 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?

States a specific verb+resource ('Replaces a subject in a video with a character from a reference image') and describes the alternative 'animate' mode (motion transfer). It does not name the closest siblings (swap_face_in_video, place_person_in_scene, restyle_video), so the agent must infer differentiation from the mode wording alone.

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 when-not guidance via the policy sentence (only own likeness/authorized content; no impersonation, deception, sexual content, minors) and tells the caller what happens next (background job, credits, project id for wait_for_video_project). It stops short of routing to competing tools when the user wants just a face swap or a static scene placement.

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 important behavioral context beyond annotations: it discloses that the operation is a background job, costs credits, and returns a project id to be used with wait_for_video_project. It also notes the v1/v2-only preset limitation. With annotations already covering safety (readOnlyHint=false, destructiveHint=false), this extra context is valuable, though it doesn't detail credit amounts or consequences for the original video.

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 sentences and front-loads the core action, followed by key constraints (version support, background job, cost, follow-up tool). Every sentence contributes useful information without 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?

Given the tool's complexity (nested objects, six parameters) and the presence of an output schema, the description covers the essential context: async behavior, cost, and the follow-up wait tool. It doesn't explain the fps_resolution trade-off or asset sourcing, but those are well documented in the schema, so the description is nearly complete for an agent to call it correctly.

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 high (83%), so the schema already documents most parameters in detail. The description mentions art-style presets and custom prompts, which loosely maps to the style object, but adds no further syntax or constraints beyond what the schema provides. A baseline 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 a specific verb and resource: 'Restyles an existing video clip with an art-style preset or a custom prompt.' It names the supported preset versions and explicitly excludes v3, which helps an agent distinguish this from sibling tools like edit_video or translate_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 clearly states that the tool starts a background job, costs credits, and returns a project id for wait_for_video_project, giving the agent essential follow-up guidance. However, it doesn't explicitly compare against alternative sibling tools (e.g., edit_video or upscale_video) or state when-not to use this tool beyond the v3 limitation.

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 readOnly=false, destructive=false, openWorld=true; the description adds materially useful behavior: a fixed 10-credit cost, subscription-dependent output size, and a returned project id intended for wait_for_image_project (async job pattern). Not covered: whether credits are refunded on failure, expected job duration, or the output artifact format — though the output schema covers the return 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?

Two short paragraphs with zero filler: policy guardrails, then mechanics (cost, output, next step). The core action is stated only after the policy preamble, which slightly buries the purpose, but the total length is well matched to a tool of this complexity.

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?

Given an output schema and 100% schema coverage, the description supplies what the structured fields cannot: cost, subscription-dependent sizing, the async follow-up call, and legal/ethical restrictions. An agent can select, invoke, and continue the workflow from this description plus the schema.

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 nested assets object (face_swap_mode enum, face_mappings, source_file_path, target_file_path) is fully documented inline, so the baseline is 3. The description's phrase 'source face image or selected face mappings' echoes the schema's two modes without adding format or constraint detail.

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 ('Swaps faces in a supplied photo') plus the two input modes (source face image or face mappings), which is far more than the title alone. It does not distinguish itself from close siblings such as edit_face_in_photo, swap_head_in_photo, or swap_face_in_video, so an agent must infer the photo-vs-video split from the name.

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 first paragraph sets hard usage constraints (own likeness only; no impersonation, deception, sexual content, or minors), and the second names the follow-up tool (wait_for_image_project), effectively documenting the workflow. However, it gives no guidance on when to pick this over alternatives like edit_face_in_photo or swap_head_in_photo, and the exclusions are content policy rather than tool-selection guidance.

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?

Adds substantial context beyond the annotations: it is asynchronous (starts a background job), it consumes credits, and it returns a project id that must be fed to wait_for_video_project. It does not disclose limits such as max clip length or failure/refund behavior, which matters for a paid async job.

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 paragraphs with no filler: policy first, then mechanics. The policy block is slightly long relative to the operation description, but every sentence carries information the agent must respect.

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?

Output schema exists so return values need no explanation, and the description still correctly flags chaining to wait_for_video_project. The only gap is operational detail (job duration, credit amount, clip-length limits) for a paid, open-world operation.

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 description only needs to add value. It does reinforce the mutual exclusivity of the two face_swap_mode branches, but that is already stated in the schema, so this lands at the baseline.

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+resource (swaps faces in an existing video) and enumerates the two operating modes (all faces via reference image, or selected faces via detect_faces results). The 'video' scope cleanly separates it from swap_face_in_photo and swap_head_in_photo in the sibling list.

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 states when NOT to use it (impersonation, deception, sexual content, minors) and the authorization requirement, and points to detect_faces results as the prerequisite for the individual-faces path. It does not say when to prefer swap_face_in_photo or replace_character_in_video, so routing between siblings is only partially covered.

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?

Beyond the annotations (which only confirm it is a non-destructive write with open-world scope), the description discloses two critical traits: the operation costs 10 credits and it is asynchronous, returning a project id that must be polled via wait_for_image_project. The content-policy constraints add further behavioral context the annotations do not carry.

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 tight paragraphs: the safety/authorization constraint is front-loaded, then the mechanics (swap, cost, return value). Every sentence carries 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 an async, credit-consuming image mutation tool, the description covers purpose, cost, required follow-up workflow, and usage restrictions, while the input schema fully documents parameters and an output schema exists to describe return values. Nothing an agent needs in order to call it 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%, and each of the three parameters (name, nested assets paths, max_resolution) is fully documented in the schema with examples and format rules. The description adds no parameter-level meaning, which is acceptable given the schema does the heavy lifting, so 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 gives a concrete verb and resource: it 'swaps a head from a supplied image onto a supplied body image', which is clearly more specific than the title. It does not explicitly distinguish itself from close siblings such as swap_face_in_photo, edit_face_in_photo, or place_person_in_scene, so an agent must infer the head-vs-face distinction.

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 states clear when-not conditions ('Do not use for impersonation, deception, sexual content, or content involving minors') and a required authorization precondition regarding likeness rights. It also directs the agent to the follow-up call ('returns a project id for wait_for_image_project'), though it never names a sibling alternative for face-level edits.

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 it is non-read-only, non-destructive and open-world. The description adds genuinely new behavioral facts: it launches a background job, consumes credits, and hands back a project id consumed by wait_for_video_project. That is real transparency beyond structured fields, though cost amount and failure behavior are unstated.

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 what the tool does, followed by the workflow and cost implication. Nothing is redundant with the title or name.

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 an async job-creating tool with an output schema and rich parameter docs, the description covers the essentials an agent needs: it is a background job, it costs credits, and it requires a wait step. It omits any note on failure modes or what happens if the segment is outside limits, but the core is 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?

Schema description coverage is 100%, so file paths, resolution tiers, clip length limits and the language enum are already fully documented in the schema. The description adds no parameter-level detail beyond what is there, 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?

States a specific verb and resource ('Translates speech in a supplied video segment') and scopes it to a segment rather than a whole file. It does not explicitly differentiate itself from the similar sibling add_subtitles_to_video, which keeps it from a 5.

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 names the follow-up step ('returns a project id for wait_for_video_project') and flags that it costs credits, which implies an async workflow. It never says when to choose this over alternatives such as add_subtitles_to_video or edit_video, so usage is only implied.

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 flag it as a non-read-only, open-world operation, and the description adds genuinely new context: credit cost range (25-200) tied to scale and mode, and that it returns a project id rather than a finished file. It does not mention the tier restriction on 4x or failure modes, keeping it below a 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, no filler, with the core operation front-loaded and the async handoff stated after it. 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?

Output schema exists and the rich input schema covers parameters, so the description's job is mostly routing and cost signaling, both of which it does. It stops short of noting the Creator+ tier requirement for 4x or typical processing time, small residual gaps for a paid async job.

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 mode enums, the 2/4 scale constraint, the 4096px input limit, and credit multipliers are all already documented in the schema. The description only restates the 2x/4x option without adding syntax or defaults, so 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?

States a specific verb (upscales), resource (image), and constraint (2x or 4x), which cleanly separates it from upscale_video and the many create_* siblings. An agent can identify the operation 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?

The description implies the use case (make an image larger/higher resolution) and points to wait_for_image_project for the async follow-up, but never states when to prefer this over edit_image or generate_image, nor any preconditions for input assets. Usage is inferable but not spelled out.

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?

Goes beyond the annotations by disclosing that the operation is asynchronous and consumes credits — neither is inferable from readOnlyHint=false/destructiveHint=false/openWorldHint=true. It stops short of stating whether credits are refunded on failure or any rate limits.

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, zero waste: the what/how comes first, then the async-plus-cost-plus-next-step facts. Nothing is repeated from the schema or annotations verbatim.

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?

An output schema exists, so return values need not be explained, and the description covers the async lifecycle, cost, and the follow-up tool. The remaining gap is failure/timeout behavior and credit refund policy, which matter for a paid async job.

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 resolution enum semantics (short side vs long side), clip start/end, and video_file_path formats. The description adds only a light restatement ('selected output resolution', 'segment') — baseline 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?

States a specific verb ('Upscales') and resource ('a supplied video segment') plus the key outcome (preserving aspect ratio, selected output resolution). The 'video' resource cleanly separates it from the sibling upscale_image without needing to name it.

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 says it starts a background job and returns a project id 'for wait_for_video_project', which routes the agent to the correct follow-up tool. It does not discuss when to prefer upscale_video over restyle_video or edit_video, so the alternative-selection guidance is only partial.

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?

Goes well beyond the readOnlyHint/non-destructive annotations by disclosing polling semantics, timeout/resume behavior, the 8 MiB aggregate inline-download cap, and the requirement to use signed URLs verbatim (a real auth/side-effect signal). This is exactly the kind of 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?

Four tight sentences, front-loaded with the core behavior and terminal states, followed by usage, return content, and constraints in a sensible order. Dense but no filler; only the signed-URL sentence sits slightly apart from the main flow.

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 and 0% param coverage, the description does most of the work: it names return values (project and download URLs), the inline preview option and its size limit, and the timeout/resume contract. Missing only explanations of the polling interval and inline-download count knobs.

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 6 params, so the description must compensate. It clarifies the `id` source, implies `timeout_seconds`, and covers the inline-download byte cap, but leaves `poll_interval_seconds`, `max_inline_downloads`, and `include_inline_downloads` unexplained.

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 ('Polls an audio project') plus the terminal conditions (completes, errors, canceled, times out). It implicitly distinguishes itself from the single-shot get_audio_project sibling via the polling behavior, but never names that sibling directly.

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 preconditions ('Use with the id returned by an audio create tool') and an explicit recovery rule ('After a timeout, resume with the same id rather than creating another generation'). It does not explicitly say when to prefer get_audio_project over this polling tool, leaving one gap.

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/non-open-world, yet the description still adds genuine value: it says what is returned (project plus download URLs), that inline previews are optional and share an 8 MiB total budget, and that signed URLs must be used verbatim. Minor tension: the schema's per-download default is also 8 MiB, so the 'total limit' phrasing could be misread, but this is not an annotation 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 tight sentences, each doing distinct work: purpose/terminal states, required id provenance, return payload plus limits, and timeout recovery. Front-loaded with the polling behavior before operational caveats — 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?

No output schema exists, and the description does cover the return payload and timeout behavior, which is the most important gap. However, for a six-parameter polling tool the tuning parameters (interval, caps, per-byte limit) remain entirely undocumented anywhere, leaving an agent to guess at polling cost and preview sizes.

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 six parameters, so the description carries the full burden. It only indirectly touches two of them (timeout via the resume advice, inline downloads via the preview/8 MiB sentence) and never explains timeout_seconds units, poll_interval_seconds, max_inline_downloads, or max_bytes_per_download semantics.

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: 'Polls an image project until it completes, errors, is canceled or times out', with the terminal states enumerated. It does not explicitly distinguish itself from the sibling get_image_project or wait_for_video_project/wait_for_audio_project, so sibling differentiation is left to inference.

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 context: 'Use with the id returned by an image create tool' and a strong recovery rule — after a timeout, resume with the same id rather than creating another generation. It does not name get_image_project as the non-blocking alternative, so the when-not-to-use case is only implied.

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?

Goes beyond the readOnlyHint annotations with real behavioral context: long-polling, terminal outcomes, download URLs on completion, timeout resumption, and signed-URL handling. However, 'Does not inline video content' sits in tension with the include_inline_downloads and max_inline_downloads parameters, leaving the agent unsure whether inlining is possible; that ambiguity needs resolving.

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?

Six short sentences, front-loaded with the core behavior, then the usage constraint, then the caveat. Every sentence carries a distinct rule and none restates the 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?

Adequate for a polling tool with no output schema: the agent knows when it returns and roughly what it returns. But with 0% schema coverage across five parameters and an unresolved inlining contradiction, key call-shaping details are still 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 0% and there are five parameters, yet the description explains only id (implicitly, as the id from a create tool). timeout_seconds, poll_interval_seconds, include_inline_downloads and max_inline_downloads get no mention at all, so an agent must guess at their meaning and defaults.

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 (polls a video project) plus the full terminal-state set (completes, errors, canceled, times out), which cleanly separates it from the single-shot get_video_project and from the fetch_video_download siblings.

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?

Ties the tool to the id returned by a video create tool and gives an explicit recovery rule: after a timeout, resume with the same id rather than creating another generation. It also warns to use signed URLs as returned. It stops short of saying when to poll here versus calling get_video_project for a single status check.

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