Magic Hour

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

With no annotations, the description carries the full burden and does so well. It discloses that the operation is async, returns id and credits_charged immediately, requires polling or a wait helper, lists terminal statuses, and notes that hotlinked URLs can fail. This is far more than a typical 'does something' description.

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 and credit cost, followed by two tightly scoped bullets covering async flow and file-path best practices. Every sentence adds distinct 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?

Given the tool's complexity—async generation, credit cost, file uploads, and result retrieval—the description covers the full lifecycle: starting the job, checking status, fetching downloads, and handling input files. The presence of an output schema further reduces the need to describe return shapes.

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 strong. The description adds meaningful guidance for *_file_path parameters: prefer Magic Hour file paths or file_path from the upload endpoint, be cautious with direct public URLs, and use the presigned upload flow when in doubt. This goes beyond the schema's static 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 opens with a specific action, 'Change outfits in photos in seconds', which clearly identifies the tool's core function and resource. It is easily distinguishable from siblings like body_swap or face_swap, though it does not explicitly name a differentiating sibling.

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

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

The MCP guidance explains how to handle the async job and how to prefer Magic Hour file paths versus direct URLs, which is useful operational context. However, there is no explicit statement about when to use this tool versus alternatives like body_swap_create_image or face_swap_photo_create_image.

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

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

With no annotations 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 provided, the description carries full behavioral disclosure. It openly states the call returns id and credits_charged immediately, requires waiting for completion, expects statuses like complete/error/canceled, and warns about hotlinked URL failures — strong transparency for a mutation-style async 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 organized with a short headline and two focused MCP guidance bullets. It front-loads the most critical async behavior and keeps the content dense without excessive repetition, though the opening line is somewhat generic.

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 lifecycle — initiation, immediate return values, polling/waiting, completion statuses, download URLs, and file input caveats. With an output schema present and detailed parameter schema coverage, this is a complete enough definition, though it could have explicitly noted model-specific limits.

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

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

Schema coverage is already high at 86%, so baseline is 3. The description adds meaningful param-level guidance beyond the schema, particularly around *__file_path values: prefer Magic Hour file paths or upload-returned file_path values, avoid unstable hotlinks, and use the presigned upload flow when in doubt. This is useful semantic context for the assets parameter.

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?

Description states 'Edit images with AI' — a clear verb and resource. It does not, however, explicitly differentiate itself from sibling image-editing/generation tools like ai_image_generator_create_image or ai_face_editor_edit_image, so it is adequately clear but not distinctive.

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 meaningful procedural guidance: it explains that this is an async job, that the agent should call wait_for_image_project or poll the endpoint, and that file paths should come from an upload flow. It does not, however, state when to choose this tool over sibling image tools, leaving usage context 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 disclosure burden. It clearly states the async behavior, immediate return of id and credits_charged, and the polling workflow. It could mention failure/error handling or rate limits, but it covers the most important behavioral trait (async job lifecycle) well.

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 main description is two sentences, front-loaded with the core purpose, followed by a compact MCP guidance block. Every sentence earns its place. The long model list lives in the schema, not the description, so the description itself remains appropriately sized.

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

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

Given the rich input schema (100% parameter coverage) and the existence of an output schema, the description's job is mainly to explain the async workflow and result retrieval, which it does well. Minor gaps: it doesn't mention credit cost variation or possible error handling, but the essential operational flow is covered.

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 baseline is 3. The description adds value by framing the tool around 'advanced model selection', signaling that model choice is important and that pricing/capabilities vary. It also explains the async consequence of submitted parameters (returns id immediately), which is not in the schema.

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

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

The description states a specific verb and resource: 'Create an AI image with advanced model selection and quality controls.' It clearly distinguishes this from sibling tools with more focused scope (e.g., ai_image_upscaler_create_image, ai_image_editor_create_image) by positioning it as the general creation 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 MCP guidance explicitly explains that this starts an async job and tells the agent exactly what to do next: call wait_for_image_project with the returned id or poll the endpoint until terminal status. This is clear when-to-use and how-to-proceed guidance that is not available from sibling tool names alone.

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 does it well. It discloses async execution, immediate return of id and credits_charged, cost of 10 credits, polling statuses, download URLs, and the helper's exact_download_urls behavior. This is strong transparency.

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 and cost, then uses a compact MCP guidance bullet for the async flow. Every sentence contributes actionable information, and the structure makes the workflow easy to follow.

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 full lifecycle: initiating the job, immediate response fields, waiting for completion, polling statuses, and retrieving download URLs. Combined with the output schema signal and rich input schema, an agent has enough context to select and 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 description adds no parameter-level explanation, but the input schema provides useful descriptions for name, topic, template, and searchWeb. The top-level style object itself lacks a description and overall schema coverage is only 50%, so the description misses an opportunity to clarify the required structure, but the nested schema mostly compensates.

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

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

