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

With no annotations provided, the description carries the behavioral burden. The verb 'Get' implies a non-mutating read operation, and the scope of the account is clarified as the one owning the API key. However, it does not disclose things like authentication expectations, whether the call consumes credits, or response/error behavior; the simple nature of the operation keeps this from being more critical.

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, well-structured sentence conveys the purpose, the resource, and the scope of the account. There is no filler or repetition; every part of the sentence contributes 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 zero-parameter retrieval tool with an output schema present, the description is sufficient. It clearly states what is returned (credit balance and subscription details) and whose data is accessed (the API key owner). The output schema can handle the specific return structure, so no additional detail 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?

The tool has zero parameters, so the input schema is trivially complete and the description does not need to explain parameter behavior. The description still adds value by explaining what the returned data represents, which is more than the empty 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?

The description uses the specific verb 'Get' and names a precise resource: the current credit balance and subscription details of the API key owner's account. This clearly distinguishes it from the sibling tools, none of which target account or billing information.

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 clear context for when to use the tool: whenever an agent needs the account's credit balance or subscription details. It does not explicitly list when-not-to-use or name alternatives, but no sibling tool serves this purpose, so the usage context 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?

With no annotations, the description carries the full burden and succeeds: it discloses the async job model, immediate id and credits_charged return, terminal statuses, downloads behavior, and the 25-credit cost. It even highlights that the wait helper returns exact_download_urls separately from 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?

The description is compact and organized with a purpose statement followed by two scoped bullets. The only minor issue is the slightly promotional 'just a photo reference' phrasing, which is less precise than the schema's actual requirement of a person file and a garment file.

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 image-generation flow and lack of annotations, the description covers the end-to-end lifecycle: initiation, waiting, completion, downloads, and file input policy. The presence of an output schema fills in return-value details, so no critical gap remains for an agent to invoke this tool correctly.

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

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

The input schema already covers all parameters with descriptions, so the baseline is 3. The description adds meaningful operational guidance for *_file_path values: prefer existing Magic Hour paths or upload-URL file_paths, and use the presigned upload flow when hotlinked URLs are questionable. This goes beyond the schema's basic 'either URL or file_path' 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 opening sentence names a specific verb ('change') and resource ('outfits in photos'), making the tool's domain unmistakable. It implicitly differentiates this tool from sibling image-creation tools like face_swap_photo_create_image and head_swap_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 MCP guidance explicitly tells the agent what to do after invocation: use wait_for_image_project with the returned id or poll until a terminal status. It also gives file-path policy, preferring Magic Hour file paths or upload-URL file_paths over unstable hotlinked URLs. However, it does not explicitly state when to choose this tool over siblings like body_swap_create_image, though the use case is clear from the purpose.

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

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

With no annotations provided, the description carries the full disclosure burden and does so thoroughly. It explains that the call starts an async job, returns id and credits_charged immediately, how to poll for completion, and what statuses to expect. It also discloses cost, output dimension variability by subscription, and common file-path failure modes.

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 well-structured and front-loaded: purpose and cost first, then actionable MCP guidance in bullets. Every sentence adds value, and the formatting makes the async workflow and file-path rules easy to parse.

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 description is highly complete. It covers the async workflow, polling, completion statuses, download URLs, credit cost, output resolution caveats, and file input best practices. The detailed schema and output schema cover the remaining parameter and return-value details.

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

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

The schema already documents all parameters at 100% coverage, so the baseline is 3. The description adds meaningful extra guidance for file_path values, including preferring upload-URL file paths over hotlinked URLs and explaining when direct URLs may work. This goes beyond the schema descriptions.

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's function: 'Edit facial features of an image using AI.' This distinguishes it from sibling tools like face swap, body swap, or headshot generation. The purpose is specific, concrete, and easy to act on.

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

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

The description provides strong context for when to use the tool, such as editing facial features and handling async image generation. It gives explicit guidance on using wait_for_image_project after invocation and on preferring Magic Hour file paths over direct URLs. It does not explicitly name sibling alternatives or exclusion conditions, but the use case is clear enough.

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?

There are no annotations, so the description carries the full behavioral disclosure burden. It explicitly reveals that the tool starts an async job, returns id and credits_charged immediately, what terminal statuses exist, and how to retrieve the finished result and download URLs. This is strong transparency for a generation 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?

The description is compact and well-structured: a clear first sentence states the core action, and the MCP guidance bullet delivers the async workflow without unnecessary filler. Every sentence adds operational value.

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

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

Given the async nature of the tool, the description covers the essential lifecycle: immediate return, credit charges, waiting/polling, terminal statuses, and download URLs. The presence of an output schema further reduces the need to document return fields, making this description complete for correct invocation and follow-up.

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 schema already documents name, prompt, and output_format with meaningful descriptions. The description adds the credit-cost context but does not add extra semantics for the parameters themselves, so it neither fully compensates for uncovered schema gaps nor repeats the schema. A 3 is appropriate.

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

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

The description states a specific verb and resource: 'Create an AI GIF' followed by concrete detail on credit cost and async job behavior. It clearly distinguishes this tool from siblings like ai_image_generator_create_image by naming the output format (GIF) and the async generation model.

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 clear post-invocation usage guidance: it explains that the call returns immediately, and tells the agent to call wait_for_image_project with the returned id or poll the endpoint. It does not explicitly compare against alternative creation tools, so it earns a 4 rather than a 5.

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

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

With no annotations, the description carries the full behavioral burden, and it does so thoroughly. It discloses that this is an async job, that it costs 50 credits, that the immediate response contains id and credits_charged, and that the eventual project can reach complete/error/canceled states with downloads. It also warns that hotlinked URLs can fail, adding important reliability context.

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

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

The description is well structured: a one-sentence purpose and cost statement up front, followed by two focused guidance bullets. Every sentence carries operational value, and the async workflow and file upload constraints are presented in a scannable format without rhetorical filler.

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

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

Given the tool's async nature, cost implications, required asset, and nested schema, the description covers all critical contexts: how to obtain the final result, how to handle file paths reliably, and what to expect in the immediate response. The output schema exists, so there is no missing return-value burden. An agent can invoke and successfully complete the workflow using this description alone.

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

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

The schema already covers 67% of parameters, including name and style.prompt descriptions. The description adds substantial semantics for assets.image_file_path by explaining preferred file_path sources, the upload-URL flow, and risks of direct URLs. This goes beyond the schema's basic 'image used to generate the headshot' explanation, though it does not elaborate on name or style.

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 'Create an AI headshot,' a specific verb plus a clear resource, and immediately distinguishes it from the many sibling create_image tools by centering the headshot use case. The tool name reinforces this, so an agent can select it without ambiguity.

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

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

The MCP guidance explicitly tells the agent what to do after invocation: call wait_for_image_project with the returned id or poll the endpoint until completion, with concrete statuses. It also gives file_path selection guidance with a clear 'when in doubt, use the presigned upload flow first' directive, including when direct URLs may be acceptable.

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

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

With no annotations present, the description carries the full burden and delivers exceptionally. It discloses the async job model (returns id and credits_charged immediately), the exact completion states to poll for (complete, error, canceled), that completed projects include downloads with direct URLs, and that the wait helper returns exact_download_urls separately from expiration metadata. It also warns about the failure modes of hotlinked URLs and prescribes the safer upload flow — precisely the behavioral traits an agent cannot infer from the schema.

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

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

The purpose sentence is front-loaded and the MCP guidance is organized into two scannable bullets. The async-result bullet is tight and information-dense; the file-path bullet is slightly verbose but every clause carries actionable guidance. Given the tool's complexity (async, polling, upload flows), the length is justified.

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?

The description covers the operational essentials an agent needs: async return semantics, how to obtain results (wait helper or polling), completion states, download URLs, and file-path sourcing. An output schema exists, so return values need not be explained. The only gap is tool-selection context among sibling image tools — the description never explains when this general editor is preferred over specialized siblings.

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

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

