Magic Hour

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false. The description adds meaningful scoping behavior: the account is resolved implicitly from the API key, so no account identifier is needed. It does not cover rate limits or auth failure behavior, but it exceeds the annotation baseline.

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

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

One sentence, front-loaded with the verb and resource, no filler or restated title content. Every clause earns its place by specifying exactly which fields are returned.

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 zero parameters, declared read-only annotations, and an output schema that already documents the returned credit/subscription structure, the description is complete. Nothing an agent needs to call this correctly is missing.

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

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

The tool takes no parameters, so per the rubric the baseline is 4. The description reinforces that identity comes from the API key rather than a parameter, which is the only semantic an agent could get wrong here.

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

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

States a specific verb (Get) and resource (account details), and enumerates the exact payload: current credit balance and subscription details. This is clearly distinguishable from every sibling, none of which expose account-level billing data.

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 rather than stated: an agent can infer this is the tool to call before spending credits or to check plan status, but the description names no alternatives or conditions. For a zero-parameter account-scoped read there is little to disambiguate, so implied guidance is adequate but not strong.

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

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

The description adds substantial behavior beyond annotations: it discloses the 25-credit cost, async return shape with id and credits_charged, completion statuses, download URL availability, helper behavior around exact_download_urls, and file-path pitfalls. Annotations only provide basic safety hints, so the description is doing significant extra work.

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, then organized into MCP guidance and restrictions. It is somewhat long, but each paragraph contains useful, non-redundant information for an async, credit-based image generation 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?

Given the async behavior, nested asset parameters, credit cost, output schema, and safety annotations, the description is complete enough for correct invocation. It covers result retrieval, file preparation, and authorized-use restrictions without needing to restate the full output schema.

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

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

Schema coverage is 100%, so the schema already documents the parameters well. The description still adds meaningful operational guidance for *_file_path values, explaining that presigned upload flows are safer than direct public URLs, which goes beyond the schema 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 clearly states the tool changes outfits in photos and notes the credit cost. It does not explicitly distinguish the tool from close siblings like body_swap, head_swap, or ai_image_editor, so it lacks 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?

It gives strong usage context: async job handling via wait_for_image_project or polling, file-path preparation guidance, and explicit prohibited uses such as impersonation and sexual content. However, it does not compare this tool against alternative image-editing siblings for tool selection.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds genuinely useful non-schema behavior: the per-edit cost of 1 frame, the subscription-dependent output dimensions, the async return shape, and the terminal statuses. It does not disclose failure modes for invalid inputs, but the added context is substantial.

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

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

Purpose and cost are front-loaded in the first sentence, followed by structured MCP guidance bullets. The content is dense but every element (cost, async pattern, wait helper, file-path sourcing) serves a purpose. Slightly long but not padded.

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

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

With an output schema present, the description need not explain return values, yet it usefully confirms the async contract and terminal statuses and where downloads appear. Combined with full schema coverage and the annotations, an agent has what it needs to invoke this correctly. The only gap is explicit 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, and the description goes beyond it by explaining how to supply `*_file_path` values: prefer an existing Magic Hour path or a returned upload `file_path`, and warning that hotlinked URLs can fail. That adds real semantic value for the `assets.image_file_path` parameter even though the `style` sub-fields are left entirely to 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+resource: 'Edit facial features of an image using AI'. This clearly differentiates from adjacent siblings like face_swap_photo_create_image and head_swap_create_image, which replace identity rather than adjust expression/pose. It stops short of explicitly naming those alternatives, so it is clear but not fully sibling-routing.

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: it explains the async job model, that it returns `id` and `credits_charged` immediately, and how to obtain the finished result via `wait_for_image_project` or polling. It also explains the preferred file-path sourcing. It does not, however, state when to choose this over the many face-altering 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?

Annotations only tell the agent this is a non-read-only, non-destructive, closed-world write. The description adds substantially beyond that: a concrete cost (50 credits per GIF), async job semantics, the immediate return payload (id plus credits_charged), terminal status values, and the fact that completed projects carry direct download URLs. This is rich behavioral context an agent needs before invoking a paid async operation.

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

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

The core purpose and cost are front-loaded in the first two sentences, and the remaining MCP guidance is bulleted and scannable. It is slightly verbose, but nearly every clause (async, wait helper, statuses, downloads) carries distinct information, so little 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?

Because an output schema exists, the description does not need to enumerate return fields, yet it helpfully explains the async lifecycle and the credits_charged handoff anyway. Combined with annotations covering the safety profile, the definition is nearly complete; only the missing sibling-comparison guidance keeps it from a 5.

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

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

With 67% schema description coverage, the schema already documents name, style.prompt, and output_format, so the baseline is 3. The description adds no parameter-level meaning of its own (it only mentions the required style.prompt indirectly via credits/prompt context), so it neither compensates for the coverage gap nor falls below baseline.

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

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

The description opens with a specific verb+resource: 'Create an AI GIF.' This clearly distinguishes the tool from static-image siblings like ai_image_generator_create_image at the resource level. However, it never explicitly contrasts itself with those siblings or with animation_create_video, so the differentiation is implied rather than stated.

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

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

It supplies a clear post-invocation workflow (call wait_for_image_project or poll the GET endpoint until status is complete/error/canceled), which is useful operational guidance. But it gives no guidance on when to choose this tool over ai_image_generator_create_image or other image-creation siblings, leaving tool selection to inference.

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

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

Annotations cover only the safety profile (not read-only, non-destructive, open-world), and the description adds substantial context beyond that: the 50-credit cost per headshot, that execution is async, exactly what is returned immediately (`id`, `credits_charged`), terminal statuses, and that completed projects carry `downloads` URLs. It also warns that hotlinked source URLs may fail. This is rich, decision-relevant behavioral disclosure.

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

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

The core action and cost are front-loaded in one short line, then organized into two clearly labeled bullets covering async handling and file-path sourcing. Every sentence carries information, though the file-path bullet is dense enough to be slightly hard to scan.

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-object, async, 3-parameter tool with an output schema present, the description covers lifecycle, cost, result retrieval, and input sourcing well enough to invoke correctly. It relies on the output schema for return-value structure and on sibling names for tool selection, which is a reasonable division of labor.

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

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

Schema coverage is 67%, and the description compensates meaningfully for the asset parameter by explaining that `*_file_path` values should come from an existing Magic Hour file or the upload-URL endpoint, and why (hotlinked URLs can fail). The `name` and `style.prompt` parameters are left to the schema, which documents them adequately (including the recommendation to omit the prompt).

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 'Create an AI headshot' gives a specific verb and resource, matching the tool name unambiguously. It does not, however, distinguish itself from the crowded set of sibling image generators (ai_image_generator_create_image, ai_face_editor_edit_image, head_swap_create_image), so an agent must infer the boundary 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 explains the async lifecycle clearly: the call returns immediately, and to get a finished result you call `wait_for_image_project` with the returned id or poll `GET /v1/image-projects/{id}` until terminal status. It also gives concrete when-to guidance for file paths (prefer existing Magic Hour paths or presigned uploads over hotlinked URLs). It stops short of saying when this tool should be chosen over the other generator/editor 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?

Annotations only cover safety (readOnly=false, destructive=false, openWorld=true); the description goes well beyond that, disclosing that the call starts an async job and immediately returns id plus credits_charged, the terminal statuses to poll for, and that completed projects carry downloads with direct URLs. It also warns that hotlinked URLs can fail and prescribes the upload flow, which is real 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 one-line purpose is front-loaded and the guidance is split into two tight bullets that each carry distinct information. Nothing is padded; the long model/resolution documentation lives in the schema where it belongs, keeping the description proportionate.

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

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

