Magic Hour

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 handles it excellently. It states that the operation is asynchronous, what is returned immediately, what statuses to expect, how to retrieve completed downloads, and it warns about the failure mode of hotlinked URLs. It also mentions the credits cost, which is material behavior not visible in the schema.

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

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

The description is a bit long, but every sentence contributes practical guidance. It is front-loaded with the core function and cost, then breaks down workflow steps into a clear labeled bullet structure. The dense content is justified because the tool has an intricate async flow.

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

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

For a complex async tool with no annotations and no visible output schema details, the description covers all necessary operational ground: async initiation, result retrieval, status checks, download URLs, and file-upload conventions. The agent has enough to invoke the tool correctly and follow up with helper calls. The only minor omission is explicit rate-limit or authentication guidance, but that is often handled at the API level globally.

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 provides 100% parameter coverage, so the baseline of 3 applies, but the description adds meaningful extra guidance beyond the schema. It gives explicit instructions on what *file_path values should be, explains how to obtain them via upload URL endpoints, and warns against relying on public URLs. This goes beyond merely restating the schema fields.

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

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

The description opens with a specific, action-oriented statement — 'Change outfits in photos in seconds with just a photo reference' — which clearly identifies the tool's unique purpose among the many image-creation siblings. The distinction between this and other tools like head_swap or body_swap is evident from the 'outfits' phrasing and the garment-focused input schema.

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

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

The description gives concrete operational guidance: it starts an async job, returns an id, and instructs the agent to use wait_for_image_project or poll the endpoint. It also provides conditional file-path guidance ('prefer... Direct public media URLs may work... when in doubt, use the presigned upload flow'), which is useful for choosing inputs. It doesn't explicitly name alternative tools to consider, but the usage context is clear enough for an agent to know when this tool applies.

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 burden. It discloses cost, subscription-dependent output size, async submission behavior, immediate response shape, terminal statuses, download URL behavior, and file-path pitfalls. This is far more transparent than a minimal one-line 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 front-loads the core purpose, cost, and output caveat, then separates the MCP guidance into clear bullets. It is somewhat long, but the length is earned by the complexity of async workflows and asset-upload handling, with little 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 complex async tool with nested parameters and an output schema, the description covers all invocation-critical information: what is returned immediately, how to get the final result, statuses to poll for, where downloads appear, and how to handle file assets. Nothing essential is missing.

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

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

The schema coverage is 100%, so the schema already explains all parameters, including the style sub-parameters and assets. The description adds useful value by explaining how *_file_path values should be supplied, including the difference between Magic Hour file paths, presigned upload returns, and potentially unreliable hotlinked URLs.

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

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

The description opens with a specific verb+resource ('Edit facial features of an image using AI'), which makes the purpose clear. It does not explicitly differentiate itself from siblings like face_swap_photo_create_image or head_swap_create_image, so it stops short of full sibling-level distinction.

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

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

It provides clear workflow guidance: the call is async, returns id and credits_charged immediately, and the agent should call wait_for_image_project or poll the status endpoint until a terminal state. It also gives practical guidance for file_path inputs. Alternative-tool comparisons are not explicitly stated, but the usage context is clear.

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

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

With no annotations provided, the description fully carries the behavioral transparency burden and does so well: it discloses the 50-credit cost, the async initiation, crediting of charges, the returned id, and the 'complete', 'error', or 'canceled' statuses. It also tells the agent exactly where to find downloads and how wait_for_image behaves differently.

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

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

The description is well-organized and front-loaded: purpose and cost first, then async behavior and retrieval guidance. Each sentence conveys meaningful operational detail without filler or redundancy, and the length is justified by the tool's async nature.

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 provides all non-schema context a caller needs: cost, immediate response shape, how to obtain the final result, relevant statuses, and where downloads appear. The provided output schema covers the rest. No critical behavioral context is missing.

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

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

The input schema already documents the name, prompt, and output_format parameters with examples and defaults, so the description is not required to repeat them. However, the description adds no direct parameter-level semantic guidance beyond referencing credits and the asynchronous flow. At ~67% schema coverage, the description stays at the baseline rather than enhancing parameter understanding.

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

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

The opening line 'Create an AI GIF' uses a clear verb and resource, giving an unambiguous one-sentence purpose. It is distinguishable from sibling image-generation tools because it specifically targets GIF/animation generation, not static images. No ambiguity remains about the tool's core function.

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

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

The description provides clear context on how to use the tool: it starts an async job, returns an id, and directs the agent to either call wait_for_image_project or poll the endpoint for the final result. It does not explicitly contrast this tool against alternative creation tools, but the async workflow guidance is concrete and 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 provided, the description fully discloses important behavior: the operation is asynchronous, it charges 50 credits, it immediately returns id and credits_charged, and statuses must be polled until complete/error/canceled. It also exposes the failure mode of hotlinked URLs and the download-expiration nuance in wait_for_image_project's response.

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

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

The description is front-loaded with the core action and cost, then uses compact bullets for operational guidance. Every sentence adds necessary information, and the formatting makes the asynchronous flow and file input advice 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?

Given the output schema already documents return shapes, the description covers all essential operational context for this tool: invocation cost, async return, completion statuses, next-step helper, and robust file path selection. An agent has enough guidance to call the tool and process the result correctly without further searching.

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 name, image_file_path, and the style.prompt field with examples. The description adds practical meaning for the image_file_path parameter by explaining how to source a valid path and why presigned uploads are preferred, which is valuable 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 an AI headshot', which is a specific verb and resource. It immediately identifies the tool's purpose and adds a cost constraint ('Each headshot costs 50 credits'), making it unambiguous among the many sibling image-creation 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 execution: call wait_for_image_project with the returned id, or poll the endpoint until completion. It also gives a concrete decision rule for file inputs, stating when to use a Magic Hour file path, a presigned upload file_path, or a direct URL, with the caveat 'when in doubt, use the presigned upload flow first.'

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

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

With no annotations to rely on, the description carries the full burden and handles it very well. It discloses async behavior, immediate return values, completion statuses, download URLs, expiration metadata, and even failure-prone input types like hotlinked URLs. This is unusually transparent for a tool 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 compact, well-organized under an 'MCP guidance' label, and front-loads the essential async behavior before the file-path guidance. Every sentence adds useful information without repeating schema content.

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

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

Given the 7-parameter nested schema, the presence of an output schema, and the absence of annotations, the description covers the critical behavioral context: async job lifecycle, completion handling, downloads, and file upload strategy. An agent has enough information to invoke the tool and follow up correctly.

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

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

Schema coverage is 86%, so the schema carries most parameter meaning. The description adds important semantics for image path inputs, explaining the preferred Magic Hour file_path, the upload-URL flow, and why direct public URLs can be unreliable. This meaningfully reduces the chance of incorrect file handling.

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 'Edit images with AI,' which clearly names the verb and resource. The tool name itself reinforces that this is an image editor rather than a generator, but the description does not explicitly differentiate it from other image-editing sibling tools such as face editor, clothes changer, or body swap.

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 strong operational guidance: it explains the async nature, the returned id, and the wait helper or polling endpoint. However, it never explicitly states when to choose this tool over alternative image-editing siblings, so usage is more implied than directly specified.

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 behavior disclosure burden. It thoroughly explains the asynchronous nature, immediate return of id and credits_charged, polling statuses, and download URLs, leaving the agent well-informed about the actual request lifecycle.

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 brief, front-loaded with the core action, and densely packed with necessary MCP workflow information. Every sentence in the second paragraph earns its place by explaining async behavior and retrieval paths.

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 image-generation tool with six parameters and a nested style object, the description covers the full request lifecycle: immediate response, follow-up wait/poll strategies, statuses, and download access. The output schema provides the remaining return value details, so no critical operational context is missing.

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

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

