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?

Goes well beyond the annotations (readOnly=false, openWorld=true, destructive=false) by disclosing credit pricing per engine, the 30s cap with a get_credits confirmation step, driver file constraints (mp4/mov, 50 MB, 30s, uploaded first), background/async execution, and a concrete polling interval and terminal statuses.

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

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

Purpose is front-loaded in the first sentence and the remaining sentences each carry operational payload (costs, limits, workflow). It is dense and slightly long, and the 'Same as `clipugc videos motion`' CLI mapping is marginal, but there is 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?

With no output schema, the description still states the return shape ('clip id and status') and the complete follow-up path via get_video and download_video. For a 7-parameter async generation tool, nothing an agent needs to invoke and follow through 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 the schema lacks: the image/photo mutual-exclusion rule ('exactly one of'), that prompt is only read by kling, that resolution is wan-only with a 720p default, and the credit cost differences between engines.

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 ('Animate a character look ... by copying the motion of a driver video') and distinguishes itself from sibling clip creators like create_clip and create_scene_replace_clip by naming the motion-copy mechanism and the two supported source types.

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

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

Gives explicit operating conditions: exactly one of image or photo, engine selection tradeoffs (kling reads prompt, wan keeps background/ignores prompt), and a full post-call workflow (poll get_video, then download_video). It does not explicitly contrast when to choose this tool over the other clip-creation siblings, which keeps 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?

Annotations only declare the safe-mutation profile (readOnly=false, destructive=false, openWorld=true). The description adds substantial behavioral context beyond that: cost model (3 credits/second, rounded up, capped at 30s), several-minute render time, background execution, a visible 'AI generated' label burned into output, and file size/duration limits. These are exactly the facts an agent needs before invoking.

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 dense paragraph that is well front-loaded: the operation and its visual semantics come first, then requirements, then cost, then the polling workflow. It is long, and the CLI alias and the schema-duplicated mp4/50MB/30s constraints are slightly redundant, but every sentence carries operational value.

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

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

With no output schema, the description still covers the return value (clip id and status), the asynchronous nature of the call, and the complete completion-detection loop. For a 4-parameter, asynchronous, credit-consuming generation tool, 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 is 3, but the description adds meaning beyond the schema: 'image' must be a designed character look rather than a user photo, and 'driver' is a local file that gets uploaded first. keep_sound and resolution are left to the schema, which already documents them adequately.

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?

Specific verb+resource ('put an AI influencer into a video... the character takes the place of the person in it') with explicit scope constraints and a direct mapping to the CLI equivalent `clipugc videos replace`. It is clearly distinguishable from siblings like create_motion_clip or merge_ad, which involve different operations.

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

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