Schema coverage is high (86%), so the schema already documents most parameters well. The description adds genuine value for the assets parameter by explaining how to source *_file_path values: prefer an existing Magic Hour file path or the upload-URL endpoint result, and prefer presigned uploads over potentially failing hotlinked URLs. This compensates for the schema's thin coverage of the assets field, which even contains a copy-paste error ('direct URL to the video file').

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 clear verb+resource: 'Edit images with AI.' This correctly conveys that the tool modifies existing images via a prompt rather than generating from scratch, which distinguishes it semantically from ai_image_generator_create_image. However, it does not explicitly differentiate it from the many other image-editing siblings (ai_face_editor_edit_image, photo_colorizer_create_image, etc.), so an agent must infer the general-purpose editing scope.

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 provides strong operational workflow context — how to handle the async job, when to call wait_for_image_project, and when to use the presigned upload flow. What it does not do is state when to choose this tool over the ~13 sibling image tools, and no alternatives are named. Usage is implied by name and schema rather than explicitly routed.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly states that the call starts an async job, returns id and credits_charged immediately, enumerates final statuses, and explains how completed projects expose downloads. This is thorough and directly actionable.

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

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

The description is compact and front-loaded: one sentence states the purpose, then a bullet of MCP guidance adds the essential async workflow. Every sentence earns its place, and there is no fluff or repetition of schema content.

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

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

Given the rich output schema and comprehensive parameter documentation, the description fills the critical gap the schema cannot: async behavior and how to obtain finished results. It names the helper, enumerates statuses, and notes download URLs, so an agent has everything needed to invoke and follow up correctly.

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

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

Schema coverage is 100% and every parameter is documented in detail, including model constraints, resolution options, and style defaults. The description adds little parameter-level meaning beyond the phrase 'advanced model selection and quality controls,' so the baseline 3 is appropriate.

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

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

The opening sentence identifies a specific action ('Create an AI image') and resource ('AI image') with a nod to model selection and quality controls. It does not explicitly differentiate this general-purpose generator from specialized siblings like ai_face_editor_create_image or ai_clothes_changer_create_image, though the name and 'advanced model selection' hint at its general role.

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 post-call instructions (call wait_for_image_project or poll GET /v1/image-projects/{id}), but it says nothing about when to select this tool vs the many sibling image generators. There are no alternative-based exclusions, so selection context is mostly left to the tool name and implied generality.

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

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

With no annotations, the description fully carries the behavioral disclosure burden. It discloses async behavior, immediate return value, polling statuses, download URL availability, credit costs per mode, and the deprecated 'pro' mapping. It also warns about hotlinked URLs potentially failing, which is important operational behavior for an agent to know.

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 well-structured: a one-sentence purpose plus credit summary, followed by clearly separated MCP guidance bullets. It front-loads the core action and pricing, then provides actionable async and file-handling details. Every sentence contributes useful information without 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?

Given the tool's async nature and the presence of an output schema, the description is remarkably complete. It covers the full lifecycle from invocation to result retrieval, including credit charges, polling statuses, download URLs, upload file path guidance, and mode caveats. An agent has enough context to call the tool and handle its response 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 parameters. The description adds meaningful value beyond the schema by explaining credit multipliers, mode behavior, and the preferred file path workflow. This goes beyond the baseline 3 without being redundant with 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 and resource: 'Upscale your image using AI.' This clearly distinguishes it from sibling tools like ai_image_editor_create_image or ai_image_generator_create_image, since upscaling is a unique operation among the siblings. The credit-cost detail further anchors what this specific tool does.

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

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

The description provides clear operational context: it starts an async job, returns an id immediately, and instructs when to call wait_for_image_project or poll the endpoint. It also gives explicit guidance on when to use presigned uploads vs direct URLs. It doesn't explicitly compare against sibling tools, but the usage context is strong enough for an agent to know when to invoke this tool.

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

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

With no annotations provided, the description carries the full behavioral burden, and it delivers: it discloses the 10-credit cost, the async job start returning id and credits_charged immediately, the polling mechanism with terminal statuses (complete, error, canceled), the downloads field with direct URLs, and the exact_download_urls distinction in the wait helper. It does not cover auth requirements or insufficient-credit failure behavior, but the disclosed workflow traits substantially exceed the minimum.

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 and cost are front-loaded, followed by a labeled 'MCP guidance' section that organizes the async workflow without fluff. The guidance is dense but each sentence earns its place (return contract, wait helper, polling statuses, download URLs). Slightly long, but the structure makes it scannable.

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, credit-charging tool with a nested style object and an output schema, the description covers the essential workflow: immediate return contract, how to obtain the final result, status values, and download URL handling. The output schema covers return values, so that omission is fine. Gaps are minor: no error/refund behavior on failure and no auth note, but the core call-and-retrieve lifecycle is fully explained.

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

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

The description adds no parameter-level meaning; all param semantics live in the schema, which describes name, topic, template (with full enum), and searchWeb. Schema description coverage is exactly 50% at the top level because the style object itself lacks a description, but its nested properties are well documented. The description neither compensates for the gap nor is it needed to, leaving this at an adequate midpoint.

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?

"Create an AI generated meme" states a specific verb (create) and resource (meme), clearly distinguishing it from the many sibling create_image tools such as ai_gif_generator_create_image, ai_image_generator_create_image, and head_swap_create_image. The added cost note (10 credits) reinforces what this specific operation entails. An agent can select this tool correctly based on the first sentence 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 description gives solid procedural guidance for the async workflow (call wait_for_image_project with the returned id or poll the endpoint), but it never says when to prefer this tool over sibling meme/image creators, nor does it name any alternative or exclusion. Usage context for the request orchestration is clear, but sibling-selection guidance is absent.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that the tool is asynchronous, returns an `id` and `credits_charged` immediately, and explains the completion statuses (`complete`, `error`, `canceled`) and the availability of `downloads` with direct URLs. It also mentions the exact_download_urls behavior of the helper. This is rich, honest, and goes well beyond minimal expectations.

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 well-structured and front-loaded. The first sentence states the core purpose and cost, and the MCP guidance block is organized into concise, directly actionable steps. Every sentence adds value, and it avoids redundant restatement of the schema.

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

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

The description covers everything needed to use this tool correctly in an agentic flow: async behavior, immediate return values, how to retrieve the finished result, which statuses to watch for, and where the output downloads live. Since an output schema exists, detailed return-value documentation is unnecessary. There are no meaningful gaps for calling this tool successfully.

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

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

Schema coverage is 67%, and the schema already provides useful descriptions for `name`, `content`, and `art_style`, including an example and template list for `art_style`. The description adds little parameter-level meaning beyond the schema, but it also does not need to because the schema is reasonably self-explanatory. A baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Create an AI QR code.' This clearly differentiates it from the many sibling image-generation tools in the list, which all have distinct purposes. The tool name and description align, and there is no ambiguity about what the tool produces.

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

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

The description provides explicit guidance on the async workflow: it says the generation starts immediately, returns `id` and `credits_charged`, and instructs the agent to call `wait_for_image_project` or poll the endpoint. It does not explicitly compare this tool to alternative image generators, but the QR-specific scope makes the primary use case obvious, and the async handling instructions are very 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?

With no annotations, the description fully discloses the async nature, immediate response fields, polling statuses, completion downloads, and exact_download_urls behavior. It also warns about hotlinked URL fragility and points to the presigned upload path, which is essential risk-relevant context.

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

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

The description is dense but well-structured: one-purpose opening sentence, async lifecycle guidance, then file-path handling. The MCP guidance section is front-loaded with the most consequential behavior (async + wait helper) and every sentence delivers actionable information.

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

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