Schema description coverage is 100%, and the schema provides deep details for all parameters, including model costs, resolutions, tiers, and defaults. The description adds little direct parameter semantics beyond saying 'advanced model selection and quality controls,' which is acceptable given the schema's richness.

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

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

The description clearly states the tool creates an AI image with advanced model selection and quality controls, which is a specific verb and resource. It does not explicitly distinguish itself from sibling generators beyond the 'advanced model selection' detail, but the core action is unambiguous.

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

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

The description provides clear post-call guidance for handling async jobs, including when to use wait_for_image_project versus polling. However, it does not explain when this image generation tool should be used instead of the many sibling image-related tools, nor does it list 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 provided, so the description carries the full burden. It discloses that the call starts an async job, returns an id and credits charged immediately, explains polling and statuses, mentions completed downloads, and warns about hotlinked URLs. That is rich behavioral detail 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 structure is front-loaded with purpose and cost, then MCP guidance. It is a bit long but every part earns its place given the complexity and the absence of annotations. It avoids redundant repetition of schema content.

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

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

Given that the tool has a nested input schema, async behavior, and an output schema, the description covers the full lifecycle: how to call it, how to wait for it, how to check status, and how file paths should be prepared. No critical information is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds important meaning by relating scale_factor and mode to credit costs, noting tier restrictions for 4x, and giving practical guidance for assets.image_file_path.

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 uses a specific verb and resource: 'Upscale your image using AI.' This clearly identifies the tool's function and distinguishes it from sibling image creation 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 description gives strong context about the async behavior, how to wait for completion, and how to handle file paths. It does not explicitly discuss when to select this tool over alternatives, but the clarity of the task and the workflow guidance make the intended use clear.

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

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

With no annotations provided, the description carries the full burden—and it delivers. It discloses that the job is async, that id and credits_charged return immediately, that each run costs 10 credits, how to poll for completion, and what happens on success. This is exemplary 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 compact and front-loaded: a one-sentence purpose statement, the credit cost, then a tight guidance block. Every sentence carries useful decision or invocation information without fluff.

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

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

For an async image-generation tool, the description covers the essential context: cost, immediate response, next steps, polling states, and completion artifact URLs. It does not explain the full output schema or every error/edge case, but those are partly covered by the nested schema and output schema metadata.

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

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

Schema description coverage is 50%, and the description adds almost no parameter-level meaning. It doesn't explain the style object or required topic/template fields, but the schema already documents the nested properties and default searchWeb value. This balances to a baseline score.

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 verb and resource: 'Create an AI generated meme.' It also adds context about credit cost, making the tool's function obvious. However, it does not explicitly distinguish it from sibling image-generation tools, so it misses the top 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 MCP guidance gives a clear post-invocation workflow: use the returned id with wait_for_image_project or poll the endpoint until completion, with specific terminal statuses. This is strong contextual guidance, though it stops short of explaining when to choose this tool over a sibling like ai_image_generator_create_image.

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

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

With no annotations provided, the description carries the full transparency burden and handles it well. It discloses that the job is asynchronous, that id and credits_charged return immediately, what statuses indicate completion, and that downloads and exact_download_urls are available in the finished result.

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 gives structured MCP guidance for the async workflow. Every sentence adds useful information with no filler.

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

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

The description explains the full lifecycle: initiating the job, receiving the id, waiting or polling, and resolving downloads. Combined with the schema and output schema, this is complete enough for an agent to invoke the tool and handle the result 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 does not add parameter-level guidance beyond the schema, but the schema already documents content, style, and name with examples and descriptions. Since the schema carries the parameter semantics sufficiently, this is acceptable, though the description could have reinforced what kind of content becomes a functional QR code.

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 an AI QR code.' This distinguishes it from the many sibling create_image tools, and the cost note adds concrete scope. Nothing is vague or tautological.

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

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

The description explicitly tells the agent what to do after invoking the tool: use wait_for_image_project with the returned id or poll the image-projects endpoint until a terminal status. It also names the exact sibling helper, so the agent knows the correct follow-up path.

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

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

With no annotations, the description carries the full behavioral burden, and it succeeds: it discloses that the job runs asynchronously, that it immediately returns `id` plus `credits_charged`, that polling must continue until `complete`, `error`, or `canceled`, and that completed projects contain `downloads` URLs. This is strong behavioral disclosure 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 definition uses a short summary followed by two focused, purposeful explanation sections. Every sentence addresses a practical concern: async response, polling, result availability, and valid file path handling. The length is appropriate for the tool's complexity.

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

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

The description covers the full call lifecycle, terminal statuses, download access, and file-path validity guidance, which is strong given no annotations. The one gap is that "audio or text input" is not fully reconciled with the schema, which requires `audio_file_path` as a nested required property; this could lead an agent to think text-only input is supported.

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

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

Schema coverage is 100%, so the schema already documents all parameters and the baseline is 3. The description adds meaningful semantics for `*_file_path` values: prefer Magic Hour file paths or upload-URL `file_path` values, and avoid fragile hotlinked URLs. That guidance directly improves param usage without being redundant.

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

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

The description names a specific operation and artifact: "Create a talking photo from an image and audio or text input." The output type "talking photo" distinguishes it from siblings like lip_sync_create_video or image_to_video_create_video. The wording is concise and does not simply restate the tool name.

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

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

The description gives clear guidance for the async workflow: if the user wants the finished result, call wait_for_video_project or poll the video-project endpoint. It also instructs callers when to prefer Magic Hour file paths and presigned uploads over hotlinked URLs. It does not explicitly compare this tool against sibling generation tools, but it provides clear procedural context.

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?

Because no annotations are provided, the description correctly carries the full behavioral burden, and it does so thoroughly: async job returning 'id plus credits_charged immediately'; statuses 'complete,' 'error,' or 'canceled'; downloads with direct URLs; credits charged only for rendered frames; and free-tier resolution caps. The hotlink-vs-presigned-upload warning is also an honest, non-obvious behavioral insight.

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 organized with clear section headers ('What this API does', 'Good for', 'How it works', 'Key options', 'Cost', 'MCP guidance') and bulleted lists, with the core purpose front-loaded. It is one of the longer descriptions, but each section earns its place with actionable information.

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

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

For a tool with no annotations and a rich schema, the description covers the full call lifecycle: upload, job creation, polling, so completion and download, plus cost estimation behavior. Since there is an output schema, the description needn't re-explain the return envelope; the mention of what returns immediately (id, credits charged) is sufficient. Minor lack of details on edge cases like retries or cancellation handling, but this is quite complete for a create-call.

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

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

Schema coverage is 86%, so the baseline is 3 and the description still adds meaningful meaning: it clarifies the *_file_path semantics (prefer Magic Hour file paths or upload-URL returned paths; hotlinks can fail), the free-tier 576px limit, and mentions fields such as face_swap_mode, start_seconds/end_seconds, and text prompts that go beyond the schema. A 5 isn't warranted because some fine-grained param constraints remain schema-only, which is acceptable.

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

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

The description states a specific verb + resource: 'Create the same Video Editor you can make in the browser, but programmatically,' which clearly identifies this as the programmatic video-editing job creator. It also signals that it creates videos from uploaded media inputs. However, with several sibling tools (video_to_video_create_video, text_to_video_create_video, image_to_video_create_video), the description never explicitly distinguishes itself from those alternatives, so it stops just short of a 5.

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

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

It gives clear use contexts ('Automation and batch processing', 'Adding video editor into apps, pipelines, or tools') and a 3-step workflow with an explicit pointer to the wait_for_video_project helper for async completion. This is actionable, but there is no explicit when-not-to-use guidance and no routing among the many sibling video-creation tools. For a tool in a large family, instructions to say which sibling to use would make this a 4 or 5.

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

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