The description opens with a specific verb and resource: 'Create an AI generated meme.' It is immediately clear what this tool does and how it differs from generic image, video, and audio siblings. The credit cost and async behavior reinforce the tool's identity.

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 workflow guidance: it starts an async job, returns an id, and tells the agent to call wait_for_image_project or poll the endpoint until a terminal status. It does not explicitly name alternative tools to prefer in other scenarios, but the usage context is unambiguous.

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

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

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 carries the full behavioral burden and does so well: it discloses async execution, immediate id/credits_charged response, expected statuses, download URL availability, and the risk of hotlinked media URLs. This is exactly the contextual information an agent needs.

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

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

The opening line is front-loaded and the guidance is organized into bullets, making the async workflow easy to parse. It is somewhat lengthy, but the complexity of the job and the absence of annotations justify nearly every sentence.

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

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

For a complex async tool with an output schema, the description covers the full invocation lifecycle: start, poll/wait, statuses, downloads, and file upload best practices. It loses a point because 'audio or text input' conflicts with the required audio_file_path; spelling out that text goes through style.prompt in prompted mode would remove the ambiguity.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real value for *_file_path values by recommending Magic Hour paths or upload-URL file_paths and warning against unstable hotlinks. The phrase 'audio or text input' is slightly misleading because audio_file_path is required, but the schema itself clarifies the requirement.

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 concrete verb-resource pair: 'Create a talking photo from an image and audio or text input.' This clearly identifies the tool's unique output and distinguishes it from image generation, video editing, and lip-sync sibling tools.

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

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

The MCP guidance explicitly tells the agent what to do after the call: use wait_for_video_project with the returned id or poll GET /v1/video-projects/{id} until terminal statuses. It also gives practical file-path guidance with a fallback. It does not contrast this tool against sibling creation tools, 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 and handles it well. It discloses that the call starts an async job returning id and credits_charged immediately, that the user must poll or use wait_for_video_project, and that completed projects include downloads. It also reveals failure modes (hotlinked URLs can fail) and cost behavior (only rendered frames are charged).

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 headings, bullets, and a numbered workflow, making it scannable. It is longer than strictly necessary and repeats some polling guidance in the MCP paragraph, but the added detail is largely justified given the complexity of an async video-creation tool.

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

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

For a 7-parameter async tool with no annotations, the description is remarkably complete. It covers prerequisites (upload URLs and file_path), async behavior and polling, output downloads, cost, resolution restrictions, and file-input edge cases. Nothing essential for correctly invoking this tool is missing.

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

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

Schema coverage is already high (86%), so the baseline is 3, but the description adds meaningful context beyond the schema. It explains how to source *_file_path values (prefer upload-URL file_path over direct URLs), warns that hotlinked URLs may fail, and clarifies resolution/plan limitations and extra field examples. This is helpful but not exhaustive for every parameter.

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 action and resource: 'Create the same Video Editor you can make in the browser, but programmatically' and outlines what it produces. However, it does not explicitly distinguish itself from the many sibling video-generation tools (e.g., text_to_video_create_video, video_to_video_create_video), so it lacks explicit sibling differentiation.

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

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

The description gives clear context for when to use it ('Good for automation and batch processing', 'adding video editor into apps') and walks through a 3-step workflow involving uploads and job polling. It does not state explicit exclusions or compare against alternatives, but the context is clear enough for an agent to infer the intended use.

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 provided, the description carries the full burden of behavioral disclosure, and it delivers: it reveals the async nature, the immediate return of id plus credits_charged, the cost model (0.1 credits per character rounded up), the terminal status values (complete, error, canceled), and the contents of completed projects (downloads with direct URLs). This is exactly the kind of non-obvious runtime behavior an agent needs.

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

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

