Magic Hour

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

With no annotations, the description carries the full burden. It does disclose this is a read operation scoped to the API key's owning account, but says nothing about auth/permission requirements, rate limits, or whether the balance is real-time. Return values are covered by the output 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?

A single front-loaded sentence with zero filler. Every word contributes: verb, both returned resources, and the precise account scope.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only getter with an output schema documenting the response, the description is nearly complete. It could be richer about auth scope, but 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 description coverage is 100%, and the only parameter is a meta 'context' field for analytics, not a functional input. The description adds no parameter meaning, but none is needed, so the basline 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 ('Get') with two concrete resources ('credit balance and subscription details') and names the exact scope ('the account that owns the API key'). This is fully distinguishable from every sibling, which are all media-generation 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?

Usage is implied by the name and the described scope, but the description gives no explicit when-to-use guidance, prerequisites, or alternative tools. For a uniquely-scoped account query with no close sibling, the implied usage is adequate but thin.

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 no annotations provided, the description carries the full burden, and it does so well: it discloses that this is an async job, that it returns `id` and `credits_charged` immediately, the terminal statuses to poll for (`complete`, `error`, `canceled`), that completed projects include `downloads` URLs with expiration metadata, and the 25-credit cost per photo. That is substantial operational context an agent would otherwise have to discover.

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 definition is front-loaded with the value proposition and cost, then organized into bulleted workflow guidance. Every sentence is actionable, though the file-path paragraph is dense and repeats the upload-guide reference twice, which slightly dilutes conciseness.

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, nested-asset, credit-charging tool, the description covers the async job lifecycle, helper-tool routing, status values, output URLs, and asset-preparation prerequisites. The presence of an output schema means return values need not be fully enumerated, so nothing an agent needs to invoke this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining how `*_file_path` values should be sourced: prefer an existing Magic Hour path or the `file_path` from the upload-URL endpoint, and warning that hotlinked public URLs can fail. It does not add detail on the `garment_type` enum or `context` field, which the schema already covers.

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 definition states a specific verb+resource combination ('Change outfits in photos') and identifies the two inputs required: a person photo and a garment reference. This is unambiguously distinct from sibling tools such as face_swap_photo, head_swap, and body_swap, so an agent can select it 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 MCP guidance explicitly routes the agent: 'If the user wants the finished result, call the wait_for_image_project helper with the returned id, or poll the matching GET endpoint.' It also gives clear when-to-use context for file paths (prefer Magic Hour paths; use the presigned upload flow when in doubt). It stops short of contrasting against sibling image tools, so not a full 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?

With no annotations, the description carries the full burden and does so richly: it discloses the per-edit cost (1 frame), subscription-dependent output dimensions, the immediate return of id plus credits_charged, the terminal statuses to poll for, that completed projects include downloads with direct URLs, and that the wait helper's exact_download_urls differ from expiration metadata. These are exactly the behavioral traits an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and cost, followed by operational guidance in compact bullets. Slightly long, but each section (async flow, file path handling) earns its place; no filler sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be re-explained, and the description complements it by covering the async lifecycle, the cost model, and asset-provisioning caveats. Given a noisy 40+ sibling namespace with no annotations, this is complete enough 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 baseline is 3. The description adds genuine meaning beyond the schema for `assets.image_file_path`: it warns that hotlinked public URLs can fail and that the presigned upload flow should be used when in doubt. It adds little about the `style` sub-parameters, which the schema already documents 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?

States a specific verb+resource: 'Edit facial features of an image using AI.' This is clearly distinct from mutation siblings like face_swap_create_video or head_swap_create_image, which replace identities rather than adjust facial pose/expression parameters. It stops short of explicitly naming those siblings to route the agent, so it is clear but not maximally differentiating.

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 MCP guidance gives concrete usage context: this starts an async job, and for results call wait_for_image_project or poll the GET endpoint until complete/error/canceled. It also advises using the presigned upload flow for file_path values. It does not, however, state when to prefer this over sibling editors such as ai_image_editor_create_image or face_swap_photo_create_image.

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 no annotations, the description carries the full burden and does so well: it discloses the 50-credit cost, that the call is async and returns `id` plus `credits_charged` immediately, the terminal statuses (`complete`, `error`, `canceled`), and that completed projects expose `downloads`/`exact_download_urls`. This is rich behavioral context beyond structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the essential verb and cost, then organized as labeled guidance. Slightly verbose in the polling detail but every element is actionable rather than 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 generation tool with a nested schema and an output schema already describing return values, the description supplies exactly the missing lifecycle knowledge (async start, polling/wait helper, statuses). Nothing an agent needs to invoke and complete the job 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 75%, so the schema largely documents the four parameters (name, style.prompt, context, output_format). The description adds no parameter-level meaning, 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 ('Create an AI GIF') and the GIF-specific scope cleanly separates it from siblings like ai_image_generator_create_image and text_to_video_create_video. An agent can identify what it produces 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 clear operational guidance for the async workflow and explicitly names the follow-up alternative (`wait_for_image_project`) versus manual polling of `GET /v1/image-projects/{id}`. It does not, however, explain when to choose this GIF generator over other generation siblings, so it stops short of full when/when-not 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?

