Magic Hour

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description adds substantial behavioral context beyond the annotations: it is an async job returning id and credits_charged, requires a follow-up wait helper or polling, returns downloads with optional exact_download_urls, and enforces signed-URL preservation. It also covers credit cost and file-path handling edge cases. Annotations already indicate it is a non-read-only, non-destructive operation, and the description does not contradict them.

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 as a safety warning, an MCP guidance block, and a tagline. It is information-dense and every major section carries useful content, but the purpose is not front-loaded and the closing marketing sentence is partly redundant. Not wasteful overall, but not optimally front-loaded.

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

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

For a complex async image-generation tool with nested parameters, an output schema, and annotations, the description covers everything needed to invoke and handle the call correctly: async lifecycle, result retrieval, file upload paths, signed-URL handling, cost, and safety restrictions. Because an output schema exists, return-value details do not need to be repeated here.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds valuable guidance for *_file_path parameters: use an existing Magic Hour path or the upload-URL endpoint's file_path after uploading raw bytes, and prefer the upload URL when unsure because hotlinked URLs can fail. It does not discuss the optional name parameter or garment_type enum, but the schema already covers those fully.

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 final sentence states a specific verb and resource: 'Change outfits in photos in seconds with just a photo reference.' This is clear enough for an agent to understand the tool's core function. However, it does not differentiate from sibling image-editing tools such as ai_image_editor or face_swap_photo_create_image, so it misses the top mark.

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 content restrictions ('Use only with the user's own likeness... Do not use for impersonation, deception, sexual content, or content involving minors') and clear post-call workflow guidance (call wait_for_image_project or poll the endpoint). It does not explain when to choose this tool over sibling image-editing alternatives, so it falls short of a 5.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) the description discloses that this is an async job, that it returns id and credits_charged, the terminal status values (complete, error, canceled), that results carry downloads (with exact_download_urls from wait helpers), the cost of 1 frame per edit, and a signed-URL preservation warning. That is unusually rich 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 guidance is front-loaded into two dense bullets covering result retrieval and file-path handling, followed by the one-line purpose statement. It is on the long side and the pricing/subscription sentence is partly promotional, but nearly every clause carries operational 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 nested-schema, async, paid mutation tool with an output schema and annotations, the description covers the full lifecycle: submit, cost, poll/wait, and result retrieval, plus file-path handling. The only substantive gap is sibling disambiguation within the create_image family.

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

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

Schema coverage is already 100%, so the baseline is 3, but the guidance adds real meaning for image_file_path: direct public media URLs 'may work if stable and fetchable as raw bytes', hotlinked URLs can fail, and the upload-URL endpoint is preferred when uncertain. The style parameters are left entirely to the schema, which is acceptable given its completeness.

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: 'Edit facial features of an image using AI', backed by the schema's expression parameters (head_yaw, mouth_smile, eye_gaze). It is clearly distinguishable in intent, but it never names or contrasts with the many close siblings (face_swap_photo_create_image, head_swap_create_image, body_swap_create_image), so an agent must infer the boundary itself.

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

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

It gives explicit conditional guidance: call wait_for_image_project with the returned id or poll GET /v1/image-projects/{id}, and 'Prefer the upload-URL endpoint when unsure' for file paths, with the caveat that hotlinked URLs can fail. What is missing is any when-to-use-this-tool-versus-siblings routing, which is notable given the crowded create_image family.

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

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

Annotations only declare the safety profile (readOnly=false, destructive=false, openWorld=false); the description goes well beyond that by disclosing async job semantics, the returned id and credits_charged, the terminal states, the 50-credit cost per GIF, and the signed-URL preservation constraint. This is exactly the kind of operational context annotations cannot carry.

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

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

Front-loaded with the lifecycle guidance an agent needs before calling, followed by the one-line purpose and cost. The "MCP guidance:" prefix and dense URL-preservation sentence are slightly noisy, but overall it is tight and 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?

For an async creation tool with a rich output schema, the description covers the full lifecycle, cost, and result handling. Remaining gaps (what triggers a failure beyond the state names, whether the job can be canceled explicitly) are minor given the output schema exists.

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 every parameter (name, style.prompt, output_format) already has an inline description and enum. The description adds nothing parameter-specific, so the schema does the heavy lifting and a 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?

"Create an AI GIF" is a specific verb+resource pair that clearly identifies the operation. It does not, however, explicitly differentiate itself from adjacent siblings such as ai_image_generator_create_image or ai_meme_generator_create_image, so an agent must infer the distinction from the name alone.

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

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

The guidance block gives concrete follow-up routing: call wait_for_image_project with the returned id, or poll GET /v1/image-projects/{id} until complete/error/canceled. That is strong procedural context, but there is no explicit statement of when to prefer this GIF tool over the other image-creation siblings.

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

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

Annotations only declare the mutation/open-world/safe-write profile. The description goes well beyond that by disclosing the async job lifecycle, the returned id and credits_charged fields, the 50-credit cost per call, and the signed-URL handling rule (preserve query parameters, never append expiration metadata) — all operationally relevant facts an agent cannot get from the annotations.

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

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

The purpose sentence is buried at the end after two long bullet blocks, so the definition is not front-loaded. Every sentence carries information, but the generic multi-tool guidance dominates over the tool's own identity, making it read as boilerplate-first.

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 async lifecycle, cost, and asset-path resolution, and an output schema exists so return shapes need not be re-explained. It could still say more about auth and the single-detectable-face prerequisite, but nothing essential for a 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 67%, so the baseline is 3. The description adds real value for `image_file_path` (existing Magic Hour path vs upload-URL file_path vs hotlinked URLs that can fail), but it says nothing about `name` or `style.prompt`, and the file-path guidance partially overlaps 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 closing line "Create an AI headshot" gives a specific verb plus a specific resource subtype, which distinguishes it from ai_image_generator_create_image, ai_meme_generator_create_image and other create_image siblings. The differentiation comes mostly from the name/title rather than any explicit contrast, 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 guidance is explicit about the async workflow: call wait_for_image_project with the returned id or poll GET /v1/image-projects/{id} until complete/error/canceled, and it gives a preference rule for asset resolution ("Prefer the upload-URL endpoint when unsure"). What is missing is any guidance on when to pick this tool over the other image-generation siblings.

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

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

Beyond annotations, the description discloses that this starts an async image job, returns `id` and `credits_charged`, and must be polled or waited on until `complete`, `error`, or `canceled`. It also describes signed URL handling, download fields, upload-path expectations, hotlink risks, and model tier eligibility, which are meaningful behavioral details not captured by the annotations alone.

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

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

The description is front-loaded with useful guidance, but it is somewhat repetitive: the prompt-only generator alternative and the image-to-video preparation note are stated in both the bullets and the following paragraph. For a complex async tool some length is justified, but the duplication prevents a higher score.

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

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

Given the async workflow, nested assets/style objects, many model choices, tier restrictions, and output schema availability, the description is highly complete. It covers alternatives, input path expectations, async lifecycle, polling/wait helpers, and URL handling, so an agent has enough context to call and follow up correctly.

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

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

Schema description coverage is high at 86%, so the schema already carries most parameter meaning. The description still adds real semantic value by explaining `assets.image_file_paths` as source-image requirements, clarifying file path versus upload URL usage, warning about hotlinks, and flagging that the default model is not universally available on Free.

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: edit supplied images using `assets.image_file_paths` and `style.prompt`. It explicitly distinguishes the tool from `ai_image_generator_create_image` for prompt-only creation, so an agent can tell the core purpose apart from the main sibling alternative.

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

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

It gives explicit when-to-use guidance: one or more source images are required, and prompt-only creation should use `ai_image_generator_create_image` instead. It also clarifies that editing is not mandatory before image-to-video when the source already meets the brief, which is a useful usage boundary.

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

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

Annotations only say it is non-read-only, non-destructive, and closed-world. The description adds substantial behavior beyond that: job is asynchronous, returns id and credits_charged (i.e., it costs credits), terminal statuses are complete/error/canceled, results carry downloads while wait helpers add exact_download_urls, and signed URLs/query params must be preserved rather than rewritten with expiration metadata.

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

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

The MCP guidance block is dense but front-loaded with the facts an agent needs first (async, id, credits, polling path, URL handling). The trailing sentence 'Create an AI image with advanced model selection and quality controls' is vague filler and would be better placed first or removed.

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

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

An output schema exists, yet the description still supplies the operationally critical return semantics (id, credits_charged, terminal statuses, downloads vs exact_download_urls) that an agent needs to chain a wait/poll call. Combined with 100% schema coverage of the six parameters, nothing needed to call or follow up 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%, including per-model resolution, tier, and image-count constraints and a deprecated-enum warning, so the schema carries the parameter burden. The description adds nothing parameter-specific beyond referring to 'advanced model selection', so the baseline 3 applies.

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

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

States a specific verb+resource: creates an AI image job with model selection and quality/resolution controls, and it explicitly labels the operation async. It does not differentiate from the many other *_create_image siblings (editor, upscaler, meme, QR, etc.), so an agent must infer from the name which generator applies.

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

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

Gives clear post-call workflow guidance: call wait_for_image_project with the returned id or poll GET /v1/image-projects/{id} until complete/error/canceled. However, it gives no guidance on when to pick this tool over sibling generators such as ai_image_editor_create_image or ai_face_editor_edit_image, nor any prerequisite tier/permission framing beyond what the schema enum lists.

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

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

Annotations only declare openWorldHint=true and non-read-only, but the description adds substantial behavior: async execution model, the exact return fields (`id`, `credits_charged`), terminal job states, credit costs differentiated by mode and scale factor, a tier restriction on 4x, and the signed-URL handling rule ('preserve signed URLs and query parameters; never append expiration metadata'). This is genuine context the structured fields do not carry.

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

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

Information is dense and largely front-loaded, with the lifecycle contract first and the purpose/cost sentence after. The 'MCP guidance' preamble is cross-tool boilerplate that would apply to many Magic Hour endpoints, and the file-path advice partially restates the schema, keeping this from a 5.

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

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

An output schema exists so return values need not be re-explained, and the description nonetheless covers the async lifecycle, result retrieval path, cost model, credential/tier constraint, and URL-handling caveat. Combined with a fully-described nested schema for a 4-parameter tool, 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 100%, establishing a baseline of 3. The description goes beyond the schema by mapping credit multipliers to modes (25 vs 50 credits) and to scale factor (200 vs 100 credits), which the schema does not state, and by reinforcing the `*_file_path` contract for uploaded assets.

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: 'Upscale your image using AI', with concrete cost/scale detail (2x = 50/25 credits, 4x = 200/100). It does not explicitly differentiate itself from similarly-named siblings such as ai_image_editor_create_image or photo_colorizer_create_image, so an agent must infer the boundary from the name.

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

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

Gives clear operational routing: the call starts an async job, and finished results require wait_for_image_project with the returned id or polling GET /v1/image-projects/{id}. It also advises preferring the upload-URL endpoint when unsure about file inputs. What it lacks is guidance about when to pick this tool over alternative image-modification siblings.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false, openWorldHint=true. The description goes well beyond them: async job semantics, the returned id and credits_charged fields, terminal states, and a warning to preserve signed URLs and query parameters rather than appending expiration metadata. That is rich operational context an agent cannot get from the annotations or 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?

Compact and every sentence carries load, but the structure is inverted: the workflow bullets precede the actual statement of what the tool does, so the purpose is not front-loaded. Minor, since the total size is small.

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

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

With an output schema present the description need not explain return values, and the async lifecycle plus credit cost make it actionable. The remaining gap is the nested style object, whose 50% description coverage is not reinforced anywhere in the description text.

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%, so the description is expected to compensate for the nested `style` object and its `topic`/`template`/`searchWeb` fields. It instead mentions no parameter at all, and the only enum-like value ("Random" template) is left to the schema without any explanation of what choosing it implies.

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

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

The description states a specific verb and resource ("Create an AI generated meme") and adds the cost model (10 credits per meme), which is concrete and useful. It is distinguishable from siblings like ai_image_generator_create_image by the meme-specific framing, though the text never explicitly contrasts 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 guidance block explicitly says the call starts an async job and then routes the agent: use wait_for_image_project with the returned id, or poll GET /v1/image-projects/{id} until complete/error/canceled. It names the sibling alternative and the condition that selects each path, leaving nothing to inference.

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

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

The annotations only mark the tool as a non-destructive write. The description fills in behavior the annotations do not cover: the job is asynchronous, it returns `id` and `credits_charged`, a track costs 1 credit per requested second, downloads live inside the results, wait helpers add exact_download_urls, and signed URLs plus their query parameters must be preserved without appending expiration metadata. Those cost and URL-handling details are exactly the extra context the annotations lack.

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 puts the key facts first, but the second paragraph repeats the first block nearly word for word: 'Returns a project ID; poll GET /v1/audio-projects/{id} for status and downloads' says again what the MCP guidance block already said about the async job and where results come from. The 'MCP guidance:' label and the doubled polling instructions make it longer than it needs to be.

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 three-parameter, nested-object write, and an output schema already documents the return shape, so the description does not need to explain it. What the description does cover (async lifecycle, cost basis, which helper to use next, download URL handling) is what an agent needs to call it correctly. The main gaps are the duplicate follow-up instructions and the lack of any note on what happens when a job fails partway through.

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

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

Schema description coverage is 67%, so the description mostly adds meaning the schema does not already spell out. It ties `duration` to cost ('1 credits per requested second'), which the schema only hints at with 'Determines credits charged'. It does not restate the lyrics/instrumental interaction or the 15–300 range, because the schema already documents them, so this is useful without being redundant.

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

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

The description opens with a specific verb and resource ('Starts an async audio job') and then says plainly that it generates music from a description, with optional lyrics or instrumental-only output. That scoping is enough to separate it from the sibling tools: the other create_* tools produce images or video, while the audio tools (wait_for_audio_project, fetch_audio_download, audio_projects_retrieve_details) only follow up on this job.

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 tells the agent both what to do after the call and which follow-up route to take: 'For finished results, call wait_for_audio_project with that id or poll GET /v1/audio-projects/{id} until complete, error, or canceled'. It names the alternative helper and the terminal states that end polling, so the agent does not have to guess the next step.

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?

Beyond the annotations (which only give the safety/mutation profile), the description adds substantial non-obvious behavior: the call is asynchronous, it returns `id` and `credits_charged`, results carry `downloads`/`exact_download_urls`, and signed URLs with query params must be preserved. It even states the cost (0 credits). This is exactly the extra context the annotations cannot carry.

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

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

Two tight blocks with no filler; the operational guidance is dense and earns its place. The ordering is slightly off, however, since the core purpose ("Create an AI QR code") is buried after the MCP workflow paragraph rather than 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?

An output schema exists so return values need not be re-explained, yet the description still covers the async workflow end-to-end (job creation, polling, terminal states, URL preservation). For a nested-parameter async tool this is sufficient for an agent to call it correctly.

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

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

At 67% schema coverage the schema documents content, style.art_style, and name itself, so the baseline is a middling score. The description adds no parameter-level meaning (no guidance on `content` format for the QR payload or the nested `style` object), so it neither compensates for the missing coverage nor loses ground.

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

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

"Create an AI QR code" states a specific verb and resource, and it cleanly distinguishes this tool from the many sibling create_image tools (meme, headshot, upscaler, etc.) that share the same service but produce different artifacts. An agent can select this tool from the name plus one sentence 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 MCP guidance explicitly tells the agent this starts an async job and to use `wait_for_image_project` (a named sibling) or poll the image-projects endpoint until a terminal state. That is strong follow-up routing, but there is no explicit when-not or comparison against the other create_image siblings, keeping it below 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?

Beyond annotations, the description discloses the async job lifecycle, returned `id` and `credits_charged`, completion states, polling/wait helper behavior, download URL handling, and file-path requirements. It also clearly states that speech is not synthesized, which is important behavioral context for an audio-driven video tool.

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

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

The definition is structured into safety, async workflow, file handling, and input requirements, with useful information front-loaded. Despite covering several topics, each section serves a clear operational purpose and avoids 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 complex async video-generation tool with an output schema and annotations already present, the description fills in the important gaps: safety constraints, lifecycle behavior, polling guidance, asset upload requirements, and the sibling alternative. Nothing critical for correct invocation appears to be missing.

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

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

Schema description coverage is 100%, so the schema already carries most parameter meaning, including file-path formats, enums, and duration limits. The description reinforces that `assets.image_file_path` and `assets.audio_file_path` are required and that text alone is insufficient, but it does not add much 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 implies the tool creates a talking-photo video by requiring a still portrait and existing recording, and explicitly says text alone is not accepted and that it does not synthesize speech. It also distinguishes the tool from `lip_sync_create_video`, but the core verb/resource statement is less direct than it could be because the body starts with safety and async-job guidance rather than a single defining sentence.

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

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

It gives explicit when-to-use constraints, including authorized likeness only and prohibitions on impersonation, deception, sexual content, and minors. It also names the alternative for existing video plus replacement audio, and explains the asset upload path requirements clearly.

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

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

Annotations only cover readOnly=false, destructive=false, openWorld=true; the description adds far more: it is an async job returning `id` and `credits_charged`, it terminates in complete/error/canceled, wait helpers add `exact_download_urls`, signed URLs must keep their query parameters, and unsupported model/resolution/plan combinations are rejected. These are non-obvious operational facts that materially change how an agent invokes the tool.

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

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

The content is useful but the shape is poor: a 'MCP guidance' preamble arrives before the tool's own purpose sentence, and the async behavior is stated twice ('Starts an async video job; returns `id`' in the first bullet, then 'Returns a project ID; poll GET /v1/video-projects/{id}' in the last sentence). Roughly a third of the text is duplicated across the two blocks.

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?

Against a nested-schema, 5-parameter tool with an output schema and partial annotations, the description covers the async lifecycle, the retrieval path, file-input sourcing, image composition prerequisites, and credit charging. Nothing an agent needs in order 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 80%, so the schema already documents model defaults, script character limits, and per-model duration values. The description adds real value on the highest-risk parameter by explaining that `*_file_path` accepts an existing Magic Hour path or the `file_path` from the upload-URL endpoint, and that hotlinked URLs can fail as raw-byte fetches.

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 spoken UGC video from a prepared image and script,' and adds the distinguishing constraint that the image must be prepared separately (via the Image Editor API), which separates it from text_to_video, image_to_video, and ai_talking_photo siblings. An agent can route to this tool without opening the schema.

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

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

Gives explicit alternatives and conditions: it names `wait_for_video_project` and the polling endpoint for finished results, points to the Image Editor API for composing the source image, and tells the agent to use the upload-URL endpoint (rather than a hotlinked URL) when the path source is uncertain. When-to-use versus when-not-to-use is fully specified.

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

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

Goes well beyond the annotations: discloses async job semantics with terminal states (complete/error/canceled), that credits are charged at queue time via credits_charged, that per-frame billing is estimated and later settled, and that failed jobs are refunded. It also warns that hotlinked URLs can fail and that signed URLs with query params must be preserved, which is exactly the operational context annotations cannot carry.

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

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

The critical operational rules are correctly placed first, but the middle 'What this API does / Good for / How it works' block restates the same point three times and includes promotional framing ('run it at scale', 'For detailed examples, see the product page') that an agent gains nothing from.

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

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

With an output schema present, the description needn't explain return values, and it correctly stops at naming downloads/exact_download_urls. Cost, async lifecycle, and upload mechanics are all covered; only the relationship to other video-editing siblings is left unaddressed.

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

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

Schema coverage is 86%, so the baseline is 3; the description adds real value on the required nested video_file_path (existing Magic Hour path vs. presigned upload file_path vs. direct public URL) and flags optional fields like face_swap_mode and start_seconds/end_seconds. It stays vague on how resolution interacts with required inputs, leaving that to the schema.

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

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

States a specific verb+resource ('Create the same Video Editor ... programmatically') and clarifies it is a prompt-driven editing job, which separates it from generator siblings like text_to_video_create_video. It does not explicitly distinguish itself from adjacent video-edit siblings such as video_to_video_create_video, ai_video_translator_create_video, or character_replace_create_video, so the agent must infer the boundary.

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?

Routes the agent concretely: after starting the job, call wait_for_video_project or poll GET /v1/video-projects/{id}, and for file paths prefer the upload-URL endpoint (video_assets_generate_presigned_url) when unsure. It does not state when to choose a different video-creation sibling instead, 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?

Goes well beyond the annotations (readOnly=false, openWorld=true, destructive=false) by disclosing the async lifecycle, the returned id/credits_charged, the terminal states (complete/error/canceled), and that wait helpers add exact_download_urls. It also documents the billing model — credits charged at queue time, per-frame tools estimate then settle, failed jobs refunded — and warns to preserve signed URL query parameters.

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

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

The operational 'MCP guidance' block is front-loaded and dense, and the 3-step flow is easy to follow. Some marketing filler ('What this API does', 'Good for' bullets, product page link) repeats information and could be trimmed without losing meaning.

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

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

For an async creation tool with a full output schema and complete parameter descriptions, nothing an agent needs is missing: how to supply inputs, how to await results, terminal states, billing/refund behavior, and URL handling. Return-value details are correctly omitted because an output schema exists.

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

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

Schema coverage is already 100%, so the baseline would be 3, but the description adds real meaning: what a valid *_file_path is (existing Magic Hour path, upload-URL response file_path, or a stable public URL fetched as raw bytes) and that hotlinked URLs may fail. It does not add anything for start_seconds/end_seconds or resolution beyond the enum 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?

States a specific verb and resource: creates a Video Translator job programmatically, equivalent to the browser product. It implies automation/batch use, which distinguishes it from one-off editing siblings, but it never explicitly names the nearest alternatives (auto_subtitle_generator_create_video, lip_sync_create_video, video_to_video_create_video) so the boundary is left to inference.

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

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

Gives concrete routing: this only starts an async job, and finished results must come from wait_for_video_project or polling the project endpoint. It also gives a clear decision rule for file inputs ('prefer the upload-URL endpoint when unsure') and explains hotlinked URLs can fail. It lacks explicit 'when not to use' guidance against related video-to-video siblings.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), it discloses that credits are charged at queue time, that per-frame billing estimates settle against actual rendered frames while per-second tools charge the final amount upfront, and that failed jobs are refunded. It also warns that signed URLs and query parameters must be preserved and that hotlinked URLs can fail — genuinely 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 front-loaded MCP guidance is the useful part, but it is buried under a large marketing block ('What this API does', 'Good for', 'How it works (3 steps)', 'Cost', product-page link) that repeats the upload guidance already given above. The 'Key options' list also names fields that don't exist in this tool's schema, which is noise rather than signal.

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

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

