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

Goes far beyond the sparse annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false). Discloses the 2-credit cost, public-by-default privacy with private=true opt-out, background/non-blocking generation with a required polling cadence, the extra cost of make_video, and the return shape (character with first_look_id). No annotation contradiction.

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?

Relatively long, but every sentence carries operational weight: cost, privacy, polling cadence, terminal statuses, and downstream routing. The core purpose is front-loaded in the first two sentences, prompting guidance sits in the middle, and advanced-path details are deferred to the end.

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 10-parameter tool with no output schema and two usage paths, this covers the essentials: return value, async behavior, polling cadence, terminal statuses, cost, privacy, and the downstream dependency on create_clip. Minor gaps: no failure-mode handling (insufficient credits, what to do on 'failed'), and no statement on whether description and dna_json can be combined.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by grouping the 10 parameters into two coherent paths (plain-text description preferred vs structured name+age/gender/dna_json) and by giving content guidance for the description field (nationality, age, hair, eyes, face shape, skin, style, realism anchor). It does not clarify edge interactions such as what happens if both description and dna_json are supplied.

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?

Opens with a specific verb+resource ('Create a new AI character from a plain-text description'), names the input format, and describes the automatic first-look generation, distinguishing it from siblings like generate_image and create_clip. The pipeline context (look id feeds create_clip) makes the tool's role 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?

Provides explicit workflow routing: confirm credits with get_credits, poll list_images every 5-10 seconds, pass the completed look id to create_clip. It also delineates the simple description path from the advanced structured path. However, it never states when not to use this tool (e.g., if only a standalone image is needed, generate_image would be the alternative), so it stops short of a full when/when-not contrast.

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 behavioral traits: it costs credits, generation runs in the background, it returns a clip id and status, and it requires polling. It also explains the practical downside of lip-sync from still images, which helps set expectations. No contradiction with annotations exists.

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

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

The description is dense but every sentence earns its place: purpose, cost, prompt guidance, input constraint, return value, and follow-up polling. The most important operational facts are front-loaded, and no filler or redundancy is present.

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 still explains the return value ('Returns the clip id and status') and the full post-call workflow through get_video and download_video. It covers prerequisites, cost, input requirements, and background behavior, making it sufficiently complete for correct invocation.

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

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

Schema coverage is 100%, so the baseline is already strong. The description adds meaningfully beyond the schema: exact credit costs, the constraint to provide exactly one of image/photo, the scene-staged distinction, and prompt guidance for natural-looking video. This significantly improves parameter understanding.

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

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

The description clearly states the tool's function: 'Animate a character look (or your own photo) into a short video clip.' This is a specific verb and resource, and the title reinforces it. However, it does not explicitly distinguish this from the sibling create_motion_clip, leaving some potential ambiguity about which video-creation tool to choose.

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 practical context: check get_credits first, provide exactly one of image or photo, prefer silent reaction prompts for realistic results, poll get_video, then call download_video. It does not explicitly state when not to use this tool versus alternatives like create_motion_clip, so it stops short of a full when/when-not set of exclusions.

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

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

The description goes well beyond annotations by disclosing that the operation costs 3 credits per driver second capped at 30 seconds, that the driver is uploaded first, that generation runs in the background, and that the agent should poll every 5–10 seconds until status is 'completed' or 'failed'. It also specifies the next step. This is rich behavioral context with no contradiction against 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 description is dense but every sentence earns its place: action summary, cost, driver constraints, the exactly-one rule, return values, and the polling/download follow-up. It is front-loaded with the purpose and contains no repetition of schema content.

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

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

Given the absence of an output schema and the complexity of a background generation task, the description fully covers what is returned (clip id and status), how to poll with the correct parameters, and what action to take on completion or failure. It also addresses prerequisites such as credit confirmation and file limits, so an agent can invoke and monitor the tool correctly without prior knowledge.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying the mutual exclusivity of image/photo, the upload-first requirement, and the credit cost basis. These details help an agent reason about parameter combinations, pushing it above baseline.

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

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

The description opens with a specific verb and resource: 'Animate a character look (or your own photo) by copying the motion of a driver video.' It clearly identifies the operation as motion transfer, and the reference to `clipugc videos motion` ties it to a known command, distinguishing it from the sibling create_clip. This is not a tautology and leaves no ambiguity about what the tool accomplishes.

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

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

The description provides strong contextual guidance: driver format/size/duration limits, the requirement to upload first, the 'exactly one of image or photo' rule, the need to confirm credits via get_credits, and a detailed post-call polling workflow with get_video and download_video. It does not explicitly state when not to use this tool versus alternatives like create_clip, so it misses the top tier.

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?

Even though annotations are present, the description adds meaningful behavioral context: it costs no credits, creates missing parent directories, downloads to a local mp4 file, and fails on incomplete videos. These details go beyond the structured annotations and help the agent predict side effects and failure modes.

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

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

The description is compact and front-loaded with the core action and resource, followed by essential behavioral notes. Every sentence contributes useful information: kind semantics, CLI equivalence, path handling, cost, and failure condition. No filler or redundancy is present.

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 three-parameter download tool with no output schema, the description is complete. It covers what the tool does, the valid inputs, default behavior, side effects, cost, and failure conditions. An agent has everything needed to invoke it correctly and anticipate the outcome.

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

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