No annotations are provided, so the description carries the full burden. It discloses that this starts an async job, returns 'id' plus 'credits_charged' immediately, what the terminal statuses are ('complete', 'error', or 'canceled'), and what completed projects include ('downloads' with direct URLs). It also warns that hotlinked URLs can fail. This is rich, non-obvious behavioral context.

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 front-loaded with the core action and cost, which is good. However, the MCP guidance section is quite dense and mixes workflow instructions with file-path advice; it could be structured more crisply. It's not excessively wordy, but the second bullet is a long block of text that requires careful parsing.

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 that an output schema exists (so return values needn't be fully explained), the description still covers the async lifecycle, the polling/waiting behavior, and the file-path sourcing rules. Combined with the schema and output schema, an agent has everything needed to call this correctly and handle the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 75%, so the schema already defines most parameters well. However, the description adds critical operational context for the 'assets' parameter's 'image_file_path' value ('prefer an existing Magic Hour file path or a file_path returned by the upload-URL endpoint... when in doubt, use the presigned upload flow first'), which goes beyond the schema's field-level description. This compensates for the remaining coverage gap and adds real 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?

The description states a specific verb and resource ('Create an AI headshot') and discloses cost (50 credits). It distinguishes itself from siblings like ai_image_generator_create_image by being headshot-specific, but it doesn't explicitly contrast with the nearest sibling, like ai_face_editor_edit_image. Clear purpose, but sibling differentiation relies on domain knowledge.

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 MCP guidance explicitly describes the async workflow and routes the agent to the right helper ('call the wait_for_image_project helper with the returned id, or poll the matching GET /v1/image-projects/{id} endpoint'). It also gives clear rules for when to use the presigned upload flow versus direct URLs. This is actionable when/when-not guidance for a complex workflow.

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 no annotations, the description carries the full burden and does so well: it discloses that the call is asynchronous, immediately returns id and credits_charged, enumerates the terminal statuses, and notes that completed projects expose downloads with direct URLs and that the wait helper surfaces exact_download_urls separately from expiration metadata. It stops short of covering auth requirements, rate limits, or why hotlinked URLs fail beyond a general warning.

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 structure is front-loaded and scannable: a one-line purpose followed by two labeled bullets separating the async lifecycle from file-path rules. It is slightly verbose in the second bullet, but every clause (presigned upload fallback, raw-bytes requirement, hotlink failure risk) carries 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?

For an 8-parameter nested tool with an output schema, the description supplies the operational context an agent actually needs to run the async flow correctly, so return-value details are appropriately left to the output schema. The remaining gap is selection context: nothing tells the agent when this general editor is the right choice versus the more specific editing tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 88%, so model, resolution, aspect_ratio, image_count, and the assets shape are thoroughly self-documented. The description reinforces the *_file_path sourcing rule (prefer an existing Magic Hour path or an upload-URL file_path) but adds little the schema does not already state, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opener gives a clear verb+resource ('Edit images with AI'), so the agent knows this mutates an existing image rather than generating one from scratch. However, it offers no differentiation from the many adjacent siblings (ai_face_editor, ai_clothes_changer, ai_image_upscaler, ai_image_generator), leaving the agent to infer scope from 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 guidance block explicitly describes the post-call workflow — call wait_for_image_project with the returned id, or poll GET /v1/image-projects/{id} until a terminal status — and prescribes the presigned upload flow when unsure about file paths. That is real when/how guidance for the async flow, but there is no guidance at all on choosing this tool over its image-editing 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?

With no annotations, the description carries the full burden and does so well: it discloses that the call is asynchronous, returns id plus credits_charged immediately (cost signal), lists the terminal statuses (complete, error, canceled), and states that completed projects include download URLs with expiration metadata. This is exactly the behavioral context an agent needs.

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 short and front-loaded: one purpose sentence followed by a tight async-handling block. It is dense but every sentence serves a purpose; the only minor cost is that the guidance block is slightly prose-heavy for what could be a shorter instruction.

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-generation tool with rich schema, nested objects, and an output schema, the description covers the remaining unknowns: async nature, immediate return shape, follow-up path, and terminal states. Nothing needed to invoke or follow up correctly appears 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 documents every parameter including the verbose model/resolution tables. The description adds only 'model selection and quality controls,' which adds no syntax or format detail 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?

The description states a specific verb and resource ('Create an AI image') plus a scope note about model selection and quality controls. It does not explicitly differentiate itself from the many sibling image-generation tools (ai_image_editor, ai_image_upscaler, ai_meme_generator), but the generic framing implies a general-purpose generator.

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 guidance block gives explicit next-step routing: if the user wants the finished result, call wait_for_image_project with the returned id or poll the GET endpoint until a terminal status. It names the sibling and the condition. It does not, however, say when to prefer this general generator over the specialized image 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?

With no annotations, the description carries the full burden and does so well: it discloses async job semantics, that it returns id plus credits_charged immediately, terminal statuses, and that completed projects carry downloads URLs. It does not state auth/permission requirements, but credit cost and async lifecycle are the higher-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?

Front-loads purpose and cost, then a clearly delineated 'MCP guidance' block. Efficient, though the credit-cost enumeration in the first paragraph is somewhat verbose relative to the schema's own mode descriptions.

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 and the description still explains the async completion model, polling targets, and returned fields, which is exactly what an agent needs to sequence this call with wait_for_image_project. Nothing material is missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, and the description goes beyond it by clarifying the credit multiplier relationship between mode and cost, and by explaining how *_file_path values should be sourced. This adds semantic value the schema alone does not connect.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence gives a specific verb (upscale) plus resource (image) and immediately pairs it with concrete cost behavior. It is unmistakable against siblings like ai_image_generator_create_image or ai_image_editor_create_image, since upscaling is the distinct operation.

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 this is an async job and names the exact follow-up path ('call wait_for_image_project with the returned id, or poll GET /v1/image-projects/{id} until status is complete/error/canceled'). It also gives when-to-use guidance on asset sourcing, recommending the presigned upload flow over direct hotlinked URLs.

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 no annotations, the description carries the full burden and delivers well: it discloses the 10-credit cost per meme, that the call is asynchronous, what is returned immediately (id, credits_charged), the terminal statuses to wait for, and that completed projects expose download URLs. Gaps remain around authentication requirements, rate limits, and whether credits are refunded on error/cancel.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and cost, then a clearly delineated guidance block. Sentences are mostly tight, though the polling clause enumerating statuses and the note about exact_download_urls are slightly verbose for the value they add.

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-metered generation tool with an output schema and nested style object, the description covers cost, async semantics, result retrieval, and terminal states. It is close to complete; the only notable omission is any note about permissions or the practical meaning of the large template enum beyond what the schema states.

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 67%, so the schema already documents name, topic, template, and searchWeb itself, including the very large template enum. The description adds no parameter-level meaning (no guidance on topic phrasing or when to enable searchWeb), 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 + resource ("Create an AI generated meme") and adds the credit cost, which is real information not in the name. The meme-specific resource distinguishes it in practice from generic siblings like ai_image_generator_create_image, but the description never explicitly names or contrasts that 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?

The "MCP guidance" block gives concrete usage context: the call is async, it returns immediately, and results are obtained either via wait_for_image_project or by polling GET /v1/image-projects/{id} until complete/error/canceled. It does not state when to prefer this over sibling generators, but the operational guidance is clear and actionable, matching the 4 anchor (clear context, no 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?

With no annotations present, the description carries the full burden and does so well: it discloses async job semantics, immediate return of id and credits_charged, the terminal status values (complete/error/canceled), that completed projects include downloads URLs, and the cost (0 credits). This is the key behavioral trait for an async generation tool and it is fully surfaced.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the purpose in one line, then a clearly delimited MCP guidance block. Efficient overall, though the final sentence about exact_download_urls versus expiration metadata is somewhat niche and only marginally earns its place.

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 image-generation tool with no annotations, the description supplies everything an agent needs to invoke and consume it: the async nature, the follow-up tool, status handling, and return fields. An output schema exists, so the return-value detail is arguably redundant, but nothing required 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 75%, near the baseline threshold, and the schema already documents name, content, style.art_style, and context in detail. The description adds no additional parameter meaning (e.g., format of 'content', how style templates interact with custom values), so the schema does the heavy lifting and 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 ('Create an AI QR code'), which is a distinct resource among the many create_image siblings. However, it never explicitly differentiates itself from tools like ai_image_generator_create_image or ai_meme_generator_create_image, leaving selection to the reader's inference from the name 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?

Provides clear workflow context: it tells the agent this starts an async job and names the concrete follow-up (call wait_for_image_project with the returned id, or poll GET /v1/image-projects/{id}). It lacks guidance on when to choose this QR tool over other image-generation siblings, so it is clear context without 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?

With no annotations present, the description carries the full burden and does so well: it discloses that the call starts an async job, returns `id` and `credits_charged` immediately, enumerates the terminal states, and notes that completed projects carry `downloads` URLs with expiration metadata. It also warns that hotlinked public URLs can fail, a genuine behavioral caveat an agent could not infer from 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?

The purpose is front-loaded in a single line, followed by two tightly scoped bullets covering result handling and file-path handling. It is slightly redundant (it mentions both the wait helper and raw polling of the same endpoint), but 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?

For a 7-parameter nested-schema mutation with an output schema, the description supplies everything an agent needs that structured fields do not: async lifecycle, what the immediate response contains, how to obtain the finished artifact, and how to prepare valid file inputs. Nothing material 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 baseline is 3. The description adds real value on top of that by explaining what a valid `*_file_path` value is and steering the agent to the presigned upload flow when direct URLs are unreliable, which is semantics the schema does not capture.

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 first sentence states a specific verb and resource ("Create a talking photo") and names the required inputs (image plus audio/text), so an agent immediately knows the operation. It does not, however, distinguish itself from the similarly-scoped siblings `lip_sync_create_video` or `image_to_video_create_video`, leaving the agent to infer the difference from the name 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?

The MCP guidance gives clear operational context: this is async, so it tells the agent to call `wait_for_video_project` or poll `GET /v1/video-projects/{id}` until a terminal status. It also gives concrete advice on when to prefer the presigned upload flow over direct URLs. It stops short of any when-not-to-use guidance or explicit routing away from sibling creation tools.

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 no annotations to lean on, the description carries the full burden and does so well: it discloses that this starts an async job returning id plus credits_charged immediately, lists terminal states (complete/error/canceled), explains that downloads contain direct URLs and that the wait helper returns exact_download_urls separately from expiration metadata, and describes the cost model (charged only for rendered frames, estimate at queue time, final total after completion).

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?

Well structured and front-loaded with headers ('What this API does', 'How it works', 'Key options', 'Cost', MCP guidance), so an agent can scan it quickly. It is longer than strictly necessary for a tool definition, with product-page links and marketing phrasing that are only marginally useful, but nothing is egregiously redundant.

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 correctly does not need to spell out return fields, and it fills the genuine gaps instead: the presigned upload prerequisite for *_file_path values, the async job lifecycle, and the wait helper. It stops short of documenting failure handling or whether hotlinked URL failures are recoverable, but the coverage is strong for a tool of this complexity.

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 88%, so the schema already documents nearly every parameter, making 3 the correct baseline. The description adds useful context about input types (file vs YouTube link) and names start_seconds/end_seconds and a text prompt, but its claim that free users are limited to '576px' does not match the 480p/720p/1080p enum, creating minor confusion rather than added precision.

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: programmatically create the same Video Editor available in the browser, with the prompt-driven edit intent conveyed via the style field. It is clear on its own, but it never contrasts itself with the many neighboring video-creation tools (video_to_video_create_video, text_to_video_create_video, character_replace_create_video), so an agent must infer which video sibling applies.

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 'Good for' bullets (automation, batch processing, embedding in apps) and the 3-step workflow imply when this tool fits, and the MCP guidance routes follow-up to wait_for_video_project or the GET endpoint. However, there is no explicit when-to-use versus the other create_video siblings, which is the key selection decision for an agent in this catalog.

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 no annotations, the description carries the full burden and does well: it discloses that this is an async job returning id + credits_charged immediately, the cost model (0.1 credits/character, rounded up), terminal statuses (complete/error/canceled), and file-path failure modes with hotlinked URLs. It omits auth/permission requirements, which is the main 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?

Purpose is front-loaded, pricing follows, then operational guidance. Every sentence is load-bearing and there's no redundancy, though the guidance block is dense enough to slow scanning.

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 async generation tool with an output schema, the description covers the essential call flow, follow-up polling, return fields, and file-path pitfalls. Release/download retrieval is only partially described, but the output schema and wait helper cover the rest.

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 75%. The description adds real meaning beyond the schema: the cost-per-character rule ties to the length of style.prompt, and the MCP guidance explains the accepted forms of the assets.audio_file_path value plus presigned-upload fallback, which the schema only states abstractly.

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+action: 'Clone a voice from an audio sample and generate speech.' The 'from an audio sample' clause implicitly distinguishes it from the plain voice generator sibling, but it never names that sibling explicitly, 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?

The MCP guidance gives useful workflow context (call wait_for_audio_project with the returned id, or poll the GET endpoint) and file-path prerequisites. However, it never states when to choose this over ai_voice_generator_create_audio, so the alternative-selection guidance 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?

With no annotations, the description carries the full behavioral burden and does so richly: it discloses async job creation, immediate return of id and credits_charged, per-character credit cost with rounding, polling statuses (complete, error, canceled), and that completed projects include downloads. Missing auth/rate-limit details are minor given the depth.

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 definition is front-loaded with purpose and cost, then uses a labelled 'MCP guidance' section for the async workflow. It is appropriately sized and every sentence earns its place.

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 described, and the description still explains the async flow and follow-up steps. Given the nested style object and huge voice enum are fully documented in the schema, the description is complete enough.

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 name, style.prompt, style.voice_name, and context. The description adds pricing tied to prompt length but no additional parameter syntax or meaning 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 clear verb+resource: 'Generate speech from text' and clarifies it starts an async audio generation job. However it does not explicitly differentiate from the sibling ai_voice_cloner_create_audio, which also generates audio from text, so sibling differentiation is missing.

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 post-invocation routing: if the user wants the finished result, call wait_for_audio_project or poll the GET endpoint. It does not state when to choose this tool over the voice-cloner sibling, and gives no 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?

With no annotations, the description carries the full burden and does so well: it discloses the async job model, the immediate return of id plus credits_charged, terminal statuses (complete/error/canceled), availability of download URLs, and warns that hotlinked URLs can fail. This is exactly the behavioral context an agent needs before invoking a long-running generation 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?

Front-loads the one-line purpose before the guidance, and the bulleted structure keeps async handling and file-path rules scannable. Slightly verbose, but each guidance block is actionable rather than 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 8-parameter, nested, async generation tool with an output schema already covering return values, the description completes the picture on lifecycle and asset input rules. The only meaningful omission is guidance on selecting this over sibling video-generation tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents every parameter. The description adds a small amount of meaning by linking fps and end_seconds to cost estimation, but contributes nothing beyond that. Baseline 3 is appropriate when the schema does the heavy lifting.

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 clear verb and resource ("Create a Animation video") and adds a useful cost-model detail (frame cost derived from fps and end_seconds). It does not, however, differentiate this from the crowded set of *_create_video siblings such as text_to_video, image_to_video, or video_to_video.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The MCP guidance gives strong operational direction (async job, poll or wait_for_video_project, file_path vs URL handling), but it never states when to choose this tool over an alternative video-generation sibling. Usage is implied by resource type rather than contrasted against alternatives.

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 no annotations present, the description must carry the full behavioral burden. It does disclose the single most important trait — irreversibility ('Permanently delete... not reversible') — but omits auth/permission requirements, whether the parent project record survives, and cascading effects on related assets.

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 the destructive action front-loaded and zero padding. The trailing 'please be sure before deleting' is slightly redundant with 'permanently... not reversible' but earns its place as a caution for a destructive tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a delete tool with no annotations and no output schema, the description covers irreversibility but leaves real gaps: permission/auth needs, scope of deletion (project vs. rendered files), and post-deletion state. The naming tension between 'audio_projects_delete' and 'rendered audio file(s)' is left unresolved.

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 both parameters (id, context) are already documented in the schema, making the baseline 3. The description's phrase 'rendered audio file(s)' adds a small hint about what the id points to, but it never clarifies whether the id identifies the project or the rendered output — a meaningful ambiguity for a destructive call.

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 (delete) and resource (rendered audio files), using 'permanently' to sharpen the meaning. It is cleanly distinguishable from siblings like image_projects_delete and video_projects_delete purely by resource, and from audio_projects_retrieve_details by action.

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 issues a warning ('be sure before deleting') but gives no when-to-use guidance, no prerequisites, and no alternatives. There is no mention of the sibling retrieve or download tools an agent might use to verify what is about to be destroyed.

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 no annotations, the description carries the full burden and does well: it enumerates every status value and its meaning, states that the `downloads` field only populates after a successful render, and warns that download URLs are pre-signed and must be used verbatim (no shortening, no query stripping, no appending expires_at). It does not mention auth requirements or rate limits, which keeps it short of 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?

The status table and guidance bullets are front-loaded and scannable, and every bullet carries operational meaning except the low-value "draft — not used" entry. A minor typo ("a audio project") is the only other friction.

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 re-explained, yet the description still covers the two things an agent must know to interpret results: what each status means and how to handle the download URLs. Combined with the error-path instruction, an agent can act on the response without further inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented in the schema — including that `id` comes from the POST create APIs. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening line states a specific verb and resource ("Check the progress of a audio project") and the status list makes the read-only job-inspection scope unmistakable. It does not, however, name or differentiate itself from the sibling wait_for_audio_project, which covers overlapping polling territory. Clear purpose, but no explicit sibling differentiation.

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 MCP guidance explicitly says when to call it (after a create tool, to poll job status) and prescribes actions per outcome (surface downloads on complete, surface the error on error). It omits the alternative wait_for_audio_project, so it gives clear context but no 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?

With no annotations, the description carries the full burden and does so well: it discloses async job semantics, that it returns id plus credits_charged immediately, that the job must be polled to completion, that credits are charged only for rendered frames with an estimate at queue time, and that completed projects expose downloads URLs. It also warns about hotlinked URL failures and prescribes the presigned upload flow, which is actionable behavioral context.

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?

It is well front-loaded and header-structured, but noticeably bloated with marketing copy, a separate Cost section, and repeated doc links that overlap with the schema and product page. Several bullets restate what the 3-step workflow already implies, so not every sentence earns its place.

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 still covers the async lifecycle, the helper alternative, file-path handling, and credit estimation. For a 7-parameter async generation tool with no annotations, nothing essential for a correct call 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, but the description adds real meaning: it explains the resolution plan gating (free tier limits vs HD), names optional fields (face_swap_mode, start_seconds/end_seconds, prompt), and gives explicit guidance on *_file_path values and when direct URLs can fail. The only blemish is a minor mismatch (description says free tier is 576px while the schema enum lists 480p).

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 (“Create the same Audio To Video ... programmatically”) and clearly frames the tool as audio-plus-video synthesis. It does not explicitly contrast itself with the many sibling video-creation tools (image_to_video, text_to_video, video_to_video), so an agent must infer the distinction from the name rather than the text.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a concrete 'Good for' list (automation, batch processing, embedding in apps) and a 3-step workflow for use, plus an explicit routing rule: call wait_for_video_project or poll GET /v1/video-projects/{id} if the user wants the finished result. It stops short of stating when NOT to use this tool versus the other create_* 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?

Despite no annotations, the description fully discloses the async behavior, what's returned immediately (id, credits_charged), how to get results (wait_for_video_project or polling), completion states, and download URL availability. It also explains the file path preference and failure modes for direct URLs. This is rich behavioral context that goes well beyond 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?

The description is front-loaded with purpose and follows with structured MCP guidance sections. It's efficient and well-organized, though the guidance section is fairly long relative to the simple core purpose. No significant wasted sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an async video generation tool with 6 parameters (4 required) and an output schema, the description covers the full lifecycle: invocation, async handling, result retrieval, and input file handling. Combined with the detailed schema, an agent has everything needed to call and use this 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 coverage is 100%, so the schema already documents all parameter semantics thoroughly. The description's file path guidance adds some practical context about the `*_file_path` parameters, but doesn't provide additional syntax or format details beyond what's in 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?

The description states a specific verb and resource: 'generate subtitles for your video in multiple languages.' This is clear and distinctive from most siblings. However, it doesn't explicitly distinguish itself from other video creation siblings like ai_video_editor or character_replace — the task type is obvious from the name but the description doesn't reinforce the distinction 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?

The MCP guidance section provides explicit operational instructions: it's an async job returning `id` and `credits_charged` immediately, with clear polling instructions and helper tool references. The file path guidance is also actionable with a fallback strategy. This is thorough when-to-use and how-to-use 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?

With no annotations, the description carries the full behavioral burden and does it well: it discloses the async job model, that id and credits_charged return immediately, credit scaling from resolution (50 at 640px upward), the terminal statuses, that downloads/expiration metadata come back on completion, and the hotlinked-URL failure caveat. It omits auth/permission requirements and any rate limits or error-handling specifics.

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?

Purpose and cost model are front-loaded in the first sentence, followed by clearly grouped MCP guidance bullets. Every sentence is informative, though the polling/file-path advice is verbose enough to be tightened slightly.

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 generation tool with an output schema, no annotations, and a nested asset schema, the description covers the async lifecycle, how to retrieve results, and file-input pitfalls. Missing only auth/prerequisite context, which would be the last piece needed for fully self-sufficient invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, including detailed file-path semantics for both nested assets, so the baseline is 3. The description adds value mainly for resolution by tying it to credit cost, but does not add syntax or meaning beyond what the schema already documents for assets/name/context.

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 ('Swap a person into a scene image') plus the underlying models and resolution tiers, so an agent knows exactly what it produces. It stops short of explicitly contrasting with close siblings like head_swap_create_image or face_swap_photo_create_image, leaving differentiation 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 solid operational guidance (call wait_for_image_project or poll GET /v1/image-projects/{id} until complete/error/canceled, and prefer a presigned upload file_path when in doubt), but this is post-call workflow rather than when-to-choose-this-tool. Nothing tells the agent when to pick body swap over head_swap or face_swap_photo, so selection guidance 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?

With no annotations, the description carries the full burden and does well: it discloses that this is an async job returning id plus credits_charged immediately, the terminal statuses (complete/error/canceled), that completed projects include downloads, and the credit cost model (charged only for rendered frames, with an estimate at queue time). It omits auth/permission requirements and rate-limit behavior, 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?

It is front-loaded and clearly sectioned, but marketing framing ('Good for', 'Cost', product-page links) and the 3-step walkthrough add bulk beyond what an agent needs. Roughly half the text earns its place; the rest is promotional padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter async generation tool with an output schema and nested style/assets objects, the description supplies the async lifecycle, follow-up routing, cost behavior, and asset-path expectations. The main omission is any statement about required credentials or scope, but otherwise an agent has what it needs to invoke and then wait for the 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 3 baseline is met by the schema alone. The description adds value beyond it by steering the agent on *_file_path values (prefer an existing Magic Hour path or a presigned-upload file_path; hotlinked URLs may fail) and by noting resolution plan limits, though the stated '576px' free-tier cap sits slightly awkwardly against the schema's 480p/720p enum.

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 ('Create the same Character Replace you can make in the browser, but programmatically'), making the operation identifiable at a glance. It does not, however, differentiate itself from close siblings such as face_swap_create_video or face_swap_photo_create_image, which an agent may confuse with this 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?

It gives clear conditions for use ('Automation and batch processing', 'Adding character replace into apps, pipelines, or tools') and explicitly routes the agent to the follow-up helper: call wait_for_video_project with the returned id, or poll GET /v1/video-projects/{id}. There is no explicit 'when not to use' or sibling-alternative comparison, so it falls short of a 5.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses that this starts an async task, returns an `id` for later retrieval via face_detection_retrieve_details, and notes the free-now/pricing-may-change condition. It stops short of permissions/auth or rate-limit detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the one-line purpose, then layers use case, pricing, and MCP flow in clearly labeled form. Slightly verbose (the pricing note is marginal), but each section is skimmable and earns its place.

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 does not need to explain return values, and it covers the missing pieces: async task/id lifecycle, the retrieval sibling, and file-path sourcing rules. An agent has everything needed to invoke 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 coverage is already 100%, so the baseline is 3, but the description adds operational value for target_file_path beyond the schema: prefer an existing Magic Hour file_path or an upload-URL result, and warns that hotlinked/public URLs can fail so the presigned upload flow is safer.

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 ('Detect faces in an image or video') and immediately names the downstream use case (multi-face swaps via the face-swap photo/video APIs). This clearly differentiates it from siblings like face_swap_photo_create_image and face_detection_retrieve_details.

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?

Explains when to reach for it (to get a face list before doing individual multi-face swaps) and routes the agent to the companion retrieve-details step. It gives clear positive context but no explicit exclusions or when-not-to-use 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?

No annotations are provided, so the description carries the full burden. It does disclose the return content ('list of faces detected in the image or video'), which is genuine behavioral context, but says nothing about permissions, failure modes, or whether the task result is retained/expires. Adequate but incomplete for an unannotated 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?

Two sentences, front-loaded with the action and followed by the use case. The inline documentation links add length but earn their place by pointing to the consuming swap APIs.

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 need not be explained, and the description covers purpose plus downstream integration. It stops short of clarifying the relationship to the detect_faces sibling, but is otherwise complete for a single-id retrieval 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 description coverage is 100%, so both the id (with its provenance link to the face detection API) and the analytics-only context field are already documented in the schema. The description adds no parameter-level meaning beyond that, 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 ('Get the details of a face detection task'), which cleanly separates it from the sibling face_detection_detect_faces, which creates the task. It does not name that sibling explicitly, but the 'task details' framing makes the retrieval role clear.

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 explains the downstream purpose clearly ('to use in the face swap photo or face swap video API calls for multi-face swaps'), which implies why an agent would call it. However, it never states when to use it versus siblings like face_detection_detect_faces, nor any prerequisites (e.g., an id already returned from detection).

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 no annotations, the description carries the full burden and does so well: it discloses that this starts an async job returning id plus credits_charged immediately, that completion requires polling or the wait helper, that credits are charged only for rendered frames, and that free-tier resolution is capped at 576px. These are exactly the behavioral traits an agent needs before calling.

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?

Content is front-loaded and organized with headers, but it is long and somewhat redundant — the 'How it works' steps overlap heavily with the MCP guidance paragraph, and marketing links/product-page references add bulk. Most sentences earn their place, but the piece could be tightened.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists, the description need not explain return values, and it instead covers the async lifecycle, the wait helper, cost behavior, and input-path conventions. For a nested-object, 6-parameter async generation tool with no annotations, this is complete enough to call 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%, so the baseline is 3, but the description adds real value beyond the schema: the file_path vs. direct-URL guidance for *_file_path values, the upload-URL workflow, and the mention of face_swap_mode, start/end_seconds, and resolution constraints. It is above baseline without being exhaustive on every field.

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 ('Create ... Face Swap') and explicitly frames it as the programmatic/video variant, which distinguishes it from the sibling face_swap_photo_create_image and other create_* tools. An agent can tell what it produces 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 'Good for' list gives clear usage contexts (automation, batch, pipelines) and the MCP guidance names the concrete follow-up path (wait_for_video_project or poll GET /v1/video-projects/{id}). It does not explicitly state when NOT to use this versus e.g. face_swap_photo_create_image, so it falls short of a full when/when-not treatment.

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 no annotations, the description carries the full burden and does a solid job: it discloses the credit cost (10 credits per photo), that output dimensions depend on subscription, that the job is asynchronous with a specific terminal status set, and that hotlinked URLs may fail. It stops short of stating auth requirements or what happens on a failed/charged 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?

Purpose and cost are front-loaded in the first two sentences, followed by two focused guidance bullets covering the async result flow and file-path sourcing. Every sentence carries actionable content 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?

An output schema exists, so return values need not be restated, and the description still adds the async polling path and download-URL notes. Combined with full schema coverage for a 3-parameter nested tool, this is nearly complete, missing only sibling-selection guidance.

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 baseline is 3. The description exceeds that by adding meaning the schema lacks: prefer an existing Magic Hour file_path or a presigned-upload file_path over direct public URLs, which may fail when hotlinked. That directly informs how to populate the *_file_path parameters.

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 ("Create a face swap photo") that maps cleanly to the tool name. It is clear what the tool does, but it never differentiates itself from close siblings like head_swap_create_image, body_swap_create_image, ai_face_editor_edit_image, or face_swap_create_video, so an agent must infer the boundary from names 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?

The MCP guidance gives strong operational context (async job, use wait_for_image_project or poll GET /v1/image-projects/{id}, prefer presigned upload flow for file paths), but it never says when to pick this tool over the many sibling image-generation tools. Usage is implied by the workflow rather than by explicit selection criteria.

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?

No annotations are provided, so the description carries the full burden; it discloses that output is inline MCP audio content, that only compatible clients can consume it, and the critical gotcha that the signed URL must be passed verbatim with query parameters intact. It omits error/expiry behavior and how max_bytes constrains the 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 tight sentences: the first states purpose and return type, the second front-loads the most common failure mode (URL trimming) plus the expires_at clarification. No filler, and the highest-value guidance comes early.

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 annotations and no output schema, the description correctly describes the return form (inline audio) and the key call-time pitfall. It is nearly complete but leaves the max_bytes size-limit behavior and any failure mode for expired/signed URLs unexplained.

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 only 33% (only 'context' is documented), so the description must compensate. It does explain the required download_url semantics (exact full signed URL, do not trim query params) but says nothing about max_bytes, leaving one of three parameters undocumented in both places.

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 ('Fetch') plus resource ('audio downloads[n].url from a completed audio project') and the resulting form ('inline MCP audio content'). The audio scoping cleanly distinguishes it from the parallel fetch_image_download and fetch_video_download siblings without needing the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear prerequisite ('from a completed audio project') and a client constraint ('for compatible clients'), which tells the agent when the tool is applicable. It stops short of explicitly naming when to prefer a sibling or what to do if the project is not complete.

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 no annotations, the description carries full behavioral burden and does add real value: it discloses the return type (inline MCP image content for compatible clients) and the signed-URL handling rule (do not trim query parameters, expires_at is separate). It omits error/expiry behavior and says nothing about the max_bytes limit, so it is not complete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose then the critical URL-handling caveat, with essentially no filler. The minor grammatical slip ('a image') does not impede comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the description correctly explains the return value and the source of the required URL. It leaves the max_bytes parameter and failure cases (expired URL, size limits) unexplained, which is a gap for a fetch tool with three parameters.

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 33%, and the description usefully compensates for the undocumented download_url by specifying it must be the exact full signed URL from downloads[n].url without trimming. It adds nothing, however, for max_bytes, so one of three parameters remains 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 (fetch), a specific resource (an image download from a completed image project), and the delivery mechanism (inline MCP image content). This clearly separates it from siblings like fetch_audio_download, fetch_video_download, and image_projects_retrieve_details.

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 phrase 'from a completed image project' implies a prerequisite (the project must have finished) and points to the downloads[n].url source, giving usable context. However, it never names an alternative tool or states when not to use this tool, so routing guidance 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?

With no annotations, the description carries the full burden and does disclose meaningful traits: the result is an embedded MCP binary resource, it is limited to compatible clients, and the URL is signed and time-limited. It omits auth requirements, behavior on expired URLs, and error handling, leaving notable gaps for a fetch 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?

Two sentences, front-loaded with purpose and followed by the crucial URL-passing caveat; every clause earns its place. The phrase 'for compatible clients' is slightly vague but does not waste much space.

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 or annotations, and three parameters exist, so the description should do heavy lifting. It covers purpose, return type, and URL format well but leaves max_bytes behavior and failure modes undocumented, making it adequate rather than 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 only 33% (just the context field), so the description must compensate, and it does for the critical parameter: it explains that download_url must be the exact full signed URL without trimming query parameters and that expires_at is separate metadata. It adds nothing for max_bytes, but the key parameter is well covered.

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 (Fetch) and resource (a video download from a completed video project) and describes the return as an embedded binary resource, clearly distinguishing it from siblings like fetch_image_download, fetch_audio_download, and video_assets_generate_presigned_url.

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 implies usage by scoping to 'a completed video project' and noting it is 'for compatible clients', which gives context. However, it never states when to prefer this over video_assets_generate_presigned_url or what to do for incompatible clients, so the routing guidance 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?

With no annotations provided, the description carries the full behavioral burden and does so well: it discloses the 10-credit cost per image, that the job is asynchronous, that it returns `id` plus `credits_charged` immediately, the terminal statuses to poll for, that completed projects include `downloads`, and the failure mode of hotlinked URLs. This is well beyond what structured fields convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core action and cost before the more detailed MCP guidance, and each sentence serves a purpose. It runs long, but the length is justified by the number of behaviors (async flow, credit cost, file handling) that must be communicated.

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 goes further by describing the async lifecycle and how to obtain results. Combined with 100% schema coverage on all four parameters, an agent has everything needed to invoke and follow up 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 the baseline is 3. The description adds genuine value on top: it clarifies that `max_resolution` may be set lower than the plan maximum, and it gives file-source guidance (prefer a Magic Hour file path or an upload-URL `file_path`; hotlinked URLs can fail) that enriches the `*_file_path` 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: 'Swap a head onto a body image.' This is unmistakably distinct from siblings like face_swap_photo_create_image and body_swap_create_image, since the head-onto-body operation is named directly. An agent can identify the tool 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 explains the post-invocation workflow (poll or call wait_for_image_project), which is useful process guidance, but never states when this tool should be chosen over siblings such as face_swap_photo_create_image or body_swap_create_image. Usage is implied by the operation name rather than explicitly scoped.

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 no annotations, the description carries the full burden and does well: it discloses that this starts an async job, returns id plus credits_charged immediately, costs 5 credits per image, the terminal statuses, and that completed projects include download URLs and expiration metadata. It omits auth requirements and rate limits, so not a full 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the one-line purpose and cost, then uses a structured bullet block for the MCP workflow. It is somewhat long, but every sentence (async return shape, wait helper, file path policy) earns its place.

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, nested-asset tool with an output schema present, the description supplies the workflow, cost, status lifecycle, and input-path rules an agent needs. It does not need to explain return values since the output schema covers them; minor gaps remain around auth and failure handling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it advises preferring an existing Magic Hour file path or a file_path returned by the upload-URL endpoint, and warns that hotlinked public URLs can fail. This interpretation of the *_file_path semantics goes beyond 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 ('Remove background from image'), which is naturally distinct from siblings like ai_image_upscaler or ai_face_editor. It does not explicitly name or contrast siblings, so it falls just short of the top score, but an agent can identify the purpose immediately.

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 guidance explains the async workflow (call wait_for_image_project or poll the matching endpoint) and how to supply file paths, which is useful operational context. However, it never states when to choose this tool over the many sibling image tools, nor any exclusion conditions, so the when-to-use dimension 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?

With no annotations, the description carries the full burden, and it does disclose the single most important trait: the deletion is permanent and irreversible. It stops there, saying nothing about permission requirements, whether child renders/downloads are also removed, or whether the resource is recoverable.

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 followed by the irreversible warning; nothing is padded. Could be marginally tighter, but it earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple destructive delete with full schema coverage and no output schema, the description gives an agent enough to call it safely: what it does and that it cannot be undone. Behavioral edge cases (cascade effects, auth) remain unspecified, keeping it short of complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the id parameter is fully documented as the project ID returned by create APIs, so the schema does the heavy lifting. The description adds no parameter meaning beyond what the schema already states (it does not even confirm that "rendered image(s)" maps to the project id).

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 ("Permanently delete the rendered image(s)") that clearly separates it from sibling reads like image_projects_retrieve_details. It does not, however, explicitly acknowledge the parallel delete siblings (audio_projects_delete, video_projects_delete) or the "project" granularity, so the resource naming is slightly loose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to call this versus alternatives (e.g., retrieve details first, or fetch_image_download to just get the file). The only usage-adjacent sentence is the caution "please be sure before deleting," which is a warning rather than routing 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?

With no annotations, the description carries the full burden and does well: it enumerates every status value with its meaning, notes that `downloads` is only populated after a successful render, and warns that each `downloads[n].url` is a full signed URL that must not be shortened or have parameters stripped/appended. It omits auth/permission requirements and any rate-limit or polling-interval guidance, which would have closed the gap completely.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the one-line purpose, then uses tight headers and bullets for statuses and operational guidance. Every line — including 'draft — not used' — carries actionable 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?

Covers the full polling workflow, per-status handling, error surfacing, and the signed-URL caveat; the output schema exists so return-value structure need not be restated. The only meaningful omission is guidance relative to the wait_for_image_project alternative.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented in the schema, and the description adds no syntax or format detail for `id` or `context`. The baseline 3 applies when the schema does the heavy lifting and the description contributes nothing extra about parameters.

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 ('Check the progress of a image project') that immediately distinguishes it from the audio/video retrieve_details siblings. The added note that `downloads` populates after a successful render pins down exactly what the tool reports on.

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 to use it 'after a create tool to poll job status' and instructs what to do per status (surface downloads on complete, surface error on error). It does not, however, acknowledge the wait_for_image_project sibling or explain when to poll vs. when to wait, leaving the most relevant alternative undifferentiated.

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?

No annotations are provided, so the description carries the full burden — and it discharges it: it discloses that the call starts an async job returning id plus credits_charged immediately, how to await the result, the terminal statuses, and that credits are billed only for rendered frames. It also warns that hotlinked URLs may fail, which is a real operational caveat.

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?

Well sectioned and front-loaded with the operation, workflow, and cost, so an agent can extract the essentials quickly. It carries some marketing framing ('Good for automation and batch processing', 'see the product page') that does not strictly earn its place, keeping it below a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter async generation tool with heavy per-model matrix behavior, the description covers the create/await lifecycle, cost model, asset sourcing, and return handling. With an output schema present it appropriately does not need to enumerate return fields, and it points to the retrieval path instead.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds genuinely non-redundant guidance about *_file_path values — prefer an existing Magic Hour path or a file_path from the upload-URL endpoint — which is not captured by the schema. It does not add meaning beyond the schema for the model/resolution/duration enums, which the schema already documents exhaustively.

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 ('Create the same Image To Video ... programmatically') and the required image input distinguishes it from text_to_video_create_video, video_to_video_create_video, and audio_to_video_create_video siblings without opening their schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear 3-step workflow, names the wait_for_video_project helper and the polling endpoint, and explains when to prefer the presigned upload flow. It lacks an explicit 'use this instead of X when...' comparison against the other *_create_video siblings, so it stops just short of a 5.

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

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

With no annotations present, the description carries the full burden and does so well: it discloses async behavior (returns id and credits_charged immediately), the terminal statuses (complete/error/canceled), that downloads carry direct URLs, that credits are charged only for rendered frames with an estimate at queue time, resolution limits by plan tier, and generation_mode tier availability.

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?

Headers and the 3-step flow are well front-loaded, but the piece is long and mixes marketing copy ('the same Lip Sync you can make in the browser') and cost details that duplicate the schema's generation_mode pricing. The genuinely load-bearing MCP guidance is buried at the bottom.

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 starts an async job, an output schema exists, and the schema is fully described, the description supplies everything else an agent needs: the immediate return shape, the waiting/polling path, the completed-project downloads, and how to obtain valid file_path values.

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 seven parameters, making 3 the baseline. The 'Key options' section adds some framing (inputs, resolution, start_seconds/end_seconds) but it also lists a field like 'face_swap_mode' that does not exist on this schema, adding noise rather than the missing detail the schema could not supply.

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 ('Create the same Lip Sync... programmatically') and scopes it as an automated/batch/embedded capability. It is clearly distinguishable from siblings like face_swap_create_video or ai_video_editor_create_video because the resource (lip sync) and its async nature are explicit.

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 concrete when-to-use guidance ('Automation and batch processing', 'Adding lip sync into apps, pipelines, or tools') and an explicit routing rule: call wait_for_video_project or poll GET /v1/video-projects/{id} when the finished result is wanted. It also states when to prefer the presigned upload flow over hotlinked URLs.

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 no annotations provided, the description carries the full behavioral burden and delivers: it is async, returns id plus credits_charged immediately, costs 10 credits per image, and includes downloads with direct URLs on completion. It also discloses the fragility of direct public URLs. This is unusually rich disclosure for a mutation/generation tool with zero annotation coverage.

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?

Purpose and cost are front-loaded in a single crisp sentence, then structured bullet guidance follows. The guidance is somewhat long, but each bullet carries distinct actionable information rather than padding, so it stays efficient without being maximally terse.

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 generation tool with nested asset params and an output schema, the description covers the missing pieces an agent needs: async lifecycle, retrieval path, credit cost, and file-input sourcing. Output values needn't be re-explained because an output schema exists, yet the description still notes downloads and exact_download_urls, leaving nothing critical 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 description coverage is 100%, so baseline is 3. The description nevertheless adds real value about how to populate *_file_path values (prefer existing Magic Hour paths or upload-URL file_path; hotlinks can fail), which is operational meaning beyond the schema's field text.

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+resource ('Colorize image') and adds a concrete cost fact (10 credits). It is specific enough to distinguish from sibling image tools like ai_headshot_generator or image_background_remover, though it never explicitly names or contrasts against them. Slightly close to restating the tool name, which caps it below 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?

It explicitly explains the async workflow, names the alternative retrieval paths (the wait_for_image_project helper or polling GET /v1/image-projects/{id}), and clarifies termination statuses. It also gives conditional guidance on file_path sourcing, preferring Magic Hour paths or upload-URL results over hotlinked URLs, with an explicit fallback ('when in doubt, use the presigned upload flow first').

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?

No annotations are provided, so the description carries the full behavioral burden. It does convey that this is a harmless diagnostic read (a reachability probe implies no mutation), but it does not state side effects, latency, or what a failure response looks like.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with zero filler; nothing redundant and nothing that could be cut.

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-required-parameter health check with an output schema already covering the return value, the description is nearly sufficient; the only real gap is the absence of any guidance on when an agent should invoke it.

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 'context' parameter is exhaustively documented in the schema itself, so the description adds no parameter meaning. Baseline 3 applies when the schema does all the work.

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 (check) and a specific resource (Magic Hour MCP server reachability), which is unambiguous and immediately distinguishable from every sibling tool, all of which are media generation/retrieval operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent can infer you call this when connectivity is in doubt, but the description never says when to reach for it (e.g., before retrying a failed generation, after an auth change) nor names any alternative diagnostic path.

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 no annotations, the description carries the full burden and does well: it discloses the async job model (returns id and credits_charged immediately), the polling/wait_for_video_project follow-up, the credit-charging model (charged per rendered frame, estimate at queue time), and that completed projects expose downloads. It omits auth/permission requirements and rate limits, 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?

Content is front-loaded and organized under clear headers, but it is long and padded with a template "Key options" section whose input types (file/YouTube upload) do not apply to a text-to-video tool. Some sentences therefore do not earn their place.

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, yet the description still helpfully covers the async return shape and how to retrieve results. Combined with the rich parameter schema, an agent has enough to invoke the tool correctly, though the generic input-type boilerplate is a minor mismatch.

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%, so the schema already documents model/resolution/aspect_ratio/end_seconds constraints in depth, establishing a 3 baseline. The description's "Key options" block partly compensates but is largely generic boilerplate (mentions uploading video/image/audio and YouTube links that do not exist in this tool's schema), which risks confusing rather than clarifying the actual parameters.

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+resource ("Create ... Text To Video ... programmatically") and frames it as automation of the browser product. This distinguishes it from the many sibling video generators (image_to_video, video_to_video, lip_sync) by the text-driven input, though it never explicitly names those siblings as 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?

The "Good for" block gives context (automation, batch processing, embedding in apps/pipelines), which implies when to reach for an async programmatic job. However there is no explicit when-not guidance and no direct naming of the sibling tools it should be chosen over.

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 no annotations, the description carries the full burden and does well: it discloses that the response array matches request order, that files must be PUT to the returned URL, and that extension support varies by asset type (including the gif/face-swap caveat). It does not cover auth/permission scope or expiry of the presigned URLs, which is the main 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?

Front-loaded purpose followed by scoping, constraints, and workflow guidance, with clean headings and a concrete curl example. Slightly long and the extension table duplicates schema content, which costs a point but does not obscure the key 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?

An output schema exists, so return values need no explanation, and the description supplies the full end-to-end context an agent needs: why the URL exists, what extensions are legal, how to upload, and how the resulting file path feeds later create calls. Nothing material 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 documents both parameters. The description's per-type extension list largely restates what the schema's extension field says, adding only the ordering guarantee for the response array. 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 ('Generates a list of pre-signed upload URLs for the assets required') and immediately scopes the tool as only needed when uploading into Magic Hour's storage, separating it from the many *_create_* generation siblings that consume file paths rather than produce upload targets.

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 it is and is not needed ('only necessary if you want to upload to Magic Hour's storage'), and the MCP guidance tells the agent to prefer existing file paths or direct URLs and to fall back to the presigned flow when hotlinked URLs are unreliable. This routes the agent to alternatives with clear conditions.

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 no annotations, the description carries the full behavioral burden and does disclose the key trait: the deletion is permanent and irreversible. It omits other relevant traits for a destructive op, such as required permissions, whether associated assets/renders are also removed, and whether the returned resource is a project or a file.

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 the destructive action front-loaded, and no wasted words. The second sentence is mildly redundant with 'permanently' but still earns its place as a warning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, single-required-param delete tool with no output schema and no annotations, the description covers permanence and irreversibility adequately. It falls short on auth expectations and what exactly is removed (project vs rendered output), which matters for a destructive 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 coverage is 100%, so both parameters (id and context) are already fully documented in the schema. The description adds no syntax, format, or meaning beyond that, 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 (delete) and resource (the rendered video), which lets an agent distinguish it from the many create/edit siblings. However, it says 'rendered video' while the tool name and id param describe a 'video project', leaving a small ambiguity about whether the project or its rendered output is deleted, and it names no sibling for contrast.

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 never says when to use this versus alternatives such as video_projects_retrieve_details, nor any precondition. The caution 'be sure before deleting' is a warning, not usage guidance that routes the agent.

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 no annotations, the description carries the burden and does a good job: it discloses that `downloads` is only populated after a successful render, defines every status value, and warns that URLs are pre-signed and must be used verbatim. It omits auth/permission requirements and any rate-limit or polling-cadence guidance, 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?

Front-loaded one-line purpose, then a scannable status bullet list, then operational guidance. Every line contributes; the status enum and the URL-handling warning are both information an agent actually 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?

An output schema exists, so return values need not be re-explained, and the description still adds the status vocabulary and the signed-URL handling rule. For a simple two-parameter polling tool this is fully sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both parameters are documented in the schema, so the baseline is 3. The description adds no extra meaning about `id` or `context` beyond what the schema already states, though it does explain output 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 ('Check the progress of a video project') and enumerates the status states the tool reports, which is more informative than a restatement. It does not, however, explicitly differentiate itself from the sibling wait_for_video_project or fetch_video_download, which an agent must disambiguate against.

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 'MCP guidance' block gives a clear trigger ('Use this after a create tool to poll job status') plus explicit follow-up actions for the complete and error cases. It stops short of naming the alternative (wait_for_video_project) or stating when polling is preferable to a blocking wait, so it is clear context rather than 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?

With no annotations present, the description carries the full burden and does so well: it discloses that the job is asynchronous and immediately returns `id` plus `credits_charged`, enumerates terminal statuses (complete/error/canceled), explains the credits-per-rendered-frame cost model with estimate-at-queue vs final total, and warns that hotlinked media URLs can fail. It also flags build-time concerns like the presigned upload flow for `*_file_path` values.

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?

It is long, but the header-based structure (What it does / Good for / How it works / Key options / Cost / MCP guidance) is front-loaded and scannable, with the core async-return behavior surfaced early. There is some repetition — the presigned upload flow is described in both the numbered steps and the final bullet.

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 complex tool with 7 parameters, nested objects, and an output schema, the description covers the end-to-end lifecycle an agent needs: input sourcing, job creation, polling/status handling, and result retrieval via `downloads`. Return-value detail is correctly left to the output schema while the async contract is explained.

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 already high (86%), so the baseline is 3; the description adds real value by tying `*_file_path` values to the upload-URL endpoint, warning about unstable hotlinked URLs, and noting constraints like free-tier 576px resolution and start/end second usage. Minor imprecision: it references `face_swap_mode`, which is not among this tool's schema fields.

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+resource — programmatically creating a Video To Video job — and describes the workflow, cost, and options. It does not explicitly differentiate itself from close siblings like image_to_video_create_video, text_to_video_create_video, or animation_create_video, so an agent must infer the distinction from the tool name and the 'video source' 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?

It gives clear when-to-use context (automation, batch processing, embedding in apps/pipelines) and a concrete 3-step invocation path. It also names the follow-up alternative, `wait_for_video_project`, for retrieving the finished result. It stops short of stating when *not* to use this versus the other create_video 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?

With no annotations, the description carries the full burden and does disclose non-obvious traits: it polls, resolves on four terminal states, returns the final project JSON, attempts to inline downloads only when complete, and returns sanitized fields. The URL-integrity warning is a valuable behavioral gotcha, though auth requirements and timeout-failure behavior are not described.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the purpose in the first sentence, then layers return behavior and the URL-handling caveat. Every sentence carries information, though the repeated URL warning adds some density without being wasteful.

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 polling tool with no output schema and very low schema coverage, the description covers return content reasonably but omits parameter meanings and edge-case behavior. It is adequate but leaves real gaps an agent must guess at.

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 14% schema description coverage across 7 parameters (only 'context' is documented). The description only vaguely gestures at inline downloads, leaving timeout_seconds, poll_interval_seconds, max_inline_downloads, max_bytes_per_download, and include_inline_downloads unexplained in both schema and description, so it fails to compensate 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 ('Poll an audio project') plus the terminal conditions it resolves on, and the name/description clearly separate it from wait_for_image_project, wait_for_video_project, and audio_projects_retrieve_details. 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?

Usage is implied by the polling semantics (call it to block until the project finishes), but there is no explicit when-to-use vs. when-not guidance and no mention of alternatives like audio_projects_retrieve_details or fetch_audio_download. The instruction near the end concerns how to handle returned URLs, not when to select 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?

With no annotations, the description carries the full burden and does substantial work: it discloses the blocking/polling loop, the four terminal states, that downloads are only inlined on completion, that returned fields are sanitized, and a critical usage constraint about not mutating download URLs. It omits timeout/poll defaults, auth requirements, and rate-limit 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?

Front-loaded with the polling purpose, followed by return behavior and then the URL-handling warning, which is the one instruction most likely to cause failures. Slightly dense but every sentence carries operational value.

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 tool with no output schema and no annotations, the description usefully explains the return shape and inlining behavior, which partly offsets the missing output schema. It still leaves six tuning parameters and their units/bounds unexplained, so an agent cannot confidently set anything beyond the required id.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 14% (only `context` is documented), so the description must compensate for six undocumented parameters. It alludes to inline-download behavior but never explains timeout_seconds, poll_interval_seconds, max_inline_downloads, max_bytes_per_download, or include_inline_downloads, leaving their meaning to bare defaults in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (poll), resource (image project), and the exact terminal conditions (completes, errors, canceled, times out), which is far more than a tautology. It does not name or differentiate itself from the closely related wait_for_video_project/wait_for_audio_project or image_projects_retrieve_details, so the sibling routing is left to the agent.

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 makes the polling semantics clear, implying it is called after an image project has been kicked off to block until a terminal state. However, it never states when to prefer this over the non-blocking image_projects_retrieve_details or when to fall back to fetch_image_download, and gives no prerequisites.

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