With no annotations present, the description carries the full burden and does so well. It discloses that this is an async job, that the immediate response contains id and credits_charged, that costs depend on character count and round up, that completed projects expose downloads URLs, and that hotlinked URLs are fragile.

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 organized as bullets and MCP guidance. Each sentence earns its place; the content about async behavior, cost, file paths, and helper usage is dense and directly supports correct invocation rather than fluff.

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

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

The description covers the full invocation context: cost, async lifecycle, return behavior, completion states, download URLs, required file path guidance, and helper alternatives. An output schema is present, so the description does not need to enumerate return fields. The sibling wait_for_audio_project is referenced as the intended follow-up, and the note about upload-file-flow gives the agent enough direction to work 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 name, prompt, and audio_file_path, but the description adds genuinely useful semantics on top, especially around the audio_file_path param: acceptable formats, why presigned upload URLs are safer, and how direct media URLs can fail. The cost explanation adds context to the prompt parameter. Only a little extra semantic support is missing for the name and style params.

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 action and resource: 'Clone a voice from an audio sample and generate speech.' This clearly identifies both the verb and the domain, and distinguishes it from sibling tools like ai_voice_generator_create_audio, which generates audio without cloning from a sample.

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 the async nature and tells the agent when to call wait_for_audio_project or poll the endpoint rather than treating the immediate response as the final result. It also advises between using an existing file path, the presigned upload flow, and direct URLs, including a clear 'when in doubt' rule.

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

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

There are no annotations, so the description carries the full responsibility for behavior disclosure. It thoroughly explains that the job is asynchronous, that credits are charged by character count and rounded up, that the call returns immediately, that statuses include complete/error/canceled, and that completed projects include download URLs. This is far more transparent than the schema alone could be.

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

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

The description is compact and front-loaded: the core action and cost model appear first, followed by a tightly scoped MCP guidance block for async orchestration. Every sentence carries useful information, though the guidance block is slightly packed with polling details that could have been trimmed.

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 as an async creation job, the description completely addresses the main usage gap: how to go from the initial request to the finished audio. It mentions the immediate return value, the wait helper, the polling endpoint, terminal statuses, download URLs, and the helper's exact_download_urls addition. No critical workflow step is left unexplained.

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

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

Schema description coverage is 100%, and name, style, prompt, and voice_name all already have schema-level documentation. The description's mention of a character-cost relationship reinforces prompt semantics but does not add new parameter definitions or substantially improve on what the schema already provides.

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

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

The opening phrase 'Generate speech from text' states a specific verb, a concrete resource, and the input modality, making the tool easy to distinguish from sibling audio, video, and image generators. The mention of character-based cost and text-to-speech also reinforces that this is a text-to-audio 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 description clearly states when to use this tool versus immediately waiting on the result: it starts an async job, returns id and credits_charged, and tells the caller to use wait_for_audio_project or poll the endpoint when the finished result is needed. It does not explicitly contrast against ai_voice_cloner_create_audio, but the text-based generation context is strong enough to guide a reasonable 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 of behavioral disclosure and does it thoroughly. It clearly explains the async behavior, immediate return of `id` and `credits_charged`, terminal statuses, download URL behavior, and the unreliable nature of hotlinked media.

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 then separates asynchronous and file-path guidance into two clear blocks. It is dense but each sentence carries useful, non-redundant information.

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

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

Given the nested schema, 7 parameters, and output schema, the description covers the non-obvious invocation details: asynchronous job lifecycle, status polling, download URLs, and safe file-path sourcing. It lacks sibling differentiation, but the operational picture is complete enough for an agent to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful operational context by tying `fps` and `end_seconds` to frame cost and by giving practical guidance on how `*_file_path` values should be sourced. This goes beyond the schema.

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

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

The description states a clear verb-resource pair: 'Create a video animation.' It is clear about what the tool does but does not distinguish it from sibling video-generation tools like text_to_video_create_video or image_to_video_create_video. The distinction must be inferred from the tool name and parameters.

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

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

The MCP guidance provides strong post-invocation instructions: how to wait or poll for completion, and when to prefer presigned upload file paths over direct URLs. However, it does not say when to use this tool over the alternative video-generation siblings.

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

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

With no annotations at all, the description carries the full burden of behavioral disclosure. It explicitly calls out permanence and irreversibility, which are the most crucial facts for a destructive operation. It does not mention side effects or error behavior, but the central irreversible consequence 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?

Two short, purposeful sentences with no filler. The core action is front-loaded, and the warning about irreversibility is compact but decisive.

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

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

For a one-parameter delete operation, the schema and description cover the argument and the critical permanence warning. There is slight ambiguity about whether the audio project itself or just its rendered audio file(s) is destroyed, and no output/error semantics are mentioned, but nothing else is essential for calling the 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 only parameter, id, is already fully described in the schema with an example and provenance ('returned by all POST APIs that create an audio'). The description adds no additional parameter-level nuance, so the baseline of 3 for high schema coverage is appropriate.

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

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

States a specific verb ('delete') and resource ('rendered audio file(s)'), and the permanent-deletion framing makes it immediately distinguishable from sibling retrieval and creation tools. The description also aligns with the tool name audio_projects_delete while being explicit about the destructive nature.

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 'not reversible, please be sure before deleting' warning implies this should only be used when destruction is genuinely intended. However, it does not explicitly say when to use this over alternatives, e.g., verifying first via audio_projects_retrieve_details or canceling if the user is uncertain.

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

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

With no annotations, the description carries the full burden. It proactively explains when the 'downloads' field is populated, describes each status value, and warns that download URLs are signed and must not be altered. This is rich behavioral context beyond a simple 'get' definition.

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

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

The description is well-organized with a short lead sentence, a status list, and an MCP guidance block. Every part earns its place, including the URL-handling warning, without excessive filler.

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

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

For a single-parameter retrieval tool, the description is complete: it explains the parameter source, how to use the tool after creation, what each status means, what to do when complete or errored, and how to treat the download URLs. The output schema handles the return shape.

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 fully describes the 'id' parameter with an example and notes that create APIs return it. The description reinforces this by saying to use the tool after a create tool, but it does not add meaningful new meaning beyond what the schema provides. 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 states a specific verb and resource: 'Check the progress of a audio project' and goes on to list the possible statuses. This clearly distinguishes it from create/delete siblings and from wait_for_audio_project by focusing on one-time retrieval of current state.

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 tells the agent to use this tool after a create tool to poll job status and gives concrete follow-up behavior for both 'complete' and 'error' outcomes. It does not name wait_for_audio_project as an alternative for blocking waits, but the polling context is clear and 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?

No annotations exist, so the description carries the full behavioral burden — and it succeeds thoroughly. It discloses the async contract (returns id and credits_charged immediately), cost model (only frames that render), resolution tier limits (free users capped at 576px), file-input failure modes (hotlinked URLs can fail), and completed state behavior (downloads with direct URLs). The agent can predict the tool's behavior without guesswork.

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 (What, Good for, How it works, Key options, Cost, MCP guidance), which is appropriate for the complexity. Front-loaded summary sections help an agent scan quickly. It is slightly verbose and repeats the upload-URL concept more than once, but most content 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 definition covers the full lifecycle: preconditions (upload inputs, get file_path), invocation, postconditions (job statuses, downloads, direct URLs), cost estimation, plan restrictions, and a sanctioned wait/poll path. An output schema already exists, so return-value details do not need to be in the description. This is a remarkably complete standalone definition for a complex async job tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value above the schema by clarifying which inputs are expected ('usually a file, sometimes a YouTube link'), how to prefer file_path values over direct public URLs, and that direct public media URLs may work only under certain conditions. This gives the agent practical guidance for filling the asset parameters 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: 'Create the same Audio To Video you can make in the browser, but programmatically.' It clearly distinguishes this tool from sibling video generators (image_to_video, text_to_video, video_to_video) by naming the exact product category and its core conversion task. An agent can confidently identify what this tool does without opening the schema.

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

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