For a complex async tool with no annotations, the description covers the full invocation lifecycle: what is returned, how to wait/poll, terminal statuses, download URLs, and file path sourcing. Output schema exists, so return-value documentation is not required, and nothing needed to call the 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?

Input schema covers 100% of parameters, so baseline is 3. The description adds meaningful file-path semantics beyond the schema by distinguishing Magic Hour file paths, upload-URL-returned file_paths, and direct public URLs, which directly affects parameter correctness.

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

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

The first sentence names a concrete operation—create a talking photo from an image plus audio—clearly separating it from siblings like text_to_video or image_to_video. However, the phrase 'audio or text input' is slightly misleading because the schema requires audio_file_path and no separate text input parameter exists; text only appears as an optional style prompt.

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 explicit post-invocation guidance: return of id/credits_charged, how to get finished result via wait_for_video_project or polling, and statuses to watch. It does not compare this tool against alternative creation tools, but the workflow guidance is clear enough for an agent to act correctly.

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

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

With no annotations, the description carries the full burden and exceeds it: it discloses that this is an async job that returns an ID immediately, requires polling or a wait helper, includes credit-cost behavior, explains file path preferences and potential URL failures, and notes free-tier resolution limits. This is rich behavioral transparency beyond basic schema data.

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 structured with clear headings, bullet points, and a numbered 3-step workflow. Every section serves a distinct purpose: what it does, use cases, how it works, key options, cost, and MCP-specific guidance. It is comprehensive without being redundant, and key operational details are front-loaded.

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

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

Given the tool's complexity (7 params, nested objects, async behavior, output schema), the description covers all necessary context: input preparation, job creation, status polling, result retrieval, cost model, and file path caveats. It also provides an output schema and clearly explains what is returned, so an agent has everything needed to invoke it correctly.

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

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

Schema coverage is high (86%), so the baseline is 3. The description adds meaningful parameter-related context, especially for `assets.video_file_path` (prefer existing Magic Hour file paths, presigned upload flow, hotlink risks) and resolution limits (free vs paid tiers). It also mentions optional fields like `start_seconds`/`end_seconds` and text prompts, supplementing 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 clearly states the tool creates the Video Editor programmatically, with explicit verbs ('Create the same Video Editor... but programmatically') and identifies the resource (video editor job). It distinguishes itself from sibling video-generation tools by focusing on the editor use case (automation, batch processing, integration into apps/pipelines).

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 clear context for when to use this tool ('Good for' automation and batch processing, adding video editor to apps) and explains the full workflow (upload inputs, create job, poll status). It does not explicitly name alternatives or exclusion conditions, but the 'Good for' and workflow guidance make usage context 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?

With no annotations provided, the description carries the full behavioral burden and excels: it discloses async job semantics, the immediate return of id and credits_charged, terminal statuses (complete/error/canceled), downloads with direct URLs, and the per-character cost model with rounding. This is precisely the kind of operational context an agent needs and cannot infer from the schema.

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

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

The description is front-loaded with the purpose sentence, followed by cost, then the async workflow, then file-input caveats — the right priority order. The bulleted MCP guidance keeps dense operational detail scannable, and every section earns its place; only the file-path paragraph is slightly wordy with its conditional clauses.

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 tool with nested objects, pricing implications, and an output schema, the description is remarkably complete: what it returns immediately, how to obtain the finished result, what terminal states look like, where downloads appear, and how to supply the input file correctly. Nothing an agent needs to drive this workflow end-to-end is missing.

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

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

Schema coverage is 67%, and the description adds real value beyond it — especially for audio_file_path, where it gives a preference order (existing Magic Hour path or upload-URL file_path first, direct URLs only when stable and fetchable) plus the failure mode for hotlinks. The cost-per-character detail also links the pricing model to the prompt parameter, supplementing the schema's character-limit note.

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

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

The opening sentence "Clone a voice from an audio sample and generate speech" states a specific verb and resource with no ambiguity. The cloning concept inherently distinguishes this tool from the sibling ai_voice_generator_create_audio, so an agent can tell them apart without opening either schema.

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

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

The MCP guidance explicitly tells the agent what to do after invocation: call wait_for_audio_project with the returned id, or poll the GET endpoint until a terminal status. It also provides conditional input guidance — prefer Magic Hour file paths, use the presigned upload flow when in doubt, and beware hotlinked URLs. However, it never explicitly contrasts this tool with ai_voice_generator_create_audio for the selection decision itself.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that this is an async job, that it returns id and credits_charged immediately, and how to reach completion via statuses and downloads. It even notes the helper's exact_download_urls behavior, which is beyond what structured fields would convey.

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

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

The description is compact, front-loads the core action, and then uses a clearly labeled MCP guidance section for the async workflow. Every sentence adds operational value without repetition.

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

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

For a two-parameter tool with an output schema, the description covers the essential runtime behavior: immediate response fields, terminal statuses, how to retrieve completed audio, and download URLs. An agent has enough to invoke it and handle the follow-up correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful parameter-related context by explaining that each character costs 0.1 credits and is rounded up. This gives the agent a cost implication for the prompt parameter that the schema does not state.

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 'Generate speech from text,' a specific verb and resource that clearly identifies this as a text-to-speech creation tool. It does not explicitly contrast itself with the sibling ai_voice_cloner_create_audio, so it misses the top score for sibling differentiation.

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

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

The MCP guidance gives clear post-invocation steps: call wait_for_audio_project with the returned id or poll the GET endpoint until a terminal status. It does not state when to choose this tool over the voice cloner or other audio tools, so it lacks explicit when-not/alternatives guidance.

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

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

With no annotations provided, the description carries the transparency burden and does it well: it discloses async behavior, immediate id and credits_charged return, final statuses, download URLs, exact_download_urls, and file URL risks. It does not mention rate limits or authentication, but covers the most consequential behavioral traits for correct use.

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 concise and well-organized, front-loading the purpose and then providing bulleted MCP guidance. Each sentence contributes useful operational detail, though the exact_download_urls note is slightly niche and the opening line could have added more differentiating detail.

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 complex nested schema, the async behavior, and the absence of annotations, the description is quite complete for invocation and follow-up: it covers job lifecycle, return fields, and file input pitfalls. The main gap is not explaining the 'Animation' domain or choosing this tool over sibling generation tools.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine value by explaining that estimated frame cost depends on fps and end_seconds, and by giving practical guidance on *_file_path values that is not fully captured in the schema. This pushes it above 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?

'Create a Animation video' states a verb and resource, but it essentially restates the tool name and does not explain what an 'Animation video' is or how it differs from sibling video creators like text_to_video_create_video, image_to_video_create_video, or video_to_video_create_video. The cost sentence adds related information but not purpose differentiation.

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

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

The MCP guidance gives clear operational context: this is an async job, the user should call wait_for_video_project with the returned id, and file_path values should come from Magic Hour or the upload flow. It does not explicitly name alternative tools or when-not-to-use conditions, 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states the operation is permanent and irreversible, which is the most critical behavioral trait for a delete tool. It does not detail every side effect, such as whether associated metadata is also removed, but the core destructive behavior is clearly communicated.

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 a single, focused sentence that leads with the core action, then adds the critical warning. Every word earns its place and there is no redundant or filler content.

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

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

For a one-parameter destructive operation with no output schema, the description is largely complete: it states the action, the resource, and the permanence. It could add a brief note about what happens to the underlying project or any related files, but the essential context for a safe call is 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%, and the id parameter is already well documented with its source and example. The description adds no new parameter-level meaning, 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 clearly states a specific action ('Permanently delete') and a specific resource ('rendered audio file(s)'). The audio scope distinguishes this tool from sibling tools like video_projects_delete and image_projects_delete without needing to inspect schemas.

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

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