With an output schema present and annotations covering safety, the description is close to complete for a 7-param async generation tool: it covers job lifecycle, result retrieval, and asset input requirements. The one gap is tool-selection context relative to the many sibling image 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 already 86%, so the schema carries most parameter meaning. The description adds value on top by giving operational rules for the *_file_path values — prefer a Magic Hour path or upload-endpoint result, direct public URLs only if stable and raw-bytes — which the schema mentions but does not adjudicate.

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+resource ('Edit images with AI'), which is clear and actionable. It does not, however, distinguish itself from close siblings such as ai_image_generator_create_image or the other edit-style tools (ai_face_editor_edit_image, photo_colorizer_create_image), so an agent must infer the boundary from the 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 is strong on operational usage — it explains the async job pattern, when to call wait_for_image_project, and when to prefer the presigned upload flow. But it never says when to choose this tool over ai_image_generator or the more specialized editors, which is the selection decision an agent most needs.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries the important behavioral load: it discloses that the call is asynchronous, returns `id` plus `credits_charged` immediately, that completion states are `complete`/`error`/`canceled`, and that completed projects carry `downloads`/`exact_download_urls` plus expiration metadata. This is meaningful context the annotations cannot convey. It stops short of describing credit-refund or failure semantics.

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

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

One sentence of purpose followed by a tightly packed guidance block that is front-loaded with the async behavior and the next-tool call. Every sentence earns its place; the only redundancy is that return-content detail (downloads URLs) is also available via the output schema.

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

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

For a 6-parameter, nested-object tool with enums and an output schema, the description covers the orchestration gap an agent would otherwise miss (async handoff to wait_for_image_project, terminal statuses, expiration metadata). Combined with the rich schema, an agent has enough to invoke and follow up correctly; only cross-sibling selection guidance 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 schema itself carries per-model resolution/tier/credit detail, so the baseline is 3. The description adds no parameter-level meaning beyond 'advanced model selection and quality controls'; it only names the returned `id` and `credits_charged` 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?

States a clear verb+resource ('Create an AI image') and scopes it with 'advanced model selection and quality controls', which separates it from the many sibling generators that produce images from existing inputs (editor, upscaler, clothes changer). It does not name any specific sibling, so differentiation is implied rather than 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?

The MCP guidance gives an explicit when-flow: it returns async, and if the finished result is wanted, call `wait_for_image_project` or poll the GET endpoint until a terminal status. This is strong operational guidance. It does not, however, say when to pick this generator over siblings like ai_image_editor_create_image or ai_headshot_generator_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?

Annotations only declare the safety profile (readOnly=false, destructive=false, openWorld=true). The description adds substantial behavioral context beyond that: credit pricing per mode and scale factor, that the call returns `id` and `credits_charged` immediately, the async completion states (complete/error/canceled), and the presence of `downloads` with expiration metadata.

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 purpose, then pricing, then operational MCP guidance in clearly separated bullets. Slightly lengthy, but every sentence carries actionable information for invocation.

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-object, 4-parameter tool with pricing and file-input constraints, the description covers credit costs, async lifecycle, polling alternatives, and input-source preferences. Output schema exists, and the description still summarizes the key return fields, leaving nothing essential 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 parameter descriptions already do the heavy lifting (baseline 3). The description adds real value on `image_file_path` semantics — preferring an existing Magic Hour file path or an upload-URL-returned `file_path`, and warning that hotlinked public URLs can fail — which goes beyond what the schema states.

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

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

Opens with a specific verb+resource ('Upscale your image using AI'), which clearly separates it from the many generator/editor siblings. It does not explicitly name a sibling to avoid, but the upscaling function is unambiguous.

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 strong procedural routing: it explains the async job model, tells the agent to call `wait_for_image_project` or poll the GET endpoint, and gives clear guidance on when to use the presigned upload flow vs. direct URLs. It lacks explicit when-to-use-this-vs-`ai_image_editor` framing but covers the practical path thoroughly.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds materially: the 10-credit cost, the async nature of the call, and the immediate return of id plus credits_charged. That cost and async disclosure is genuine value beyond the annotations, though failure modes and cancellation 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-loaded with the purpose and cost, then a clearly delineated 'MCP guidance' block for the async workflow. It is efficient and scannable, with only mild redundancy in mentioning both the helper and the raw polling endpoint.

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 job with a nested style object and an output schema, the definition covers the essentials: cost, immediate return shape, follow-up helper, terminal statuses, and where download URLs live. Since an output schema exists, it need not detail the return payload, and it stays appropriately scoped.

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

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

Schema description coverage is 50%, and each visible property (name, topic, template, searchWeb) already carries its own description and constraints. The description adds no parameter-level meaning at all, 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?

The description opens with a specific verb and resource: 'Create an AI generated meme.' That is unambiguous, but it does not differentiate this tool from the many sibling ai_*_create_image generators beyond the implicit 'meme' resource, so it stops short of a 5.

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

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

It gives clear post-invocation guidance: the call starts an async job, and to get the finished result you call wait_for_image_project with the returned id or poll GET /v1/image-projects/{id}. This is strong operational routing, though it says nothing about when to prefer this tool over sibling generators.

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

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

Annotations already declare the safety profile, and the description adds substantial behavioral context: it starts an async job, immediately returns id and credits_charged, describes terminal statuses, and explains how to retrieve completed downloads. No annotation contradiction is present.

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 then provides necessary async workflow details. The MCP guidance is somewhat long but each sentence carries useful invocation or retrieval 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 async image-generation tool with an output schema and annotations, the description covers the important invocation and completion workflow. It does not discuss auth or rate limits, but those are not clearly required here.

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%, and the description adds no additional parameter meaning beyond the schema. The schema already documents name, style.art_style, and content, so the description neither compensates significantly nor harms usability.

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 QR code.' This clearly identifies the tool's purpose among many sibling image-generation tools, though it does not explicitly contrast itself with alternatives like ai_image_generator_create_image.

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

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

The description provides workflow guidance for async completion: call wait_for_image_project or poll the image-projects endpoint. However, it does not explain when to choose this tool over other image-generation siblings, leaving selection guidance implicit.

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

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

Adds substantial behavior beyond the annotations: the call returns immediately with id and credits_charged, terminal statuses are complete/error/canceled, completed projects carry downloads URLs, and the wait helper exposes exact_download_urls separately from expiration metadata. It also discloses the file-path/upload-flow requirement and hotlink failure mode.

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 followed by a clearly bulleted 'MCP guidance' block; every bullet carries actionable information. Slightly long, and the 'or text input' claim is loose given the required-asset schema.

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

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

For an async, multi-asset generation tool with an output schema, the description covers the lifecycle, polling path, download metadata, and content restrictions. The only real gap is the unexplained text-input mention, which could mislead an agent into expecting a text-only invocation path.

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 meaningfully extends it by explaining what a valid *_file_path is, that the presigned upload flow is preferred, and that unstable public URLs can fail. It adds no guidance on start_seconds/end_seconds or max_resolution 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 ('Create a talking photo from an image and audio...'). However the phrase 'or text input' is not backed by the schema, which requires both image_file_path and audio_file_path, and the entry point is not explicitly distinguished from close siblings like lip_sync_create_video or audio_to_video_create_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?