The description provides a concrete usage context under 'Good for' — automation, batch processing, and integration — and walks through the full 3-step workflow from upload to polling. The MCP guidance explicitly tells the agent to call wait_for_video_project or poll GET /v1/video-projects/{id} for the finished result, which is strong practical guidance. However, it does not explicitly state when NOT to use this tool versus its sibling 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 burden and does an excellent job: it discloses that the tool starts an async job, returns only id and credits_charged immediately, requires polling/waiting, and lists possible final statuses. It also explains file upload pitfalls and recommends the presigned upload flow. This is far beyond minimally transparent.

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

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

The description is organized in a clear, front-loaded summary followed by two focused MCP guidance blocks. Every sentence contributes actionable information with no fluff. The slightly longer length is justified because the async workflow and file-path constraints genuinely need explanation.

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 the full lifecycle: creating the job, waiting for results, possible statuses, download URLs, and file upload strategy. The output schema exists to describe the return values, so the description does not need to duplicate that. The description is complete enough for an agent to call the tool and interpret post-call steps 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?

Input schema descriptions already cover all parameters at 100%, so the baseline is 3. The tool description adds valuable extra semantics beyond the schema, specifically clarifying how '*'_file_path' values should be obtained and why the presigned upload path is preferred over public URLs. This helps the agent disambiguate the most error-prone kind of 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 opens with 'Automatically generate subtitles for your video in multiple languages,' which states a specific verb (generate), resource (subtitles for a video), and outcome. This clearly distinguishes it from sibling creation tools like image_to_video_create_video or text_to_video_create_video, which do different transformations.

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 next-step guidance: after the async job starts, use wait_for_video_project or poll the endpoints until a terminal status. It also gives concrete file-path handling rules with upload URLs and warns about hotlinked URLs. It does not explicitly state 'use this when subtitles are needed instead of other tools,' but the context and workflow are sufficiently clear.

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

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

With no annotations, the description carries the full behavioral burden and does so strongly. It discloses that the job is async, that id and credits_charged are returned immediately, that credits vary by resolution starting from 50 credits, which statuses indicate completion/failure, and that downloads include direct URLs. This is substantial 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 information-dense but well organized: a one-line purpose, then a focused MCP guidance block with two bullets. No filler is present, and the opening sentence front-loads the core purpose. It earns its length through the important async wait and file-handling instructions.

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

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

Given the nested assets object, async behavior, resolution-to-credit relationship, and file upload concerns, the description covers everything an agent needs to call the tool correctly and retrieve the final result. The existence of an output schema covers return details, while the description covers the workflow, statuses, downloads, and wait helper.

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

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

Schema coverage is already 100%, so the baseline is 3. The description adds meaning on top by explaining the credit implications of resolution and giving concrete guidance on how to source file_path values, including when to prefer the presigned upload flow. This is meaningful added semantic context rather than a restatement of 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: 'Swap a person into a scene image' using Nano Banana 2 Lite/Nano Banana 2. This clearly differentiates the tool from sibling face swap, head swap, and clothes changer tools without needing to inspect the schema.

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

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

The description gives clear context on how to handle the async workflow: call wait_for_image_project with the returned id or poll the GET endpoint. It also gives practical input guidance for *_file_path values. It does not explicitly name alternatives for when to use body_swap versus other edit tools, but the tool's purpose is unambiguous enough that this is a minor gap.

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

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

No annotations are provided, so the description carries the full behavioral burden. It explicitly discloses that the API returns `id` plus `credits_charged` immediately, that the job completes asynchronously with statuses `complete`, `error`, or `canceled`, and that results appear in `downloads` with direct URLs. It also adds billing context about credits being charged only for rendered frames. This is strong but not exhaustive, since auth or failure specifics are not covered.

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 clear headers, bullets, and a simple 3-step overview. It is appropriately front-loaded with the core 'What this API does' and 'Good for' sections, then dives into workflow, cost, and MCP details. Some redundancy exists between 'Key options', the schema, and inline parameter caveats, but the structure keeps the bloat manageable.

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

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

Given the nested schema and async job semantics, this description is robustly complete: it covers the uploading prerequisite, the job creation call, status polling, result download URLs, the `wait_for_video_project` helper, billing estimates, and file-path sharp edges. It even clarifies that the helper returns `exact_download_urls` separately. Little else is needed for an agent to invoke 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?

The input schema already covers 100% of parameters, and the description goes beyond the schema by explaining which file path values are safe, when direct public URLs might fail, and when to use the presigned upload flow. It also clarifies treat `_file_path` semantics, resolution plan limits, and mentions optional fields such as `face_swap_mode` and `start_seconds`/`end_seconds`.

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

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

The description says exactly what the tool does: 'Create the same Character Replace you can make in the browser, but programmatically.' It names the resource (character replace video jobs), the workflow (upload, create job, poll, download), and the asynchronous result being generated. This clearly distinguishes it from neighboring face/swap/video 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 description gives solid context for when to use it ('automation and batch processing', 'adding character replace into apps, pipelines, or tools') and explains the async polling flow. It also routes users to `wait_for_video_project` when they want the finished result versus just job creation. It does not explicitly enumerate when-not-to-use relative to sibling tools like `face_swap_create_video`, but the name and scope are fairly diagnostic.

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. It usefully discloses that the call is async and returns an id, that faces must be fetched via the details endpoint, that direct URLs may fail, and that pricing is currently free. The only minor omission is lack of explicit guidance about what the immediate response contains beyond the id, though this is partly covered by the output schema.

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

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

The description is longer than average, but every section serves a purpose: purpose, use-case context, pricing note, async workflow, and file path recommendations. The most important operational detail (async id and details endpoint) is front-loaded near the top of the MCP guidance. It is structured rather than rambling, though the pricing note could be trimmed.

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 moderate complexity, async nature, and two parameters, the description covers the full call flow: what it detects, why you'd use it, how the async id fits in, how to retrieve results, potential file-source pitfalls, and an upload solution. The presence of an output schema handles return-shape details, so nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by giving practical file_path guidance, explaining the presigned upload flow, and clarifying stability issues with direct URLs. The confidence_score semantics are already well covered in the schema, so the description does not need to repeat them.

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

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

The description starts with a clear verb and resource ('Detect faces in an image or video') and immediately explains the downstream use case: feeding detected faces into face swap photo/video APIs. It also explicitly points to the sibling face_detection_retrieve_details endpoint for retrieving results, distinguishing this tool from the retrieval step and other face-related tools.

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

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

It clearly explains when to call this tool: to get a face list before multi-face swaps. The MCP guidance provides a concrete async workflow (call this, get id, then call details endpoint), and it gives practical file_path rules with presigned upload fallback. This is explicit and 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?

No annotations are present, so the description carries the burden of behavioral disclosure. It states the tool returns a list of faces for later swap calls, implying a read-only retrieval action, but it does not describe retention, task-completion expectations, or what happens if the task is still processing. The presence of an output schema covers return details, but notable behavioral gaps remain for an un-annotated 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 two sentences, with the primary action in the first sentence and necessary cross-references in the second. It is front-loaded and free of redundant filler, with lean formatting and no repetition of schema information.

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

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