The schema already covers all parameters at 100% coverage, so the baseline is 3. The description adds value by explaining that 'ad' refers to a merged_video_id, that output can be an absolute path with auto-created directories, and that defaults are clipugc-video-<id>.mp4 or clipugc-ad-<id>.mp4. This enhances the schema's parameter documentation.

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

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

The description clearly states a specific action ('Download') on a specific resource ('a completed clip' or 'a completed merged ad') to a local mp4 file. It also distinguishes the two supported kinds ('clip' and 'ad'), making the tool's purpose unambiguous and differentiating it from siblings like get_video or create_clip.

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

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

The description gives clear context for when the tool is appropriate: use it after a clip or ad has completed, and it explicitly warns that it fails if the video is not yet complete. It does not name alternative tools explicitly, but the conditionality and the local-file outcome provide sufficient usage guidance.

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

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

The description discloses cost, asynchronous background generation, expected polling cadence, success/failure statuses, and that results are image IDs. These are exactly the behaviors not visible in the annotations or schema, and nothing contradicts the annotation hints.

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?

Five dense sentences with a clear order: purpose, alias, generation constraint, cost, output, and polling workflow. Every sentence contributes information not otherwise available in structured fields, and the key purpose is front-loaded.

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

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

Despite having no output schema, the description explains return values (image IDs) and the full lifecycle: trigger, poll for terminal status, and continue into create_clip. It is complete enough for an agent to invoke correctly and integrate with 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 adds meaningful semantics for scene (describe only setting, outfit, light; never the person again) and shots (cost is per shot). It does not over-repeat parameter names and leaves schema definitions to carry enums and defaults.

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: generate new looks/reference images of an existing character. It also differentiates from character creation by emphasizing the character already exists, and the downstream reference to create_clip further positions it in the workflow.

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

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

It clearly establishes when to use the tool (produce new looks for an existing character), how to budget (2 credits per shot, confirm with get_credits), and how to follow up (poll list_images, then pass IDs to create_clip). It lacks an explicit when-not-to-use statement naming sibling alternatives, so it doesn't quite reach the top bar.

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

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

Annotations already provide readOnlyHint=true, and the description adds important context beyond that: the call itself 'Costs no credits,' the data is for the 'authenticated user,' and the costs are 'live.' This helps the agent set user expectations without overexplaining.

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 short sentences with no filler: the first states the core return value, the second explains when to call it, and the third notes it is free. The most important behavioral facts are front-loaded and every sentence earns its place.

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

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

With no parameters, read-only annotations, and no output schema, the description supplies all essential context: what is returned, the cost categories, the recommended call timing, the stop-early policy, and the fact that the call itself is free. Nothing critical is missing for an agent to invoke it correctly.

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

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

The tool has zero parameters, so there is nothing for the description to clarify about arguments. The baseline of 4 applies because no parameter semantics are needed, and the description still explains what the returned information represents.

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

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

The description opens with a clear verb and resource: 'Return the authenticated user's credit balance and the live per-action credit costs.' It lists the specific cost categories, making the tool's scope unambiguous and distinct from all sibling generation and retrieval tools.

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

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

The description explicitly tells the agent when to call this tool: 'Call it before any generation tool so you can tell the user the cost and stop early when the balance is too low.' It also gives a deterministic rule for cost-aware behavior and notes the CLI equivalent, leaving no ambiguity about its role.

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 mark the operation as read-only, and the description adds meaningful context on top: the possible statuses, that clip records additionally expose merge_status and merged_video_id once merged, and that it costs no credits. It does not contradict the read-only/open-world 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?

Four short sentences carry all the essential information: behavior, kind variants, polling role, statuses, merge fields, and cost. The main action is front-loaded and no sentence 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?

For a 2-parameter read-only poll tool with no output schema, the description fully covers what an agent needs: how to get the id/kind, what statuses to expect, the merge-specific fields, and cost. The absence of error/not-found behavior is a minor gap that does not compromise 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 coverage is 100%, so the baseline is 3; the description adds a little context by mapping id/kind to CLI commands and to the outputs of the creation tools, but most parameter meaning (clip vs ad, default kind, id format) already lives in the schema. It does not materially reduce the agent's need to read the schema.

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

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

The description opens with a specific verb and resource: 'Get the current status of a clip ... or of a merged ad', which immediately tells an agent what the tool does. It also names its role as 'the poll tool for create_clip, create_motion_clip and merge_ad', clearly distinguishing it from sibling creation/list/download tools.

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

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

It states exactly when to use it: after create_clip, create_motion_clip, or merge_ad, to poll status. It also covers both kind variants with defaults and CLI equivalents, but does not explicitly list exclusions such as 'use download_video when you need the actual media file', so it falls just short of a 5.

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

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

The readOnlyHint annotation already signals a safe read operation, and the description adds useful behavioral details: it costs no credits, supports three different listing modes, and returns items with specified fields plus pagination. This goes beyond the annotation without contradicting it.

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

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