The verb 'delete' implies when to use this tool, and the irreversible warning signals caution. However, there is no explicit guidance about when not to use it, no mention of checking with audio_projects_retrieve_details first, and no comparison to alternative workflows.

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

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

With no annotations provided, the description carries the full behavioral burden, and it does so thoroughly. It discloses the full status lifecycle, explains that `downloads` is populated only after a successful render, describes the `error` field, and warns that download URLs are signed and must be used exactly as returned. This goes well beyond the bare operation name.

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 longer than average but well-organized with a status list and a separate MCP guidance block. Each section serves a purpose, though there is mild redundancy between 'downloads is populated after render' and the guidance to surface downloads on complete.

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 one-parameter retrieval tool, the description covers all necessary operational context: status meanings, what to surface to the user, and exactly how to handle signed download URLs. Given the output schema exists upstream, the description does not need to enumerate return fields and is complete for 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?

There is only one parameter and the schema description coverage is 100%. The schema already explains `id` as a unique ID returned by POST APIs. The description does not add param-specific semantics beyond referring to the audio project, but it doesn't need to because the schema is complete.

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: 'Check the progress of a audio project.' It also clarifies that the `downloads` field appears after a successful render collectively with a status list. However, it does not explicitly differentiate itself from the sibling `wait_for_audio_project`, which likely polls the same resource, so it is clear but not fully differentiated.

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

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

The MCP guidance explicitly states when to use it: 'Use this after a create tool to poll job status.' It also tells the agent what to do on completion or error. It lacks a 'when not to use' or references to alternatives like `wait_for_audio_project`, so it has clear context but no exclusions.

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

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

With no annotations present, the description carries the full behavioral burden and does so thoroughly: it discloses that this starts an async job returning id and credits_charged immediately, that callers must poll or wait via wait_for_video_project, that statuses include complete/error/canceled, and that completed projects expose downloads URLs. It also discloses billing behavior and file-path caveats for hotlinked URLs.

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 long but well-structured with clear headings: 'What this API does,' 'Good for,' 'How it works,' 'Key options,' 'Cost,' and 'MCP guidance.' The MCP guidance is essential and directly actionable; minor redundancy exists between the opening and the 'Good for' section, but the length is justified.

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 creation tool with nested objects and no annotations, this description is unusually complete: it covers prerequisite upload steps, job lifecycle, response behavior, cost, resolution constraints, and how to obtain the final result via wait/poll helpers. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: the resolution limitation, the behavior of *_file_path values, and the async response fields. It does not walk through every parameter, but the extra context is valuable.

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 clear verb and resource: 'Create the same Audio To Video you can make in the browser, but programmatically.' It precisely names the tool's function, though it does not explicitly differentiate it from sibling tools like text_to_video_create_video or image_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?

The 'Good for' section provides clear usage context, such as 'Automation and batch processing' and 'Adding audio to video into apps, pipelines, or tools.' The 3-step workflow also signals when the upload step is necessary, but it does not explicitly state when not to use this tool or name alternative tools.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly: it discloses the immediate return of id plus credits_charged, the async job lifecycle, possible terminal statuses, the downloads field, and exact_download_urls. It also warns about hotlink fragility and directs agents 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?

The description is front-loaded with the core purpose, then uses two focused guidance blocks for async behavior and file path handling. Every sentence adds operational value, with no filler or repetition.

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

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

For a no-annotation, nested-parameter, async tool, the description covers creation, immediate response shape, waiting behavior, status outcomes, download URLs, and upstream file preparation. Combined with the schema's rich parameter documentation, nothing critical is missing for correct invocation.

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

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

The schema already provides 100% parameter coverage, so the baseline is 3. The description adds real value with concrete guidance for `_file_path` values, including preferring upload-returned Magic Hour file paths and avoiding unstable hotlinks. It does not need to restate the detailed style conditional rules already in the schema.

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

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

The opening sentence names a specific verb and resource: automatically generating subtitles for a video. It adds the multi-language scope, which distinguishes it from generic video creation and editing siblings like ai_video_editor_create_video and text_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?

The MCP guidance clearly sets expectations for the async lifecycle and tells the agent to call wait_for_video_project or poll the endpoint if a finished result is needed. It does not explicitly compare against alternative subtitle tools, but the use case is unambiguous and the helper routing 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?

With no annotations provided, the description carries the full behavioral burden, and it does so thoroughly. It discloses that the call starts an async job, returns id and credits_charged immediately, requires polling or a wait helper, and that completed projects include download URLs. It also warns about hotlinked URL failure and recommends the presigned upload flow, which is valuable behavioral context beyond what the schema provides.

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 purpose, then uses two clearly labeled bullet sections for async behavior and file-path guidance. Every sentence adds value, and there is no redundant restating of schema fields. The structure makes the most important operational details easy 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 tool with nested assets, an enum parameter, and async behavior, the description is complete. It covers immediate return values, completion statuses, how to retrieve finished images, and how to handle input files correctly. Given the output schema exists, the lack of additional return-value detail is not a 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 a baseline of 3 applies, but the description adds meaningful context beyond the schema. It explains that resolution drives credit cost and gives explicit file-handling guidance for *_file_path values, including when direct URLs may or may not work. This extra guidance helps an agent avoid common invocation errors.

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: 'Swap a person into a scene image using Nano Banana 2 Lite or Nano Banana 2.' It clearly identifies the tool's core function and scope, making it easy to distinguish from sibling create-image tools like face_swap_photo_create_image or head_swap_create_image. The model and resolution details further clarify what makes this tool unique.

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 clear, actionable guidance: it explains the async nature, tells the caller to use wait_for_image_project with the returned id, and recommends preferring Magic Hour file_path values over direct URLs. It does not explicitly name sibling tools as alternatives or state when not to use this tool, but the context is strong enough for an agent to select it appropriately.

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

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

With no annotations, the description carries the full burden and does an excellent job. It explicitly discloses that the job is asynchronous, returns id and credits_charged immediately, requires polling, reports terminal statuses, and exposes downloads. It also warns about file path handling and hotlinked URL failures.

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 long but well-structured with clear sections and front-loaded purpose. The MCP guidance is valuable and earns its place, though some redundancy exists between 'How it works' and the schema/API workflow.

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 tool with nested parameters and no annotations, the description is remarkably complete. It covers the full lifecycle from upload and job creation through polling to downloading results, plus cost, resolution limits, and file path gotchas. An output schema presumably covers return-value details.

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 every parameter. The description adds useful high-level context around resolution limits, file inputs, and costs, but it does not deeply elaborate on individual parameter semantics 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?

The description states a clear verb and resource: programmatically create a Character Replace video job. It is easy to understand what the tool does, but it does not differentiate itself from sibling tools like face_swap_create_video or video_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?

The 'Good for' section gives broad usage context such as automation, batch processing, and app integration. However, it does not mention alternative tools or when not to use this tool, leaving sibling selection mostly to the agent's 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?

With no annotations provided, the description carries the full burden and handles it well: it discloses the async task behavior, the returned id, the need to poll the details endpoint, file-path reliability caveats, and pricing changes. This goes well beyond the minimum.

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 a one-sentence purpose, followed by a short use-case note and targeted MCP guidance. The bullets and linked docs keep it scannable without redundant restatement of the schema.

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

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

The description covers the essential procedural context: async task lifecycle, how to retrieve results, and how to provide valid input files. Given the output schema exists, return-value details are not required, and the file-upload guidance closes the main practical 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 the structured parameter descriptions already carry the baseline. The description adds valuable file-path guidance (prefer upload-returned file_path over hotlinked URLs), which explains common failure modes beyond what the schema states.

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

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

The description opens with a specific verb and resource ('Detect faces in an image or video') and then clarifies the output is a list of faces intended for face-swap workflows. It differentiates itself from the sibling retrieve-details tool by explaining that this call starts an async detection task and returns an id, while face_detection_retrieve_details returns the detected faces.

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

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