For a simple one-parameter retrieval tool with an output schema, the description explains why an agent would call it (to get detected faces for multi-face swaps) and where the id comes from (implied by the parameter schema). It adds the needed integration context that is not obvious from the schema, but it does not explicitly mention the task lifecycle or any polling requirement, leaving the agent slightly under-informed.

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% for the only parameter, id, including example and explicit origin from the face detection API. Since the schema already documents the parameter thoroughly, the description adds little extra parameter detail, so the baseline 3 stands.

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 and resource with a concrete statement: 'Get the details of a face detection task' and clarifies it returns 'the list of faces detected in the image or video.' It clearly distinguishes itself from sibling face_detection_detect_faces, which creates the task, by focusing on retrieving existing detection results.

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 a clear precondition and use case: use this API to retrieve detected faces for subsequent face swap photo/video calls, especially for multi-face swaps. It does not spell out when not to use it or explicitly name alternatives, but the context is strong enough to guide an agent to select this tool after a detection task exists.

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

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

With no annotations provided, the description carries the full behavioral burden, and it succeeds. It discloses that the tool starts an async job, returns id and credits_charged immediately, requires polling or a wait helper, reports final statuses, and behaves differently for direct URLs vs uploaded file paths.

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, useful examples, and front-loaded purpose. Each section earns its place, and the MCP-specific guidance is separated from general product context.

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 async lifecycle: upload, create, poll/wait, download, and cost behavior. It also handles edge cases such as public URL reliability and file upload fallback, making it complete for an agent to use correctly.

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

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

Schema description coverage is 100%, so the baseline is high. The description adds meaningful parameter-level guidance beyond the schema: how to obtain and pass file_path values, when direct URLs may be unreliable, and that face_swap_mode and start/end_seconds are the important options.

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 clearly that this API creates a Face Swap programmatically and explicitly labels it as an async video generation job. This distinguishes it from sibling tools like face_swap_photo_create_image and the surrounding media-creation family.

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 strong usage context: it is good for automation, batch processing, and embedding into apps. It also gives explicit agent guidance around the wait_for_video_project helper and direct polling. However, it does not explicitly state when not to use this tool or mention the photo face-swap sibling as an alternative.

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

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It covers several important behaviors: photo generation costs 10 credits, output dimensions depend on subscription, the job is asynchronous, credits_charged is returned immediately, and file_path values behave differently for hotlinked URLs. This is substantive disclosure for a create operation.

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

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

The description is reasonably compact and front-loaded with the core purpose and cost. The MCP guidance is structured into a meaningful list and each sentence delivers operational value. It is slightly long, but the content 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 context is rich: detailed schema descriptions cover nested parameters, pricing and async behavior are disclosed, and the description explains how to wait for completion. The schema covers parameter mechanics, and the description covers workflow. The main missing piece is explicit sibling/tool selection guidance, but for the mechanics of this tool, the definition is valuable.

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 because parameters are already well-documented with examples and conditions. The description adds useful guidance for *_file_path values, such as preferring upload-URL returned file_path or noting that hotlinked URLs can fail, which helps agents populate parameters correctly in practice.

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 'Create a face swap photo', identifying the exact verb and resource. This differentiates the tool from video face swap at a glance, though it does not explicitly name and contrast the sibling image tools such as head_swap_create_image or body_swap_create_image.

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

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

The description provides strong operational guidance: it explains that the operation starts an async job, returns id and credits_charged, and tells the agent to use wait_for_image_project or poll the status endpoint. However, it never explicitly states when to choose this tool versus alternatives such as face_swap_create_video, head swap, or body swap, so the selection guidance is only implied.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that the tool returns inline audio content and gives a critical instruction about not trimming the URL, but it does not mention potential side effects (if any), error conditions, or the behavior of the `max_bytes` parameter. It is partially transparent but not comprehensive.

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

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

The description is two sentences with no wasted words. It front-loads the core purpose and immediately follows with the critical usage caution. It is appropriately sized for a tool with two parameters and is 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?

For a simple two-parameter tool with no output schema and no annotations, the description covers the essential context: what it does, where to get the input, and the output format. The missing explanation of `max_bytes` and lack of error conditions are minor gaps given the low complexity, so it is fairly complete.

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

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

The schema description coverage is 0%, so the description must compensate for both parameters. It provides strong semantic guidance for `download_url` by specifying it should be the exact signed URL from `downloads[n].url` and clarifying that `expires_at` is not part of the URL. However, it gives no explanation for `max_bytes`, leaving its purpose and effect undocumented. Thus, it partially compensates but has a clear gap.

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

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

The description clearly states the verb (Fetch), the resource (audio `downloads[n].url` from a completed audio project), and the output format (inline MCP audio content). It distinguishes itself from the sibling tool `fetch_image_download` by explicitly targeting audio projects, and the mention of 'completed audio project' further narrows its scope.

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

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

The description indicates when to use the tool (when you have a completed audio project and need to fetch its audio content) and provides a key usage instruction about passing the exact signed URL without trimming query parameters. However, it does not explicitly name alternative tools or conditions for using them, so it misses the full 'when-not' guidance.

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

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

Since no annotations are provided, the description carries the full burden of behavioral disclosure, and it does add meaningful context: the output format (inline MCP image content for Inspector or compatible clients), the requirement for exact signed URLs (query parameters are load-bearing), and the crucial distinction that expires_at is separate metadata, not part of the URL. However, it does not disclose what max_bytes does (truncate? error?), what happens if the project isn't complete, or any error conditions. The description adds useful behavior but leaves significant gaps.

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

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

Two tight sentences with zero waste. The first sentence front-loads the purpose, and the second delivers the critical URL-handling caveat immediately after. Every clause earns its place, from the inline content format detail to the expires_at clarification. The minor grammar issue ('a image') is the only blemish.

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 tool with only 2 parameters and no output schema or enums, the description provides nearly everything an agent needs: the input contract (exact signed URL), output format (inline MCP image content), scoping context (completed image project), and a common pitfall (expires_at confusion). The only notable omission is the semantics of max_bytes and failure behavior, but for the tool's complexity level, the coverage is strong.

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

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

With 0% schema description coverage, the description had to compensate, and it does so excellently for download_url: it specifies passing the exact full signed URL without trimming query parameters and warns that expires_at is separate. This prevents a common mistake. However, max_bytes is not mentioned at all in the description; an agent must guess whether the default of 15,728,640 is a hard limit, and what happens if it's exceeded. The description fully covers one parameter and ignores the other.

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 verb and resource: 'Fetch a image downloads[n].url from a completed image project and return it as inline MCP image content.' This is specific about what it downloads (the image content) and from where (a downloads[n].url of a completed project). It differentiates from siblings like fetch_audio_download through the image resource type, though this distinction is carried by the tool name more than the description itself, and no sibling is explicitly named.

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 appropriate usage context with 'from a completed image project,' signaling the tool is only appropriate after project completion. The strong instruction to pass the exact full signed URL without trimming query parameters is actionable guidance for correct invocation. However, there's no explicit mention of alternatives or exclusions—it never says 'use fetch_audio_download for audio' or references the wait_for_image_project/imageProjects_getDetails workflow it belongs to. The workflow position is implied, not stated.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden and does so thoroughly. It discloses the async nature, immediate return of the id and credits_charged, statuses to poll for, download URL location, plan-based resolution cap, and credit cost, which goes far beyond a minimal mutation 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 more verbose than a one-liner, but every sentence delivers distinct value: the action, cost, resolution contract, async behavior, polling states, download result, and upload best-practice. It is well-structured with a front-loaded summary and bulleted MCP guidance, with no filler.

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

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

Given the absence of annotations, the description fully covers the lifecycle of the operation: what the user gets immediately, how to obtain the final result, expected statuses, and upload edge cases. The output schema covers the return shape, so the description need not repeat that. It is complete enough for an agent to select and drive 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 schema already documents all 3 parameters, so the description need not repeat them. The added MCP guidance provides valuable practical meaning beyond the schema: prefer Magic Hour file paths or upload-URL file_paths, and warns about hotlink failure. This enriches parameter semantics without repeating 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 clear, specific verb and resource—'Swap a head onto a body image'—making the tool's core function unambiguous. It distinguishes itself semantically from sibling tools like body_swap_create_image and face_swap_photo_create_image, though it does not explicitly name those alternatives.

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

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