The description is three sentences with no filler. The primary purpose is front-loaded, followed by scope semantics, return shape, and cost. Each sentence contributes information an 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?

For a simple read-only list tool with no required parameters, the description covers the available scopes, the default behavior, return fields, pagination, and credit cost. Since there is no output schema, the enumerated return fields are especially valuable and sufficient for an agent to interpret results.

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

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

The schema already documents all four parameters, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining what each scope value returns, which is the most important parameter behavior. Other parameters like page and per_page remain adequately covered by 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 starts with a specific verb and resource: 'List ClipUGC AI characters (AI influencers).' It also explains the scope variants and notes the CLI equivalence, making the tool's purpose unambiguous and distinct from sibling tools like list_images.

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

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

The description gives clear context for each scope value ('mine' lists own characters, 'discover' lists the public feed, 'feed' prioritizes own characters). It does not explicitly name alternative tools or state when not to use this tool, but the scope guidance makes usage conditions 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 and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context beyond annotations: 'Costs no credits' (economic behavior affecting agent decisions), the 150-char output limit, and the fact that multiple suggestions are returned ('Pick one'). This goes beyond what the schema or annotations state.

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 tightly packed sentences with zero filler. The definition is front-loaded, the usage guidance and downstream chaining follow logically, and the credit-cost note is a single useful clause at the end. Every sentence earns its place.

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

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

For a low-complexity tool (1 optional param, no required fields, no output schema), the description covers the essentials: what it does, how to tailor it, output constraint, downstream consumer, and cost. The main gap is the exact response format (e.g., an array of candidate strings), though 'Pick one' implies multiple suggestions and the 150-char limit constrains the format sufficiently.

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

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

Schema coverage is 100% and the schema already explains the context parameter well. The description adds value by stating the parameter's functional purpose — passing context produces 'tailored hooks' — which explains why the agent should bother supplying it. This is a meaningful addition over the schema's neutral 'Describe the app' phrasing.

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 ('Get'), resource ('AI-suggested hook texts'), and defines what a hook is ('the short attention-grabbing line burned over a UGC ad'). It also disambiguates the potentially misleading 'list_' name by clarifying this is a suggestion/generation tool, not a retrieval of stored hooks, and even maps it to the CLI equivalent 'clipugc hooks suggest'.

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 context for when to use the tool (when a hook text is needed for a UGC ad), how to tailor results (pass app context), and what to do with the output (pass it as hook to merge_ad). It lacks explicit when-not-to-use or alternative tool exclusions, but the chaining instruction makes its role in the workflow 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 already mark readOnlyHint and openWorldHint; the description adds meaningful behavioral detail: statuses to expect, image URL availability upon completion, CLI equivalence, and zero credit cost. This goes beyond the annotations without contradicting 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 dense and efficient, with every sentence adding useful information: what is returned, CLI equivalence, polling role, and cost. No filler or redundancy.

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

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

For a simple one-parameter read-only tool, the description fully covers purpose, usage context, output details, and cost. The readOnlyHint annotation confirms safety, so nothing essential is missing.

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

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

Schema description coverage is 100%, and the single parameter 'character' is already documented as the character id. The description does not add significant new meaning beyond the schema, so 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?

Clearly states the tool lists character looks/reference images with specific fields (id, status, scene_prompt, image URL) and identifies its role as the poll call for generate_image and create_character. This distinguishes it from siblings like list_characters and generate_image.

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

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

Explicitly positions the tool as the polling mechanism for generate_image and create_character and notes it costs no credits. It does not state when not to use it, but the intended usage context is clear.

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

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

The description goes far beyond the annotations: it discloses that files are uploaded first, the merge renders in the background, the returned id is in a different id space, and the caller must poll get_video with a specific kind parameter. It also explains the status polling loop and cost lookup. No contradiction with the annotations is present.

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

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

Every sentence earns its place and the most important information is front-loaded: the operation, inputs, and output. The description is dense but readable, and the polling instructions are specific without being padded. It is a model of efficient tool documentation.

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 fully explains the return value (merged_video_id), the id-space distinction, the required polling behavior, and the follow-up download call. It also covers preconditions, cost, and asynchronous rendering. Nothing essential for a caller to use the tool correctly is missing.

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

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

The schema already describes all four parameters at 100% coverage, so the baseline is 3. The description adds important extra meaning: it clarifies that 'video' is a clip id whose return id is an AD id in a different namespace, and that local file parameters imply an upload step. This exceeds the schema's basic descriptions without being exhaustive.

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

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

The description clearly states the operation: merging a completed clip, app screen recording, hook text, and optional music into a final UGC ad. It names the exact inputs and output, and the CLI equivalence ('clipugc videos merge') removes ambiguity. This also differentiates it from sibling creation tools like create_clip or create_motion_clip.

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

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

The description provides clear context for when the tool is appropriate: the clip must have status 'completed', costs can be checked via get_credits, and the result is an ad id rather than a clip id. It does not explicitly state when not to use it or name alternative tools, but the prerequisites and workflow give strong practical guidance.

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