Gives clear operating context: the job is async, how to obtain the finished result (wait_for_video_project or polling GET /v1/video-projects/{id}), and the acceptable content policy. It stops short of naming when a different sibling (e.g. lip_sync_create_video) would be the better choice.

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

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

Annotations only say readOnlyHint=false and openWorldHint=true; the description goes well beyond them by disclosing the async contract (returns id + credits_charged immediately), billing semantics ('Credits are only charged for the frames that actually render', estimate at queue time), tier-based resolution limits, and the failure mode of hotlinked URLs. This is exactly the behavioral context annotations cannot carry.

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

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

Front-loaded with a clear 'What this API does' heading and organized into steps, but the body is heavy with doc links, a 'Good for' marketing block, and a 'Cost' section that could be compressed. It is structured rather than bloated to the point of uselessness, but a nontrivial share of the text does not earn its place for tool selection.

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

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

With an output schema present, return-value explanation is not required, yet the description still usefully explains the async lifecycle and where downloads live. Combined with the upload prerequisites and model defaults, an agent has enough to invoke correctly; only sibling disambiguation among create-video tools 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 86%, so the schema already documents model defaults, resolution tiers, and duration limits; the description largely restates those. It does add cost-adjacent context and mentions fields (face_swap_mode) that do not appear in the schema, which is slightly confusing, but the net value over the schema is marginal.

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 Video Editor you can make in the browser, but programmatically') and scopes it to an async job. However, it never distinguishes itself from near-identical siblings such as video_to_video_create_video, character_replace_create_video, or face_swap_create_video, so an agent must infer the boundary from the option list.

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

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

'Good for: Automation and batch processing / Adding video editor into apps, pipelines, or tools' is marketing framing rather than selection criteria against siblings. The MCP guidance does give clear follow-up routing (call wait_for_video_project or poll GET /v1/video-projects/{id} until complete/error/canceled), which is genuinely useful, but no when-not-to-use or alternative-tool guidance exists.

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

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

Annotations only cover readOnly/openWorld/destructive. The description goes well beyond: it discloses the async job model, that only rendered frames are charged, that an estimate appears at queue time, the exact return fields (id, credits_charged), and that the wait helper returns exact_download_urls separately from expiration metadata. It also warns that hotlinked public URLs can fail and to prefer the presigned upload flow.

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 with the core purpose and a clean 3-step workflow, and the MCP guidance block carries the highest-value operational detail. Some framing ('Good for', product-page link, marketing tone) is padding an agent does not need, keeping it from 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 async, nested-schema, open-world generation tool with an output schema, this covers everything an agent needs: the upload prerequisite, the async lifecycle, the polling/wait alternative, cost behavior, and URL reliability caveats. 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 coverage is already 100%, so the baseline is 3, but the description adds genuine meaning: the upload-URL -> file_path workflow for *_file_path values, the fallback behavior of direct public URLs, and resolution plan gating (free tier limited vs paid HD). The 576px vs 480p wording differs slightly from the schema but is not contradictory.

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 ... Video Translator ... programmatically'), and the mention of translation targets and the target_language parameter make the purpose unambiguous. It does not explicitly distinguish itself from close siblings like auto_subtitle_generator or lip_sync_create_video, so it stops short of a 5.

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

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

It names concrete use cases ('automation and batch processing', 'pipelines or tools') and, in the MCP guidance, explicitly routes the agent: the call returns an id immediately and the agent should call wait_for_video_project or poll GET /v1/video-projects/{id} for a finished result. That is an explicit when/when-not with a named alternative.

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

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

Annotations only declare readOnly=false, destructive=false, openWorld=true; the description adds substantial context beyond that: the job is asynchronous, returns id plus credits_charged immediately (cost awareness), the terminal statuses, and that completed projects carry download URLs and expiration metadata. This is exactly the behavioral detail an agent needs to drive the tool correctly.

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 the cost formula are front-loaded in two short sentences, followed by two tightly scoped bullet points that each carry non-redundant information. Slightly verbose in the guidance block, but nearly 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?

Given an output schema exists, the description needn't explain return values, and it correctly covers the async lifecycle, follow-up tool, and asset-sourcing prerequisites for a 7-parameter nested-schema mutation. The only meaningful gap is absence of sibling differentiation among the many create_video 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 100%, so 3 is the baseline, but the description adds cross-parameter meaning the schema does not: the estimated frame cost depends jointly on fps and end_seconds, and it clarifies acceptable sources for the *_file_path parameters. That is genuine added semantics rather than restatement.

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 combination ('Create a Animation video') and the schema reveals a style/art_style/camera-effect pipeline that distinguishes it in substance from generic video creation. However, it never explicitly separates itself from the many sibling *_create_video tools (text_to_video, image_to_video, ai_video_editor), so an agent must infer the distinction from the schema rather than the prose.

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

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

It gives explicit follow-up guidance: this starts an async job, and the agent should call wait_for_video_project or poll GET /v1/video-projects/{id} until complete/error/canceled. It also states a clear preference for the presigned upload flow over hotlinked URLs for *_file_path values. It stops short of naming when to choose this tool over the other video-creation 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is structured data. The description reinforces irreversibility and adds that the deleted artifact is the rendered audio file(s), but does not disclose side effects such as whether the project record survives or whether deletion cascades.

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

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

Two short sentences, front-loaded with the action and its permanence. No filler.

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

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

For a single-parameter destructive tool with annotations covering the safety profile and no output schema, this is minimally adequate. It omits side effects (record deletion vs file deletion), failure modes, and prerequisites, which an agent calling a permanent delete would benefit from knowing.

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

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

With one parameter at 100% schema description coverage, the schema already documents the id fully, including where the value comes from. The description adds nothing about the id, so the baseline 3 for schema-heavy coverage 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 ('Permanently delete') and a specific resource ('the rendered audio file(s)'), which lets an agent distinguish it from audio_projects_retrieve_details and the parallel image_projects_delete / video_projects_delete siblings.

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

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

There is no guidance on when to use this tool versus alternatives, nor prerequisites such as ownership or project state. The only directive is a generic caution ('please be sure before deleting'), which is a warning rather than a usage rule.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations by enumerating every status value, disclosing that `downloads` is only populated after a successful render, and warning that the signed URL must be used verbatim. This is exactly the kind of behavioral context the structured fields cannot carry.

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

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

Front-loads the one-line purpose, then uses bolded sections for statuses and MCP guidance. Well organized, though the status list is somewhat verbose for a tool whose output schema already returns the status 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?

With an output schema present, return-value detail is unnecessary, yet the description still covers status lifecycle, the timing of `downloads` population, and correct URL handling. Nothing an agent needs to call and interpret this tool 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 single `id` parameter is already documented in the schema, including where the value comes from. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ('Check the progress of a audio project') and implicitly scopes it to the audio variant, setting it apart from the video_/image_ retrieve_details siblings. 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?

Explicitly says to use it after a create tool to poll job status, and instructs what to do at `complete` (surface downloads) and `error` (surface error message). It never names the sibling `wait_for_audio_project`, which is the obvious alternative for blocking/polling, so the routing guidance is incomplete.

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

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