With an output schema present, the description needn't explain return values, and it still covers the async lifecycle, billing/settlement, refund-on-failure, and the upload prerequisite. Nothing essential for a correct invocation is missing, though the stray non-existent parameters create slight ambiguity about what is actually configurable.

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 compensates further by explaining the `*_file_path` convention (existing Magic Hour path or the `file_path` from an upload-URL response, with public URLs only working if stable and raw-byte fetchable). The resolution enum's paid-plan requirement is echoed from the schema, and 'Key options' oddly mentions `face_swap_mode` and a text prompt that aren't parameters here, which caps it at 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 opening line states a specific verb and resource: it starts an async video upscaler job and returns `id` and `credits_charged`. The marketing block ('Create the same Video Upscaler you can make in the browser') restates this rather than adding precision, and it never explicitly distinguishes itself from near neighbours like ai_video_editor_create_video or video_to_video_create_video, but 'upscale' is unambiguous enough to route correctly.

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

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

It explicitly routes the agent: for finished results call `wait_for_video_project` with the returned id or poll the endpoint until `complete`/`error`/`canceled`, and it advises preferring the upload-URL endpoint when unsure about a URL's fetchability. What's missing is any when-not-to-use guidance versus the other create_video siblings, so it stops short of a 5.

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

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

Annotations only declare readOnly=false, destructive=false and openWorld=true; the description goes much further by disclosing that the job is asynchronous, what is returned (`id`, `credits_charged`, `downloads`, `exact_download_urls` from wait helpers), terminal states, that signed URLs and query params must be preserved, and that hotlinked media URLs can fail while direct fetchable URLs may work.

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

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