It clearly states when to use the API (before multi-face swaps) and routes the agent to the face-detection details endpoint for face retrieval. It does not explicitly enumerate when-not-to-use cases, but the workflow context is unambiguous enough 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?

No annotations are provided, so the description carries the behavioral burden. It clearly describes a read-style operation returning a list of faces and includes useful downstream integration context. However, it never explicitly confirms no side effects, nor does it cover auth, rate limits, or task-completion expectations, leaving some behavior to inference.

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, each earning its place: the first states the operation and the second adds the concrete use case with supporting links. There is no filler, no redundant schema repetition, and the core meaning is front-loaded.

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

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

With a one-parameter schema at 100% coverage and an output schema present, the description is nearly complete: it explains what is returned, when to use the tool, and how the result feeds into face swap APIs. The only minor omission is explicit guidance about prerequisite task state, but the id provenance is already documented in the schema.

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

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

Schema description coverage is 100%, so the baseline applies. The description adds no extra parameter detail, but the schema's id field already documents its provenance ('returned by the face detection API'). An agent can correctly supply the required ID using only 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 clear verb-resource pair: 'Get the details of a face detection task.' The second sentence clarifies the exact payload (list of detected faces) and downstream use, distinguishing it from the sibling face_detection_detect_faces, which creates a detection task. There is no ambiguity about what this tool retrieves.

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 explicit usage context: 'Use this API to get the list of faces detected... to use in face swap photo/video API calls for multi-face swaps.' This tells an agent when to call it. It does not spell out when not to use it or name a direct alternative for task creation, so it falls just short of a 5.

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

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

With no annotations provided, the description carries full disclosure burden and does so thoroughly. It reveals asynchronous behavior (returns id plus credits_charged immediately), job lifecycle statuses, where to find downloads, reliability caveats about hotlinked URLs, the free-tier resolution limit, and the credits-only-for-rendered-frames cost model. This is far beyond what the schema alone provides.

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 long but carefully structured with clear headings: What this API does, Good for, How it works, Key options, Cost, and MCP guidance. It is front-loaded with purpose, and each section carries actionable information. It is denser than strictly necessary due to repeated upload URL references, but the structure keeps it navigable.

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

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

For a complex tool with a nested assets object, required fields, an output schema, and async behavior, the description covers the full call lifecycle: uploading inputs, creating the face swap job, waiting for completion, and downloading results. It also covers error/canceled statuses, file-path pitfalls, and cost behavior. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter-level guidance beyond the schema by explaining that *_file_path values should be existing Magic Hour paths or file_path values from the upload-URL endpoint, and that direct public URLs may work but can fail. It also highlights key parameter families like face_swap_mode and start/end seconds.

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 by stating exactly what the API does: 'Create the same Face Swap you can make in the browser, but programmatically.' It is unambiguous that this is a face-swap video creation tool and clearly conveys that it launches an async video generation job, distinguishing it from photo-only face swap and other video creation 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?

The 'Good for' section explicitly names automation, batch processing, and app/pipeline integration as the intended use cases. The MCP guidance is concrete: it tells agents to call wait_for_video_project or poll GET /v1/video-projects/{id} until complete/error/canceled, and to use Generate Upload URLs for inputs. It does not explicitly name alternative face-swap tools as exclusions, but the context is otherwise clear.

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

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

With no annotations present, the description carries the full disclosure burden and largely succeeds. It reveals the async job nature (returns id and credits_charged immediately, requires polling or a wait helper), the credit cost, terminal statuses (complete/error/canceled), that completed projects include downloads with direct URLs, and the failure modes of hotlinked URLs. This goes well beyond what a bare 'create' description would provide, though it stops short of detailing error/edge behaviors or idempotency.

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 well-structured: a one-sentence purpose lead, a pricing note, then organized MCP guidance split into async workflow and file-path handling. Every section earns its place and the most decision-critical facts (async behavior, cost, wait helper) are front-loaded. It is moderately long but the density of actionable information justifies the length; no filler or tautology.

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 real complexity — async execution, two face-swap modes with conditional parameters, nested assets object, credit billing, and output retrieval — the combination of description and 100%-covered schema is nearly complete. The description covers the async lifecycle and file acquisition; the schema covers mode semantics and conditional requirements; an output schema exists so return values need not be restated. The only notable gap is that the prerequisite step of calling face_detection_detect_faces for individual-faces mode appears only in schema text, not in the operational 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 coverage is 100% with rich per-field descriptions covering conditional requirements (source_file_path for all-faces, face_mappings for individual-faces), maxItems, examples, and the face-detection provenance of original_face. The description adds genuine value by explaining how *_file_path values should be sourced — prefer Magic Hour file paths or upload-URL file_paths over unstable hotlinks — which directly informs correct parameter construction. This exceeds the baseline-3 expectation for high schema coverage.

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

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

The description states a specific verb+resource ('Create a face swap photo') and adds distinguishing context: the 10-credit cost and subscription-dependent output dimensions. It is clearly the photo variant of face swap versus the sibling face_swap_create_video, though it never explicitly names that sibling or differentiates from overlapping tools like head_swap_create_image or body_swap_create_image, leaving some differentiation to inference.

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

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

The MCP guidance is strong on operational workflow: it explicitly tells the agent this is async, to call wait_for_image_project with the returned id, or poll until complete/error/canceled, and how to source *_file_path values. However, it provides no when-to-use vs. alternatives guidance — nothing explains when to choose this over face_swap_create_video, head_swap_create_image, or ai_face_editor_edit_image. Selection among overlapping siblings is implied only by the word 'photo'.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It reveals that the result is inline MCP audio content rather than a plain URL, and warns that the signed URL must be passed exactly, including query parameters, with expires_at treated as separate metadata. It does not describe max_bytes limits or error behavior, but the critical runtime constraints are surfaced.

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

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

Two purposeful sentences: the first states the operation and audience, the second delivers the critical URL-handling instruction. There is no filler, and the most important operational warning is placed directly with the relevant parameter.

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

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

For a two-parameter tool with no output schema and no annotations, the description provides enough to call it correctly: the source of the URL, the inline return behavior, and the URL format constraint. It leaves max_bytes semantics and failure behavior implicit, but those are secondary given the schema default and the simplicity of the operation.

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

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

Schema description coverage is 0%, so the description must compensate. It adds essential semantics for download_url: the value must be the exact full signed URL, query parameters must not be trimmed, and expires_at is not part of the URL. However, max_bytes receives no explanatory coverage beyond what the schema default implies.

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 action ('Fetch... and return it as inline MCP audio content'), a concrete resource ('downloads[n].url' from a completed audio project), and naturally differentiates from sibling fetch_image_download and fetch_video_download through the audio resource. The inline-content detail adds clarity about what the tool actually does beyond simply fetching a URL.

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

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

It clearly scopes use to completed audio projects and inline-audio-compatible clients, which gives the agent a clear selection context. It does not explicitly name alternatives or state when not to use it, but the audio-specific target is enough to route correctly alongside its image and video counterparts.

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

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

With no annotations supplied, the description carries the behavioral disclosure burden. It openly states that the result is inline MCP image content for compatible clients and warns that `expires_at` is metadata, not part of the URL—this helps prevent a likely misuse. It does not mention size-limit or error behavior, but the core behavior and a key edge case are disclosed.

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 the primary action and output first, followed immediately by the most critical input instruction. No filler or repeated schema information; 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?

The tool has no annotations and no output schema, so the description must cover both behavior and context on its own. It explains the source URL and return format well, but omits the meaning of `max_bytes` and any guidance about waiting for project completion or handling expired URLs. This leaves moderate gaps for a two-parameter tool.

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

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