Annotations only cover readOnly/destructive/openWorld; the description adds substantial context beyond them — that it is an async job returning id plus credits_charged immediately, the complete/error/canceled terminal states, that credits are charged only for rendered frames with an estimate then final total, and that hotlinked URLs may fail so the presigned upload flow should be preferred.

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 and organized under clear headers, but considerably longer than needed for invocation and padded with template text (product page link, 'Key options' list of fields that don't exist on this tool). Several sentences 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?

For a complex async generation tool with nested params and an existing output schema, the description supplies everything an agent needs: the async lifecycle, the wait helper, download locations, cost behavior, and file-path sourcing — no critical gap remains.

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 schema already documents every field including the nested assets. The description adds useful file_path handling guidance but also references fields not present here (e.g. face_swap_mode) and a '576px' free-tier limit that conflicts with the schema's 480p/720p/1080p 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?

States a specific verb+resource ('Create ... Audio To Video ... programmatically') and lists intended uses like adding audio to video. However, it never distinguishes this tool from the many create_video siblings (image_to_video, text_to_video, video_to_video), and the copy-pasted 'depending on project type' phrasing weakens specificity.

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 'Good for' context and a concrete 3-step workflow, and the MCP guidance explicitly tells the agent to use wait_for_video_project or poll GET /v1/video-projects/{id} for the finished result. It lacks an explicit statement of when to prefer this over 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?

Annotations only declare readOnlyHint=false, destructiveHint=false, openWorldHint=true – a bare minimum. The description adds substantial value: it discloses that this is an async job returning id + credits_charged immediately, explains the polling lifecycle (complete/error/canceled), notes that completed projects include downloads with direct URLs, and warns that hotlinked URLs may fail so the presigned upload flow should be preferred. This is behavior beyond what annotations provide.

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 purpose, then a labeled 'MCP guidance' block that is scannable. Two paragraphs are dense but each sentence carries actionable information about async workflow or file handling; no filler. Slightly long but justified by the complexity.

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

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

Despite the tool being a 5-param nested async job with no output schema for the initial call, the description covers the full lifecycle: dispatch, polling alternative, terminal statuses, download URL availability, and file-source pitfalls. Combined with the 100% schema coverage, an agent has everything needed to invoke 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 schema already documents all 5 parameters including the nested style custom_config and assets. The description adds specific operational guidance for *_file_path values (prefer Magic Hour paths or upload-URL results; hotlinked URLs may fail) that isn't fully in the schema. Baseline 3 is appropriate given the schema's thorough documentation.

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: 'Automatically generate subtitles for your video in multiple languages.' This clearly distinguishes it from siblings like ai_video_translator_create_video (translation) or lip_sync_create_video (sync), and the resource (subtitles for video) is unambiguous.

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 clearly explains the async workflow and directs the caller to wait_for_video_project or the GET endpoint, naming the alternative explicitly. It doesn't state when NOT to use this tool versus e.g. video_translator, but the async/polling guidance is concrete and directly actionable.

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

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

Annotations are thin (readOnly=false, destructive=false, openWorld=true), and the description carries the load well: it discloses the async job contract (immediate id + credits_charged), terminal statuses, download URL availability, credit cost varying with resolution, and the file-path provenance requirement. It also states authorization/acceptable-use limits, which is meaningful behavioral context for a likeness-swap 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?

Purpose and cost driver are front-loaded in the first sentence, followed by clearly bulleted operational guidance. Slightly dense and references internal helper/endpoint names, but every sentence contributes 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?

An output schema exists, so return values need not be re-specified, and the description nonetheless covers the async lifecycle, terminal statuses, download output, and input provenance. For a 3-parameter async generation tool, nothing an agent needs to invoke and complete the flow correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by tying the resolution parameter to credit cost ('from 50 credits at 640px upward') and by explaining how *_file_path values should be sourced. The nested assets object and its two required paths are already documented 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 + resource ('Swap a person into a scene image') and even names the underlying models per resolution tier, so the operation is unambiguous. It does not, however, differentiate itself from close siblings like face_swap_photo_create_image or head_swap_create_image, leaving the agent to guess which swap tool fits.

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 context: it says the job is async, that the agent should call wait_for_image_project or poll the GET endpoint until terminal status, and that file paths should come from the presigned upload flow rather than hotlinked URLs. It stops short of stating when to prefer this tool over sibling swap/edit tools, which is the only gap.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds substantial context beyond them: async job semantics, immediate return of id plus credits_charged, credit billing based on rendered frames, and polling/status transitions. It also adds an important usage restriction (own likeness only, no impersonation/minors).

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 header-based structure is front-loaded and scannable, but it is long and includes promotional material ('For detailed examples, see the product page', 'Good for' bullets) that does not help an agent select or invoke the tool. The operational guidance in the MCP section is dense and useful, but the marketing prose dilutes it.

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

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

For a complex async, nested-schema tool this covers everything an agent needs: the upload prerequisite and file_path convention, the create-then-poll workflow, the terminal statuses, and where downloads appear. The output schema exists, so it need not explain return shapes, and the extra legality/safety note is a bonus.

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 with examples, enums, and nested structure; the baseline is 3. The description's 'Key options' section adds plan-tier context (free users limited in resolution) but also mentions fields like face_swap_mode that are not in this schema, which is mildly misleading rather than additive.

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 the same Character Replace you can make in the browser, but programmatically') and names the key options, so an agent knows this produces a character-replacement video. It does not explicitly contrast itself with close siblings like face_swap_create_video or body_swap_create_image, so the agent must infer the distinction 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?

It gives clear triggering contexts ('Automation and batch processing', 'Adding character replace into apps, pipelines, or tools') and, in the MCP guidance, explicitly routes to the wait_for_video_project helper for the finished result. No exclusionary guidance against sibling video-generation tools is given, but the positive usage framing is concrete.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true and destructiveHint=false, so safety profile is partly covered. The description adds genuinely useful behavior beyond that: it starts an async task returning an `id`, warns hotlinked URLs can fail, and notes pricing is temporarily free — context an agent cannot get from the annotations.

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

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

Front-loaded purpose followed by usage and MCP-specific guidance; each section earns its place. The pricing note is tangential but brief, and the overall length stays proportionate to the workflow complexity.

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

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

With an output schema present, return values need not be explained, and the description completes the async two-step workflow (create task → retrieve details). It is nearly complete; an explicit note on task failure/timeout handling would close the remaining gap.

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

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

Schema coverage is 100%, so both parameters are already documented, including the confidence_score semantics. The description still adds value by advising the presigned upload flow over direct public URLs for `*_file_path`, though it says nothing about confidence_score beyond what the schema provides.

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

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

States a specific verb and resource ("Detect faces in an image or video") and frames the result as a list of faces usable downstream. It is clearly distinguished from the sibling face_detection_retrieve_details, which it names as the follow-up step.

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 use it (to obtain face lists for multi-face face-swap photo/video calls) and routes the agent to the details endpoint for retrieval. It lacks an explicit "do not use this if..." exclusion, 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered externally. The description adds the downstream purpose (feeding multi-face swaps), which is useful but not a behavioral trait of the call itself; it says nothing about latency, pagination, or what constitutes a completed task vs a pending one.

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 core purpose and followed by the practical downstream use. No redundant restatement of the title, though the second sentence is a bit long with two embedded links.

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 the description need not explain return values, and the annotation block covers the read-only safety profile. The description supplies the caller's reason for retrieving details (multi-face swap inputs), which is the main thing the structured fields cannot convey. Minor gap: no mention of task state 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% with a single required 'id' parameter whose description already explains it is returned by the face detection API. The description adds no syntax, format, or constraint beyond that, so the baseline of 3 for fully-covered params 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 opens with a specific verb and resource: 'Get the details of a face detection task.' It is distinguishable from the sibling face_detection_detect_faces (which creates/initiates the detection) and from other *_retrieve_details tools by naming the face detection resource. It stops short of explicitly contrasting with the detect_faces sibling, so it earns a 4 rather than a 5.

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

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

It gives clear usage context: use this to fetch the detected face list so it can be supplied to the face swap photo/video APIs for multi-face swaps. That tells the agent the workflow position (after detection, before swap). It does not explicitly state when-not to use it or name the alternative detect_faces tool, so it is 4 rather than 5.

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

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

Annotations only say non-read-only, non-destructive, open-world; the description goes well beyond that by disclosing that the call is async and returns id + credits_charged immediately, that credits are charged per rendered frame, that free users are capped at 576px, and that hotlinked URLs may fail in favor of the presigned upload flow. It also states an authorization/consent constraint (own likeness only, no impersonation/minors).

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 with a clear 'what this does' header, but it is long for a tool description and repeats itself: the async/credits/wait-helper points appear both in the body and again under 'MCP guidance', and 'What this API does' opens with marketing framing rather than the operation.

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, nested, async generation tool with an output schema, the description covers the full lifecycle (upload -> create -> poll -> download), the credit model, and the wait helper, so nothing an agent needs to invoke it correctly is missing. Return-shape detail is rightly left to the output schema.

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

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

Schema description coverage is already 100%, so the baseline is 3; the description adds marginal but real value by naming the notable knobs (face_swap_mode, start_seconds/end_seconds, resolution) and by clarifying that *_file_path values should come from the upload-URL flow rather than arbitrary URLs. It does not resolve the ordering/validation rules between start_seconds and end_seconds beyond what the schema says.

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 Face Swap ... programmatically') and the medium (video), which cleanly separates it from the photo sibling face_swap_photo_create_image and from character_replace_create_video. An agent can identify what this 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' section gives context (automation, batch processing, embedding in apps/pipelines) and the MCP guidance routes follow-up work explicitly to wait_for_video_project or the GET endpoint. It does not, however, contrast itself against other video-creation siblings, so the alternative-selection guidance is implicit rather than stated.

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

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

Annotations only declare a non-destructive open-world write. The description adds substantial context beyond that: it is an async job returning id plus credits_charged immediately, each photo costs 10 credits, output dimensions vary by subscription, completed projects expose downloads with expiry metadata, and it carries an explicit authorization/ethics restriction (own likeness only, no impersonation, sexual content, or minors). This is exactly the behavioral context the annotations cannot supply.

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 and the 10-credit cost are front-loaded ahead of the pricing link, and the guidance is organized into scannable bullets. It is somewhat long, with some boilerplate that repeats across the image-generation family, but no sentence is pure filler.

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

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

For a nested-object tool with a 100% documented schema and an output schema, the description supplies everything the agent still needs: the async lifecycle and which helper to call, credit cost, dimension caveat, file-path sourcing rules, and usage restrictions. Return-value details are reasonably left to the output schema.

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

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

Schema description coverage is 100%, so the baseline is 3; the description lifts it by adding file-path semantics that the schema does not (prefer a Magic Hour file_path or the upload-URL endpoint's returned file_path, since hotlinked public URLs can fail). It does not touch face_swap_mode or face_mappings, but those are fully documented in the schema.

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

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

The description opens with a specific verb+resource ("Create a face swap photo") and states cost. It is immediately distinguishable from async siblings that generate video, but it does not differentiate itself from near neighbors like head_swap_create_image, body_swap_create_image, or ai_face_editor_edit_image, so the agent must open the schema to choose among them.

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

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

The MCP guidance is unusually explicit about workflow: call wait_for_image_project or poll GET /v1/image-projects/{id} until terminal status, and prefer the presigned upload flow when file URL stability is in doubt. It stops short of saying when NOT to use this tool versus the sibling face/head/body-swap tools, so it lacks the exclusion/alternative coverage that would earn a 5.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description goes beyond that by disclosing the return format (inline MCP audio content), the client-compatibility caveat, and the URL/expires_at distinction. It does not describe max_bytes truncation behavior, so it is not exhaustive.

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 the critical URL-handling constraint immediately after. No filler. Minor grammar slip ('a audio') but structure is efficient.

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

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

With no output schema, the description correctly explains the return value (inline audio content) and the preconditions for calling. The one gap is the undocumented max_bytes parameter, which affects behavior when large audio downloads are fetched.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does this well for download_url (exact signed URL, no trimming, expires_at is separate metadata), but max_bytes is never mentioned despite having a default and implying a size limit. One of two params is effectively undocumented.

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 download from a completed audio project) and the return shape (inline MCP audio content). This clearly separates it from the sibling fetch_image_download and fetch_video_download tools by media type.

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

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

Gives an explicit precondition (project must be completed) and a precise invocation rule (pass the exact full signed URL from downloads[n].url without trimming query parameters). It does not name the alternative entry point such as wait_for_audio_project or explain when to prefer this over retrieving details, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior: the result is inline image content rather than a link, it depends on the download URL remaining unmodified, and expires_at is metadata rather than part of the URL.

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

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

Two sentences, no filler. The core action and return type come first, and the signed-URL caveat follows immediately. Every clause adds information an agent needs.

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

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

There is no output schema, and the description correctly explains what is returned (inline MCP image content) plus the client-compatibility caveat. The only real gap is the undocumented max_bytes parameter.

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

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

Schema description coverage is 0%, so the description must carry the burden. It handles download_url well (pass the exact full signed URL, including query parameters), but max_bytes is never mentioned and the expires_at clarification is about a field that is not a parameter. Partial compensation only.

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) and resource (image download), names the source field (`downloads[n].url`), and states the return form (inline MCP image content). This clearly separates it from siblings like fetch_video_download and fetch_audio_download.

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 scopes usage to a 'completed image project' and to 'compatible clients', which tells the agent when the tool is applicable. It does not explicitly name wait_for_image_project or state what to do when a client is incompatible, so it falls short of full when/when-not routing.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false. The description adds useful behavioral detail beyond annotations: return as an embedded binary resource for compatible clients, and careful handling of signed URL query parameters versus expires_at metadata. It does not cover max_bytes limits or failure modes, but is solid.

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 tightly written sentences, front-loaded with the action and return type. Every clause adds distinguishing or usage-relevant 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?