Behavioral guidance is front-loaded in bullets and every bullet carries actionable content. There is mild redundancy — the file-upload guidance largely restates the `audio_file_path`/`image_file_path` schema descriptions — and the closing "Create a Animation video" line is awkward and adds little beyond the title.

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

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

Given an output schema exists and annotations cover the safety profile, the description still supplies the async workflow, asset-resolution rules and a cost note, so it is nearly complete. The one material omission is sibling differentiation — nothing here tells an agent why to choose Animation over the other create_video tools.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it ties cost to `fps` and `end_seconds`, and adds the practical caveat that hotlinked URLs can fail and upload-URL endpoints should be preferred. It does not explain the nested `style`/`assets` conditionals further than the schema already does.

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

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

The description states a specific verb+resource ("Create a Animation video") and frames it as an async job that returns an id. However, it never distinguishes this tool from the many sibling video creators (text_to_video_create_video, image_to_video_create_video, ai_video_editor_create_video), so an agent must infer the choice from the name alone.

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

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

There is real conditional guidance for `*_file_path` (use an existing Magic Hour path or the upload-URL endpoint; prefer the upload-URL endpoint when unsure) and lifecycle guidance (call wait_for_video_project or poll until complete/error/canceled). But it never says when to pick this Animation tool over the sibling video-creation tools, which is the primary selection decision for an agent.

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

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

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

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

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

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

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

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

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

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

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