The description gives clear operational context: it is an async job, costs credits, and should be followed by wait_for_image_project or polling. However, it does not explicitly state when to choose this tool over sibling tools or when not to use it, so the when-to-use guidance is implied rather than explicitly compared.

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 available, the description carries the full behavioral burden and does so thoroughly. It discloses the async job nature, immediate return shape, credit cost, completion statuses, download URLs, and important caveats about hotlinked URLs and file path handling.

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 efficient: purpose, cost, async behavior, and file-handling caveats are clearly separated. Every sentence adds actionable information without repetition or fluff.

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

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

Given the tool's async nature, cost, and file-upload complexity, the description is complete. It gives the agent all critical operational details: returned fields, waiting strategy, output URLs, and file source constraints. The existence of an output schema further covers response shape.

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 both parameters. The description adds extra value by elaborating on the expected file source and the recommended presigned upload flow, going beyond the schema's generic 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 verb and resource 'Remove background from image,' which precisely states the tool's function. This clearly differentiates it from the many sibling image tools like face swap, head swap, or upscaler.

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 explains the async workflow: returns an id immediately and instructs whether to call wait_for_image_project or poll the endpoint. It also provides file-path selection guidance with a fallback preference. It doesn't explicitly compare this tool to alternative editing tools, but the context is strong enough for 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 behavioral disclosure burden. It clearly discloses the most critical behavior: the action is permanent and not reversible. While it does not mention side effects beyond the image(s), for a single-resource delete tool 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 a single concise sentence that front-loads the key action, and the second sentence adds an essential irreversible warning. No words are wasted and every sentence contributes necessary information.

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

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

For a one-parameter delete tool with no output schema, the description is sufficient: it states what is deleted and that the action is irreversible. The id parameter is fully documented in the schema, so no critical context 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 description coverage is 100%, so the schema already fully documents the single id parameter, including its source and an example. The description adds no extra semantic detail and does not need to, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('delete') and resource ('rendered image(s)'), and explicitly marks the action as permanent. It clearly separates this tool from retrieval siblings like image_projects_retrieve_details and from delete tools for other media types such as audio_projects_delete or video_projects_delete.

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

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

The warning 'please be sure before deleting' implies this tool should only be used when the user has confirmed deletion, but it does not state explicit when/when-not conditions or name alternatives. The usage context is mostly implied by the tool name and permanent-delete framing.

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 does so well by enumerating all statuses, clarifying when `downloads` is populated, and warning agents not to alter signed URLs. It omits marginal details like rate limits, which are not critical for a check-operation 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 purpose is front-loaded, followed by a compact status list and actionable guidance bullets. Every section provides useful information and there is no filler, making the length appropriate.

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 is present, so return values don't need restating. The description completes the picture with status meanings, the render-download lifecycle, and how the agent should surface results to end users, leaving no critical gap for correct invocation.

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

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

The input schema already fully documents `id` with an example and explanation that it comes from POST APIs (100% coverage). The description does not add much parameter-level nuance beyond what the schema already provides.

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

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

Clearly states a specific verb and resource: checking the progress of an image project. The status list and download semantics make it easy to distinguish from sibling create/delete tools and from 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?

Explicitly says to use it after a create tool to poll job status, and explains what to do when status is `complete` or `error`. It gives clear context but does not explicitly name alternatives or when not to use it.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the API starts an async job and returns id plus credits_charged immediately, explains completion/error/canceled states and downloads field, and mentions direct URL limitations. It also explains cost behavior (credits charged only for rendered frames). While it doesn't cover all edge cases (e.g., rate limits, model-specific failure modes), these are significant behavioral disclosures for a generation API.

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 fairly long but front-loads the API intent, then groups the information into Good for / How it works / Key options / Cost / MCP guidance. Every section adds operational value (async behavior, cost, file-path best practices). It is somewhat verbose given that the schema files in many of the same model-support details, but most sentences earn their place by explaining behavior and best practices.

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 API with 7 params, nested assets, model-specific validations, and output schema, the description provides the async workflow, cost model, upload strategy, and completion-status handling. It is missing explicit mention of model constraints for parameters (e.g., max duration or resolution restrictions per model), but the input schema covers those exhaustively. It also doesn't enumerate every possible FAQ in the guide, but is sufficient for an agent to correctly invoke the tool and retrieve the result.

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

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

The input schema already has 100% coverage with rich per-model comments for most parameters, so the schema carries the heavy lifting. The description does add context about resolution tiers ('free users limited to 576px') and mentions extra fields like face_swap_mode, start_seconds/end_seconds, and text prompt that aren't in the current schema properties. That is helpful context, but the schema is already very descriptive, and the description does not systematically explain required parameters beyond the image_file_path usage.

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 Image To Video you can make in the browser, programmatically, via an async job. It distinguishes the resource (image-to-video generation) from siblings like text_to_video_create_video and ai_talking_photo_create_talking_photo. The verb 'create' plus the explicit 'image to video' resource and mention of automation/scale leaves no 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 description provides a 3-step workflow, explicitly mentions the upload URL flow, tells users to poll or use the wait_for_video_project helper for completion, and clarifies when direct URLs may fail versus when to prefer presigned uploads. It also distinguishes this from video_to_video and text_to_video by focusing on image input, and the sibling list confirms the unique async video project flow with wait_for_video_project.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the tool starts an asynchronous job, returns id and credits_charged immediately, charges only for rendered frames, and requires polling/helper waiting for completion. It also discloses edge-case uncertainty with hotlinked public media URLs and gives a specific recommended flow for file_path usage.

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: it uses 'What this API does', 'Good for', 'How it works', 'Key options', 'Cost', and a separate MCP guidance section. Every section contains useful details, though the 'How it works' steps and MCP guidance repeat the asynchronous nature and file_path advice slightly. Strong front-loading of the core purpose makes it 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 complex asynchronous tool with nested inputs, the description is remarkably complete: it covers the full flow from upload URLs to polling status to retrieving downloads, explains cost/frame charging, resolution constraints, and even the return value of the wait helper. The presence of an output schema means return structures are documented, and the description adds important operational semantics (async, credits, URL reliability) that an agent needs 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 input schema already covers all 6 parameters with descriptions (100% coverage), so the baseline is 3. The description adds significant practical parameter context, especially for *_file_path values: prefer existing Magic Hour file paths, use presigned upload flow, and pass the returned file_path. This clarifies actual usage beyond the schema's generic param 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 begins with a specific verb and resource: 'Create the same Lip Sync you can make in the browser, but programmatically.' This unambiguously identifies the tool's function and distinguishes it from sibling video-generation tools (e.g., text_to_video_create_video, face_swap_create_video, audio_to_video_create_video). The name and description together are precise and non-repeatable.

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

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

The description explicitly covers what the tool is good for (automation, batch processing, integration into apps/pipelines) and outlines the 3-step workflow, which implies when to use it. It also provides detailed MCP guidance on how to handle the async result using wait_for_video_project, but it does not explicitly name alternative tools or state when not to use this tool. It gives clear context without formal exclusions.

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

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

With no annotations supplied, the description must carry the full behavioral burden, and it does. It reveals that this is an async job, that it returns id and credits_charged immediately, that waiting is required to get a result, what statuses to poll for, and what the completed project exposes. It even covers the exact_download_urls nuance and direct-URL risks.

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

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