Explicitly states prerequisites (a character look designed in ClipUGC, not the user's own photo; a local mp4/mov file), the upload-first requirement, and the exact follow-up workflow (poll get_video every 5-10s, then download_video). It also routes credit checks to get_credits. This is about as complete as usage guidance gets.

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 declare a non-read-only, idempotent, non-destructive, open-world operation; the description adds genuinely new context beyond them — file-system side effects (missing parent directories are created), the mp4 output form, zero credit cost, and the precondition that the video must have completed. It omits anything about overwrite behavior when the destination file already 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?

Three tight sentences, front-loaded with the clip/finished distinction and ending on the precondition. The parenthetical CLI mappings add length for marginal benefit to an agent, but nothing is repetitive or padded.

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 tells the agent the result lands in a local mp4 file and defines the default filename, which covers the practical return expectation. Minor gaps remain around what is reported back on success and behavior on conflicting destinations.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning the schema does not: the output path must be absolute, and the id is the same identifier returned by other tools. The `kind` enum semantics (clip vs finished vs ad, and which id type each expects) are also reinforced.

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 ("Download a completed clip ... or a completed finished video") and disambiguates the two variants via the `kind` parameter, even mapping each to its CLI command. It does not, however, distinguish itself from the sibling `get_video`, so an agent must infer that this writes a file while get_video likely returns metadata.

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: default is `kind "clip"` for clip ids, `"finished"` for a merged_video_id, and it notes the tool fails if the video has not completed yet. No exclusions or named alternatives (e.g. use get_video first to check status) are offered, so it stops short of explicit when-not guidance.

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

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

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 declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds two nontrivial traits beyond that: the call is free ('Costs no credits') and it returns live cost values that are subject to change, which matters for pre-generation budgeting.

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 return contents, then the usage rule, then the cost note. The parenthetical enumeration of eight cost keys is long but earns its place because no output schema exists to document them.

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 must explain what comes back, and it does: balance plus a named list of per-action costs. Auth scope, cost, and pre-call timing are all covered, so an agent can call this correctly with no further context.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing parameter-level to compensate for. The description instead documents the shape of the response payload, which is a bonus rather than a substitute.

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?

Specific verb + resource: 'Return the authenticated user's credit balance and the live per-action credit costs'. It enumerates the exact cost keys returned and names the CLI equivalent, so an agent distinguishes this instantly from the generation siblings like create_clip or 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?

Explicit when-to-use with a rationale: '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 clarifies the inverse condition (costs no credits), 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?

Annotations only declare that this is a read-only operation, so the description carries real weight by disclosing the status state machine (pending/processing/completed/failed), the presence of merge_status and merged_video_id on clip records, and that the call costs no credits. It stops short of timing/backoff guidance for polling, which keeps it off a 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 primary purpose and mode split are front-loaded in the first sentence, followed by the polling role and return states. It is information-dense but every sentence contributes; the inline CLI command references add length without adding much for an agent.

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

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

With no output schema, the description supplies the return semantics that matter — the status enum, the merge fields, and the zero-cost guarantee — plus the polling relationship to three creator tools. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds meaning on top: it states that kind defaults to "clip" and that "finished" expects the merged_video_id from a clip record. The enum value "ad" is left unexplained in both schema and description, which is the only gap.

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

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

States a specific verb and resource, and splits the resource into two distinct modes (clip vs finished video) with their CLI equivalents. It explicitly identifies itself as the poll tool for create_clip, create_motion_clip and merge_ad, so an agent can place it precisely among siblings.

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

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

The description clearly says when to reach for it: polling the status of ids returned by create_clip, create_motion_clip and merge_ad. It gives no explicit "do not use for X" exclusion (e.g., how it differs from download_video or list_* tools), but the usage context is unambiguous.

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

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

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 facts the annotations don't: the call costs no credits and the returned hook is capped at 150 characters. It stops short of describing how many hooks come back or their ordering.

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, front-loaded with the purpose, then the equivalence to the CLI command, then the usage chain and cost. No filler and nothing buried.

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-optional-param, no-output-schema tool, the description covers what is returned (hook texts, 150-char limit), that it's free, and how to consume the result. Missing only the cardinality/shape of the returned list, which an output schema would normally supply.

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?

Only one optional parameter exists and schema description coverage is 100%, so the schema already documents `context` fully. The description's 'Pass context describing the app for tailored hooks' explains the payoff of providing it, which is a mild addition beyond the schema's example, but nothing about format or length limits is added.

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 ('Get AI-suggested hook texts') and parenthetically defines what a hook is, so an agent unfamiliar with the domain can still tell this apart from siblings like list_images or list_characters. It also ties the tool to a concrete downstream artifact (the line burned over a UGC 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?

Gives a clear when-to-use path: pass context to get tailored hooks, then pick one and hand it to merge_ad as the `hook` argument. That routes the agent through the intended workflow, though it doesn't state when this tool should NOT be used (e.g. if an existing hook is already chosen).

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?

Annotations only declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description goes well beyond that by disclosing asynchronous background rendering, the required polling cadence (every 5-10 seconds until "completed" or "failed"), the cost gate, and the id-space caveat. These are exactly the behavioral traits annotations cannot convey.

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

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

Front-loaded with the core purpose, then proceeds through prerequisite, cost, ordering, and post-call workflow in a logical sequence with no filler clauses. It is on the longer side and the polling instructions read slightly like a runbook, but every sentence carries actionable information.

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

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

There is no output schema, so the description carries the full burden and does: it names the returned field (merged_video_id), explains that rendering is async, and prescribes how to poll and download. Nothing an agent needs to invoke and correctly follow through on this tool is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, giving a baseline of 3. The description adds meaning on top: it maps inputs to concepts (clip id vs. app screen recording vs. hook text vs. optional music) and, critically, warns that the returned merged_video_id lives in a different id space than the clip id passed in.

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: it merges an app screen recording plus a hook overlay (and optional music) into a finished UGC video, and even anchors it to the CLI equivalent `clipugc videos merge <clipId>`. An agent can distinguish it cleanly from siblings like create_clip, create_motion_clip, get_video, and download_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?

Explicitly states the precondition (clip must have status "completed", verify with get_video), the cost situation (free at time of writing, check the "merge" entry of get_credits), the fixed ordering (files are uploaded first), and the follow-up tools (poll get_video with kind "finished", then download_video with kind "finished"). When-to-use and what-to-do-next are both fully spelled out.

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