With one parameter at 100% schema description coverage, the schema already documents the id fully, including where the value comes from. The description adds nothing about the id, so the baseline 3 for schema-heavy coverage applies.

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

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

States a specific verb ('Permanently delete') and a specific resource ('the rendered audio file(s)'), which lets an agent distinguish it from audio_projects_retrieve_details and the parallel image_projects_delete / video_projects_delete siblings.

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

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

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

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description goes further, enumerating all six status values, stating when `downloads` is populated, and giving a concrete warning not to shorten or mutate the signed URL. That is meaningful behavioral context beyond the structured fields.

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

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

The status list and URL-handling rule are front-loaded and scannable, and every sentence carries operational value. The 'MCP guidance' prefix is slightly clunky but does not pad the content.

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

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

An output schema exists, so return values need not be re-explained; the description nonetheless supplies the status semantics and download-URL handling that the schema alone would not convey. For a single-parameter read/poll tool, 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 description coverage is 100% and the single `id` parameter is fully documented in the schema (including that it comes from POST create APIs). The description adds no syntax, format, or lookup guidance beyond the schema, so the baseline of 3 applies.

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

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

States a clear verb+resource: 'Check the progress of a audio project,' plus it clarifies that `downloads` is populated after a successful render. It does not, however, distinguish itself from close siblings like wait_for_audio_project or fetch_audio_download, so an agent cannot route between them from the text alone.

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

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

Gives explicit lifecycle context: 'Use this after a create tool to poll job status,' and tells the agent what to do on `complete` (surface download URLs) and `error` (surface the error message). It stops short of naming the alternative wait_for_audio_project or saying when not to poll manually.

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?

Beyond the annotations, the description discloses important async behavior: the call starts a job and returns id and credits_charged, then requires polling or wait_for_video_project until completion, error, or cancellation. It also explains signed URL handling, upload behavior, credit charging, settlement, and refunds for failed jobs.

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 and front-loads important async guidance, but it is overlong and includes generic marketing/boilerplate plus examples like face_swap_mode that are not relevant to this audio-to-video schema. It could be shortened without losing core 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?

For a complex, paid, asynchronous media-generation tool, the description covers the critical workflow, status handling, cost behavior, upload path requirements, and result access. With an output schema present, it does not need to fully document return values, and the remaining context is sufficient 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 schema already documents parameters well. The description adds useful file-path semantics, explaining that *_file_path values should come from Magic Hour assets or the upload URL endpoint, and warns that unstable hotlinked URLs may fail.

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

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

The description clearly states a specific verb and resource: create an Audio To Video job programmatically. It is distinguishable from siblings by the audio-to-video resource, though it does not explicitly contrast with alternatives such as image_to_video or text_to_video.

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

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

It provides clear usage context, including automation, batch processing, and app/pipeline integration, plus a three-step workflow. It does not explicitly state when not to use this tool or name sibling alternatives for related video creation tasks.

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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), the description discloses a lot: async job semantics, the exact returned fields (id, credits_charged), terminal states, that wait helpers add exact_download_urls, and a preservation warning about signed URLs and expiration metadata. This is substantive behavioral context the annotations do not carry.

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

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