For a simple binary-fetch tool whose annotations cover safety, the description explains the return format and URL constraints adequately. The main remaining gap is the unexplained max_bytes parameter, but overall it enables correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It explains download_url well, including that it must be the exact full signed URL and that expires_at is separate metadata, but it never explains the max_bytes parameter, leaving one of two parameters semantically undocumented.

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'), resource ('video download'), and return mechanism ('embedded MCP binary resource'), distinguishing it from similar tools like fetch_audio_download and fetch_image_download. It is not a tautology and gives an agent a clear target.

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

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

Provides clear usage context: fetch from a 'completed video project' and pass the exact full signed URL. It does not explicitly name an alternative or when-not condition, but the context is sufficient for correct invocation.

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

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

Annotations cover only the safety profile (readOnlyHint false, destructiveHint false, openWorldHint true). The description goes well beyond: it discloses pricing (10 credits per image), that the call is async and immediately returns id plus credits_charged, how to poll/wait, that completed projects include downloads, and the file-path/upload-flow requirement. This is rich, non-redundant 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?

Purpose is front-loaded in the first sentence, followed by structured MCP-guidance bullets that each carry distinct information (async flow, file paths, ethics). It is somewhat dense and long, but nearly 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?

For a multi-step async generation tool with nested required assets, the description covers the async lifecycle, result retrieval, cost, file-path sourcing, and policy constraints. Although an output schema exists, the extra retrieval guidance for an async job is genuinely necessary and present.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters including the file-path format and max_resolution clamping. The description's note that max_resolution can be set below the plan maximum largely restates the schema's clamping note. Baseline 3 applies 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?

