Magic Hour

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

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

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

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

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

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

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

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

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

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

The input schema already covers all parameters with descriptions, so the baseline is 3. The description adds meaningful operational guidance for *_file_path values: prefer existing Magic Hour paths or upload-URL file_paths, and use the presigned upload flow when hotlinked URLs are questionable. This goes beyond the schema's basic 'either URL or file_path' text.

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

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

The opening sentence names a specific verb ('change') and resource ('outfits in photos'), making the tool's domain unmistakable. It implicitly differentiates this tool from sibling image-creation tools like face_swap_photo_create_image and head_swap_create_image.

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

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

The MCP guidance explicitly tells the agent what to do after invocation: use wait_for_image_project with the returned id or poll until a terminal status. It also gives file-path policy, preferring Magic Hour file paths or upload-URL file_paths over unstable hotlinked URLs. However, it does not explicitly state when to choose this tool over siblings like body_swap_create_image, though the use case is clear from the purpose.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the tool starts an async job, returns `id` and `credits_charged` immediately, explains polling and status values, describes the `downloads` field, and mentions costs and output-size dependency. This is exceptionally transparent and goes far beyond what the structured schema provides.

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

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

The description is well-structured and front-loaded: a concise purpose statement, cost note, pricing link, and then clearly separated MCP guidance bullets. Every sentence adds operational value; nothing is redundant or filler. Despite being longer than minimal, it earns its length.

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

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

Given the tool's complexity, async nature, nested style parameters, and upload requirements, the description covers all essential operational aspects: job initiation, waiting, polling, statuses, downloads, file path handling, and output-size variability. The output schema signal further reduces the need to explain return values, but the description still gives the key immediate return fields.

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

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

The schema already provides 100% description coverage, so the baseline is 3. The description adds valuable extra meaning for `*_file_path` values by explaining the preferred upload flow versus direct URLs and warning about hotlink failures. This goes beyond the schema and merits a 4.

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

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

The first sentence states a specific action and resource: "Edit facial features of an image using AI." This clearly distinguishes the tool from siblings like generic image editors or clothes changers. Even with a null title, the description leaves no ambiguity about what the tool does.

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

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

The description clearly tells the agent when to use the tool: to edit facial features in an image. It also gives important context about async execution and how to wait for results, but it does not explicitly name alternatives or state when not to use this tool. It is clear context without exclusions, so it earns a 4 rather than a 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently explains that the tool is async, returns 'id' and 'credits_charged' immediately, deducts 50 credits, and describes the completion states and how to retrieve results. This exceeds typical transparency for such tools.

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

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

The description is concise and well-structured: a one-sentence purpose statement followed by a focused 'MCP guidance' block. It front-loads the key cost and async behavior without redundant elaboration, though the guidance paragraph is slightly dense.

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

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

The description covers the essential aspects an agent needs: cost, async behavior, how to get the final result (via wait helper or polling), and expected statuses. It does not mention error handling specifics, but given the tool's nature and the provided schema (including an output schema), it is sufficiently complete for correct invocation.

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

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

The schema already provides detailed descriptions for all three parameters (name, style.prompt, output_format), so the description adds no additional meaning. Given the high schema coverage (67% as signaled, though all visible params have descriptions), the baseline of 3 is appropriate; the description does not need to compensate further.

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 'Create' and the resource 'AI GIF', and explicitly notes the cost per GIF. It distinguishes itself from sibling image-creation tools by focusing on GIF generation. The purpose is unambiguous and immediately understandable.

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

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

The description provides explicit MCP guidance on the asynchronous nature of the job, instructing the agent to call the 'wait_for_image_project' helper or poll the endpoint. It specifies exact statuses to check and where to find downloads, leaving no ambiguity about how to use the tool correctly.

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

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

With no annotations provided, the description fully bears the weight of behavioral disclosure. It clearly states the async nature, immediate return of id and credits_charged, the required follow-up to retrieve results, and the pitfall that hotlinked URLs can fail. This goes well beyond a simple 'create' statement and prepares the agent for the operation's real-world behavior.

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

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

The description is well-structured: it front-loads the core purpose and cost, then provides targeted MCP guidance in two bullets. The file-path instruction is verbose but essential and directly actionable. There is no filler, and the flow from purpose to async handling to input requirements is logical.

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

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

Given the async workflow and the presence of sibling wait_for_image_project, the description adequately covers the complete call sequence: initiate, receive id, wait/poll, and retrieve downloads. It addresses the likely error sources (URL stability) and credits. It does not detail the output schema, but that is covered separately, and it omits any rate-limit or retry information, which are minor for this 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?

While the schema already documents name, style, and assets with good coverage (67%), the description enriches the most critical parameter, assets.image_file_path, by explaining the preferred input methods (Magic Hour file paths or upload-URL file_path) and warning about unreliable hotlinked URLs. This adds practical meaning that the schema hints at but doesn't fully convey. Other parameters (name, style) are straightforward and need no extra explanation.

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

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

The description opens with 'Create an AI headshot,' a clear verb+resource statement that exactly matches the tool name and differentiates it from image editing, swapping, and other generation tools. It also specifies the cost and confirms the resource type, leaving no ambiguity about what the tool does.

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

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

The description provides strong post-invocation guidance: it explains that the job is async and directs the agent to call wait_for_image_project or poll the endpoint. However, it never explicitly states when to use this tool versus alternative generators (e.g., face swap or clothes changer). The intended usage is implied by the name and purpose but not directly contrasted with siblings, so exclusions are missing.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It does this excellently: it explicitly states the tool starts an async job, returns `id` and `credits_charged` immediately, requires waiting or polling, lists terminal statuses, describes `downloads` URLs, and gives detailed `exact_download_urls` behavior. It also discloses file-path pitfalls and recommends the upload flow.

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

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

The description is well-structured with a one-line purpose followed by focused MCP guidance. The bullets are somewhat long, but every sentence carries necessary operational detail for a complex async tool. It is front-loaded with the core purpose and then dives into actionable behavior, striking a good balance for its 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 most important operational context: async behavior, return shape at submission, how to retrieve results, terminal statuses, download URL handling, and file-path selection. Since an output schema exists, detailed return value documentation is not required. The description is complete enough for an agent to invoke the tool and handle the follow-up workflow correctly.

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

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

Schema coverage is high at 86%, and the schema already documents parameters thoroughly, so the baseline is 3. The description adds meaningful value by explaining how to handle `*_file_path` values, specifically recommending Magic Hour file paths or upload-URL returned paths and warning against hotlinked URLs. This directly aids parameter use beyond the schema.

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

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