Every sentence carries information with no filler, but the structure is inverted: the reader meets protocol guidance before the actual purpose, which lands in the final sentence. Front-loading the purpose would improve scannability.

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

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

An output schema exists, yet the description still usefully covers the async lifecycle, terminal statuses, and returned identifiers, and it fully addresses the tricky asset-input path for a nested-object, 5-param tool. Nothing needed to invoke 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%, so the baseline is 3, but the description adds real value by explaining how to obtain the assets.video_file_path value (existing Magic Hour path vs upload-URL file_path) and warning that hotlinked public URLs can fail. It adds meaning beyond the schema's field-level 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 names a specific verb and resource ('Automatically generate subtitles for your video in multiple languages') and clarifies the execution model ('Starts an async video job'). An agent can distinguish this from the many other create_video siblings by its subtitle-generation scope 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?

It clearly explains the follow-up workflow (call wait_for_video_project or poll the endpoint until complete/error/canceled) and gives routing guidance for file paths (prefer the upload-URL endpoint when unsure). It stops short of stating when NOT to use this tool versus sibling video tools, but the context for correct invocation is strong.

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

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

Annotations only declare readOnly=false, destructive=false, openWorld=true; the description goes well beyond that. It discloses that the call is asynchronous, returns id and credits_charged, must be followed by wait_for_image_project or polling until complete/error/canceled, that credits scale with resolution (from 50 at 640px), and that signed URL query parameters must be preserved. It also layers in authorization and content-policy constraints, which is real behavioral context an agent cannot get from structured fields.

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

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

The content largely earns its place, but the structure is inverted: two paragraphs of policy and operational guidance precede the actual purpose statement, which arrives last. An agent scanning for 'what does this do' must read to the end, and the safety preamble, while necessary, is boilerplate shared across the suite.

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-payload async generation tool with an output schema, this covers the essentials: the async contract, the follow-up tool to call, credit behavior, file-path sourcing rules, and policy limits. Return-value detail is not required since an output schema exists. The remaining gap is explicit positioning against the head_swap/face_swap_photo siblings.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns above baseline by mapping resolution values to models and cost tiers (640px/1k → Nano Banana 2 Lite, 2k/4k → Nano Banana 2, credits from 50 upward) and by explaining that *_file_path accepts either a Magic Hour path or an upload-URL file_path, with hotlinked URLs prone to failure. That adds genuine meaning beyond the enum's 'Determines credits charged for the run.'

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 final sentence states a concrete verb+resource: 'Swap a person into a scene image,' and even names the underlying models and how resolution selects them. That is far clearer than a bare 'create image.' However, it never distinguishes itself from close siblings like face_swap_photo_create_image or head_swap_create_image, leaving the agent to infer the difference from the title alone.

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

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

The description gives strong operational 'how/when' guidance for the async flow (start job, then call wait_for_image_project or poll the project endpoint) and when to prefer the upload-URL endpoint over a public URL. What it does not give is the selection guidance this dimension asks for: no statement of when to pick body_swap over head_swap or face_swap_photo. Usage is implied by the described workflow rather than explicitly bounded.

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

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

Goes well past the annotations: it discloses that the call starts an async job returning `id` and `credits_charged`, that credits are consumed with the queued charge being only an estimate while the final charge appears on the completed project, and that signed URLs must be preserved verbatim. These are exactly the cost and lifecycle traits an agent needs before invoking a mutable, credit-burning job.

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?

Dense but nearly every sentence carries information; the safety preamble and the MCP guidance bullets both do work. Slight deduction because the actual purpose sentence lands third, after the policy and the async/credits guidance, which is a less front-loaded arrangement for a tool whose identity should be established first.

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

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

With an output schema present and full param coverage, the description supplies the remaining gaps: async lifecycle, credits, and file-path sourcing. Minor residual gaps are durations/resolution compatibility, which it defers to the parameter schemas, and no explicit sibling routing, but nothing needed to call it correctly is absent.

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

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

Schema coverage is 100%, so baseline is 3; the description earns above that by restating the three required inputs and explaining that model choice constrains duration, resolution and subject-selection support. It also adds practical meaning to the `*_file_path` params (existing Magic Hour path vs upload-URL `file_path` vs stable public URL) that the schema only gestures at.

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 pair ('Replace a video subject or transfer video motion onto a reference character image') and the required inputs, which distinguishes it from generic video tools like video_to_video_create_video. It never names a sibling explicitly (e.g. face_swap_create_video or body_swap_create_image), so an agent must infer the boundary from the replace/animate framing rather than from a direct contrast.

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

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

Gives clear when-to-use context (subject replace vs motion transfer) plus operational guidance: prefer the upload-URL endpoint when unsure about file paths, and use wait_for_video_project rather than polling. It also gates use on authorization and prohibits impersonation/sexual/minors content. What's missing is a direct statement of when a different sibling (face_swap_create_video, body_swap_create_image) is the better choice.

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

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

Annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) signal a non-read-only external call, but the description adds meaningful behavior: it is asynchronous and returns an id, requires a second call to fetch results, has file-fetching caveats, and is currently free. It does not state rate limits or exact failure modes, keeping it just short of full transparency.

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

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

The core purpose sentence is buried after a multi-bullet MCP guidance block, so the definition is not front-loaded. The guidance and the pricing note are useful, but the ordering and some overlap (file-path advice appears in both the guidance block and effectively repeats the schema) make it less tight than it could be.

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

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

With an output schema present, return values needn't be explained, and the description covers the async lifecycle, the required follow-up call, and input-source handling. It is complete for correct invocation, though it could note expected latency or that the id must be polled until completion.

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 genuinely adds value for `target_file_path` by explaining the acceptable sources and steering users toward the upload-URL endpoint. It adds less beyond the schema for `confidence_score`, which is already well documented.

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: 'Detect faces in an image or video.' It also distinguishes itself from siblings by naming the retrieval endpoint (face_detection_retrieve_details via 'the face-detection details endpoint') as the follow-up and identifying the face-swap APIs as downstream consumers. An agent can tell this apart from face_swap_* and retrieve_details without opening a 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?