The description is well-structured: a one-sentence purpose statement, a one-sentence cost note, then a dense but purposeful MCP guidance bullet. Everything earns its place and the most important facts are front-loaded; the only minor issue is that the guidance bullet packs several pieces of workflow information into one long run-on section.

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 trickiest aspects of this tool — asynchronous execution, immediate vs. final results, how to retrieve output, and cost accounting — are all fully covered. An output schema exists so return values are structured, and the description correctly routes the agent to wait_for_audio_project. It could mention failure causes or the 1000-character limit, but those are either in the schema or minor gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds the cost-per-character detail that contextualizes the prompt parameter, but it does not explain how to construct the nested style object or add meaning beyond what the schema already documents, so it stays at baseline.

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

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

The first sentence, 'Generate speech from text,' states a specific verb and resource clearly. However, it does not explicitly distinguish itself from the close sibling ai_voice_cloner_create_audio, which also creates audio, so it misses the differentiation needed for 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 MCP guidance section gives clear post-invocation workflow context: call wait_for_audio_project with the returned id or poll until status is terminal, and it describes what completed projects contain. However, it never explicitly states when to use this tool versus alternatives like ai_voice_cloner_create_audio, leaving selection to implication from the tool's name and 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 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, the description carries the full behavioral burden and does so well: it lists all statuses, notes that downloads only exist after a successful render, and warns that signed URLs must be used exactly as returned. This is substantial, actionable behavioral context.

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

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

Purpose is front-loaded, followed by a compact status list and focused MCP guidance. Every section adds value with no redundant filler.

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

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

For a one-parameter retrieval tool with an output schema, this is nearly complete: it covers polling usage, status semantics, and download URL handling. It could more explicitly distinguish itself from wait_for_audio_project, but the guidance is already actionable.

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 the single id parameter 100%, including that it is returned by the POST APIs. The description reinforces that the id comes from a create call but does not add new parameter-level meaning beyond that.

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

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

States a specific action: 'Check the progress of a audio project' and provides a concrete status taxonomy. The verb and resource make it easy to distinguish from create, delete, and wait tools despite not naming them explicitly.

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

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

Explicitly tells the agent to use this after a create tool to poll job status and maps statuses to user-facing actions. It does not name exclusions or the wait_for_audio_project alternative, so routing between those siblings is left somewhat implicit.

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

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

With no annotations provided, the description fully discloses the async nature: it returns id and credits_charged immediately, requires polling until complete/error/canceled, and includes downloads on completion. It also adds practical caveats about hotlinked URLs and credit charging for rendered frames, which 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 long but well-structured with clear headers, bullet points, and numbered steps. Every section earns its place, and the most important info—what it does, the async behavior, and the required follow-up—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?

Given the complex async job flow, nested assets object, and lack of annotations, this description is exceptionally complete. It covers the 3-step workflow, status handling, downloads, cost expectations, output schema availability, and file-path pitfalls. Nothing essential is missing for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents parameter meanings. The description adds valuable extra context: resolution limits for free users, preferred file_path usage via the upload-URL flow, and examples of extra fields. This enriches parameter understanding beyond the schema alone.

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 creates the same 'Audio To Video' product programmatically, naming a specific action and resource. It distinguishes itself from sibling tools by emphasizing audio-to-video generation and the asynchronous job workflow.

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?

A 'Good for' section explicitly names automation, batch processing, and integration into apps/pipelines. The MCP guidance also clarifies when to use wait_for_video_project or polling. It doesn't compare against alternative creation tools like text_to_video_create_video, but the use case is clearly scoped.

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

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

With no annotations 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 provided, the description carries the full burden, and it delivers: async job behavior, immediate return of id and credits_charged, expected statuses, download URL semantics, cost-only-for-rendered-frames, and warnings about hotlinked URLs. This is thorough and 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 long but well-organized with headers, bullets, and a 3-step breakdown. It is front-loaded with the core purpose, then covers key options, cost, and MCP-specific behavior; nearly every sentence earns its place.

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

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

The description covers the full workflow: upload preparation, async job creation, polling/waiting, result downloads, cost behavior, and file-path constraints. Combined with the available output schema, an agent has everything it needs to call and follow through 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% and parameter descriptions are already detailed, so the baseline is 3. The description adds meaningful operational context beyond the schema: input can be a YouTube link in some project types, free-tier resolution caps at 576px, and extra fields like face_swap_mode and start/end seconds may apply.

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

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