The description states a clear verb and resource: 'Edit images with AI.' This distinguishes the tool from generative image creation or upscaling at a basic level. However, it does not explicitly differentiate from sibling image-editing tools like ai_face_editor_edit_image or body_swap_create_image, leaving some ambiguity for an agent choosing among similar 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 explains how to use the tool (async job, wait helper, polling) but does not provide explicit when-to-use versus alternatives guidance. It implies usage by saying 'Edit images,' but there are no exclusions or sibling comparisons. An agent would need to infer selection criteria from the name and schema rather than from clear guidance.

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

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

With no annotations provided, the description carries the full burden, and it delivers: it discloses the async job behavior, immediate return of id and credits_charged, how to obtain the finished result via the wait helper or polling until complete/error/canceled status, and that completed projects include downloads with direct URLs. It even notes the exact_download_urls distinction. This is thorough, accurate 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 purpose statement is front-loaded in one concise sentence, followed by a well-organized MCP guidance block covering the async workflow. The guidance is earned content given the job-based nature of the tool. Minor inefficiency: it describes both the wait helper and the raw polling GET endpoint, where the wait helper alone would suffice for most agents.

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

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

The output schema covers return values and the input schema covers all 6 parameters at 100% coverage, so the description only needs to convey the workflow — which it does completely. It tells the agent the job is async, what comes back immediately, how to wait for completion, the possible terminal statuses, and where download URLs live. Nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description itself adds minimal parameter-level meaning beyond the schema, but the schema already documents each parameter richly (model enum with costs/resolutions/tiers, resolution per-model support, style tool enum). The description's mention of id and credits_charged adds return-context rather than parameter semantics. Baseline 3 is appropriate.

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

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

The description states a specific verb+resource ('Create an AI image') and adds 'advanced model selection and quality controls' which clearly distinguishes this general-purpose generator from the many specialized siblings (ai_clothes_changer, ai_face_editor, ai_headshot_generator, etc.). An agent can immediately tell this is the general/advanced tool rather than a niche one.

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 workflow guidance: it explicitly says this starts an async job, returns id plus credits_charged immediately, and tells the agent to call wait_for_image_project or poll the GET endpoint for completion. However, it does not explicitly state when to use this tool versus the many sibling image generators (when-not/alternatives routing is only implied by 'advanced model selection'). The async guidance is present but the sibling differentiation is absent.

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

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

With no annotations provided, the description carries the full burden, and it delivers: it discloses async execution, immediate return of id and credits_charged, terminal statuses, download URLs, credit costs by scale/mode, and potential failures with hotlinked URLs. There is no contradiction with any annotation because none are present.

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

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

Although longer than average, the description is well structured: a one-sentence summary, a cost breakdown, then bulleted MCP guidance. Every section adds actionable information, and the async caveat is front-loaded so the agent knows what to expect.

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, cost-accounted, file-input tool with no annotations, nothing critical is missing. It covers how to start the job, how to await completion, how to interpret results, and how to supply input files. The schema and output schema handle parameter and return types, and the description handles the behavioral context.

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 four parameters, so the baseline is 3. The description adds genuine value by mapping scale/mode combinations to exact credit costs and by giving file-path selection guidance for assets.image_file_path that is not inferable from the schema alone.

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

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

The description opens with a specific verb and resource ('Upscale your image') and the tool name itself identifies this as the upscaler among many sibling create-image tools. It further disambiguates the operation by explaining credit costs and modes, making the purpose unmistakable.

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

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

The MCP guidance clearly states that this starts an async job and tells the agent to call wait_for_image_project with the returned id or poll the endpoint until a terminal status. It also gives explicit file_path handling guidance. It does not enumerate when not to use this tool versus sibling image tools, but the unique upscaling operation makes the primary usage context clear.

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

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

With no annotations, the description carries the full burden. It clearly discloses that the tool starts an async job, returns id and credits_charged immediately, charges 10 credits, reaches complete/error/canceled states, and provides download URLs plus exact_download_urls via the helper. This is exemplary 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 compact: one sentence for the core purpose and cost, followed by a tight bullet for async behavior. Every sentence adds necessary guidance without filler.

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

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

Despite moderate complexity, the description covers cost, async semantics, statuses, retrieval, and download URLs. An output schema exists, so return values are further documented; no material context needed for correct invocation is missing.

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

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

Schema description coverage is only 50%, and the description adds no parameter-level meaning beyond what the schema already provides. It does not mention required style, topic, template, or the searchWeb option, so it fails to compensate for the schema 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 states 'Create an AI generated meme', which is a specific verb plus resource. The meme resource is distinct among siblings such as ai_image_generator_create_image and ai_gif_generator_create_image, so an agent can select it without opening schemas.

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

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

The MCP guidance gives clear instructions on what to do after invocation: call wait_for_image_project or poll the endpoint until a terminal status. It does not explicitly contrast this tool with alternatives, but the async workflow guidance is strong enough to guide correct usage.

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 excels: it discloses that the tool starts an async job, returns id and credits_charged immediately, lists possible terminal statuses, and describes how download URLs are exposed. It also notes the wait helper's special exact_download_urls behavior, which is highly informative.

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 every sentence earns its place: purpose, cost, async behavior, statuses, and download retrieval are all covered without padding. The 'MCP guidance' section front-loads the critical operational detail after a one-line purpose statement.

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 mutation-style tool with no annotations, the description is remarkably complete. It explains the immediate result, how to obtain the final result, which statuses to expect, and where to find direct download URLs. Nothing critical is missing for an agent to invoke the tool and handle its outcome 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 content, style, and name, including art_style examples, so the description adds little parameter-level meaning. Schema coverage is 67%, and the description does not compensate with additional guidance about how the parameters affect the generated QR code. It does not contradict the schema, but it also does not enrich it.

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

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

The description states a specific verb and resource: 'Create an AI QR code.' This clearly distinguishes the tool from the many sibling create_image tools, since QR code generation is a distinct capability. The zero-credit note also adds a meaningful, tool-specific detail.

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

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