The opening line states a specific verb and resource: 'Swap a head onto a body image.' An agent instantly knows the transformation performed. It falls short of a 5 because it does not differentiate itself from close siblings like body_swap_create_image or face_swap_photo_create_image, which an agent selecting between image-swap tools would need.

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 an async job, how to retrieve results via wait_for_image_project or polling, and how to supply file paths. The ethical constraints ('own likeness or authorized content') add usage boundaries. It lacks explicit when-to-use-this-vs-sibling guidance for the other swap 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?

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds substantial context beyond them: the exact cost (5 credits), that it returns id plus credits_charged immediately, the async lifecycle with terminal states, and that completed projects include download URLs. This is far richer than the annotations alone.

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 lines, followed by tightly organized guidance bullets. It is fairly long, but each sentence (async lifecycle, file path sourcing) carries actionable information without filler.

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

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

Given a 2-parameter tool with nested assets, an existing output schema, and annotations covering the safety profile, the description supplies everything an agent needs: cost, async handoff, terminal states, and file-path sourcing rules. Nothing required for correct invocation is missing.

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

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

Schema coverage is 100% and the schema already documents name, image_file_path, and background_image_file_path in detail. The description adds meaning beyond the schema by prescribing how to obtain valid *_file_path values (prefer existing Magic Hour paths or upload-URL endpoint results, hotlinked URLs can fail, use presigned upload flow when in doubt). This compensates usefully rather than merely restating.

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 ('Remove background from image'), which clearly differentiates this tool from sibling image tools like ai_face_editor_edit_image or photo_colorizer_create_image. It does not explicitly name or contrast a sibling, but the operation is unambiguous on its own.

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 gives clear operational context: it explains the async job pattern and explicitly recommends calling wait_for_image_project with the returned id or polling GET /v1/image-projects/{id} until terminal status. It does not address when to choose this tool over other image-editing siblings, but the within-tool usage guidance is strong.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description corroborates with 'Permanently' and 'not reversible', which adds a degree of permanence specificity, but discloses nothing new about auth requirements, side effects, or what happens to dependent 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, the destructive nature front-loaded, and the irreversibility warning immediately following. No filler and nothing that could be cut without losing meaning.

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

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

For a one-parameter delete tool with full schema coverage and annotations carrying the destructive flag, the description is sufficient; the gap is only the absence of guidance on verifying the target or handling dependents before deletion. No output schema exists, so no return-value explanation is required.

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

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

Schema description coverage is 100% and the single 'id' parameter is already explained in the schema (including the note that POST APIs return it). The description adds no format or sourcing detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Permanently delete the rendered image(s)'), making it clearly distinguishable from video_projects_delete and audio_projects_delete by resource. It does not explicitly name those siblings, but the resource noun does the disambiguating work.

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 warning 'please be sure before deleting' implies this is a deliberate, confirm-first action, but there is no explicit when-to-use guidance and no mention of alternatives such as image_projects_retrieve_details for checking before deleting. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety needs no restating. The description adds real value beyond them: the full status vocabulary, the fact that `downloads` is only populated after a successful render, and the warning not to alter the signed download URL.

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 action, then a scannable status list and a short guidance block. Every line carries information an agent needs; nothing is padding.

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

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

For a read-only status-poll tool with a full output schema, annotations and a single documented parameter, the description covers the remaining unknowns: what each status means and how to treat the returned download URLs. Nothing needed 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 single `id` parameter is fully documented in the schema, including where the value comes from. The description adds no syntax or format detail for the parameter, which is the expected baseline when the schema does 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 opens with a specific verb+resource ('Check the progress of a image project') and enumerates the status lifecycle, so an agent knows exactly what is returned. It does not, however, explicitly contrast itself with the sibling wait_for_image_project, which is the natural near-duplicate for polling.

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

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

It gives clear context ('Use this after a create tool to poll job status') and conditional next steps for the `complete` and `error` cases. It never names wait_for_image_project as the blocking alternative or states when-not to use this tool, so the routing guidance is incomplete.

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

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

Annotations already declare a non-destructive, open-world write, so the bar is lower; the description still adds meaningful behavior: the job is async and returns id plus credits_charged immediately, credits are charged only for rendered frames, and polling terminates at complete/error/canceled with downloads returned on completion. That is substantial lifecycle and cost context beyond the annotations, though it omits idempotency/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?

The MCP guidance paragraph is dense and valuable, but the marketing preamble ('run it at scale, or connect it to your own app or workflow') and the partly inapplicable 'Key options' list pad the definition. It is front-loaded with a clear purpose, yet several sentences do not earn their place for an agent deciding how to call it.

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

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

With an output schema present, return values need not be explained, and the description covers the async job lifecycle, cost model, and upload prerequisite well. The remaining gap is sibling differentiation among the many *_create_video tools, which matters given this crowded toolset.

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 and the schema carries the enum/duration/resolution detail. The description's file_path guidance (prefer an existing Magic Hour path or a presigned upload result) adds a little value, but its 'Key options' list cites fields like face_swap_mode and start_seconds that are not in this schema, which is generic boilerplate that could mislead rather than clarify.

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 the same Image To Video... programmatically') and the name/title reinforce image-to-video generation. However, it never distinguishes itself from close siblings like text_to_video_create_video or video_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?

It lays out the 3-step workflow (upload, create job, poll) and explicitly routes the agent to the wait_for_video_project helper or GET /v1/video-projects/{id} for finished results, which is real routing guidance. But it gives no guidance on when to pick this creation tool over the other video-creation siblings, so the when-to-use-vs-alternatives burden is only half met.

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

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

Annotations only declare readOnly=false, destructive=false, openWorld=true; the description goes far beyond by disclosing that this is an async job returning `id` plus `credits_charged` immediately, that credits are charged per rendered frame, that completion yields `downloads` URLs, and that the wait helper also returns `exact_download_urls`. It also adds file_path sourcing caveats (hotlinked URLs can fail) and an authorization/usage policy.

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 front-loaded with headers and a numbered 3-step flow, and the MCP guidance is placed last where an agent needs it. It is longer than necessary, with the 'What this API does' and 'Good for' sections partly restating each other, but no sentence is actively harmful.

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-schema, async, credit-metered generation tool, the description covers the full lifecycle: prepare inputs, submit, poll/wait, download. Output schema exists so return values need not be detailed, yet the description still clarifies the immediate response and the credit/estimate behavior.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real value on top by explaining file_path sourcing for `*_file_path` fields, the presigned-upload flow, the free-tier 576px resolution cap versus paid HD, and the role of start/end seconds. Mentioning a `face_swap_mode` field that is not in this schema is mildly noisy but not misleading.

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 Lip Sync available in the browser, with concrete inputs (video, image, or audio) implied. However, it never distinguishes itself from the closest sibling, ai_talking_photo_create_talking_photo, which also animates a face to audio — an agent could plausibly confuse the two.

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

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