The description states a specific verb and resource: create a Character Replace video programmatically, with clear "what this API does" framing. It does not explicitly contrast this with related sibling tools like face_swap_create_video, though the product-specific name makes confusion unlikely.

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 concrete usage contexts: automation, batch processing, app/pipeline integration, and a 3-step workflow with upload URLs and the wait_for_video_project helper. It lacks explicit when-not-to-use guidance or direct alternative selection among sibling video tools, 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 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, the description carries full behavioral disclosure. It reveals that the API is asynchronous, returns id and credits_charged immediately, requires polling or a wait helper, charges only rendered frames, and explains file-path edge cases such as hotlinked URLs failing. This is exceptional transparency.

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 headers, bullet points, and a dedicated MCP guidance section. It front-loads the core purpose and workflow, and each section adds practical value. Some redundancy exists, but overall it remains 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 async video-generation tool with no annotations, the description is complete: it covers the full workflow from uploading inputs to retrieving results, explains cost behavior, status states, and helper functions. The presence of an output schema reduces the need to describe return structures further.

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 parameters in detail. The description adds meaningful guidance beyond the schema, such as preferring Magic Hour file paths over direct URLs, explaining resolution limits, and summarizing key option categories without duplicating 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's purpose: 'Create the same Face Swap you can make in the browser, but programmatically.' It further specifies that this starts an async video generation job, distinguishing it from image-only face swap tools like face_swap_photo_create_image.

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

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

The description provides clear usage context: automation, batch processing, and integration into apps or pipelines. It does not explicitly name alternative tools or state when not to use this tool, but the automation-focused framing and step-by-step workflow make the intended use obvious.

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

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

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, the description carries the burden and does a good job: it discloses that downloads appears only after a successful render, enumerates all statuses, and warns that download URLs are signed and must be used verbatim. It does not discuss authentication or rate limits, but those are less central for a status retrieval.

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-line purpose, a compact status list, and a practical MCP guidance block. It front-loads the primary action and each 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?

For a status-polling tool, it covers lifecycle statuses, the downloads field, the signed URL caveat, and next actions on completion/error. It lacks an explicit pointer to the wait_for_image_project sibling for blocking waits, but is otherwise complete for a tool with an 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 single id parameter is already fully documented in the schema, including that POST APIs return it, and schema coverage is 100%. The description adds no extra parameter nuance, so it earns the baseline.

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

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

The first sentence names a specific operation: checking the progress of an image project, with statuses and downloads giving the agent a concrete picture. It is clear enough to identify as the details/status tool, though it does not explicitly contrast with the sibling wait_for_image_project.

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

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

It explicitly says to use the tool after a create call to poll job status and gives follow-up actions for complete and error. It does not state when to prefer wait_for_image_project, so it stops short of a full when-to-use/when-not-to-use matrix.

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 async nature: 'This starts an async video generation job and returns `id` plus `credits_charged` immediately.' It also explains polling via wait_for_video_project or the status endpoint, terminal statuses like complete/error/canceled, downloads field, credit charging only for rendered frames, resolution tier limits, and file path reliability caveats. This goes well beyond the schema.

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

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

The description is long but well-structured with clear sections: What this API does, Good for, How it works, Key options, Cost, and MCP guidance. The opening line is front-loaded and effective. While every section earns its place, the overall length is substantial and could potentially be trimmed without losing value, so not a perfect 5.

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

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

The description is complete for a complex tool: it covers the full lifecycle from upload URLs to job creation to polling to downloads, explains billing behavior, gives model/resolution guidance, and warns about file path pitfalls. It even mentions the output schema's return fields (id, credits_charged, downloads) and points to the wait helper. Nothing an agent needs to call this tool correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter in detail, including model-specific support lists. The description's 'Key options' section adds a high-level summary, and the MCP guidance adds practical advice on file_path values, but it does not substantially enrich meaning beyond what the schema already provides. 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 opens with a specific, actionable statement: 'Create the same Image To Video you can make in the browser, but programmatically.' It clearly identifies the resource (image-to-video generation) and the operation (create a job), and the name reinforces this. It also distinguishes itself from sibling tools by focusing solely on image-to-video creation, not audio-to-video or text-to-video.

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

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

The 'Good for' section explicitly states the intended contexts: automation, batch processing, and integrating image-to-video into apps or pipelines. The 'How it works' steps provide a clear execution workflow. However, it does not explicitly mention when NOT to use this tool or compare it to sibling alternatives like text_to_video_create_video or video_to_video_create_video, so it stops short of 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 behavioral burden and handles it well. It discloses that the tool starts an async job and returns id plus credits_charged immediately, lists job statuses (complete, error, canceled), mentions direct download URLs, explains credit charging per rendered frame, and warns that hotlinked public URLs can fail.

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 headings, bullets, and a dedicated MCP guidance section, making it scannable. It loses a point due to slight redundancy between the opening summary and 'Good for' section, and the misleading 'Extra fields' label applied to start_seconds/end_seconds, which are actually required.

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

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