The description provides clear context for the async workflow and explicitly instructs the agent to call wait_for_image_project with the returned id if the user wants the finished result. It does not explicitly contrast this tool with alternative image-generation tools, but the procedural guidance is strong and unambiguous.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Schema coverage is high (86%), so the baseline is 3. The description adds meaningful parameter-related context, especially for `assets.video_file_path` (prefer existing Magic Hour file paths, presigned upload flow, hotlink risks) and resolution limits (free vs paid tiers). It also mentions optional fields like `start_seconds`/`end_seconds` and text prompts, supplementing the schema.

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

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

The description clearly states the tool creates the Video Editor programmatically, with explicit verbs ('Create the same Video Editor... but programmatically') and identifies the resource (video editor job). It distinguishes itself from sibling video-generation tools by focusing on the editor use case (automation, batch processing, integration into apps/pipelines).

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

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

The description provides clear context for when to use this tool ('Good for' automation and batch processing, adding video editor to apps) and explains the full workflow (upload inputs, create job, poll status). It does not explicitly name alternatives or exclusion conditions, but the 'Good for' and workflow guidance make usage context strong.

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

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

With no annotations, the description carries the full burden and does it well: it discloses async job creation, the immediate `id` and `credits_charged` return, terminal statuses, download availability, and the failure mode of hotlinked URLs.

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

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

The description is more verbose than average but well structured with a one-line purpose, cost bullets, and MCP guidance. Details like `exact_download_urls` are slightly niche, but they support correct follow-up behavior rather than 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 creation tool with nested parameters and no annotations, the description covers the async lifecycle, polling/waiting options, terminal statuses, download results, and file-input pitfalls. Since an output schema exists, not repeating the return shape 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 67%, and the description adds meaningful semantics for `*_file_path` values by explaining upload-URL flow versus hotlinks, plus per-character credit cost relevant to `style.prompt`. It does not add much about `name`, but the schema already describes that 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 opening sentence uses specific verbs ('clone', 'generate speech') and states the resource (a voice from an audio sample). This clearly differentiates it from siblings like ai_voice_generator_create_audio, which would not clone from a supplied 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 tells agents to use wait_for_audio_project or poll the GET endpoint after the async job starts, and it gives concrete file-path handling rules. It does not, however, compare this tool with alternative creation tools or state when it should be chosen over them.

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

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

With no annotations provided, the description carries the full behavioral burden and handles it well. It discloses that the call is asynchronous, that it returns id and credits_charged immediately, that polling or the helper is required, which terminal statuses matter, and what completed projects contain. It also exposes the credit cost formula. This is unusually 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 compact, front-loaded with purpose, and uses a clearly separated MCP guidance block. Every sentence contributes either selection context or invocation-critical behavioral information. There is no redundant restating of schema fields.

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

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

The description is complete for an async generation tool: it explains inputs, cost, immediate return value, how to obtain the final result, and what the final result contains. The output schema is present, so the lack of a formal return shape in the description is not a gap. Required style object and voice_name are already detailed in the schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by tying prompt length to cost ('Each character costs 0.1 credits'), which affects how the prompt parameter should be used. It also references completed downloads but the schema already documents prompt limits and voice_name, so the extra value is limited but real.

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

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

The description opens with 'Generate speech from text', a specific verb and resource, and later clarifies it starts an async audio generation job. It does not explicitly differentiate itself from the sibling ai_voice_cloner_create_audio, but 'from text' and the focus on a voice_name selection make the core purpose unambiguous. The distinction is implicit rather than explicit, so it falls 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?

The MCP guidance section clearly tells the agent what to do after calling: use wait_for_audio_project or poll the GET /v1/audio-projects/{id} endpoint. It also explains when the result counts as finished via status values. However, it does not provide guidance on when to choose this tool over ai_voice_cloner_create_audio or give exclusions, so usage direction is strong but not fully complete.

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

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

With no annotations, the description carries full disclosure burden. It clearly states the call returns immediately with id and credits_charged, describes the async status lifecycle, explains how to retrieve completed downloads, and warns about hotlinked URL failures while recommending the presigned upload flow. This is genuinely strong behavioral context.

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

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

The description is compact and front-loads the purpose and cost implication, then organizes async workflow and file-handling guidance into two focused bullets. Every sentence earns its place with no unnecessary filler.

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

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

For a nested-parameter async creation tool, the description provides everything needed: async behavior, immediate return values, completion polling, download retrieval, and file upload strategy. Combined with the rich input schema and existing output schema, there are no significant 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 coverage is 100%, providing a solid baseline. The description adds value by linking fps and end_seconds to frame-cost calculation and by providing actionable guidance for *_file_path parameters about preferring Magic Hour file paths or the presigned upload flow over direct 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?

States a specific verb and resource ('Create a Animation video'), clearly identifying what the tool does. It does not explicitly distinguish itself from sibling video-creation tools such as image_to_video_create_video or text_to_video_create_video, so it falls short of a 5.

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

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

The MCP guidance explains the async workflow and when to call wait_for_video_project, and the file-path bullet gives practical upload guidance. However, it offers no guidance on when to choose animation_create_video over sibling video-generation tools, leaving tool-selection context absent.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states permanence and irreversibility, which are critical for a destructive operation, but it does not clarify whether only rendered audio files are deleted or the entire audio project record, nor does it mention permissions, side effects, or return behavior.

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

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

The description is two short sentences with no waste. The core action is front-loaded, and the irreversibility warning is a necessary addition that earns its place.

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

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

For a simple single-parameter deletion tool with no output schema, the description is reasonably complete: it names the resource, states the action, and warns about permanence. A small gap remains regarding whether the project metadata or only the rendered file(s) are removed, and what the response looks like, but this is not essential to invoking 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 covers the single 'id' parameter completely with its own description, so the baseline is 3. The tool description adds no additional semantics beyond implying that the id identifies the audio project whose rendered files will be deleted.

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 (permanently delete) and a clear resource (rendered audio file(s)). It is distinct from siblings like audio_projects_retrieve_details, wait_for_audio_project, and fetch_audio_download, so an agent can easily tell which tool handles deletion.

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?

No guidance is provided about when to use this tool versus alternatives, and no prerequisites are mentioned. The 'please be sure before deleting' warning conveys caution but does not explain when deletion is appropriate or how to get the required id if not already known.

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

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

No annotations are provided, so the description carries the behavioral disclosure burden. It does this well by explaining when downloads get populated, enumerating all statuses, and warning that download URLs are signed and must be used exactly as returned. This goes well beyond a basic 'retrieve details' statement.

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 efficiently structured: a one-sentence purpose, a compact status list, and targeted MCP guidance. Every line adds value, and the most actionable guidance about polling and signed URLs is placed appropriately.

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 with an output schema, the description supplies all necessary operational context: what statuses to expect, what to do on completion, what to do on error, and how to handle download URLs. Nothing critical is missing for an agent to invoke and interpret the tool correctly.

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

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