Explicit workflow guidance: this starts an async task returning an `id`, and you must use the details endpoint with that id before doing individual face swaps. It also gives file-path usage rules (existing Magic Hour path vs. upload-URL endpoint's file_path, prefer upload when unsure, hotlinked URLs may fail). When-to-use and the alternative pathway are both covered.

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

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

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

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

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

Two sentences, front-loaded with the core purpose and followed by the practical downstream use. No redundant restatement of the title, though the second sentence is a bit long with two embedded links.

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

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

An output schema exists, so the description need not explain return values, and the annotation block covers the read-only safety profile. The description supplies the caller's reason for retrieving details (multi-face swap inputs), which is the main thing the structured fields cannot convey. Minor gap: no mention of task state handling.

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

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

Schema coverage is 100% with a single required 'id' parameter whose description already explains it is returned by the face detection API. The description adds no syntax, format, or constraint beyond that, so the baseline of 3 for fully-covered params applies.

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

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

The description opens with a specific verb and resource: 'Get the details of a face detection task.' It is distinguishable from the sibling face_detection_detect_faces (which creates/initiates the detection) and from other *_retrieve_details tools by naming the face detection resource. It stops short of explicitly contrasting with the detect_faces sibling, so it earns a 4 rather than a 5.

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

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

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

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

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

The description adds substantial behavioral context beyond annotations: async job creation, returned id and credits_charged, job states, download URL handling, credit estimation, and upload/presigned URL behavior. These details are important for safely invoking and managing a generative video job.

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?

Despite being detailed, the description is appropriately structured for a complex async video-generation tool. Safety constraints, job lifecycle, upload guidance, and required modes are separated cleanly, and no sentence is obvious filler.

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

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

For a complex face-swap video tool with nested assets and async processing, the description covers the essential invocation path, result retrieval, upload handling, mode-specific requirements, and credit behavior. An output schema exists, so return value details are not required beyond what is already provided.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds cross-field relationships: required start/end/assets, matching video_source with video_file_path or youtube_url, image_file_path for all-faces, and face_mappings for individual-faces. It does not elaborate on optional fields like style.version, so it falls just short of 5.

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 title and tool name clearly state the specific action: swapping faces in an existing video. The description reinforces this by describing an async video job with video assets, and it is distinguishable from the photo face-swap sibling by the video-specific requirements.

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

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

It gives explicit safety exclusions, explains asynchronous job handling, names the wait/poll alternative, and clarifies when to use upload URLs versus direct public media URLs. It also distinguishes all-faces mode from individual-faces mode with the relevant requirements.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false, openWorld=true), and the description layers on substantial extra context: async job semantics, returned fields (id, credits_charged), the 10-credit cost, subscription-dependent dimensions, and signed-URL handling rules. That is well beyond what the structured fields convey.

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

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

Dense but well-organized into policy, MCP guidance, and a create/summary line. Minor weakness: the core purpose sentence appears at the end rather than being front-loaded, and the pricing/link sentence is marginally expendable.

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

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

For an async, nested-schema, credit-charging tool with an output schema, the definition covers invocation, job lifecycle, polling alternative, cost, and asset-path pitfalls. Nothing essential to correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds practical meaning for the *_file_path params: prefer the upload-URL endpoint, raw-byte fetchability matters, and hotlinked URLs may fail. This is genuine guidance the schema does not supply.

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 a face swap photo'), which separates it from generic image generators and video tools. It does not, however, distinguish itself from close siblings such as head_swap_create_image or body_swap_create_image, so an agent choosing among face-manipulation tools gets no explicit routing help.

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

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

Gives real when-not-to-use guidance (no impersonation, deception, sexual content, minors) and clear operational context (start async job, then use wait_for_image_project or poll). It stops short of naming which sibling to pick instead for a related swap task.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds non-obvious behavior: the 8 MiB inline cap, the requirement to preserve query parameters, and the note that `expires_at` is metadata rather than part of the URL. It does not describe error behavior on expired URLs, but it exceeds the annotation bar.

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

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

Three sentences, front-loaded with the core action, then the URL requirement, then the size constraint. No filler or repetition of schema/annotation data.

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

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

No output schema exists, yet the description states what is returned (inline MCP audio content) and the practical constraint that governs it. For a two-parameter read tool with annotations covering safety, nothing needed to call it correctly is missing.

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

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

With 0% schema description coverage, the description must carry the load, and it does: it explains that `download_url` must be the exact full signed URL with query parameters intact, and it implies the role of `max_bytes` via the 8 MiB inline cap. Minor gap is that `max_bytes` is never tied to its parameter name explicitly.

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

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

States a specific verb (Fetch) plus resource (audio download) and the exact source field (`downloads[n].url`), and identifies the return form (inline MCP audio content). An agent can distinguish it from siblings like fetch_image_download and fetch_video_download without opening a 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?

Explains the precondition (a completed audio project) and gives an explicit exclusion/alternative for the size limit: use the signed URL directly for downloads over 8 MiB. It does not name a sibling tool, but the when-to-use condition and the size carve-out are 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the 8 MiB inline cap, the requirement to pass the untrimmed signed URL, and the note that expires_at is separate metadata rather than part of the URL.

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

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

Three tight sentences, front-loaded with the core action and output, followed by the URL-passing rule and the size limit. Every sentence adds a constraint the agent needs.

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

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

With no output schema, the description correctly explains the return type (inline image content for compatible clients) and the size/URL constraints. It is nearly complete; error behavior for expired URLs or non-image content is not covered, but that is a minor omission for a read-only fetch tool.

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

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

Schema description coverage is 0%, so the description carries the burden, and it does: download_url must be the exact full signed URL with query parameters intact, and the 8 MiB cap maps directly to max_bytes (default 8388608). It does not explicitly define max_bytes' unit or that it overrides the inline cap, leaving a small 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 a specific verb (Fetch), resource (image download URL from a completed image project), and output form (inline MCP image content), which clearly separates it from fetch_video_download and fetch_audio_download in the sibling list. An agent can pick this tool without opening the schema.

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

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

It gives a clear precondition ('from a completed image project') and a when-not branch ('use the signed URL directly for larger downloads' beyond 8 MiB). It does not explicitly name the sibling fetch tools or the wait_for_image_project prerequisite, so routing context is implied rather than spelled out.

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

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

Annotations already establish the safe read-only, non-destructive, closed-world profile, but the description adds real behavioral context: return is an embedded binary resource, inline media is capped at 8 MiB, and `expires_at` is metadata rather than part of the URL. That is meaningful disclosure beyond the annotations.

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

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

Three sentences, purpose front-loaded, and each sentence earns its place by adding a distinct constraint (URL handling, expiry caveat, size cap). 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?

Without an output schema, the description still explains the return medium and the size fallback, and it covers the key URL pitfall. Given the trivial two-parameter surface, this is nearly complete, with only the `max_bytes` parameter left unreferenced.

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 0%, so the description must carry parameter meaning. It compensates well for `download_url` (pass the exact full signed URL, don't trim query params), but `max_bytes` is never named or explained, only implied by the 8 MiB cap. Partial compensation for a two-parameter tool warrants a 3.

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

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

States a specific verb (fetch) plus resource (a video `downloads[n].url` from a completed project) and even specifies the return form (embedded MCP binary resource). This clearly distinguishes it from siblings like fetch_audio_download, fetch_image_download, and video_assets_generate_presigned_url.

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

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

Gives a clear precondition (source must be a completed video project) and routes by size: inline for <=8 MiB, use the signed URL directly for larger downloads. It does not explicitly compare against sibling fetch/generate tools, so it stops short of full when/when-not coverage.

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 annotations covering only the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), the description carries and delivers the operational detail: async job semantics, the returned `id`/`credits_charged`, the terminal states, the 10-credit cost per image, plan-dependent resolution, clamping behavior, and the warning to preserve signed URL query parameters.

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

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