For a nested, async, credit-consuming creation tool with no annotations, the description covers the full workflow: uploading inputs, creating the job, polling or waiting for completion, retrieving download URLs, and understanding costs. It also addresses file-path reliability and plan-based resolution limits, giving an agent enough context to invoke the tool correctly.

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

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

The schema already documents all parameters with 100% coverage, so the baseline is 3. The description adds operational value by explaining that *_file_path values should prefer Magic Hour file paths or upload-URL endpoint results, that direct public URLs may be unreliable, and that resolution is plan-limited. This is useful supplemental context 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 opens with 'Create the same Lip Sync you can make in the browser, but programmatically' and repeatedly identifies the resource as a lip-sync video-generation job. This clearly distinguishes it from sibling tools like ai_talking_photo_create_talking_photo and audio_to_video_create_video without requiring schema inspection.

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

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

It explicitly frames the tool for automation and batch processing and provides clear post-submit guidance: call the wait_for_video_project helper or poll GET /v1/video-projects/{id} until completion. However, it does not explicitly state when not to use this tool versus other create_video siblings, so it falls just short of fully explicit alternative-selection guidance.

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

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

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 provided, the description carries the full burden — and it delivers. It discloses the async job semantics (returns id and credits_charged immediately), the credit-charging model (only charged for rendered frames, estimate at queue time), status polling until complete/error/canceled, downloads with direct URLs, the wait helper's exact_download_urls behavior, and free-tier resolution limits. This is rich, accurate behavioral context.

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

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

The description is longer than average but well-structured with clear headers: What this API does, Good for, How it works, Key options, Cost, MCP guidance. Purpose is front-loaded and each section earns its place. The 'Extra fields' bullet is slightly vague and the sentence 'Inputs: usually a file, sometimes a YouTube link' is ambiguous against the schema, so it's not flawless.

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

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

An output schema exists, so return-value documentation isn't the description's job, and the async workflow, polling, downloads, and cost are all covered. However, there is a real gap: the 3-step workflow tells the user to upload inputs and copy file_path, but the input schema exposes no file_path/input parameter — an agent cannot determine how to attach the uploaded asset to this call. That misalignment leaves the description incomplete for a complex 7-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?

Schema description coverage is 86%, so the baseline is 3 and the schema already documents most parameters richly (per-model resolution, duration, aspect ratio support). The description adds modest value on resolution tier limits but its 'Extra fields' sentence mentioning face_swap_mode and start_seconds is confusing since those aren't in the schema, and it calls the required text prompt an 'extra field.' Net: minimal added meaning, slight inaccuracy.

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: 'Create the same Text To Video you can make in the browser, but programmatically.' This is specific and understandable. However, it doesn't explicitly differentiate itself from nearby siblings like image_to_video_create_video or video_to_video_create_video — the 'Good for' section is about automation generically rather than what makes text-to-video unique among the 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 gives clear context (automation, batch processing, adding text-to-video into apps/pipelines) and the 3-step workflow explains the operational sequence. The MCP guidance also directs the agent to use the wait_for_video_project helper for finished results. However, it never names alternative tools or gives when-not-to-use guidance, so the when/alternatives distinction from a 5 is missing.

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 disclosure burden. It covers status semantics, when downloads gets populated, and the crucial fact that download URLs are already signed and must not be modified. This is strong, actionable transparency.

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, followed by a compact status table and MCP guidance. Every sentence earns its place, and the structure makes the polling workflow easy to follow.

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 fully equips an agent to poll correctly: it explains statuses, what to surface on completion, what to do on error, and how to handle download URLs. An output schema exists, so the description need not re-explain return values.

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

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

Schema coverage is 100%, so the id parameter is already well documented as the unique video project ID returned by creation APIs. The description adds contextual usage guidance but no new parameter-level semantics beyond what the schema provides.

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

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

The description clearly states the tool checks the progress of a video project and explains the status lifecycle. It does not explicitly differentiate itself from sibling tools like wait_for_video_project, so it stops short of full sibling differentiation.

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

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

The MCP guidance explicitly says to use this tool after a create tool to poll job status, and tells the agent what to do for complete and error statuses. However, it does not mention when not to use it or compare it to polling helper siblings, so it lacks exclusions and alternatives.

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

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