The core action and cost are front-loaded, and the guidance is organized into two clear bullets. It is longer than a minimal description, but almost every sentence adds actionable information; only the download-URL detail feels slightly over-specified for a generic agent.

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, the description presents the full invocation context: async entry, immediate response shape, waiting/polling mechanism, final statuses, downloads, and file-path caveats. Combined with the existing output schema, the agent has enough to invoke the tool and interpret the result.

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

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

The input schema already documents both parameters well, so the baseline is 3. However the description adds practical semantics beyond the schema: how to prefer a stable Magic Hour file_path, when to use the presigned upload flow, and why direct public URLs can be unreliable.

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 phrase 'Colorize image' states a concrete action and resource. Among the sibling tools, no other tool is a colorizer, so the description can be told apart without opening another 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?

It does not name an alternative tool or explicitly say 'when not to use this', but it clearly implies the task and gives the important follow-up workflow: wait_for_image_project or polling the project endpoint until completion. It also exposes the 10-credit cost, which is useful context for an agent deciding whether to invoke it.

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

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

With no annotations, the description carries the behavioral burden. It clearly indicates a read-only connectivity check, implying no resource mutation or side effects. It does not elaborate on failure behavior, but the empty input schema and presence of an output schema cover the practical 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?

A single focused sentence that front-loads the action and target. There is no filler, redundancy, or unnecessary 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?

For a zero-parameter ping tool with an output schema, the description fully specifies what an agent needs to invoke and understand the tool. There are no prerequisites, side effects, or parameters to document.

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

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

The tool has zero parameters, so schema coverage is trivially 100%. The description adds no parameter-specific detail, but none is needed; baseline 4 applies.

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

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

States a specific verb ('Check') and resource ('Magic Hour MCP server reachability'). This clearly distinguishes it from sibling tools that create, edit, delete, or fetch media content.

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

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

The description conveys its intended use: verifying server reachability. It does not explicitly list when-not-to-use or alternatives, but no sibling tool serves as a health check, so the context is clear.

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

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

No annotations are provided, so the description carries the full burden, and it does so thoroughly. It discloses async behavior, that the API returns an id and credits_charged immediately, the exact statuses to poll for, download behavior, free-tier resolution limits, and how costs are computed over both queued and final states. This far exceeds a bare 'create a video' 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 well-structured with headings, bold labels, and numbered steps, and it front-loads the main purpose. It is somewhat long and repeats async/cost behavior between the Cost, How it works, and MCP guidance sections. This is relatively minor, so it earns a strong score but not a top score.

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 asynchronous paid video generation job, the description covers everything an agent needs to invoke it correctly: start, wait/poll, download, statuses complete/error/canceled, cost behavior, and connectivity to helper tools. Because the output schema exists, the description does not need to explain return values in detail. The definition is operationally complete.

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

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

Schema coverage is high at 86%, so a baseline of 3 is appropriate. The description adds useful context such as paid/free resolution differences and 'extra fields' like face_swap_mode and start_seconds/end_seconds, but it does not deeply connect these to the actual schema properties. Most parameter meaning is already carried by the input schema, so the description adds only marginal semantics.

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

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

The description states a specific verb and resource: 'Create the same Text To Video you can make in the browser, but programmatically.' It is clear that this tool creates text-to-video jobs at scale. It does not explicitly contrast itself with sibling tools like image_to_video_create_video or video_to_video_create_video, and the 'Upload your inputs (video, image, or audio)' line slightly blurs which inputs text-to-video actually takes.

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 usage context: automation, batch processing, and integrating text-to-video into apps or workflows under 'Good for.' The MCP guidance adds explicit next steps, telling the agent to call wait_for_video_project or poll the endpoint if a finished result is needed. No exclusions or when-not-to-use guidance is given relative to 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?

No annotations are provided, so the description must stand alone. It discloses that this is a local filesystem upload to a presigned URLcompress, which implies the server must have file access.backgroundColor. However, it does not mention potential issues like URL expiration, authentication, or error behavior. Given no annotations, this is adequate but not exhaustive.

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

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

Two sentences, no fluff. The first sentence states the action clearly, the second gives usage context. Perfectly 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 simple upload tool, it covers the purpose, the prerequisite (server reads local file), and the audience (local CLI). It doesn't mention details like expiration or method, but given the output schema exists and the tool is straightforward, it's 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 provides no parameter descriptions (0% coverage). The description explains `upload_url` as a presigned URL from the endpoint composite and mentions the local file path implicitly. However, `content_type` is not addressed at all, leaving one parameter underdocumented. The description adds some context but doesn't fully compensate for the missing 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 action: 'Upload a local file from the MCP server's filesystem to a presigned upload_url'. It specifies the source and destination, and explicitly mentions the presigned URL is returned by the upload-URL endpoint. This distinguishes it from all sibling tools, which are creators or fetchers.

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

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

Explicitly states when to use: 'for local CLI testing when the server can read the file path' and when not to: 'remote web-chat users still need a browser or backend upload bridge'. This gives clear 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 disclosure burden and does so well. It states that this does not upload files, that the response array matches input order, that a PUT request is required after a URL is returned, and that gif assets have a special face-swap constraint. This is specific, non-obvious context beyond the tool name.

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

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

The description is front-loaded, well-structured, and uses bullets notes and curl examples effectively. It is somewhat longer than necessary because the MCP guidance restates earlier workflow points and the extension table duplicates much of the schema enum, but it remains navigable and relevant.

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 endpoint has an output schema, so return-value details are not the description's job. The description covers the prerequisite workflow, the PUT upload method, extension validations, response ordering, and edge-case behavior for gif face-swap files. Overall, an agent has enough information to call the tool correctly and integrate the result into the creation flow.

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 the items, type, and extension exhaustively, so the baseline is 3. The description adds value by mapping valid file extensions to asset types and calling out that gif is only supported for the face swap video_file_path field. However, it lists gif as a separate asset type even though the schema's type enum only accepts video, audio, and image, so an agent could be led t produce an invalid 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 clearly states the tool's job in the first sentence: it generates pre-signed upload URLs for required assets. It also distinguishes itself from the actual upload step by explaining that this API only creates presigned URLs and is only needed when uploading to Magic Hour storage.

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: use it only when you need to upload to Magic Hour's storage. It also provides concrete instructions on the full workflow: upload the raw bytes to each returned upload_url, then pass the matching file_path into the create tool. It even covers when direct public URLs might work and advises preferring the presigned flow when in doubt.

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 reveals the most important behavioral trait: the deletion is permanent and irreversible. This is the key non-obvious consequence that must be surfaced. It does not discuss permissions or failure behavior, but for a straightforward delete-by-id operation the irreversibility warning is the central behavioral disclosure.

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

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

Two short sentences are efficient and front-load the action. The first sentence states what the tool does, and the second reinforces the irreversibility warning without rhetorical padding.

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

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

For a simple one-parameter deletion tool with no output schema, the description covers the essential context: what is deleted, that it is permanent, and a warning. It could go slightly deeper about consequences to associated project data or API return behavior, but given the low complexity this is a minor gap.

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

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

Schema description coverage is 100% — the single id parameter is fully described, including its origin ('returned by all of the POST APIs that create a video'). The tool description does not need to add param details, and it doesn't, so the baseline for fully covered schema 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 uses a specific verb ('delete') and a specific resource ('rendered video'), and adds the critical qualifier 'permanently' and 'not reversible.' This clearly distinguishes it from sibling retrieval tools like video_projects_retrieve_details and creation tools, while mirroring similar delete tools for audio and image projects.

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 intended use — deleting a video project when the user wants permanent, non-reversible removal — is clearly implied. The warning 'please be sure before deleting' reinforces the appropriate caution. However, there is no explicit 'use when' or 'use instead of' guidance, so it does not fully earn a 5.

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

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