Content is dense and front-loaded with the safety guardrail followed by the workflow block, and nearly every sentence earns its place. The main structural flaw is that the core purpose ('Swap a head onto a body image') is buried in the last line rather than leading the description.

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 3-parameter async image job with a nested `assets` object and an existing output schema, the description covers everything an agent needs: cost, resolution constraints, file-path sourcing, polling/waiting behavior, and URL handling caveats. An output schema exists, yet the extra return-value context is additive rather than redundant.

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 baseline is 3. The description adds real meaning beyond the schema: the per-image credit cost, that `max_resolution` may be set below the plan maximum, and cross-referencing of the `*_file_path` upload pattern. Some of the clamping text duplicates the schema, so it is not a full 5.

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 final sentence states a specific verb and resource: 'Swap a head onto a body image.' That is unambiguous about the operation. However, it does not differentiate from adjacent siblings like face_swap_photo_create_image or body_swap_create_image, leaving the agent to infer which swap variant applies.

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 usage constraints ('only with the user's own likeness', 'do not use for impersonation/deception/sexual content/minors') and routes the agent to a lifecycle alternative (wait_for_image_project vs polling GET). But it offers no guidance on when to choose this tool over the many sibling image-generation tools, which is the harder selection decision.

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

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

Annotations already cover readOnly=false, destructive=false, openWorld=true, but the description adds substantial context beyond them: async lifecycle with id/credits_charged return, per-image cost of 5 credits, downloads field plus exact_download_urls from wait helpers, and the constraint to preserve signed URLs without appending expiration metadata. This is genuinely useful behavioral detail for a paid async mutation.

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 content is dense and mostly earns its place, but the structure is inverted: it opens with generic MCP workflow boilerplate and only states the tool's actual purpose ("Remove background from image") in the final line. Front-loading the purpose ahead of the shared guidance would make it substantially more scannable.

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

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

For a 2-parameter nested-schema tool with an output schema present, the definition covers the essentials: purpose, cost, async retrieval path, and asset sourcing. Return-value details are correctly left to the output schema. Only the missing sibling differentiation keeps it from being fully complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by advising how to source image_file_path (existing Magic Hour path vs upload-URL endpoint file_path), warning that direct public URLs only work if stable/fetchable and that hotlinked URLs can fail, which adds real decision value.

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

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

The description does state a specific verb+resource: "Remove background from image." That is clearly distinct from siblings like ai_image_editor_create_image or ai_clothes_changer_create_image. However, the actual purpose statement is buried at the very end beneath a large generic guidance block, which weakens how quickly an agent identifies what this 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?

It gives concrete operational guidance: the job is async, use wait_for_image_project with the returned id or poll GET /v1/image-projects/{id} until complete/error/canceled, and for *_file_path prefer the upload-URL endpoint when unsure. It never explicitly states when NOT to use this tool versus a sibling editor, but the workflow routing is clear.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description corroborates with 'Permanently' and 'not reversible', which adds a degree of permanence specificity, but discloses nothing new about auth requirements, side effects, or what happens to dependent assets.

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

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

Two short sentences, the destructive nature front-loaded, and the irreversibility warning immediately following. No filler and nothing that could be cut without losing meaning.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already declare this is a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description goes beyond that by explaining that `downloads` only populates after a successful render, enumerating all six statuses, and warning against mangling the signed URL (no shortening, no stripping query params, no appending expires_at). That is genuine behavioral value the annotations do not carry.

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

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

The operational guidance is front-loaded ahead of the prose, and each status bullet is a single line that earns its place for an agent branching on status. Minor waste: the title 'Get image details' is effectively restated by 'Check the progress of a image project', and the 'draft — not used' entry is dead weight.

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

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

An output schema exists, so return-field documentation is not required, yet the description still supplies the status vocabulary and result-handling rules, which is the key missing piece in structured data. The one real gap is the unresolved relationship to wait_for_image_project, which an agent selecting among polling tools would need.

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

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

There is a single required `id` parameter and schema description coverage is 100%, with the schema already explaining that the ID comes from the POST create APIs. The description adds no format, prefix, or sourcing detail beyond that, so the baseline of 3 is correct.

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?

It states a concrete verb and resource — 'Check the progress of a image project' — and the status enumeration makes the scope unambiguous. It distinguishes itself from create tools by framing itself as the post-create poll step, but it never names its closest sibling (wait_for_image_project), so an agent still has to infer which of the two polling tools to use.

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 opening guidance gives an explicit trigger ('Use this after a create tool to poll job status') plus per-status follow-up actions: surface `downloads` on `complete`, surface the error on `error`. That is actionable usage context, but there is no explicit 'when not to use' and no named alternative such as wait_for_image_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?

Beyond the annotations, it discloses that this is an async job returning `id` and `credits_charged`, that credits are consumed with the queued charge being an estimate versus the final charge on the completed project, and that signed URLs must be preserved. That is substantial operational context; only the failure/retry semantics of the queued job are left out.

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

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

Content is front-loaded and every bullet carries useful operational detail, but the 'MCP guidance' framing adds a layer of nesting and some path guidance overlaps the `assets.image_file_path` schema description. Slightly dense rather than wasteful.

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 generation tool with an output schema, the description covers invocation prerequisites, async lifecycle, credit implications, and file-path sourcing. 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%, so the baseline is 3, but the description adds real meaning: it names the two required inputs and explains how to obtain `*_file_path` (existing Magic Hour path, upload-URL endpoint's `file_path` after uploading bytes, or a stable public URL), plus a note that model/duration/resolution/audio support vary. That goes beyond the per-field schema text.

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

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

States a specific verb and resource (animate a supplied image into video) and names the required inputs `assets.image_file_path` and `end_seconds`, which separates it from `text_to_video_create_video` and other video siblings. The intent plus the input precondition make selection 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?

Explicitly routes the agent: use `wait_for_video_project` with the returned id or poll `GET /v1/video-projects/{id}` until `complete`/`error`/`canceled`, and prefer the upload-URL endpoint over hotlinked URLs when unsure of a file path. When-to-use and when-to-avoid are both stated.

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

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

Annotations only declare readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description goes well beyond them: it discloses async job semantics, the returned `id` and `credits_charged`, polling/wait-helper flow, signed-URL preservation rules, credit consumption with queued-estimate vs final-charge distinction, and content-policy restrictions. That is substantial behavioral context an agent needs before calling.

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

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

Content is front-loaded with the legal/policy guardrail, then operational guidance, then requirements. The bulleted 'MCP guidance' structure is scannable, though the block is dense and some sentences (URL query-parameter handling) could be tightened. Nothing is truly wasteful, but it is longer than strictly necessary.

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

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

For a nested, async, credit-consuming generation tool, the description covers job lifecycle, polling alternatives, asset sourcing, credit implications, and policy limits. An output schema exists, so return values need not be re-explained, and the description still notes `downloads` and wait-helper `exact_download_urls`. 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 beyond the schema by spelling out the cross-field dependency between assets.video_source and either video_file_path or youtube_url, and by explaining how `*_file_path` values are obtained. It does not add detail on max_fps_limit or style.generation_mode beyond what the schema already documents, so it stops short of a 5.

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 — 'Match existing video to replacement audio' — and the title confirms it lip-syncs an existing video to new audio. It explicitly names the sibling it is not ('For a still portrait plus audio, use ai_talking_photo_create_talking_photo'), so an agent can route correctly without opening any 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?

Explicit when-to-use and when-not-to-use: requires assets.audio_file_path plus a matching video source, and routes still-image cases to ai_talking_photo_create_talking_photo. It also clarifies that text alone is not a valid audio input, and gives guidance on when to prefer the upload-URL endpoint over direct public 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?

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true). Beyond that, the description discloses the async job model, that an id and credits_charged are returned, terminal states, the 10-credit cost, signed-URL preservation rules, and the file_path input workflow. This is rich behavioral context that goes well past the annotations.

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

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

The content is dense and mostly earns its place, but the structure is inverted: lengthy MCP/file-path guidance comes first and the actual purpose ("Colorize image. Each image costs 10 credits.") is tacked on at the end. Front-loading the purpose would make it scannable.

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

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

For an async image-generation tool with an output schema and annotations, everything an agent needs is present: how to start the job, what is returned, how to wait for completion, cost, and input-path handling. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds real value on top: it clarifies the *_file_path convention, the upload-URL presigned flow, and the caveat that hotlinked public URLs can fail while stable raw-byte URLs may work. This is meaningful semantics beyond the schema text.

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

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

The description states a specific verb+resource: "Colorize image." It is unambiguous and distinct from siblings like ai_image_editor_create_image or image_background_remover_create_image. However, it does not explicitly differentiate itself from those neighbors, and the core purpose sentence is buried at the very end rather than front-loaded.

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?

Strong procedural guidance: it explains the async pattern, tells the agent to call wait_for_image_project or poll GET /v1/image-projects/{id} until complete/error/canceled, and gives clear direction on when to prefer the upload-URL endpoint. It lacks guidance on when to choose this tool over alternative image tools, but the operational context is thorough.

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

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

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

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

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

A single front-loaded sentence with zero waste; the purpose and target are both in the first clause.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Four sentences, each carrying information, front-loaded with what is returned before filtering and pagination details. Slightly long but nothing is filler.

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

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

An output schema exists, so return values need not be spelled out, yet the description still clarifies the two URL types an agent will encounter. Combined with annotations and full param coverage, nothing needed to invoke it correctly is missing; only an explicit no-result/edge-case note is absent.

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

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

Schema coverage is 100%, so type, limit, and cursor are all fully documented in the schema; baseline 3 applies. The description's restatement of the type filter and cursor mechanics adds convenience but no meaning beyond what the schema already provides.

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

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

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

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

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

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

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

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

Annotations only say readOnlyHint=false, destructiveHint=false, openWorldHint=false; the description adds the substantive behavior: async job semantics, returned id and credits_charged, terminal states, that downloads come back and wait helpers add exact_download_urls, and the caveat to preserve signed URLs/query params without appending expiration metadata. That is real context beyond structured fields.

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

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

Two tight paragraphs, front-loaded with lifecycle guidance and ending with the disambiguation rule. The 'MCP guidance:' prefix is slightly meta but every sentence carries actionable information; no filler.

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

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

For a non-destructive async job creation tool with a rich 8-param schema and an output schema, the definition covers everything an agent needs: what it returns, how to get finished results, and which sibling to pick instead. No material gaps.

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

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

Schema description coverage is 88%, and the schema already documents audio, model, resolution, end_seconds, aspect_ratio and references per model exhaustively. The description only names style.prompt and end_seconds without adding format or constraint detail, so it neither compensates nor detracts — baseline 3.

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 ('Generate a new scene from style.prompt and end_seconds') and explicitly contrasts with the sibling image_to_video_create_video. An agent can distinguish it from the many other *_create_video siblings without opening any 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?

Gives an explicit selection rule — use when no supplied starting image is required, otherwise use image_to_video_create_video — and also prescribes the post-creation path (call wait_for_video_project or poll GET until complete/error/canceled). When-to-use, when-not, and the next step are all spelled out.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, and the description does not contradict them — 'only creates presigned upload URLs' clarifies that no bytes are transferred during this call, which is genuinely useful beyond the annotation. It also warns that hotlinked URLs can fail. It stops short of covering expiry/auth characteristics of the returned URLs, so a 4 rather than 5.

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

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

The guidance block is front-loaded and the workflow, extension table, and example are each clearly demarcated. There is mild redundancy — extensions appear both grouped here and again in the schema's extension description — but nothing is filler.

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

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

With an output schema present, return-value documentation is unnecessary, and the description instead covers the full operational context an agent needs: the required sequence of calls, the upload mechanism, the extension constraints, and the ordering guarantee. Nothing material is missing for a single-item, non-destructive URL-generation tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value above that by grouping valid extensions per asset type (video/audio/image/gif) rather than the schema's flat list, and by restating the ordering guarantee that the response array matches the request item order. It does not add per-parameter syntax detail beyond that.

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

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

The description states a specific verb and resource: 'Generates a list of pre-signed upload URLs for the assets required.' It immediately scopes this to Magic Hour storage and makes clear this is not the upload itself, distinguishing it from the sibling *_create_* and fetch_* tools that consume the resulting file paths.

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

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

It gives explicit when-to-use ('only necessary if you want to upload to Magic Hour's storage'), when-not-to-use, and alternatives ('Direct public media URLs may work if stable... Prefer the upload-URL endpoint when unsure'). The two-step workflow (generate URL, then PUT raw bytes, then pass file_path to the create tool) is spelled out with a concrete curl example.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so irreversibility is largely covered by structured data. The description restates permanence and adds that it targets the 'rendered video' specifically, which is minor added value over the annotation but no information about auth requirements or side effects on assets.

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

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

Two short sentences, front-loaded with the action and outcome. No filler, though the second sentence is somewhat redundant with the destructive annotation.

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

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

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

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

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

Schema coverage is 100% and the schema itself explains the id, including where it comes from ('returned by all of the POST APIs that create a video'). The description adds nothing beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb (delete) and resource (rendered video) with a clear scope qualifier. It is distinguishable from create/retrieve siblings by the verb, but it does not explicitly name the analogous destructive siblings (image_projects_delete, audio_projects_delete) to confirm the parallel.

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

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

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

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

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

Annotations already cover read-only/destructive/open-world safety, so the bar is lower, and the description clears it by disclosing the full status lifecycle (queued/rendering/complete/error/canceled), that `downloads` is only populated after a successful render, and the important rule that the signed URL must be used verbatim. It stops short of auth or rate-limit behavior, and the status list partially overlaps the output schema.

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

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

The most decision-relevant content (poll-after-create, URL handling) is front-loaded in a short guidance block, and the prose is tight. There is minor redundancy — the tool title is effectively restated as 'Check the progress of a video project' — and the trailing 'draft — not used' entry adds little.

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 read tool with annotations and an output schema, the description supplies what structured fields cannot: polling workflow, status semantics, error surfacing, and signed-URL integrity. The main gaps are the unmentioned `wait_for_video_project`/`fetch_video_download` alternatives and any auth or rate-limit expectations.

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 single `id` parameter is already described as the value returned by the POST creation APIs. The description only echoes this obliquely via 'after a create tool,' adding no format, sourcing, or failure-mode detail beyond the schema — the baseline 3 applies.

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

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

The description states a specific verb+resource: 'Check the progress of a video project,' and clarifies that the `downloads` field only appears after a successful render. It is clear on its own, but it never differentiates itself from the very close sibling `wait_for_video_project` (long-poll alternative) or `fetch_video_download`, leaving the agent to infer which retrieval path applies.

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 real conditional guidance: use it after a create tool to poll status, surface `downloads` URLs on `complete`, and surface the error message on `error`. There are no exclusions or named alternatives, however — most notably `wait_for_video_project`, which is the obvious competing way to await the same job.

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