With no annotations provided, the description carries the full behavioral burden and does so thoroughly. It discloses that the API starts an async job and immediately returns id plus credits_charged, that users must poll or use the wait helper, that completed projects include downloads, and that direct public URLs may fail. It also explains credit billing and free-tier resolution limits, which are not available in structured fields.

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

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

The description is well-structured with headings, bullets, and a numbered workflow, making it scannable. It is long but mostly justified by the tool's complexity and lack of annotations. There is some repetition, such as emphasizing 'programmatically' and the file-path upload guidance appearing in multiple places.

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 and nested parameters, the description is unusually complete: it covers the full workflow, upload flow, job lifecycle, polling, downloads, cost behavior, and common failure mode with hotlinked URLs. Combined with the output schema, nothing essential is missing for an agent to invoke and monitor the tool correctly.

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

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

Schema coverage is high (83%), so the baseline is 3, but the description adds genuinely useful parameter context beyond the schema: how to obtain and pass file_path, when YouTube URLs are appropriate, resolution tier limits, and extra optional fields. It helps the agent make better decisions about video_source and file handling without repeating the schema's field-level documentation.

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

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

The description states a specific action and resource: 'Create the same Video To Video you can make in the browser, but programmatically.' It also identifies automation and batch processing as core use cases. However, it does not explicitly differentiate itself from sibling video creation tools such as image_to_video_create_video or 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 description provides clear 'Good for' use cases, a 3-step workflow, and explicit MCP guidance for async job handling: call wait_for_video_project or poll GET /v1/video-projects/{id} until complete. It also gives practical file-path guidance, advising the presigned upload flow over direct hotlinked URLs. It does not mention exclusions or when to prefer a sibling tool, so it stops short of full alternative routing.

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

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

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.

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

For a polling tool with six parameters, no output schema, and no annotations, the description covers the main loop and download behavior but leaves meaningful gaps: parameter semantics are undocumented, failure-mode return values are unspecified, and there is no mention of how this relates to the create_image siblings whose projects it awaits. It is adequate for basic use but incomplete for nuanced calls.

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, but it never defines any of the six parameters. It only indirectly references download-related behavior ('attempts to inline image downloads', 'sanitized download fields') and polling, which gives partial context for include_inline_downloads, max_inline_downloads, max_bytes_per_download, and the timeout/interval parameters. Parameter names and defaults are self-explanatory, but direct documentation is absent.

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

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

The description states a specific verb ('Poll'), a specific resource ('an image project'), and the exact terminal conditions (completes, errors, is canceled, or times out). This clearly distinguishes it from sibling wait_for_audio_project and wait_for_video_project, since the resource type is named explicitly.

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

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

Usage is implied rather than explicit: the description says it polls an image project but never states 'use this after creating an image project' or contrasts it with the project-retrieval siblings like image_projects_retrieve_details. An agent can infer the intended context from the name and the create_* siblings, but no explicit when/when-not guidance is given.

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 must carry behavioral disclosure. It does so by stating that the tool repeatedly polls until completion, error, cancel, or timeout, and returns sanitized download fields. It also adds an important operational warning about using exact_download_urls[n] or downloads[n].url verbatim, which goes 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?

Two sentences, both purposeful: the first defines the tool's behavior and terminal states; the second gives a critical URL-handling directive. The main verb is front-loaded and no text is wasted.

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

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

The description covers the main waiting behavior and the download-URL caveat, but with no annotations, no output schema, and 5 undocumented parameters it leaves gaps around optional inline-download params, exact return shape, and how it relates to sibling retrieve/fetch tools. It is adequate for a default id-only call, 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?

The input schema has 0% description coverage, and the description adds almost no parameter-level meaning. 'Poll' and 'times out' implicitly map to poll_interval_seconds and timeout_seconds, but max_inline_downloads, include_inline_downloads, and the required id are not explained at all.

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 the specific verb 'Poll' and names the resource, 'a video project'. It enumerates the terminal states it waits for — completes, errors, canceled, times out — and states the result, sanitized download fields, making it clearly distinguishable from create/retrieve/delete siblings.

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

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

The first sentence establishes a clear use case: use this tool when you need to poll an existing video project until it reaches a terminal state. It does not explicitly name alternative tools like video_projects_retrieve_details or create_video tools, and there are no exclusion statements, so it falls just short of full routing guidance.

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