The description adds essential meaning to `download_url`—it must be the exact full signed URL, query parameters intact, and `expires_at` must not be appended. However, schema coverage is 0% and the optional `max_bytes` parameter is never explained in the description, leaving its purpose and effect to inference from its name and default value.

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

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

The description states a specific action—'Fetch' an image using the exact signed `downloads[n].url` from a completed image project—and clearly defines the output as inline MCP image content. This distinguishes it from sibling download tools like fetch_audio_download and fetch_video_download by naming the image-specific resource and outcome.

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 provides clear context: use the tool only with a URL from a completed image project and pass the exact full signed URL without trimming query parameters. It does not explicitly name alternatives or state when not to use it, but the timing and input constraints are strong enough guidance for an agent.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses the return type, an important strict-input rule (never trim query parameters), and clarifies that expires_at is separate metadata rather than part of the URL—all meaningful context beyond the tool's name. It does not mention expiration/error behavior, which prevents a perfect score.

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

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

Two compact sentences with no filler. The core purpose is front-loaded in the first sentence, and the second sentence adds only the critical usage detail about the URL format. Every word 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 tool with no output schema and no annotations, the description adequately covers the input and return shape, but it omits max_bytes semantics, expiration or error conditions, and the expected sequencing with wait_for_video_project or video_projects_retrieve_details. It is sufficient for a straightforward call but incomplete for robust agent decision-making.

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 for the lack of property descriptions. It explains download_url thoroughly, including the exact signed URL requirement and the query-parameter caveat, but it entirely omits any explanation of max_bytes, leaving that parameter underdocumented.

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

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

The description states a specific verb ('Fetch'), a clear resource ('a video downloads[n].url'), and a return format ('embedded MCP binary resource'), which distinguishes it from the audio and image download siblings. It is neither tautological nor vague—it precisely names what the tool does and what input it expects.

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 correct usage context: the video project must be completed and the caller must already possess the signed URL. It does not explicitly name alternative tools like wait_for_video_project or video_projects_retrieve_details, nor does it state when not to use this tool, leaving some routing 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?

With no annotations provided, the description carries the full burden and does an excellent job: it discloses the 10-credit cost, async job behavior, immediate return of id and credits_charged, subscription-dependent resolution, clamping behavior, download URL availability, and caveats about hotlinked URLs. This is far beyond the minimum.

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 dense but appropriately sized for an async tool with nontrivial input requirements. It front-loads the core operation and cost, then organizes workflow guidance in a clear 'MCP guidance' block. Every sentence adds useful information and nothing feels redundant or filler.

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

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

Given the tool's complexity, the description covers everything an agent needs to call it correctly: async result retrieval, cost, file input constraints, resolution behavior, and download URLs. The presence of an output schema means the description need not enumerate return fields, and it still provides enough context to complete the full workflow.

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 input schema already documents all parameters at 100% coverage, which sets the baseline at 3. The description adds meaningful extra guidance beyond the schema, especially around preferring Magic Hour file paths, using the presigned upload flow, warning that hotlinked URLs can fail, and clarifying the credit cost tied to image generation.

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

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

The description clearly states the operation: swapping a head onto a body image, with the verb 'Swap' and the specific resource. However, it does not differentiate this tool from closely related siblings like body_swap_create_image or face_swap_photo_create_image, so it stops just short of the highest clarity score.

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 strong workflow guidance: it explains the async nature, how to retrieve results via wait_for_image_project or polling, and how to handle file paths. However, it never explicitly says when to choose this tool over alternatives or when not to use it, so the selection guidance is implied rather than explicit.

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

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

With no annotations, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It explains async execution, immediate return of id and credits_charged, required follow-up polling, terminal statuses, download URLs, the wait helper's exact_download_urls behavior, and the failure risk of hotlinked URLs. This is rich, non-obvious context that the schema cannot convey.

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

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

The description is front-loaded with the one-sentence purpose and cost, then organized into two focused MCP-guidance bullets. It is longer than a minimal description, but every sentence carries operational information an agent needs; there is no filler or duplication of schema content.

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

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

For an async image-creation tool with nested required assets and a supporting wait helper, the description covers the full lifecycle: cost, immediate response, follow-up, terminal statuses, download retrieval, and file-path sourcing. Since an output schema exists, restating return values is unnecessary. The guidance is complete enough for an agent to invoke and complete the task 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?

The input schema already documents both parameters with 100% coverage, so the baseline is 3. The description adds meaningful guidance beyond the schema: prefer existing Magic Hour file paths or upload-URL file_paths, note that direct public URLs may work but hotlinks can fail, and use the presigned upload flow when uncertain. This materially helps an agent supply correct asset values.

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 precise imperative: 'Remove background from image.' This names a specific operation and resource, and the tool name plus sibling list make its niche — background removal rather than generic image editing, colorizing, upscaling, or generation — 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?

It does not explicitly compare against sibling create-image tools, but it provides clear operational context: the job is async, costs 5 credits, returns an id immediately, and should be followed by wait_for_image_project or polling. It also gives concrete file-path guidance, preferring Magic Hour file paths or presigned-upload results over hotlinks. There are no exclusions or alternative-tool callouts, so it is not a full 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so effectively by explicitly stating the action is permanent and not reversible. This is critical information for an agent deciding whether to proceed.

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 deliver the core action and the key warning without any redundant detail. The irreversibility warning is front-loaded immediately after the action statement, making the risk impossible to miss.

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 one-parameter destructive tool, the description covers the essential semantics: what is deleted and that it is permanent. It does not describe return values or post-delete state, but the low complexity and complete schema make the definition reasonably complete.

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

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

The schema already provides 100% coverage for the single 'id' parameter, including an example and a clear explanation of where the value comes from. The description adds no additional parameter context, so the baseline score 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 uses a specific verb ('delete') and a specific resource ('rendered image(s)'), clearly distinguishing this tool from audio/video delete and retrieve siblings. It also reinforces permanence, leaving no ambiguity about what the tool does.

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

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

There is no guidance about when to use this tool versus alternatives such as image_projects_retrieve_details or wait_for_image_project. The destructive nature is clear, but the description does not state the intended workflow position or caution the agent to verify the id before deleting.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does this well by enumerating all possible statuses and clarifying that the downloads field is only populated after a successful render. It also gives a critical behavioral note about download URLs being full signed URLs that must not be modified. This goes beyond what the schema provides and is highly useful for the agent.

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 well-structured with a clear main statement, a status list, and MCP guidance. It is longer than the absolute minimum but every sentence earns its place by providing necessary behavioral and usage detail. The status list could be considered redundant if the output schema already contains it, but it is still valuable for immediate comprehension.

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

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

Given the presence of an output schema and the tool's simplicity (one parameter), the description is quite complete. It covers when to use it, how to interpret statuses, and how to handle the download URLs. It does not mention pagination or other edge cases, but these are likely not relevant for a single-project retrieval. The description could also note that the tool is read-only, but that is implied by its purpose.

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 input schema already covers the only parameter, id, with a complete description and example (100% schema coverage). The tool description does not add additional semantics about the parameter, so the baseline of 3 is appropriate. No extra context is needed because the schema is sufficient.

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's purpose: to check the progress of an image project. It uses a specific verb ('check') and resource ('progress of an image project'), and it distinguishes itself from sibling tools like wait_for_image_project by explicitly describing this as a polling operation rather than a waiting one. The mention of statuses and the downloads field further clarifies what the tool does.

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

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

The description provides clear usage context: 'Use this after a create tool to poll job status.' It also gives specific handling instructions for complete and error statuses. However, it does not explicitly mention alternatives like wait_for_image_project for when a user prefers blocking behavior, so it stops short of full differentiation.

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

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