No annotations are present, so the description carries the full burden and does it well: it explains the `downloads` field is only populated after a successful render, enumerates all statuses, and warns that signed download URLs must be used as-is. This provides important behavioral context for an agent. It does not explicitly state the operation is read-only, but 'check progress' clearly implies it.

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

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

The description is well-organized with a one-sentence purpose, a status map, and MCP guidance. There is a small amount of redundancy between the first sentence about `downloads` and the `complete` status entry, but the bulleted format keeps it scannable and useful.

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, the description covers purpose, statuses, download URL handling, and the proper polling workflow. An output schema exists, so the return shape is already documented. Nothing critical is missing for an agent to use this tool correctly.

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

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

The input schema already documents `id` completely, including its purpose and where to get it. The description adds no additional parameter semantics beyond emphasizing that the tool is used after a create operation, so the schema carries the full weight. Baseline of 3 applies.

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

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

States a specific verb and resource: 'Check the progress of a video project.' The status list and note about `downloads` clarify exactly what details are returned. It is clearly distinct from siblings like `wait_for_video_project` and `video_projects_delete`.

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?

Directs the agent to use this after a create tool to poll job status, which is actionable. It also tells the agent what to do on `complete` and `error` statuses. However, it does not explicitly name alternatives such as `wait_for_video_project` or state when not to use 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 burden, and it does this well. It discloses the async job behavior, immediate return of id and credits_charged, terminal statuses, download URLs, the behavior of the wait helper, credit-charging rules, resolution limits, and upload/path reliability. This is strong behavioral disclosure.

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

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

The description is well-structured with bold headers, bullets, and numbered steps, making it easy to scan. It front-loads purpose and usage. Some repetition exists between the opening 'What this API does' section and the 'Good for' bullet, and the product-page link could be considered clutter, but it remains mostly efficient.

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

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

Given the complexity of this endpoint—nested assets, async completion, uploads, downloads, and wait helpers—the description covers all the major decision points. It names the actual endpoint, the pollable statuses, the helper tool, and the file path pitfalls. Since an output schema exists, not detailing the full response in prose is acceptable.

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 83%, so the schema handles most parameter meaning. The description adds meaningful value by explaining file_path semantics, presigned upload flow, direct-URL risks, and prominent fields like start_seconds, end_seconds, style, and prompt. It does not cover every parameter in prose, but the schema already covers those details.

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

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

The description clearly identifies the tool as a programmatic way to create video-to-video outputs, with a specific verb and resource scope. It distinguishes from some siblings by calling out automation, batch processing, and pipeline integration. A small ambiguity exists where it says inputs can be video, image, or audio, while the schema requires a video source, which slightly clouds the otherwise clear purpose.

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 usage context: automation, batch workflows, apps, and pipelines, and emphasizes the asynchronous nature of the job. It also explains when to use the wait helper or polling endpoint. However, it does not explicitly compare itself against sibling generators such as text_to_video_create_video or image_to_video_create_video, so the when/not-when guidance is good but not exhaustive.

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

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

The description discloses several behaviors: polling until completion/error/cancel/timeout, returning final project JSON, attempting inline downloads when complete, and returning sanitized download fields. It also gives specific usage instructions about not modifying download URLs. Since there are no annotations, the description carries the full burden and does a fair job, though it doesn't explicitly state whether the operation is read-only or has side effects, but polling is inherently non-destructive.

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 four sentences, with the core action stated first. It includes critical caveats about URL usage without unnecessary elaboration. No wasted words.

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 six parameters and no output schema, so the description should compensate for both input and output documentation. It covers the high-level behavior and return, but lacks parameter explanations and detailed output structure. The guidance on URL handling is valuable but does not fill the gaps for parameters like max_inline_downloads or poll_interval_seconds.

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 explain each parameter's role. It only mentions 'Poll' which implies timeout and interval, and 'inline audio downloads' which relates to the download-related parameters, but it does not explain what these parameters do, their defaults, or their effects. The description focuses on output URL handling rather than input parameter semantics, leaving the agent to guess at meanings.

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: 'Poll an audio project until it completes, errors, is canceled, or times out.' It names the resource (audio project), the action (poll), and the outcome (final project JSON). It also distinguishes from siblings like wait_for_video_project and wait_for_image_project by specifying 'audio project.'

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

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

The description indicates when to use the tool—when you need to block until an audio project finishes. It also sets expectations for the return and the handling of download URLs. However, it does not explicitly mention alternatives like audioProjects_getDetails for one-time fetching, though the polling intent is clear.

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

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

No annotations exist, so the description carries the full burden, and it mostly delivers. It discloses polling to terminal state, conditional download inlining ('when complete, attempts to inline image downloads for Inspector or compatible clients'), and the mention of 'sanitized download fields' signals data processing. Gaps remain: no behavior on timeout expiry, failure codes, or rate limits, but this is a strong disclosure level for an unannotated tool.

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

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

Four sentences, front-loaded with the core polling purpose and ending with a critical safety warning about URL handling. Minor redundancy ('Returns sanitized download fields' repeats an idea in sentence two). No wasted words otherwise; the warning earns its place, making this tight, though 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?

No output schema exists, so the description must serve as the return contract. It covers 'final project JSON' and 'sanitized download fields', adequate for a poller's use case. But it omits terminal behaviour semantics: what happens on timeout, what an error/canceled state looks like in the response, and the meaning of 'sanitized'. With sibling wait_for_* tools following the same pattern, an agent gets the gist but lacks failure semantics.

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

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

With schema description coverage at 0%, the description must compensate. It partially does: 'attempts to inline image downloads' relates to include_inline_downloads and max_inline_downloads, and 'sanitized download fields' hints at output handling. However, it doesn't clarify timeouts, poll interval, or byte limits beyond self-evident names. Meaningful but incomplete compensation for the coverage gap.

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

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

Description states a clear verb+resource: 'Poll an image project until it completes, errors, is canceled, or times out.' The 'image project' scoping differentiates it from wait_for_audio_project and wait_for_video_project, though it doesn't name those siblings explicitly, which would be 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?

Usage context is mostly implied: it's the tool to wait on image projects, with alternatives (wait_for_audio_project, wait_for_video_project) obvious by name. It does provide a strong downstream instruction: 'Use exact_download_urls[n] or downloads[n].url exactly as returned; do not shorten it...', but there's no explicit when-to-use/when-not-to-use contrast with siblings or the getDetails endpoints.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool polls until terminal states, returns sanitized download fields, and warns against modifying URLs. This gives a clear behavioral contract for a polling operation, though it does not mention rate limits or how errors are surfaced (e.g., as exceptions or status codes).

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

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

The description is two sentences with no filler. The primary purpose is front-loaded, and the critical usage instruction about URL integrity follows immediately. 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 output schema and no parameter explanations, yet the description only partially compensates. It states the terminal outcomes and the nature of the output, but it does not detail the expected return structure beyond 'sanitized download fields', nor does it mention potential edge cases like project not found or timeout behavior. For a polling tool that may be used in automated workflows, this leaves notable 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 0%, yet the description does not explain any of the three parameters (id, timeout_seconds, poll_interval_seconds). While the parameter names are somewhat self-explanatory, the description offers no additional meaning or constraints, leaving the agent to guess how they relate to the polling behavior described.

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 action (poll), the resource (a video project), and the terminal states (completes, errors, canceled, or times out). It also names the output ('sanitized download fields'), making the tool unambiguous and distinct from siblings like wait_for_audio_project and 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?

The description implies when to use it (when you have a video project and need to wait for completion), and it gives a specific post-invocation instruction about using the returned URLs exactly as provided. However, it does not explicitly mention alternatives or conditions when not to use this tool, leaving some room for inference.

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