Schema coverage is 100%, and the schema already describes the id parameter as the unique ID returned by creation APIs. The description reinforces the connection to create tools but does not meaningfully add parameter semantics beyond the schema, so the high-coverage baseline of 3 is appropriate.

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

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

The description opens with a clear verb and resource: 'Check the progress of a audio project.' It defines the tool's purpose unambiguously and the status list makes its role as a status/detail retrieval tool obvious, distinguishing it from sibling create/delete/download tools even without explicitly naming them.

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

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

The description explicitly instructs agents to use this after a create tool to poll job status, and gives concrete next actions for complete and error statuses. It does not explicitly contrast this with wait_for_audio_project, but the polling guidance is clear enough to be 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 present, the description carries the full behavioral burden and does so thoroughly: it discloses that this starts an async job returning id and credits_charged immediately, that callers must poll or wait via wait_for_video_project, that statuses include complete/error/canceled, and that completed projects expose downloads URLs. It also discloses billing behavior and file-path caveats for hotlinked URLs.

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

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

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

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

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

For a complex async creation tool with nested objects and no annotations, this description is unusually complete: it covers prerequisite upload steps, job lifecycle, response behavior, cost, resolution constraints, and how to obtain the final result via wait/poll helpers. Nothing essential for correct invocation is missing.

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

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

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

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

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

The description opens with a clear verb and resource: 'Create the same Audio To Video you can make in the browser, but programmatically.' It precisely names the tool's function, though it does not explicitly differentiate it from sibling tools like text_to_video_create_video or image_to_video_create_video.

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

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

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

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

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

With no annotations, the description carries full behavioral burden and does so thoroughly: it discloses that the call is asynchronous, returns id and credits_charged, how to reach completion (wait helper or polling), what terminal statuses look like, that downloads URLs are included, and that hotlinked URLs may fail.

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

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

The first line states the purpose, then the MCP guidance is broken into two actionable bullets. Every sentence carries operational information; there is no filler and the most important async behavior is front-loaded.

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

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

Given the rich 100%-covered input schema and existing output schema, the description supplies the missing operational context: async initiation, completion retrieval, status values, download URLs, and file-path best practices. Nothing critical is left for the agent to guess.

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 advising on all *_file_path parameters: prefer Magic Hour file paths or upload-URL results, public URLs may work but hotlinks can fail, and use presigned upload when in doubt. This supplements the asset parameter guidance.

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

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

The opening sentence names the specific action ('generate subtitles') and resource ('your video'), and the async-job framing distinguishes it from sibling video tools. It is immediately clear this is the auto-subtitle generator, not a general video editor.

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

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

The MCP guidance gives concrete when/how instructions: call wait_for_video_project for the finished result or poll the endpoint until terminal status, and use the presigned upload flow for file paths. It does not explicitly compare to alternative video-generation siblings, but the context is strong enough that an agent will not confuse 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 provided, the description carries the full burden of behavioral disclosure, and it delivers: it explicitly says the job is async, what is returned immediately (id and credits_charged), how to wait or poll, what terminal statuses to expect, and that completed projects include direct download URLs. It also warns that hotlinked URLs can fail and recommends the presigned upload flow, which is exactly the kind of behavioral context an agent needs.

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

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

The description is front-loaded with the core purpose in the first sentence, then uses two guidance bullets for async behavior and file-handling tips. Every sentence earns its place; the MCP guidance is dense but not padded, and the structure makes the integration steps easy to follow.

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

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

Given there is an output schema, the description does not need to explain every return field, but it still covers the important runtime behavior: async id/credits, polling statuses, download URLs, and file path constraints. It is complete enough for an agent to invoke the tool correctly and handle the follow-up workflow without additional external knowledge.

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 each parameter, but the description adds meaning beyond that: it explains that resolution maps to model tiers and credit cost, and it gives concrete guidance for *_file_path values, including preferring Magic Hour file paths, using the upload-URL flow, and why direct public URLs may be unreliable. This is genuinely additive rather than 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 opens with a specific verb and resource: 'Swap a person into a scene image,' which clearly identifies the operation. It also adds model and resolution context, making it distinguishable from face/head swap siblings even though it does not explicitly name them. A 5 would require more direct sibling differentiation, but the purpose is otherwise 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 gives no explicit 'use this instead of X' guidance or exclusions among the many create_image sibling tools. The intended use case is implied by the body-swap framing and by the file-path guidance, but an agent is not told when to prefer this tool over, say, face_swap_photo_create_image or head_swap_create_image. The strong procedural guidance about async jobs is about how to use it, not when to select 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 full burden and does an excellent job. It explicitly discloses that the job is asynchronous, returns id and credits_charged immediately, requires polling, reports terminal statuses, and exposes downloads. It also warns about file path handling and hotlinked URL failures.

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

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

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

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

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

For a complex async tool with nested parameters and no annotations, the description is remarkably complete. It covers the full lifecycle from upload and job creation through polling to downloading results, plus cost, resolution limits, and file path gotchas. An output schema presumably covers return-value details.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents every parameter. The description adds useful high-level context around resolution limits, file inputs, and costs, but it does not deeply elaborate on individual parameter semantics beyond the schema.

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

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

The description states a clear verb and resource: programmatically create a Character Replace video job. It is easy to understand what the tool does, but it does not differentiate itself from sibling tools like face_swap_create_video or video_to_video_create_video.

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

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

The 'Good for' section gives broad usage context such as automation, batch processing, and app integration. However, it does not mention alternative tools or when not to use this tool, leaving sibling selection mostly to the agent's inference.

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

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

There are no annotations, so the description carries full responsibility for behavioral disclosure. It clearly states that this starts an async task, returns an id, and requires a follow-up details call. It also reveals URL reliability risks, the free/pricing caveat, and preferred file-path handling, going well beyond the minimum.

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

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

The description is front-loaded with a clear one-line summary and then organized into context, pricing, and MCP guidance. It is longer than average but most sentences add operational value. The pricing note is slightly tangential but still useful for cost-sensitive agents, so the length is mostly justified.

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

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

Given the async nature of the tool, the description covers the complete invocation flow: start detection, retrieve id, call details endpoint, and then proceed to face swaps. It also provides practical upload guidance and links to relevant docs. With an output schema present, no further return-value explanation is needed.

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

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