With no annotations provided, the description fully carries the behavioral burden. It discloses async job submission, immediate return of id and credits_charged, required polling until complete/error/canceled, download URLs, credit charging behavior, resolution tier limits, and file_path/hotlink pitfalls. This is comprehensive and operationally useful.

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 long but well-structured with headers, front-loaded key facts, and action-oriented steps. The MCP guidance section is dense but earns its place because it tells the agent exactly how to handle the async lifecycle and file path inputs.

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 nested 7-parameter schema and available output schema, the description covers the complete async workflow, polling, downloading, cost model, and file upload caveats. It does not enumerate every parameter, but the schema already provides those details.

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

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

Schema description coverage is 100% and each parameter already has rich documentation, so the baseline is 3. The description adds helpful practical context around file_path handling and mentions resolution limits, but it does not need to duplicate schema-level parameter details.

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 it 'Create[s] the same Image To Video you can make in the browser, but programmatically', identifying a specific verb (create), resource (image-to-video job), and use case. It is unambiguous and easily distinguished from sibling creation tools like text_to_video_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?

It provides strong contextual guidance: automation/batch processing, a 3-step workflow, and explicit MCP guidance to call wait_for_video_project or poll the GET endpoint when the finished result is needed. It does not explicitly contrast with alternative video-creation siblings, but the resource-specific wording makes the intended use clear.

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

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

With no annotations, the description carries the full burden and discloses rich behavior: it starts an async job returning id and credits_charged immediately, explains polling until complete/error/canceled, output downloads, per-frame credit charging, resolution limits, and file_path reliability caveats. No contradictions.

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 long but well-structured with clear headings, bullets, numbered steps, and a dedicated MCP guidance section. Purpose and use cases are front-loaded, and each section contributes operational guidance.

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?

It covers the full workflow: upload inputs, create the job, wait for completion, and download outputs, plus cost behavior and file path rules. Even with the output schema present, the end-to-end lifecycle is described thoroughly.

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 practical value by advising agents to prefer Magic Hour file paths over direct public URLs, explaining when hotlinks fail, and summarizing key options like resolution limits and extra fields.

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

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

The description opens with 'Create the same Lip Sync you can make in the browser, but programmatically,' naming a specific verb, resource, and value proposition. It clearly distinguishes this as the lip-sync creation API among many image/video creation 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?

The 'Good for' section explicitly lists automation, batch processing, and adding lip sync into apps/pipelines/tools, giving clear contexts for using it. It doesn't name sibling alternatives or state when not to use it, but the use-case framing is explicit enough.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explicitly explains that this is an async job, returns id and credits_charged immediately, requires polling or the wait_for_image_project helper, and describes terminal statuses and download URLs. It also discloses the cost and file-path reliability caveats.

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 purpose and cost, then organized into concise, relevant MCP guidance bullets. Every sentence adds operational value, and there is no redundant restatement of schema fields.

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

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

Given the async generation workflow, nested assets object, and use of external upload endpoints, the description is complete. It covers job lifecycle, polling/waiting behavior, download access, file upload semantics, and cost while leaving return-value details to the existing 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?

The schema already describes both parameters at 100% coverage, and the description adds meaningful extra guidance beyond the schema. It explains how to supply *_file_path values correctly, preferring Magic Hour paths or upload-URL file_path values, and warns that hotlinked URLs can fail with a recommended presigned upload fallback.

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 action and resource: 'Colorize image.' This clearly identifies what the tool does, and the name photo_colorizer_create_image reinforces the intent. However, it does not explicitly differentiate itself from sibling image-generation tools, 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?

The description gives operational guidance about async behavior and file paths, but it does not explain when to choose this tool over alternatives like ai_image_editor_create_image or ai_image_generator_create_image. It notes the 10-credit cost but offers no usage conditions or exclusions.

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

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

No annotations are present, so the description carries the behavioral disclosure burden. The word 'Check' conveys a read-only, non-mutating operation, and 'reachable' defines the success criterion. It does not detail timeout or failure modes, but the tool is simple enough that this is a minor gap rather than a significant 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?

The description is a single, front-loaded sentence with no filler. Every word contributes to explaining what the tool does. It is concise without sacrificing clarity.

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

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

For a zero-parameter health check with an output schema, the description is fully adequate: an agent knows that no arguments are required, what the tool measures, and can rely on the output schema for return details. No additional context is needed 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?

The input schema has zero parameters, so there are no parameter semantics to document. The description appropriately focuses on the tool's purpose rather than inputs, which is the correct baseline for a parameterless tool.

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 uses a specific verb ('Check') and a clear resource ('Magic Hour MCP server reachability'). It is immediately distinguishable from all content-generation siblings, none of which perform health checks. The purpose is unambiguous and complete.

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 clearly implies when to use the tool: whenever the agent needs to verify server reachability before calling dependent tools. It does not explicitly state when-not-to-use or name alternatives, but with no related sibling tool and zero parameters, no exclusion is necessary. Context is clear enough for correct 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?

With no annotations, the description carries the full burden. It discloses ordering, authenticated ownership, item contents (durable file_path vs temporary signed URL), and pagination behavior. It is clearly read-only, though it does not explicitly state that no modifications occur or mention rate limits.

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

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

Three dense sentences with no filler. The core behavior is front-loaded, and each additional sentence adds meaningful detail (item contents, filtering, pagination).

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?

The output schema covers return values, and the description covers auth, ordering, item contents, filtering, and pagination. With zero required parameters and no annotations, this is complete for a list tool.

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

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

Schema coverage is 100%, so the schema already documents type, limit, and cursor thoroughly. The description adds no new parameter semantics; the cursor explanation duplicates the schema's description. Baseline 3 is appropriate.

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

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

The description starts with 'Returns active saved items owned by the authenticated account, newest first,' which clearly identifies the verb, resource, and ordering. It also lists the item types (characters, references, voices, moodboards, brand kits), and no sibling tool covers listing saved assets, so it is easily distinguished.

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 clear context: filtering by type, pagination via cursor, and that items are for reuse in generation APIs. There are no similar list tools among siblings, so explicit when-not-to-use guidance is unnecessary, but it could have been slightly more explicit about when to choose this over other retrieval tools.

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

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

With no annotations provided, the description carries the full burden. It discloses the async nature (starts a job and returns id plus credits_charged immediately), provides the polling/wait helper path, explains the cost model (credits for rendered frames), and notes free-tier resolution limits. It does not cover rate limits or error handling, but covers the most critical behavioral aspects.

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 well-structured with clear sections ('What this API does', 'Good for', 'How it works', etc.) and includes a dedicated 'MCP guidance' block that is highly useful for an agent. While lengthy, each section adds value and the most important information (purpose, async behavior) is front-loaded. It is not overly verbose, though it could be trimmed slightly.

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

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

Given the tool's complexity (async, many model options, multiple parameters), the description covers the essential flow: upload inputs, create job, poll for completion, and download. It references the wait_for_video_project helper and mentions cost and resolution restrictions. With an output schema present, return value details are not needed in the description. Minor gaps like error handling and rate limits exist but are not critical.

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

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

Schema coverage is 86%, so the schema already documents most parameters in detail (including model-specific support). The description adds some context beyond the schema, such as the free-tier 576px resolution limit, but does not elaborate on individual parameters beyond what the schema provides. It mentions 'extra fields' generically without specifics, so it does not fully compensate for the remaining 14% but is adequate given high schema coverage.

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

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

The description explicitly states it creates text-to-video programmatically, mirroring the browser feature. It clearly differentiates from sibling video tools like image_to_video and audio_to_video by naming 'Text To Video' and describing the async job creation. The verb 'create' and resource 'video' are specific and 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 'Good for' section lists automation, batch processing, and integration, and the 'How it works' steps give a clear workflow. However, it does not explicitly state when to prefer this tool over alternatives like image_to_video or audio_to_video; the distinction is only implied by the name. It also mentions input types ambiguously ('video, image, or audio') which could confuse an agent deciding between tools.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the response array matches the request order, that the API only creates presigned URLs rather than uploading, and that callers must later send a PUT request. It also includes important edge-case behavior about gif support and hotlinked URLs, giving the agent realistic expectations.

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 long but every section earns its place: purpose, response ordering, extension lists, a special-case note, an upload example, and MCP guidance. It is front-loaded with the core purpose and progressively adds operational detail, making it easy for an agent to extract what it 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?