Gives clear context for use ('Automation and batch processing', 'Adding lip sync into apps, pipelines, or tools') and the MCP guidance explicitly routes the agent to wait_for_video_project or the GET /v1/video-projects/{id} poll for the finished result. No explicit when-not-to-use or sibling-alternative comparison is offered.

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

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

Annotations only cover the safety profile (readOnly=false, destructive=false, openWorld=true), so the description carries real additional value: it discloses the 10-credit cost per image, the async job semantics, the immediate return of id plus credits_charged, the terminal status values, and the downloads/exact_download_urls on completion. This is exactly the behavioral context an agent cannot get from the annotations.

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

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

Front-loads the core action and its cost ('Colorize image. Each image costs 10 credits.') before the structured MCP guidance bullets, which is good ordering. The idempotent wait-helper detail about exact_download_urls versus expiration metadata is extraneous for tool selection and costs it a point.

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

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

With an output schema present, the description is not obligated to enumerate return fields, yet it still covers the async lifecycle, cost, follow-up tool, and file-path sourcing rules. Nothing an agent needs to invoke this nested-parameter tool 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 and the schema already documents both name and assets.image_file_path. The description nonetheless adds non-obvious meaning: that hotlinked public URLs can fail and that the presigned upload flow with its returned file_path is the safe path, which is a real caveat 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 leads with a clear verb+resource ('Colorize image'), which is specific enough to separate it from siblings like ai_image_upscaler_create_image or image_background_remover_create_image. It does not explicitly name a competing tool or state when this is the wrong choice, so it falls just short of 5.

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

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

The guidance gives concrete operational routing: it tells the agent this returns immediately and to follow up with wait_for_image_project (or poll GET /v1/image-projects/{id}) until a terminal status. It also gives prescriptive advice on sourcing *_file_path values. What's missing is any statement of when to use this colorizer versus other 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered structurally. The description adds that the check targets server reachability, but does not disclose latency, timeout, or what 'reachable' means in practice.

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 waste; the purpose and target are both in the first clause.

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

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

An output schema exists, so return-value details need not be repeated. For a zero-parameter health-check tool whose annotations cover safety, the description is sufficient, though it could note what a failure response implies.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies.

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

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

States a specific verb ('Check') and resource ('Magic Hour MCP server') with the exact condition being tested ('is reachable'). No sibling tool offers a health/connectivity check, so it is trivially distinguishable.

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

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

The description implies the usage context (verify connectivity), but does not state when to call it versus alternatives, nor whether it should precede other calls. For a trivial one-purpose tool this is adequate but unstated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: newest-first ordering, account-scoped ownership, the durability distinction between file_path and the temporary signed URL, and the pagination contract.

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

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

Four sentences, each carrying information, front-loaded with what is returned before filtering and pagination details. Slightly long but nothing is 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 spelled out, yet the description still clarifies the two URL types an agent will encounter. Combined with annotations and full param coverage, nothing needed to invoke it correctly is missing; only an explicit no-result/edge-case note 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 coverage is 100%, so type, limit, and cursor are all fully documented in the schema; baseline 3 applies. The description's restatement of the type filter and cursor mechanics adds convenience but no meaning beyond what the schema already provides.

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

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

States a specific verb and resource ('Returns active saved items owned by the authenticated account, newest first') and defines the resulting payload (assets with durable file_path plus temporary signed URL). An agent immediately knows this is a read of the account's own saved assets, distinct from the many create/retrieve siblings.

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

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

Gives clear context: use the type filter to find characters, references, voices, moodboards, or brand kits, and pass next_cursor as cursor to page. No explicit when-not-use or named alternative, but the read-only listing role is unambiguous.

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

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

Annotations only declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description carries the real behavioral load and does it well: it discloses async semantics, that it returns id plus credits_charged immediately, that credits are billed only for rendered frames, the queue-time estimate vs final total, terminal statuses (complete/error/canceled), and that downloads carry expiration metadata. None of this is recoverable from 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?

Headings ('What this API does', 'Good for', 'How it works', 'Key options', 'Cost') make it skimmable and the 3-step flow is clear. It is somewhat long with promotional framing ('the same Text To Video you can make in the browser') and repeated docs links, and the most actionable content (MCP guidance on polling) sits last.

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 an output schema, the description covers prerequisites (upload + file_path), the create/poll/download lifecycle, cost model, and tier-based resolution limits, so an agent has enough to invoke and follow up correctly. It is docked for the misleading extra-field list that names parameters this schema doesn't accept.

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% and per-model constraints for model, resolution, aspect_ratio and end_seconds are already exhaustively documented in the schema, so the description adds little. It also introduces noise: it cites 'face_swap_mode' and 'start_seconds/end_seconds' as extra fields that do not exist in this tool's schema, and states free users are 'limited to 576px' while the schema says 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 names a specific verb+resource: creating a Text-To-Video generation job programmatically. It's distinguishable from siblings like image_to_video_create_video and video_to_video_create_video by name and by the 'text to video job' phrasing. It loses a point because the generic 'Upload your inputs (video, image, or audio)' step-1 boilerplate blurs the no-input, text-driven identity of 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?

The 'Good for' section gives clear context (automation, batch processing, embedding in apps/pipelines), and the MCP guidance explicitly routes the agent: call wait_for_video_project with the returned id or poll GET /v1/video-projects/{id} until a terminal status. It names the alternative helper, but doesn't state when NOT to use this tool 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?

Annotations declare a safe, non-destructive, non-open-world operation, so the safety burden is low. The description still adds real behavioral context: the response array order matches the request body, a PUT with the raw file bytes is required afterward, and valid extensions differ per asset type (including the gif-only-for-face-swap caveat). It omits auth/expiry behavior of the presigned URLs, 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?

Front-loaded with purpose, then constraints, then a concrete curl example and MCP guidance. It is somewhat long and repeats the extension list that already appears in the schema's `extension` description, which is the only real waste.

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

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