The input schema already documents both parameters with full coverage. The description adds practical value by explaining how to choose the target_file_path value, warning about hotlinked URLs, and recommending the upload URL flow. Confidence threshold semantics are already well described 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 opens with a specific verb and resource: 'Detect faces in an image or video.' It also names the downstream use case (face swap photo/video APIs), which clearly distinguishes this tool from the many sibling generation tools. An agent can tell exactly what this tool does and why it exists.

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 says when to use the tool: to get the list of detected faces before making face swap calls for multi-face swaps. The MCP guidance goes further, explaining the async flow and directing the agent to the face-detection details endpoint. File-path guidance also helps choose between direct URLs and the presigned upload flow.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It conveys that this is a retrieval operation ('Get', 'get the list of faces detected') and adds useful downstream context. However, it does not explicitly state read-only intent, authentication requirements, or any lifecycle/status considerations beyond saying 'details of a face detection task.' This is adequate but not richly 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 two sentences and stays on point. The first sentence states the core purpose, and the second adds valuable downstream usage context with links. It is not bloated, though the first sentence is somewhat close to the tool name in wording.

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 with an output schema present, the description provides the necessary context: what the id refers to, where the id comes from, and why the result is needed. It does not over-explain return values because the output schema covers that. Minor lifecycle or status details could be added, but nothing essential is missing for correct invocation.

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

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

The input schema covers the only parameter fully: id has a description, type, example, and a link explaining where the id comes from. The description adds no additional parameter-level meaning beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description uses a specific verb and resource: 'Get the details of a face detection task' and 'get the list of faces detected in the image or video.' This clearly distinguishes it from the sibling face_detection_detect_faces, which is the creation/scan counterpart. The purpose is immediately obvious even 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 states when to use this tool: to obtain detected faces for use in face swap photo or video calls, especially multi-face swaps. It also tells the agent that the id comes from the face detection API. It does not explicitly name alternatives or state when not to use it, but the context is strong enough for an agent to route correctly.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses that the job is async, returns id and credits_charged immediately, requires polling or a helper, lists terminal statuses, mentions downloads, and warns about hotlinked URLs. This is exemplary 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 organized with the core purpose and cost first, followed by clearly separated MCP guidance bullets. Every sentence earns its place: cost, output dimensions, async workflow, completion states, download handling, and file path best practices. No redundancy exists.

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 task with a nested assets object, async execution, and file path nuances, the description covers all necessary operational context. It explains the async lifecycle, result retrieval, and file-upload guidance. The output schema exists and handles return-value 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 description coverage is 100%, so the baseline is 3. The description adds value by giving cross-cutting guidance for all *_file_path values: prefer Magic Hour file paths or upload-URL results, and avoid unreliable hotlinks. This extra semantic layer goes beyond the schema, warranting a 4.

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 a face swap photo,' which is a specific verb plus resource. It clearly distinguishes itself from siblings like face_swap_create_video by stating 'photo,' and from body/head swap tools by naming face swap explicitly.

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

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

The MCP guidance provides rich procedural context, e.g., how to wait for results and how to handle file paths, but it never explicitly states when to use this tool vs alternatives or when not to use it. Usage is implied by the tool name and purpose rather than directly contrasted with sibling tools.

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

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

With no annotations, the description carries the behavioral disclosure burden. It reveals key non-obvious traits: the URL must be passed exactly without trimming query parameters, expires_at is separate metadata, and the result is inline MCP audio content. It does not discuss expired-URL failure behavior, but the core operational behavior is 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 two sentences with no filler; the action and critical URL-handling caveat are front-loaded. The minor grammar issue ('a audio') does not materially harm understanding.

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 fetch tool, the description covers purpose, return format, and the most important usage caveat. While it could mention expiry/error behavior or explicitly explain max_bytes, the schema defaults and low tool complexity make the current definition reasonably complete.

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

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

Schema description coverage is 0%, so the description must compensate. It adds essential meaning for download_url by explaining it must be the exact full signed URL and that expires_at should not be included. max_bytes is not described, but its type and default value make it low-risk and largely self-explanatory.

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

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

The description names a specific verb ('Fetch'), a specific resource ('downloads[n].url' from a completed audio project), and the expected return type ('inline MCP audio content'). This clearly differentiates the tool from sibling fetch_image_download and fetch_video_download without needing to inspect schemas.

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

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

The description implies the tool is for fetching completed audio project downloads and emphasizes passing the exact signed URL, but it does not explicitly state when to choose this over the image/video fetch siblings or what to do in incompatible clients. The context is clear enough to infer, though not explicitly routed.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It discloses that the result is returned as inline MCP image content and that expires_at is separate metadata, not part of the URL. It does not mention what happens with max_bytes limits or incompatible clients, but the core behavior is 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?

Two focused sentences, each earning its place. The purpose is stated first, followed by the critical URL-handling constraint. No filler or repetition.

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

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