For a tool with one parameter and an output schema, the description is remarkably complete. It covers when to use the tool, how to construct the request, what happens after receiving URLs, and how to integrate results with create tools. The inclusion of extension constraints and direct-URL caveats addresses likely failure modes without requiring the agent to inspect external documentation.

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?

Although the schema already describes the items parameter at 100% coverage, the description adds substantial meaning: per-asset-type valid extensions, a note that gif is only supported for the face swap API's video_file_path field, and a concrete curl example. This goes well beyond the schema and helps the agent construct valid requests.

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: 'Generates a list of pre-signed upload URLs for the assets required.' It clearly states the tool's narrow role—only for uploading to Magic Hour's storage—and distinguishes it from the many create_* sibling tools by explaining it does not perform generation or upload itself.

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

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

The description gives explicit when-to-use guidance: 'This API is only necessary if you want to upload to Magic Hour's storage.' It also explains the intended workflow—upload raw bytes to each returned upload_url outside the generation call, then pass the matching file_path into the create tool—and even cautions against relying on direct public media URLs, directing users to prefer the presigned flow.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states that the operation is permanent and irreversible, which is the most critical behavioral trait for a delete tool. It does not mention side effects on associated assets or permission requirements, but the core destructive nature is clearly conveyed.

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

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

The description is two short sentences with no filler. It front-loads the action and consequence, and the warning sentence earns its place by reinforcing irreversibility. Every word contributes to the tool's clarity.

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 one-parameter delete tool with no output schema, the description covers the essential operational facts: what is deleted and that deletion is permanent. It could mention what happens to the project's associated data or whether deletion is possible during processing, but such detail is arguably beyond what is needed for a straightforward delete. Overall, it is sufficiently complete for the tool's complexity.

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

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

The input schema already has 100% coverage for the single 'id' parameter, including a description that explains it is the unique ID returned by POST APIs. The description adds no parameter-level information, but because the schema is already comprehensive, the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('Permanently delete') and resource ('the rendered video'), making it unmistakably a delete operation. It implicitly differentiates itself from sibling create/retrieve tools and other delete tools by targeting video projects. Despite a slight wording mismatch ('rendered video' vs 'video project'), the intent is clear and 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 description provides no explicit when-to-use guidance or comparison with alternatives. It does not mention that this tool is for removing a video project when it is no longer needed, nor does it exclude cases like still-processing videos. The warning 'please be sure before deleting' implies finality but does not help an agent decide when to call this versus another tool.

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

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

With no annotations, the description carries the full behavioral burden. It thoroughly discloses the status lifecycle, when the downloads field is populated, and that URLs are already signed and must not be modified. This is substantive behavioral context beyond the schema.

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

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

The description is well-organized with statuses and MCP guidance, and every section adds useful context. Minor redundancy exists between 'downloads field is populated after a successful render' and the status descriptions, but overall it remains focused and scannable.

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?

The description covers the essential operational flow: poll after creation, interpret statuses, surface downloads or errors, and preserve signed URLs. Since an output schema exists, return-value details are not necessary, though a brief mention that polling should continue until a terminal status is reached would make it fully complete.

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

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

The schema description coverage is 100%, and the single id parameter is documented there. The tool description adds no additional parameter-level meaning, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool checks video project progress and maps to a specific resource and action. It distinguishes itself from create tools via 'use this after a create tool to poll job status,' but it does not explicitly differentiate itself from the sibling wait_for_video_project 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 description gives clear context: it should be used after a create tool to poll job status, and it explains how to handle complete and error states. However, it does not provide explicit when-not-to-use guidance or mention alternatives such as wait_for_video_project.

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

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

The description is exceptionally transparent about behavior. It explains that the tool starts an async job, returns 'id' and 'credits_charged' immediately, and provides explicit instructions on waiting for completion via the wait_for_video_project helper or polling. It also discloses cost implications, file path handling, and potential pitfalls with direct URLs. This covers all behavioral aspects thoroughly.

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 well-structured with clear sections ('What this API does', 'Good for', 'How it works', 'Key options', 'Cost', 'MCP guidance'). Despite its length, each section serves a distinct purpose and contributes useful information. The content is front-loaded with the core purpose and progressively provides operational details. There is no redundancy or fluff.

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?

The description is comprehensive for a complex async API. It covers the creation flow, waiting mechanism, output retrieval (downloads), error handling, cost estimation, and file upload specifics. It also includes a link to the product page and upload guide for further reference. Every aspect an agent needs to correctly invoke and handle the tool is addressed.

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 description adds significant value beyond the input schema. It explains the 'Key options' (inputs, resolution, extra fields) and provides detailed guidance on *_file_path values, including the preferred usage of Magic Hour file paths and the presigned upload flow. The MCP guidance clarifies the roles of different parameters (e.g., video_source, start_seconds, end_seconds) and how they interact. This goes well beyond the schema descriptions.

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's purpose: 'Create the same Video To Video you can make in the browser, but programmatically.' It explicitly identifies the resource (video-to-video transformation) and differentiates from sibling tools by its name and described functionality. The 'Good for' section further clarifies its intended use cases.

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 guidance on when to use the tool ('Good for' automation and batch processing) and includes a detailed 'How it works' section, but it does not explicitly contrast this tool with alternatives like text_to_video or image_to_video. The distinction is implied by the tool name and purpose, but not explicitly stated. This leaves some room for 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?

With no annotations, the description carries the full behavioral burden. It discloses polling until terminal states, final project JSON return, attempted inline audio downloads, sanitized download fields, and the requirement to use returned URLs exactly. It could add more detail on timeout/error shape or authentication, but core behavior is well disclosed.

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

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

Three sentences with the purpose front-loaded, followed by return behavior and a crucial URL-handling caveat. The content is dense but each sentence earns its place; no filler or repetition.

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?

The description covers terminal states, final response content, and URL usage instructions. However, with six parameters, no output schema, and no annotations, it leaves parameter behavior and timeout/error outcomes underspecified. It is adequate for a simple poll tool but not fully complete.

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

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

Schema description coverage is 0%, and the description does not compensate. It explains response fields like exact_download_urls and downloads[].url, but gives no semantics for timeout_seconds, poll_interval_seconds, max_inline_downloads, max_bytes_per_download, or include_inline_downloads. The parameter names and defaults are suggestive, but meaningful behavioral meaning is missing.

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 polls an audio project until it reaches a terminal state, names the resource ('audio project'), and specifies the outcome ('final project JSON' and inline downloads). This distinguishes it from sibling wait_for_image_project and wait_for_video_project tools, and from audio_projects_retrieve_details which is a single retrieval.

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

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

The description makes the intended use clear: wait on an audio project for completion, error, cancellation, or timeout, then receive the final result. It does not explicitly contrast with alternatives like audio_projects_retrieve_details or fetch_audio_download, nor state when not to use this tool, but the polling context is evident.

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

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

With no annotations, the description carries the full burden, and it does substantial work: it discloses poll termination conditions, the return value (final project JSON), the conditional inline-download attempt for Inspector/compatible clients, and that download fields are sanitized. It stops short of describing what the return looks like on error, cancel, or timeout, and what 'sanitized' means precisely.

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

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

Three sentences with no filler: the first establishes the core loop, the second covers the return value and client compatibility, and the third is a high-value usage warning about URL integrity. Every sentence earns its place and the essential purpose is front-loaded.

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