With an output schema present, return-value details are unnecessary, and the description instead covers the full workflow an agent needs: request shape, response ordering, the follow-up PUT upload, and how the resulting file_path feeds the create tools. 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 coverage is 100% with a nested items array, so the baseline is 3. The description adds value beyond the schema by categorizing extensions per asset type (video/audio/image/gif) and flagging that gif is only valid for a specific face-swap field, clarifying constraints the flat enum-less schema does not organize.

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 ('Generates a list of pre-signed upload URLs for the assets required') and immediately scopes it ('only necessary if you want to upload to Magic Hour's storage'). This cleanly separates it from the sibling *_create_* tools that consume the uploaded file paths.

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

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

It gives explicit when-to-use ('only if you want to upload to Magic Hour's storage'), a when-not by routing agents toward existing Magic Hour file paths or stable public URLs, and an alternative fallback ('when in doubt, use the presigned upload flow first'). The MCP guidance section names the ordering constraint relative to the create call.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so irreversibility is largely covered by structured data. The description restates permanence and adds that it targets the 'rendered video' specifically, which is minor added value over the annotation but no information about auth requirements or side effects on 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, front-loaded with the action and outcome. No filler, though the second sentence is somewhat redundant with the destructive annotation.

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

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

For a single-parameter destructive tool with full schema coverage and annotations carrying the safety profile, this is largely sufficient. The only meaningful omission is what happens to associated assets or whether the project can be recovered.

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

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

Schema coverage is 100% and the schema itself explains the id, including where it comes from ('returned by all of the POST APIs that create a video'). The description adds nothing beyond that, which is the expected baseline 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 specific verb (delete) and resource (rendered video) with a clear scope qualifier. It is distinguishable from create/retrieve siblings by the verb, but it does not explicitly name the analogous destructive siblings (image_projects_delete, audio_projects_delete) to confirm the parallel.

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 only guidance is a caution ('please be sure before deleting'), which is a warning rather than a when-to-use rule. There is no statement of prerequisites, of what happens to dependent resources, or of alternatives to deletion.

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

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

Annotations already declare readOnlyHint, openWorldHint, and destructiveHint, so the safety profile is covered. The description adds substantial operational context beyond annotations: status meanings, when downloads are populated, how to handle errors, and the critical detail that downloads[n].url is already a full signed URL that must not be modified.

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 its purpose, uses a compact status list, and follows with concise MCP guidance. Every sentence adds useful information for invoking or interpreting the tool correctly.

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

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

Given the tool's complexity, the existing output schema, and the annotations, the description is complete: it explains statuses, polling context, error handling, and download URL handling. Nothing essential for an agent to call and interpret the tool 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 single id parameter is already well documented in the input schema. The description does not add syntax, format, or usage detail beyond what the schema provides, so it meets the baseline for a fully covered parameter set.

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 clearly states the specific resource and action: checking the progress of a video project. It enumerates statuses and explains the downloads field, so an agent understands the tool's core output. However, it does not explicitly differentiate itself from similar siblings such as wait_for_video_project or the image/audio project detail tools.

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

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

It gives a clear usage context: use after a create tool to poll job status, and it specifies what to do on complete or error. It does not, however, name an alternative tool or state when not to use this tool, so it falls short of the explicit when/when-not/alternatives bar.

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

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

Annotations only declare the mutation/open-world profile, and the description substantially enriches them: it discloses that the call is asynchronous, returns id and credits_charged immediately, that credits are charged only for rendered frames with pre/post estimates, that free-tier resolution is capped at 576px, and that hotlinked asset URLs may fail. This is exactly the behavioral context an agent needs before invoking.

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?

Structure is front-loaded with headings and the operational MCP guidance is dense and useful, but several sentences are marketing filler ('automate it, run it at scale', 'For detailed examples, see the product page') that do not help an agent decide or call correctly.

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 and annotations already present, the description covers everything the agent needs: async semantics, the follow-up helper, asset-input prerequisites, cost model, and resolution constraints. Nothing essential to correct invocation is missing.

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

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

Schema coverage is 83%, so the schema already documents most fields; the description still adds value by flagging key option groups (inputs, resolution, face_swap_mode, start_seconds/end_seconds, text prompt) and by explaining the preferred form of *_file_path values and when presigned uploads are required. It does not cover the style sub-object choices in prose, but those are well enumerated in the schema.

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

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

The description states a specific verb+resource ('Create the same Video To Video... programmatically') and scopes it as an async job. It is clear what the tool does, but it never explicitly contrasts itself with adjacent transformation siblings such as face_swap_create_video, character_replace_create_video, or ai_video_editor_create_video, so the agent must infer the boundary from 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 'Good for' section and the MCP guidance give clear context (automation, batch processing, embedding in pipelines) and lay out the three-step workflow plus how to retrieve the finished result via wait_for_video_project or polling. It never states when NOT to use this tool versus the other video tools, so it stops short of explicit routing.

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

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

Annotations already declare a safe read (readOnlyHint=true, destructiveHint=false), so the description adds the genuinely non-obvious behavior: that it blocks/polls, that it opportunistically inlines audio downloads, and that returned download fields are sanitized. It does not say what happens to the caller (or the project) when the timeout is reached, which is the one behavioral 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 in the first clause, followed by return behavior and then the operational warning. Every sentence earns its place; only the URL-preservation sentence is verbose, though it is defensibly so given its correctness stakes.

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

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

With no output schema, the description does usefully sketch the return (final project JSON plus sanitized/inlined download fields), and it covers terminal conditions. However, for a 6-parameter blocking tool with 0% schema coverage, the input contract is left almost entirely unexplained, which is a real completeness gap.

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

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

Schema description coverage is 0% across 6 parameters, so the description must carry the meaning and it does not. Only timeout and inline-download behavior are hinted at ('times out', 'attempts to inline audio downloads'); poll_interval_seconds, max_bytes_per_download, include_inline_downloads, and the id semantics are never explained. The URL-handling advice concerns outputs, not inputs.

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 (poll/wait) plus resource (audio project) and enumerates the terminal conditions it waits on (complete, error, canceled, timeout). This clearly separates it from siblings like audio_projects_retrieve_details (a one-shot read) and wait_for_video_project/wait_for_image_project (different resources).

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

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

It conveys the core usage contract: call this when you need to block until the project reaches a terminal state, and it names the four terminal states that end the wait. It does not explicitly compare itself to a non-blocking retrieve sibling or state when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so safety is covered. The description adds real value beyond them: polling semantics, the shape of the return (final project JSON), inlining of image downloads, sanitized download fields, and a concrete warning not to shorten URLs or strip query parameters.

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

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

Three compact sentences, front-loaded with the polling behavior and followed by the URL-handling caution. No filler, though the URL sentence is dense and could be slightly tighter.

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

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

With no output schema, the description usefully sketches the return payload and URL handling, which is good. But for a 6-parameter tool at 0% schema coverage it leaves parameters (timeout, poll interval, byte limits, inline toggle) entirely unexplained, which is a meaningful gap for correct invocation.

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

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

Schema description coverage is 0% and there are 6 parameters (timeout_seconds, max_inline_downloads, poll_interval_seconds, max_bytes_per_download, include_inline_downloads, id). The description alludes to timeouts and inline downloads but never explains any parameter's meaning, defaults, or units, 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 (poll/wait) and resource (image project) plus the terminal conditions (completes, errors, canceled, times out). Clear enough to distinguish from wait_for_video_project and wait_for_audio_project, and from 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 terminal-state conditions imply when the tool applies (after creating a project, when you need to block until done), but there is no explicit statement of when to prefer this over image_projects_retrieve_details or fetch_image_download, nor any exclusions. Usage is inferable but not spelled out.

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

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

Annotations already declare readOnlyHint, destructiveHint, and openWorldHint, so the description adds meaningful context by disclosing polling behavior, terminal conditions (completes, errors, canceled, times out), and a URL-handling warning. It does not cover rate limits, auth needs, or timeout-side behavior, but it goes well beyond the structured safety hints.

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 with zero waste. The terminal-state behavior is front-loaded, and the second sentence delivers a necessary operational warning about URL handling.

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 tool with five parameters, 0% schema description coverage, and no output schema, the description is incomplete. It explains the polling purpose and return-field handling, but omits any explanation of what each parameter controls, which leaves the agent without enough information to invoke the tool precisely.

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

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

Schema description coverage is 0% and the description does not define any of the five parameters (id, timeout_seconds, max_inline_downloads, poll_interval_seconds, include_inline_downloads). It mentions timeout and download fields only as return/behavior concepts, leaving parameter semantics entirely undocumented.

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: poll a video project until it reaches a terminal state. It distinguishes itself from the sibling wait_for_image_project and wait_for_audio_project by naming the video project target.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives such as video_projects_retrieve_details or wait_for_audio_project. It describes the polling behavior but does not state prerequisites, exclusions, or when-not-to-use conditions.

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