Given the low tool complexity and absence of output schema/annotations, the description covers the essential selection and invocation details: source project state, URL semantics, and return type. Minor gaps remain around max_bytes behavior and the meaning of 'compatible clients', but these do not prevent correct use in most cases.

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. It does add valuable meaning for download_url (exact full signed URL, don't trim query params, expires_at is separate). However, max_bytes is left entirely unexplained beyond its default value, so parameter coverage is incomplete.

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 specific verb ('Fetch'), the resource (the image at `downloads[n].url` from a completed image project), and the return format (inline MCP image content). This distinguishes it from siblings like fetch_audio_download and fetch_video_download, which serve different media types.

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 contextual guidance: the image project must be completed, and the exact full signed URL must be passed without trimming query parameters. However, it does not explicitly state when not to use this tool or name alternative tools for audio/video downloads, so it falls short of full exclusionary guidance.

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

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

With no annotations, the description carries the disclosure burden. It adds useful behavior: the result is an embedded MCP binary resource, and the URL must be passed exactly without trimming query parameters. It does not cover expiration-failure handling, auth requirements, or what happens when max_bytes is exceeded.

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 the core action and the critical usage caveat front-loaded. Every clause earns its place and there is no repetition or filler.

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

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

Adequate for a simple fetch operation: it identifies source, output format, and the key input constraint. However, with no output schema and no annotations, it leaves `max_bytes` semantics, failure/expiry behavior, and client-compatibility caveats 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 descriptions are absent, but the description adds strong meaning to `download_url`: it must be the exact full signed URL, query parameters must not be trimmed, and `expires_at` is separate metadata. `max_bytes` is left entirely to its name and default, which is a minor gap.

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

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

States a specific action (fetch a video download URL), the exact source (`downloads[n].url`), and the output form (embedded MCP binary resource). It does not explicitly distinguish from sibling tools like fetch_audio_download or fetch_image_download, but the video resource is clear.

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

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

Implies it should be used after a video project is completed and for fetching the signed download URL. It does not explicitly state when to prefer this over fetch_audio_download/fetch_image_download or after which wait_for_* step, and gives no exclusions.

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

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

With no annotations provided, the description carries the full burden, and it does so excellently. It discloses the 10-credit cost, subscription-dependent output resolution, the async job lifecycle, the need to poll or use a wait helper, and the risk that hotlinked media URLs may fail — all important behavioral traits beyond a simple 'creates an image' statement.

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

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

The description is longer than average but well-structured with a front-loaded purpose sentence and clearly separated MCP guidance bullets. The additional length is justified by the genuinely useful async and file-handling details, though a small amount of repetition with the schema 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 and the lack of annotations, the description covers nearly everything an agent needs: cost, resolution constraints, async submission, how to retrieve results, status values, download URLs, and safe file input practices. The output schema covers return values, so the description does not need to restate them.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful value by explaining the file-path preference (`file_path` from upload flow over hotlinked URLs) and clarifying how `max_resolution` interacts with plan limits. This goes beyond what the schema already 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 opening sentence, 'Swap a head onto a body image,' names a specific verb and resource, making the operation immediately understandable. It does not explicitly differentiate itself from siblings like body_swap_create_image or face_swap_photo_create_image, but the operation is semantically distinct enough to avoid major confusion.

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 is strongly implied by the first sentence and reinforced by the details on credits, resolution, and async behavior. However, there is no explicit guidance on when to choose this tool over related siblings or when not to use it, so this dimension remains at the implied-usage level.

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 disclosure burden. It does so excellently: it states the tool is async, returns id and credits_charged immediately, requires polling or a wait helper, lists possible statuses, mentions downloads and exact_download_urls, explains credit cost, and warns about file path constraints.

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, followed by well-organized MCP guidance bullets. Every sentence contributes useful operational information, and nothing feels redundant or wasted.

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

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

The description gives an agent everything needed to call the tool and follow through: async behavior, cost, the wait helper to use, polling endpoint, status values, download URLs, and file upload constraints. This is complete for a tool with nested assets and an output schema.

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

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

The input schema already covers both parameters at 100%, so the baseline is 3. The description adds meaningful value by clarifying preferred file_path sources, warning about hotlinked URLs, and recommending the presigned upload flow. This extra guidance justifies a 4.

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.' This clearly states the tool's function and is not a tautology. However, it does not explicitly differentiate itself from sibling tools or name what it is not, so it falls short of 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 intended use is implied by the one-line purpose and the tool name, so an agent can infer when to use it. However, the description offers no explicit when-to-use/when-not-to-use guidance or comparison against alternatives such as ai_image_editor or photo_colorizer.

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

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

No annotations are provided, so the description carries the full burden of disclosing behavioral traits. It effectively communicates that the operation is permanent and irreversible, which is the most critical trait for a delete operation. However, it does not mention other behaviors such as idempotency, error handling (e.g., behavior on nonexistent ID), or any side effects on related resources. For a simple delete, this is reasonably transparent but leaves room for more detail.

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

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

The description is extremely concise: two short sentences with no filler. The key action ('permanently delete') is front-loaded, and the important caution about irreversibility follows immediately. Every word earns its place, and the structure supports quick comprehension by an 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 a tool with a single simple parameter, no output schema, and a clear destructive action, the description covers the essential context: what it does and its irreversibility. It does not explain return format or error behavior, but those are not specified by an output schema and may be less critical for a delete. The lack of any guidance on retrieving the ID (though present in the schema) is minor. Overall, it is adequate for the tool's simplicity.

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

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

The schema description coverage is 100% – the 'id' parameter is fully described in the schema, including an example and the note that it is returned by POST APIs. The tool description adds no additional meaning about the parameter beyond what the schema already provides. Since the schema fully covers it, the 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 clearly states the action ('Permanently delete') and the resource ('the rendered image(s)'). It distinguishes itself from sibling delete tools (audio_projects_delete, video_projects_delete) primarily through the tool name and the word 'image', but the description itself does not explicitly reference siblings or contrast with them. This is clear and specific, but lacks explicit differentiation.

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

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

There is no guidance on when to use this tool versus alternatives. While the name indicates it is for image projects, the description gives no context about when deletion is appropriate, prerequisites (e.g., whether the project must exist), or any mention of other tools that might be relevant (like image_projects_retrieve_details to confirm the ID). The usage context is only implied by the action itself.

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

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

No annotations are provided, so the description carries the behavioral disclosure burden. It clearly explains the status lifecycle, notes that `downloads` appears only after a successful render, and warns that the signed URLs must be used exactly as returned. It could additionally mention whether retrieval has side effects or requires auth, but for a status-retrieval tool this is strong coverage.

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

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

The description is well-structured and front-loaded: purpose first, then statuses, then actionable MCP guidance, then the critical URL-handling caveat. Every sentence adds useful information and there is no redundant filler.

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

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

For a single-parameter retrieve tool with an output schema present, the description is nearly complete: it explains statuses, the `downloads` field, and how to respond to completion or error. The only notable omission is explicit guidance about the `wait_for_image_project` alternative, which would fully close the loop on how this tool fits into a polling workflow.

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

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

The input schema has one required parameter, `id`, with 100% schema description coverage. The description does not add additional meaning about how to obtain or format the `id`, but full schema coverage already provides that meaning, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Check the progress of a image project.' It goes beyond a generic statement by defining the statuses and linking the `downloads` field to successful renders, so an agent can distinguish this from create/delete sibling tools. The resource and verb are specific and unambiguous.

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

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

The description gives explicit usage context: 'Use this after a create tool to poll job status' and tells the agent exactly what to do for `complete` and `error` statuses. However, it does not explicitly distinguish this from the sibling `wait_for_image_project` tool or mention when not to use it, so it stops short of a full when/when-not guidance.

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

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

No annotations exist, so the description carries the full burden and delivers comprehensively: async job semantics ('returns id plus credits_charged immediately'), credit charges only for rendered frames, status lifecycle (complete/error/canceled), downloads with direct URLs, hotlinked-URL failure risks, and free-tier 576px resolution limits. This far exceeds what annotations would typically communicate.

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-factored into labeled sections (What this API does, Good for, How it works, Key options, Cost, MCP guidance) with the core purpose front-loaded. Length is justified by the tool's complexity — 7 parameters, nested objects, async workflow — and each section contributes information not available in the structured schema.

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

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

For a 7-param async tool with no annotations, the description covers the full lifecycle: upload-URL step, job creation, status polling, download retrieval, cost estimation, and file-path pitfalls. Parameter details are handled by the 100%-covered schema, and return values by the existing output schema, so nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% with rich per-model tables for audio, resolution, and end_seconds, so the baseline is 3. The description adds operational meaning beyond the schema: prefer the presigned upload flow's returned file_path over direct public URLs, hotlink instability warnings, free-tier resolution caps, and examples of extra fields like 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?

States a specific verb+resource: 'Create the same Image To Video you can make in the browser, but programmatically.' The description clearly scopes this to image-to-video, distinguishing it from siblings like text_to_video_create_video, video_to_video_create_video, and audio_to_video_create_video without requiring the agent to compare schemas.

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

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

The 'Good for' section gives explicit context (automation, batch processing, integration into apps/pipelines/tools), and the MCP guidance tells the agent exactly what to do after invoking — call the wait_for_video_project helper or poll the GET endpoint. It does not explicitly name sibling alternatives or exclusion conditions (e.g., when to choose text_to_video instead), so it misses the 5 bar.

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

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

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

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

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

The description is long but well-structured with clear headings, bullets, numbered steps, and a dedicated MCP guidance section. Purpose and use cases are front-loaded, and each section contributes operational guidance.

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

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

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

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

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

Schema coverage is 100%, so the baseline is 3. The description adds practical value by advising agents to prefer Magic Hour file paths over direct public URLs, explaining when hotlinks fail, and summarizing key options like resolution limits and extra fields.

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

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

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

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

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

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

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

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

No annotations are present, so the description carries the full burden, and it delivers: it discloses async behavior, immediate return of id and credits_charged, credit cost, polling/helper workflow, terminal statuses, downloads, and exact_download_urls. It also warns about file_path handling and hotlink failures, which is valuable behavioral context.

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

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

The description is appropriately sized for the tool's complexity. The first line states the action and cost, then the MCP guidance is logically organized into async workflow and file_path best practices. Every sentence carries practical information with no redundancy.

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

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

For an async image-generation tool with nested object parameters and an output schema, the description is complete: it explains the async flow, how to retrieve the final result, the status values, and file-path pitfalls. The output schema covers return structure, so its absence in the description 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 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining preferred file_path sources, why direct URLs can fail, and recommending the presigned upload flow. This helps an agent provide correct input and avoid common errors.

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

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

The description begins with 'Colorize image,' which is a specific verb and resource. It clearly identifies the tool's core function, and the tool name itself distinguishes it from siblings like ai_image_editor or ai_image_generator. The added credit cost note further clarifies exactly what the tool does.

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

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

The description does not explicitly state when to use this tool versus alternatives, but it strongly implies usage by describing the async job flow and referencing the wait_for_image_project helper. It gives clear guidance on what to do after calling the tool, but not about choosing it over siblings.

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

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

With no annotations, the description carries the behavioral disclosure burden. It does convey that this is a non-mutating reachability check, but it provides no additional detail about response format, timing, or error behavior. For such a minimal tool, this is adequate but not rich.

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, concise sentence that front-loads the action and target. There is no wasted phrasing or irrelevant 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?

The tool is a simple reachability check with no parameters and no complex behavior. The description, combined with the provided output schema, gives an agent everything needed to invoke it correctly.

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

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

The tool has no parameters, so the baseline is 4. The description adds no parameter information, but none is needed for an empty schema.

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

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

The description states a specific action ('Check') and a specific resource ('the Magic Hour MCP server'), making the tool's purpose immediately clear. It also differentiates from the long list of sibling creation tools, which all perform media generation or management operations.

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

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

The description clearly indicates the tool is for verifying server reachability, which provides sufficient context for when to use it. It does not explicitly discuss exclusions or alternatives, but none are relevant given the unique purpose among 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 provided, the description carries the full burden and does so thoroughly. It discloses that this is an async job that returns id and credits_charged immediately, that credits are only charged for rendered frames, that resolution is limited on free tiers, and that statuses reach complete, error, or canceled. This is unusually transparent 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 long but well-organized with clear headers, bullet lists, numbered steps, and links. It front-loads the core purpose and use cases, then flows into workflow, options, cost, and MCP-specific guidance. Every major section earns its place for a complex async tool, though a bit of trimming could tighten it.

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

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

For a 7-parameter async tool with nested objects, the description covers the full lifecycle: uploading inputs, creating the job, polling status, handling completion/cancellation, and retrieving downloads. It also covers cost behavior and free-tier limitations. Since an output schema exists, the description does not need to spell out return values, and it does not leave a meaningful 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 86%, so the schema already documents most parameters in detail. The description adds helpful context around resolution limits, credit costs, and input types, but it also references a file_path step that does not map to any parameter in the provided schema, which slightly weakens parameter clarity. Overall, the description supplements but does not significantly advance 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 specific action — create text-to-video content programmatically — and names the resource clearly. It also positions the tool relative to the browser product and highlights automation, which distinguishes it from sibling creation tools like image_to_video and video_to_video.

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

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

The description gives explicit use cases ('Automation and batch processing', adding to apps/pipelines), a 3-step workflow, and MCP guidance on what to do after invocation: call wait_for_video_project or poll the status endpoint. It does not explicitly contrast this tool with sibling creation tools, but the workflow and async-handling guidance are strong enough for an agent to know when and how 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?

With no annotations present, the description carries the behavioral burden. It discloses the presigned-URL-only behavior, response ordering, valid extensions, PUT upload requirement, and a curl example. It omits auth/permission details beyond the example's auth params, but the core behavior is well 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 longer than average but every section adds value: purpose, extensions, PUT flow, example, and MCP-specific guidance. The extension list partially duplicates the schema, but the organized presentation justifies the length.

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 an output schema, the description covers the full workflow: URL generation, upload mechanics, order preservation, extension validation, and integration with create tools. An agent has enough to call it correctly and know what to do with the result.

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

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

Schema coverage is 100%, giving baseline 3. The description adds value by organizing valid extensions per asset type and noting the gif caveat for face swap, which aids correct extension selection beyond the schema's flat list.

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 clearly states it generates pre-signed upload URLs for required assets, and immediately clarifies it is only needed for uploading to Magic Hour's storage. This distinguishes it from the upload_file_to_presigned_url and fetch/download siblings.

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

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

Explicitly explains when to use it, that it only creates URLs, and that local files must be uploaded via PUT to the returned URLs before passing file_path to a create tool. Also gives concrete guidance for handling *_file_path values and warns about hotlinked URLs.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It clearly states that deletion is permanent and irreversible, which is the critical behavioral trait for a destructive operation. It does not cover authorization or response behavior, but the core consequence is disclosed.

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

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

Two short sentences with no filler: the action is stated up front and the irreversible warning follows immediately. Every word earns its place.

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

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

For a one-parameter destructive operation with no output schema, the description provides the essential context: what is deleted and that it is permanent. It omits error/not-found behavior, but the definition is sufficient 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?

The schema already documents the single 'id' parameter completely, including an example and how it is returned. The description adds no parameter-specific meaning, so it meets the schema-covered baseline of 3 but does not exceed it.

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 names the target resource ('rendered video'), so an agent knows this is the destructive counterpart to video_projects_retrieve_details. It does not explicitly differentiate from audio_projects_delete or image_projects_delete, but the resource phrase plus the tool name make the scope clear.

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

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

There is no guidance on when this tool should be chosen over alternatives, and no mention of prerequisite steps such as retrieving the project first. The 'please be sure' caveat is a caution, not a when-to-use or when-not-to-use guide.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description clearly states the tool checks video project progress and maps to a specific resource and action. It distinguishes itself from create tools via 'use this after a create tool to poll job status,' but it does not explicitly differentiate itself from the sibling wait_for_video_project tool.

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

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

The description gives clear context: it should be used after a create tool to poll job status, and it explains how to handle complete and error states. However, it does not provide explicit when-not-to-use guidance or mention alternatives such as wait_for_video_project.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It explains that the tool polls until terminal states, attempts to inline audio downloads for Inspector or compatible clients, returns sanitized download fields, and warns against modifying returned URLs. This goes beyond the tool name and provides useful operational context.

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

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

The description is three sentences with no filler. The core polling purpose is front-loaded, followed by return behavior, then a concrete URL-handling caveat. Every sentence contributes useful 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 polling tool with six parameters and no output schema, the description covers the main return contract: final project JSON, inline download behavior, sanitized fields, and URL integrity rules. It could be more explicit about how terminal states are represented or how download inclusion limits behave, but the essential guidance for selecting and using the tool is present.

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

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

Schema description coverage is 0%, and the description provides no input parameter semantics. It discusses output fields like `exact_download_urls[n]` and `downloads[n].url`, but does not explain `id`, `timeout_seconds`, `poll_interval_seconds`, `max_inline_downloads`, `max_bytes_per_download`, or `include_inline_downloads`. The parameter names are somewhat self-explanatory, but the description does not compensate for the absent schema documentation.

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

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

The description opens with a specific verb and resource: 'Poll an audio project until it completes, errors, is canceled, or times out.' This clearly distinguishes it from the sibling wait_for_image_project and wait_for_video_project tools by naming the resource type and the polling behavior.

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

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

The description makes the usage context clear: it is for waiting on an audio project and returning its final state. It does not explicitly name alternatives or exclusions, but the purpose is specific enough that an agent can infer when to use it versus project retrieval or creation tools.

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

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

No annotations are provided, so the description carries the full burden and handles it well: it discloses polling until terminal states, attempts to inline image downloads, returns sanitized download fields, and warns that URLs must be used exactly as returned. This is substantive behavior beyond what the schema offers.

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

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

The description is compact and well-structured: the core purpose is front-loaded, followed by output details and a critical usage warning. Every sentence earns its place, with no redundant or misleading 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?

There is no output schema, so the description must clarify return behavior; it does explain the final JSON and sanitized download fields. However, it omits how parameters affect polling and downloading, what happens on timeout/error at the response level, and how this relates to retrieval/fetch tools. This is a meaningful gap given six parameters and no annotations.

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

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

Schema description coverage is 0% and the description does not compensate: none of the six parameters (id, timeout_seconds, max_inline_downloads, poll_interval_seconds, max_bytes_per_download, include_inline_downloads) are explained. The only tangential mention is 'times out,' which does not clarify parameter behavior. With low schema coverage, the description should have provided parameter guidance but does not.

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

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

The description states a specific verb ('Poll') and resource ('image project') and specifies the terminal conditions: completes, errors, is canceled, or times out. This clearly distinguishes the tool from sibling wait_for_audio_project and wait_for_video_project, as well as from non-blocking retrieval tools like image_projects_retrieve_details.

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

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

The description implies when to use the tool—after creating an image project and when a blocking wait is needed—and mentions suitability for Inspector or compatible clients. However, it does not explicitly contrast this with siblings such as wait_for_video_project or image_projects_retrieve_details, leaving the when/when-not decision largely implicit.

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

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

With no annotations, the description carries the transparency burden. It discloses the polling nature, the four terminal states, that download fields are sanitized, and explicitly warns against modifying returned URLs. This is useful behavioral context, though it does not describe error response shapes or side effects.

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, with the core polling behavior front-loaded. Every sentence contributes: the action/terminal states, the output type, and a critical URL-handling instruction. There is no redundancy or filler.

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

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

The description captures the main flow and includes a strong output warning, but for a tool with five parameters, no annotations, and no output schema, it leaves optional parameter semantics unexplained and does not fully describe what happens on failure or timeout. It is adequate for default-parameter use, but not complete.

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

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

Schema description coverage is 0%, and the description does not explain any of the five parameters. While names and defaults make timeout_seconds and poll_interval_seconds inferable, max_inline_downloads and include_inline_downloads lack meaningful explanation, and id is not described as referencing a video project.

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 ('Poll') and a specific resource ('a video project'), and clearly distinguishes this from the sibling wait_for_image_project and wait_for_audio_project tools. It also states the terminal states and the kind of output returned.

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

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

The description implies the tool is used after a video project has been initiated, in order to wait for it to finish. However, it does not explicitly say when to prefer this over alternatives like video_projects_retrieve_details or how it relates to the other wait_for_* tools.

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