ClipUGC

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses that the call charges the credits quoted by draft_episode, that the charge is refunded on failure, and that the returned player card self-polls rather than requiring manual polling. These are non-obvious side effects an agent could not infer 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?

Front-loaded with the primary action, then the cost/refund note, the confirmation gate, the optional-scenes clause, and the polling instruction. Each sentence carries distinct, non-redundant information with no filler.

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

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

An output schema exists, so return values need not be explained, and the description still covers the billing, refund, and async-polling behavior an agent needs. For a mutating, credit-charging tool this is complete.

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

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

Schema coverage is 67%. The description restates the scenes semantics already present in the schema ('replace the script with the user's edits') and adds little, while the required 'story' parameter is documented in neither the schema nor the description. Baseline 3 for the moderate coverage with only marginal added meaning.

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 gives a specific verb+resource ('Approve a drafted episode and start rendering it') and explicitly ties itself to draft_episode, the sibling that produces the episode id. An agent can distinguish it from draft_episode and get_video 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?

It states the gating condition plainly ('Only after the user has seen the script and said yes') and gives an explicit anti-pattern ('do not poll get_video while it is showing'), naming the alternative tool and the situation that selects it. Nothing is left 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 say it is a non-destructive write; the description adds the costly details an agent actually needs: 2 credits up front, 7 more for make_video, private-by-default with an opt-in public cast, and asynchronous staging where the clip starts when the look finishes. The polling instruction (list_images until completed) discloses the async contract that no structured field conveys.

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 (costs, privacy default, video staging, return values, polling). The opening sentence is an awkward fragment ('Optionally from a reference photo...') that front-loads a modifier rather than the action, which is the main structural flaw.

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 ten parameters, nested objects and an output schema, the description covers the workflow end to end: input alternatives, credit confirmation, privacy semantics, video staging, returned identifiers and how to wait for the look to finish. Nothing an agent needs 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 genuine meaning: it explains that description and hints are alternative inputs for the same thing, that a reference photo does not replace the written identity, and gives content guidance (nationality, age 18+, hair, eyes, style, realism anchor).

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 new AI influencer) plus the artifact it produces (first look), which cleanly separates it from list_characters, update_character and suggest_influencers. An agent can identify the 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 real selection guidance: use a reference photo via photo_file, photo_upload or photo_url, confirm credits with get_credits, and get ready-made descriptions from suggest_influencers. It never states when to prefer update_character or when not to create a new character, so it falls 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?

Annotations only cover safety hints (readOnlyHint=false, destructiveHint=false, openWorldHint=false); the description goes well beyond them with exact credit pricing (7/5s, 13/10s, +2 for scene), the side effect of scene-staging, the returned clip id, and non-obvious polling behavior. Prescriptive guidance on silent reactions ('mouth closed, no talking, an expression arc in beats') is unusual and valuable 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?

Front-loaded with what the tool does and its cost, and every sentence carries information (pricing, reaction guidance, return value, polling). The reaction-prompt advice and polling note are slightly interleaved with the core behavior, but there is little waste.

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 flags that the clip id is returned and, more importantly, explains the self-polling player card so an agent does not misfire get_video. Cost, prerequisites, and mutation behavior are all covered for a complex zero-required-parameter, nested-object tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the credit cost attached to the scene parameter and the alternative between prompt and reaction. It leaves photo/scene interaction with image somewhat implicit, but exceeds what the schema alone conveys.

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 completed look into a short clip of the influencer.' The scene clause ('adding scene stages the look in a new place first') hints at its distinction from scene-replace siblings, but it never names create_clips, create_motion_clip, or create_scene_replace_clip, so an agent must infer which of the four clip creators 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 concrete workflow guidance: 'Confirm with get_credits' as a prerequisite and an explicit when-not ('do not poll get_video when the card is showing'). However, it does not state when to choose this tool over the three sibling clip-creation tools, leaving the main routing decision 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 readOnly=false and destructive=false, which is weak coverage for a credit-spending tool. The description supplies the critical behavior: default is a dry run that spends nothing, the plan quotes an exact total, reactions must be passed back verbatim, and the total is never exceeded. That is exactly the context an agent needs to avoid an unintended spend.

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 what the tool produces and how many, then the required inputs, then the confirmation protocol. Dense and mostly waste-free, though the middle clause listing inputs restates the schema and could be trimmed.

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

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

For a 9-parameter, credit-spending, two-phase tool, the description covers the input contract, the dry-run/confirm loop, cost bounds, and the 'grid card fills in as the clips render' progress signal. With an output schema present, return values need no further explanation.

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 explains image vs. character, the 2-10 count, mood/purpose overrides, and reaction keys. The description largely restates those fields ('Give a look id (image) or an influencer id') rather than adding format or constraint detail beyond the structured data.

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 with scope: 'Several clips of one influencer at once, each a different silent reaction from the library.' An agent can distinguish this batch operation from the singular create_clip / create_motion_clip 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?

Spells out an explicit two-step protocol: call without confirm to get the plan and spend nothing, show it, then call again with confirm true and the same reactions. It also bounds cost ('never more than the quoted total'), but it never names a sibling alternative for single-clip or motion-clip requests.

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 flag it as a non-read-only, non-destructive, closed-world write. The description goes well beyond that: per-second credit costs (3 kling / 20 vs 30 credits for 10s), the fact that without confirm it only quotes and with confirm it spends, resolution constraints, and the 30-second/50MB reference limits.

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-loads the purpose before the engine/pricing detail, and every clause carries information. It is a dense run-on paragraph rather than structured bullets, which costs a point but no sentence is wasted.

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

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

For a 9-parameter, nested-object, enum-heavy tool with an output schema present, the description covers inputs, cost model, engine behavior and the confirm gate. Nothing needed to invoke it correctly is missing, and return values are handled by the output schema.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: default engine, credit math per engine, that prompt is read only by kling, and the three accepted driver input channels (upload id, https link, chat attachment) mapped to their parameters.

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 ('make a clip where the influencer repeats the movement of a reference video') and scopes it precisely to motion transfer, which cleanly separates it from create_clip, create_clips and create_scene_replace_clip. An agent knows exactly what this produces 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?

Explains the engine trade-off (kling follows movement and reads the prompt; wan is cheaper, keeps the background, ignores the prompt) and the quote-vs-spend contract via confirm. It does not explicitly say when to prefer a sibling like create_clip instead, so it falls short of a full 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 mutation safety profile; the description adds the real behavioral payload: 3 credits per second with a worked example, a 30-second cap, the confirm-gated quote-then-spend flow, the added 'AI generated' label, and a defaulted resolution at flat price. These are exactly the traits an agent needs and none are in 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?

Front-loaded with the core action, then prerequisites, cost, and restrictions in a logical order; each sentence carries information. It is slightly dense and could compress the credit arithmetic, but there is little true 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 costed, confirm-gated mutation tool that depends on two other tools, the description covers the dependency chain, the spend gate, the cost model, and the eligibility restriction. An output schema exists, so return values need no explanation, leaving nothing material 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 genuine meaning: it clarifies confirm's quote-vs-spend semantics, ties image to a 'look id' sourced from list_images and driver_upload to list_uploads, and states the 30s/50MB constraint. This goes beyond the schema without fully documenting every field's edge cases.

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: it replaces the person in the user's own video with an AI influencer, rendered in its own room/light/camera with an 'AI generated' label. This is clearly distinct from siblings like create_clip or create_motion_clip, so an agent can route correctly 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?

Gives explicit prerequisites and the workflow (request_upload, then list_uploads to get driver_upload) and a when-not condition ('Only AI influencers designed in ClipUGC work, not ones made from an uploaded photo'). It does not explicitly compare against sibling clip-creation tools, so it stops just short of a full when/when-not/alternatives map.

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 readOnly=false and destructive=false, so the safety profile is covered. The description adds substantial context beyond them: creation is free, episodes are charged only when approved, and the tool self-reports when the user's plan lacks stories. It doesn't disclose return values, but an output schema 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?

Front-loads the action and what a series is, then folds in constraints, pricing, and plan gating. It is dense and slightly packed, but every sentence carries real information; nothing is redundant.

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 handling return values, the description covers everything an agent needs: required inputs, the character constraint, billing model, plan gating, and how episodes continue the plot. Nothing material is missing for a creation tool.

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

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

Schema coverage is 80% (baseline 3), and the description still adds meaning: 'character' must be completed and unlocked from list_characters, 'premise' is framed as who/where/what keeps happening, and 'tone' gets a concrete example. 'resolution' is left entirely to the schema, 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 ('Start a story series') and immediately defines what a series is: one AI influencer living a continuing life in short talking episodes with a carrying-over plot. This clearly distinguishes it from siblings like create_character, draft_episode, and approve_episode.

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?

Names the source of the required character ('a completed, unlocked one from list_characters'), which routes the agent to the right sibling first, and explains the approval/charging workflow and plan gating. It lacks an explicit when-not-to-use statement versus draft_episode, but the entry-point 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 destructiveHint=true; the description goes well beyond that by disclosing the cascade (looks and clips go, finished videos survive), irreversibility, the confirm-gated dry-run behavior, and the ownership restriction. These are exactly the consequences an agent needs before calling a destructive tool.

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

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

Four short sentences, front-loaded with the action and scope, then consequences, then the confirm gate. No sentence is filler; the clipped phrasing ('Only the user's own.') is dense rather than vague.

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 destructive two-parameter tool with an output schema already present, the description covers everything needed: what is destroyed, what survives, reversibility, the dry-run path, and ownership limits. Return values are correctly left to the output schema.

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

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

Schema coverage is 50% (character is undocumented), and the description compensates by explaining that the target is one of the user's own influencers and that confirm=false yields a report-only call. It adds real semantics beyond the schema's own confirm description, though it never says what form the character identifier takes.

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 (one of the user's own AI influencers) plus the cascade scope (all its looks and clips). The scope clause also distinguishes it from delete_clip and delete_video, which delete media rather than the character.

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: it applies only to the user's own influencers, is irreversible, and behaves as a dry-run unless confirm is true. It does not name a sibling alternative or state auth prerequisites, so it stops short of explicit when-not/alternatives 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?

Beyond the destructiveHint annotation, the description discloses the two traits that matter most for a mutation: the action is irreversible, and downstream artifacts ("finished videos made from it") survive. It also explains the dry-run default when confirm is omitted, which the annotations do not 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?

Three short sentences, front-loaded with the action, then the side-effect scope, then the safety mechanism. Every clause carries distinct information and nothing is repeated from the schema or annotations.

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 need no explanation, and the annotations cover the safety profile. The description adds irreversibility, cascade behavior, and the dry-run default, leaving only minor gaps such as permission requirements or error conditions.

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 50%, and the description compensates by explaining the confirm flag's real semantics — that omitting it yields a report of what would be deleted rather than a deletion, which is more informative than the schema's "True only after the user confirmed the deletion." The clip parameter remains undocumented in both places, though its meaning is self-evident.

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 gives a specific verb and resource ("Delete one of the user's own clips") plus an ownership scope constraint, which distinguishes it from delete_character/delete_image/delete_video by resource. It stops short of naming any sibling or explaining how a clip differs from those other deletable resources, so it is clear but not maximally differentiated.

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 supplies a concrete usage rule: without confirm=true the call is a non-destructive preview, which tells the agent exactly when to pass the flag. There is no explicit when-not guidance or comparison against sibling delete tools, so it is clear context rather than a full routing statement.

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 flag destructiveHint=true and readOnlyHint=false, and the description adds genuinely new behavior: the operation is irreversible, the protected first-look case, and the dry-run semantics when confirm is not true. This is exactly the extra context an agent needs before a destructive call.

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, each carrying distinct load: what it deletes, the one prohibition, and the confirm/dry-run behavior. Front-loaded with the action and 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 an output schema present, return values need not be explained, and the description covers the safety-critical facts (irreversibility, protected look, dry-run). The remaining hole is the meaning/format of the required 'image' argument, which neither description nor schema resolves.

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 50%: confirm is documented in the schema, but the required 'image' parameter has no description in either place and the description never clarifies what value it expects (a look id/index). The description does add the default-behavior meaning of confirm, which partially compensates.

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 ('Delete one of the user's own looks') and scopes it to the user's own content, which separates it from delete_character/delete_clip/delete_video by resource. It does not explicitly name a sibling to route against, and the tool is named delete_image while the description talks about 'looks', leaving a small terminology gap.

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 context: only the user's own looks, the influencer's first look is protected, and untrusted deletes are dry-run. It does not name any alternative tool or state when to prefer this over sibling deletes, so the routing guidance is implied rather than explicit.

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: it discloses that the deletion is irreversible, that a dry-run report is produced when confirm is not true, and that the underlying clip survives the operation. These are exactly the behavioral traits an agent needs before calling a destructive 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?

Three short, front-loaded sentences with no filler; the destructive nature and the confirm gate are stated immediately, and the clip-survival note prevents a likely misconception.

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?

Covers scope, irreversibility, the confirm dry-run, and collateral effects on related content. An output schema exists, so return values need no explanation, and nothing an agent needs to call this destructive tool safely 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 50%: confirm is documented in the schema, but the required 'video' parameter has no schema description. The description implies it must refer to the user's own finished video, adding modest meaning, but gives no ID format or source guidance to compensate for the 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 (delete) and resource (a finished video), and scopes it to 'one of the user's own' videos. It also disambiguates from the sibling delete_clip by clarifying that the source clip remains, so an agent can distinguish it from other delete_* 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?

Usage is implied by the destructive semantics and the confirm gate, but the description never states when to choose this over alternatives (e.g. delete_clip) or any prerequisite conditions such as required permissions. Adequate but leaves routing 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 readOnlyHint=false, destructiveHint=false and openWorldHint=false; the description adds real behavioral context beyond that — it returns the scenes and the credit cost, it must be presented to the user before approval, and it cannot be chained with approval in one turn. It doesn't clarify persistence/state effects on the story, which keeps it from 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?

Front-loaded with the core action and returns, then the workflow constraints. Slightly chatty with 'Free' and the doubled emphasis on not approving in the same turn, but every sentence carries operational 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?

An output schema exists, so return-value detail is optional, yet the description still names the scene fields and credit cost. Together with the approval-workflow constraint, an agent has enough to call it correctly; only the required story parameter and episode-persistence semantics are left implicit.

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%: minutes and direction are described in the schema, and the description corroborates direction ('follows the user's own plot in direction') but adds no extra format or constraint detail. The required 'story' parameter is undocumented in both places, so the description doesn't compensate for the coverage gap.

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

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

States a specific verb and resource ('Write the next episode's script for a story series') and immediately distinguishes the scope from the approval step by naming approve_episode. An agent can tell what this produces 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?

Explicit when-to-use (continue the story from prior events, or follow the user's own plot via direction), explicit when-not (never approve in the same turn, one episode at a time), and names the alternative tool approve_episode with the required human-checkpoint workflow.

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 generic safety profile; the description adds real behavioral context: it is free/no-credit, rate-limited to one batch a day per app, and returns videos that render asynchronously in the grid. It doesn't cover failure modes or what happens to an existing pending batch, keeping it below 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?

Information is front-loaded (what it does, then cost, then trigger, then rate limit) with little waste. The prose is somewhat run-on and packed with clauses, but every sentence carries a distinct fact.

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-format details aren't strictly required, yet the description still notes the videos render over time. Cost, rate limits, trigger timing, and regenerate behavior are all covered for a 2-param tool; only edge cases like batch expiration remain 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 description coverage is 100%, so both parameters are already documented, including the url's optionality when an app is on file. The description only adds flavor about regenerate ('three more with other faces on the same hooks'), which is a marginal gain over 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 concrete verb and output: turns an app link into three finished UGC videos with distinct AI influencers, using the app's screenshots and hook lines. This is clearly distinguishable from siblings like make_video, make_videos, and suggest_hooks.

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 triggers ('Call it as soon as the user gives an app link') and the regenerate condition ('from the next day on, regenerate true makes three more'). It does not name sibling alternatives or state when NOT to use it, 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?

Annotations only give the generic safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description carries the real burden and delivers: per-call cost (2 credits, 4 for before_after), the need to confirm budget via get_credits, and a non-obvious post-call side effect (the card updates on generation, so list_images is unnecessary). It does not cover failure/refund behavior or any permission constraints, which keeps it short of 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?

Front-loaded with purpose, then usage constraint, scope, cost, and return/side-effect in a tight sequence. Every clause earns its place, though the sentence packing purpose, cost and the list_images warning together is dense enough to slightly hurt scanability.

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 are not required; the description still explains the one non-obvious output behavior (the look appears on the card immediately). Together with cost, scope, and prompt constraints, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds genuine meaning on top by instructing that 'scene' must describe place/outfit/light and not re-describe the person, and by framing 'character' as the influencer id that scopes to own vs public cast. The other parameters are already self-documented in 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 and resource ('generate a new look (reference image) of an existing AI influencer, same face, new setting'), which is precise enough to distinguish it from siblings like create_clip, create_scene_replace_clip, and retry_image. The parenthetical clarifies what a 'look' actually is, removing ambiguity about the output type.

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

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

Explicitly says when to use it and how to fill the prompt ('describe only the place, outfit and light... never the person again'), states the supported scope (own influencers and the public cast), routes the agent to get_credits for confirmation, and explicitly says not to call list_images afterwards. Multiple when/when-not/alternative directives are present.

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 safety is covered. The description adds real value beyond that: it discloses the returned payload shape (identity, plan unlock status, looks, clips) and the cost profile ('Costs no credits'), which is not derivable from 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?

Front-loaded with the core purpose and tightly packed with useful content; the long single sentence covering payload contents is dense but each clause earns its place. Minor risk of being slightly overloaded in one breath.

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 schema coverage on parameters, the description only needs to frame selection and behavioral context, which it does. Read-only, zero-cost, identity-or-list routing are all covered.

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 both parameters (name, character) are fully documented in the schema, including the fallback matching behavior 'The closest public or own match wins.' The description adds nothing further about parameters, 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 ('One AI influencer in full') and enumerates what the profile card contains: identity attributes, plan unlock status, finished looks, and clips. It explicitly names the sibling it is not (list_characters is for browsing many), so the agent can route without opening either 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 trigger ('when the user names or picks one influencer') and an explicit alternative with its condition ('list_characters is for browsing many'). Nothing about when-to-use is left 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 already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds two pieces of non-structured context: the operation costs no credits and defaults to the user's latest plan when no id is given. It does not discuss rate limits or polling politeness, so a 4 rather than 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?

Three short sentences, front-loaded with the return value, then usage triggers, then the cost note. Every sentence carries information an agent can act on and none 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-shape detail is unnecessary, and the description covers default behavior, when to invoke, and cost. For a single-optional-parameter read tool this is nearly complete; only polling/freshness expectations are left implicit.

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 parameter's schema description ('the latest plan when empty') already covers the fallback behavior. The description's 'Without a plan id, the user's latest plan' restates that rather than extending it, 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?

The description states a specific resource (a plan created by plan_content) and what it returns (per-day clip/video status plus a playable link), which is far more than a restatement of the name. It also ties the tool to its sibling plan_content, so an agent can distinguish it from run_content_plan and plan_content 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?

It gives concrete triggers: 'when the user asks how the month is going or wants the posting list,' and notes the plan card polls it itself, which tells the agent it is safe/redundant to call for UI refresh. There is no explicit when-not or direct contrast with alternatives such as get_story or list_videos, 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 already declare readOnlyHint=true and destructiveHint=false, and the description usefully reinforces the cost profile with 'Costs no credits.' It also discloses that the listed costs are 'live' (dynamic), which annotations don't convey. It stops short of describing refresh timing or caching behavior, so it's strong but not exhaustive.

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

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

Three tight sentences: purpose first, then the enumerated cost keys, then the usage imperative. The parenthetical list is dense but each key maps to a real output field, so it earns its space rather than padding.

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

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

An output schema exists, so return-value documentation is unnecessary, and the description already covers what the tool does, when to call it, and that it is free. For a simple zero-argument read tool, nothing an agent needs 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?

Zero parameters, so there is nothing for the description to compensate for; the baseline for a no-arg tool is 4. The description adds no parameter information because none is needed.

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 (returns the signed-in user's credit balance plus live per-action costs) and even enumerates the cost keys returned. This is clearly distinct from every sibling, which are spend/create/delete 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?

Gives an explicit when-to-use rule: 'Call it before any tool that spends credits and tell the user the price.' It also implies the when-not (nothing to check for read-only siblings) and mandates the downstream action of surfacing price to the user.

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 a safe, non-destructive read in a closed world, so the bar is lower; the description still adds real value by disclosing the 30-minute link validity, the mp4 format, and the zero-credit cost. It stops short of stating whether regenerating invalidates prior links.

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 resource and link lifetime lead, kind semantics follow, and the user-facing instruction and cost note close. Every sentence carries distinct 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?

An output schema exists, so return-value details are correctly omitted, and the description covers lifetime, format, and cost for a simple two-parameter read tool. The only missing piece is a precondition that the referenced asset be finished, which the wording implies but never asserts.

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 an enum on kind, so the schema already documents both parameters and their defaults. The description restates the kind values and default, adding only the semantic mapping of each kind to an asset type, which is marginal over 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 (get a download link) and enumerates exactly which assets it applies to (completed clip, finished video, story episode) plus the output format (mp4). It does not explicitly contrast itself with the sibling get_video/get_clip, so sibling differentiation 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 a handling instruction ("Show it to the user") and a cost note ("Costs no credits"), which implies usage context, but it never says when to prefer this over get_video or list_videos, nor any precondition such as the clip needing to be completed.

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, destructiveHint=false, openWorldHint=false), yet the description adds real context beyond them: the cost model ('Costs no credits') and a conditional behavior ('The latest episode's script is included when it is waiting for approval'). That conditional inclusion is exactly the kind of trait an agent cannot infer from 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?

Two sentences, zero filler, with the resource and return payload front-loaded and the cost/condition caveats trailing. Every clause 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 an output schema present the return shape need not be explained, yet the description still characterizes the payload and the approval-dependent script, which is enough for an agent to call it correctly. It omits what happens for an invalid or missing story id, a minor gap for a read 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% for the single 'story' parameter and it already documents the provenance of the id, so the baseline is 3. The description adds no syntax, format, or validation detail beyond what the schema 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 resource ('One story series') and enumerates exactly what it returns (story so far, every episode with fields), which distinguishes it from the sibling list_stories by scope. It never explicitly names list_stories or get_content_plan as the alternative, so the differentiation is inferable rather than stated.

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 by the getter shape and by the schema's note that the id comes 'from list_stories or create_story', but the description itself gives no explicit when-to-use or when-not-to-use guidance. The note that the latest script appears only 'when it is waiting for approval' hints at a useful scenario without framing it as 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?

Annotations cover the safety profile (readOnly, non-destructive, closed-world), and the description adds genuinely non-obvious behaviour: each call in a card client draws another card, and the call costs no credits. It does not repeat the annotation claims. Only gap is no statement about rate limits or error/not-found behaviour.

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 resource and status set, then the routing/polling rules; every sentence carries distinct operational information. It is dense and 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 structure need not be explained, yet the description still flags the playable url on completion and the terminal states. Combined with the polling guidance, an agent has everything needed to call this correctly in either client type.

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 the schema lacks: which id each kind expects and where it comes from (create_clip for clip, make_video for video, approve_episode for episode), plus the default kind.

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?

Names a specific verb+resource (status of a clip/video/episode) and enumerates the three kinds with the source of each id, so it is immediately distinguishable from siblings like list_videos or create_clip. The status vocabulary (pending, processing, completed, failed) further pins down what is being fetched.

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 when-to-use ('Call it when the user asks to see or check a video') and, unusually, an explicit when-NOT-to-poll rule for card clients plus the alternative behaviour for terminal clients (poll ~10s). This is routing guidance an agent cannot infer from the schema.

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 safety is covered structurally. The description adds genuinely new behavioral context beyond them: "Costs no credits" tells the agent this call is free to invoke freely, and it discloses that the response embeds three suggested next actions with their target tool. It stops short of describing pagination or latency, but for a read-only aggregate that is minor.

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?

It is front-loaded with the imperative "Start here" and then a single dense sentence enumerating the payload, followed by the usage line and a cost note. Every sentence earns its place, though the middle enumeration is long and could be tightened without loss.

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

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

Given the low complexity (no params, read-only, closed-world, and an existing output schema), the description supplies everything an agent needs: what it returns, when to call it, that it is free, and that it points to next tools. Return-value details are already carried by the output schema, so nothing required 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?

The tool takes zero parameters, so per the rubric the baseline is 4 and there are no parameter semantics for the description to clarify. Nothing is missing or misleading 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?

The description gives a concrete, specific function — a single session-start call that aggregates credits/prices, plan limits, entity counts (influencers, looks, clips, videos, uploads), the app on file, latest items, and three suggested next tools. This implicitly and effectively distinguishes it from the granular siblings (get_credits, list_clips, list_videos, get_content_plan), which return only one slice each. An agent can tell what this does 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?

It states explicit trigger conditions: "Use it at the start of a session and whenever the user asks what to do next." That is clear context for invocation. It does not name a competing alternative or an explicit when-not (e.g., "instead of get_credits"), so it stops just short of full routing 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?

Annotations already declare readOnly, non-destructive, and non-open-world, so safety is covered. The description adds useful context the annotations do not: it costs no credits and it explains is_locked as plan-gated public faces. It does not disclose pagination behavior or ordering semantics beyond the feed note.

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 scope semantics first, then the item shape, then the credit cost, all in three tight sentences with no filler. Slightly dense but every clause carries information an agent would otherwise have to guess.

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 explaining return fields is technically redundant, yet the description's item summary (id, display_name, is_locked, cover) is harmless and helpful for selection. Combined with annotations covering safety and the credit note, an agent has enough to call it correctly; pagination defaults remain only in the schema.

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

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

Schema coverage is 100%, so baseline is 3. The description earns a bump by expanding the scope enum in domain terms ('mine' default = user's own, 'discover' = public cast, 'feed' = own first then public), which tells the agent more than the terse schema strings. The other three params (page, search, per_page) are left 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 (List) and resource (AI influencers), and the scope explanation makes the retrieval model concrete. It does not explicitly distinguish itself from get_character (single-item) or suggest_influencers, so it stops short of full sibling differentiation. An agent can still tell what it returns 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 three scope values (mine/discover/feed) are explained in plain language, which effectively tells the agent which mode to select for a given intent, including that 'feed' merges own-then-public. No explicit alternatives or exclusions are named (e.g., vs suggest_influencers), so it is clear context without routing 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?

Annotations already declare readOnly, non-destructive, non-openWorld, so the safety profile is covered. The description adds genuinely useful behavioral context: it costs no credits and results are ordered newest first. It does not mention pagination or result count semantics, which is a minor gap.

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 resource definition, then filter semantics, then usage, then cost. Every sentence carries information, though the parenthetical "(an AI influencer moving and reacting, no app footage yet)" is dense and slightly awkward.

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 explained. With annotations covering safety, both params documented, and filter/cost/ordering behavior described, an agent has everything needed to decide whether and how to call this tool.

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

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

Schema coverage is 100%, so both params are documented (limit default 12, character from list_characters). The description adds meaning beyond the schema by explaining what the character filter actually returns (public influencer's reusable finished clips plus the user's own) versus the no-character case (own clips across every influencer).

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 (list the short clips) and immediately defines the resource (an AI influencer moving and reacting, no app footage yet). It also differentiates from siblings like list_videos by clarifying these are short clips shown as a grid.

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 when-to-use ("when the user wants to see clips") and an explicit when-NOT-to-use with an alternative path (for "my newest clip" in make_video, leave clip empty, no listing needed). This routes the agent away from an unnecessary call.

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 safety is covered. The description adds real behavioral context beyond that: the status lifecycle values (pending, processing, completed, failed), the 'thumbnail when ready' timing caveat, and the cost signal 'Costs no credits'. Return format details are largely deferred to 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?

Three short sentences, front-loaded with the resource and its fields, then scope, then the polling role. Dense with signal and no filler, though the field enumeration slightly overlaps the output schema.

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

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

Given a rich output schema and covering annotations, the description only needs to add selection context, which it does via the polling relationship and credit cost. Nothing an agent needs in order to call this correctly 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 coverage is 100% with a single documented parameter ('The influencer id from list_characters'), so the schema does the heavy lifting. The description implies the id targets an influencer but adds no syntax or format detail beyond what the schema already states; 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 ('The looks (reference images) of an AI influencer') and enumerates what is returned (id, status, scene_prompt, thumbnail). It also positions itself relative to create_character and generate_image, which helps distinguish it, though it never explicitly contrasts with the closest siblings like list_characters or list_videos.

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

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

Explicitly says it is 'the poll call for create_character and generate_image', which tells the agent exactly when to reach for it, and clarifies it works for both the user's own influencers and the public cast. There is no explicit when-not guidance, but the context is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds genuinely useful behavior beyond that: the operation is free ('Costs no credits'). It does not, however, mention pagination, ordering, or empty-result behavior for a list 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?

Two tight sentences that front-load the resource identity and close with the return contents and cost. Every clause carries information (domain, return fields, cost) with 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?

With an output schema present and zero parameters, the description need not explain return values, though it redundantly lists them. Read-only and non-destructive status is covered by annotations. Only pagination/ordering behavior is unaddressed, a minor gap for a list tool.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description does not need to compensate for any schema gap 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 clear verb+resource ('list' implied by name/title, resource is 'story series') and elaborates what a story series is, which meaningfully distinguishes it from the other list_* siblings (characters, clips, images, videos). It does not explicitly contrast with get_story or create_story, so it stops short of full sibling differentiation.

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

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

There is no when-to-use guidance and no named alternative; it never says when to call this versus get_story or create_story. The only usage-adjacent note is the cost remark ('Costs no credits'), which is helpful but not routing 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds context the annotations cannot: the 48-hour retention window, the 'whether a tool used it already' flag, and the fact that the call costs no credits — all useful behavioral traits.

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 scope and followed by the trigger and the cost note. Dense and largely waste-free, though the returned-field enumeration is somewhat redundant given an output schema exists.

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

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

For a two-parameter read tool with full annotation coverage and an output schema, the description supplies everything an agent needs: what it lists, the time window, when to invoke it, what to do with the returned id, and the cost. No material gap remains.

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 both limit and purpose are already documented in the schema, making 3 the baseline. The description's 'pass the id as recording_upload...' line refers to downstream tools' parameters rather than clarifying limit or purpose, so it adds little beyond the schema.

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

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

The description states a concrete resource (files the user handed over via upload page, links, attachments) with a precise temporal scope (last 48 hours) and enumerates returned fields (id, kind, name, size, length, age, used-by-tool). This implicitly separates it from asset-listing siblings like list_videos and list_images, but it never names or contrasts those siblings explicitly.

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

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

It gives a clear trigger ('Call it after the user says they uploaded something') and a concrete follow-up (pass the id as recording_upload, photo_upload, driver_upload or music_upload), which tells the agent what to do next. It stops short of stating when not to use it or which sibling to prefer for generated assets.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds ordering ('newest first') and cost behavior ('costs no credits'), which are traits the annotations do not 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?

One compact sentence with the resource, ordering, returned fields, and cost all front-loaded; no filler and nothing that fails to earn 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?

An output schema exists, so the description need not explain return values, and the credit-cost note plus ordering cover the key runtime concerns. The only gap is that it never distinguishes this tool from the near-identical 'first_videos' sibling.

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 single 'limit' parameter is fully documented in the schema (default 12, max 50). The description adds nothing about pagination or the limit, 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 ('finished UGC videos') scoped to the user, with a clear sense of what the list contains. It does not, however, differentiate itself from the close sibling 'first_videos' or other list_* tools, so an agent still has to infer the boundary between 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?

There is no explicit when-to-use/when-not or named alternative, but 'Costs no credits' gives a real selection signal (prefer this over paid generation tools for cheap inspection). Usage is only implied rather than routed against siblings like get_video or first_videos.

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 only the write/safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false); the description adds genuinely new behavioral context: the operation is free, it returns the video id, and the returned player card self-checks so the agent should not poll get_video. That last point is non-obvious operational guidance not available in any structured field.

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?

It is front-loaded with the core action and the output, then branches into sources; the one-word 'Free.' and the card/polling note both earn their place. It runs as a dense multi-clause block rather than cleanly separated statements, which slightly hurts scannability but not substance.

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 8-parameter mutation tool with nested file objects, it covers prerequisites, source selection, optionality, and return value (the output schema handles the rest), so most of the burden is met. However, it omits any differentiation from the sibling 'make_videos', which is the most consequential omission for correct tool selection in this suite.

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 goes beyond the schema by grouping the eight parameters into a decision structure the schema presents only piecemeal: app footage is 'one of' four alternatives or nothing, and music mirrors those sources and is optional. That mutual-exclusion/branching logic is the main value 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?

It states a precise verb and output: it burns a hook line and app footage onto a completed clip to produce a finished vertical UGC video, and it names the required prerequisite (a completed clip). The one gap is that it never distinguishes itself from the near-identical sibling 'make_videos', which an agent could easily confuse with this singular tool.

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

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

It gives real routing guidance: the clip must already be completed (get_video), leaving 'clip' empty selects the user's newest clip with no need to list first, and it enumerates the four mutually exclusive app-footage sources (recording_file, recording_upload, app_video_url, or on-file from first_videos). It also explicitly says not to poll get_video while the result card is showing. It stops short of stating when to prefer this tool over make_videos.

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 by disclosing cost ('Free'), the dry-run/confirm gate that spends nothing, the hard cap of 30 videos per call, and the UI behavior that the grid card fills in as videos render. These are exactly the operational facts an agent needs before invoking a non-readOnly tool, and none of them are derivable from the annotation set.

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 purpose and cost, then inputs, then the confirm contract, then limits and UI feedback - a sensible priority order with almost no filler. The stacked parentheticals (the influencer-id aside, the footage alternatives) make a few sentences denser than they need to be, but nothing is wasted.

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

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

For a 10-parameter mutation tool with an output schema, annotations, and full schema coverage, the description supplies the missing pieces: cost, the confirm gate, batch limits, and the clips-vs-character alternative. It stops short of covering failure/partial-render behavior or whether clip ids must belong to the workspace, which would round it out.

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

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

Schema coverage is already 100%, so the baseline is 3; the description earns above that by explaining the relational semantics the schema cannot - that each hook is applied to every clip, that clips and character are alternatives (up to 10, newest first), and that footage may be omitted when the app is on file. It does not restate music or upload-id params, but those are fully described in 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 and resource ('several finished videos at once') and immediately defines the cross-product semantics: every hook on every clip sharing the same footage. It explicitly distinguishes itself from the singular sibling make_video, so an agent can route between them without opening either 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 concrete prerequisites (clip ids or an influencer id, 1-10 hook lines, footage in the make_video forms) and an explicit two-phase contract: without confirm true it only returns the pairs and spends nothing, with confirm true it starts rendering. It does not explicitly say when to prefer make_video over this tool, but the 'several at once' framing plus 'like make_video' makes the split 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, openWorldHint=false. The description adds the non-obvious behavior that this call is free and produces nothing until run_content_plan with confirm true, plus the UI outcome ('the plan card shows the table and a Confirm button'). That is real 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?

Front-loads the purpose before the cost/confirm caveat and the input guidance, so the most important facts come first. The middle sentence is dense with parenthetical asides, but every clause 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?

For a 17-parameter tool with an output schema and partial annotation coverage, the description covers what the call does, its cost/confirmation lifecycle, and the required conceptual inputs. Return values are correctly left to the output schema, though it says nothing about the many optional tuning params (mood, purpose, duration, music).

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 100% schema coverage the baseline is 3, but the description goes further: it explains the influencer id-or-name duality, the app's optionality when on file, and groups the three mutually substitutable footage inputs (recording_upload, recording_file, app_video_url) by deferring to make_video. It omits mood/purpose/clips/hooks_per_clip, but those are fully documented in 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?

Opens with a concrete verb and resource: 'Lay out up to 30 days of posts for one app with one AI influencer,' and enumerates the plan's contents (reactions, hooks, order, footage, pricing). It is unambiguously distinct from siblings like run_content_plan (which executes the plan) and make_video (whose footage inputs it borrows).

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?

States the key gating condition explicitly: 'Free: nothing is made until run_content_plan with confirm true,' which tells the agent exactly when this tool is the right call versus the execution tool. It also gives conditional input guidance ('or nothing when it is on file from first_videos') and references make_video for footage semantics.

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 (which only say readOnly=false, destructive=false, openWorld=false) by disclosing the 30-minute validity window, the ten-file cap, and that it costs no credits. It also describes the required human-in-the-loop interaction sequence, which is essential 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?

Front-loaded with the purpose, then limits, workflow, and trigger. Dense and mostly waste-free, though the four-item file-type example list is slightly long for what it conveys.

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 need no explanation, and the description covers the trigger, the constraints, the handoff to list_uploads, and the cost. Nothing an agent needs to invoke 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?

Schema coverage is 100%, so both optional parameters (note, purposes) are already fully documented. The description's list of file kinds loosely maps to the purposes enum but never references the parameters by name or adds syntax 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: it returns a link to a ClipUGC page where the user drops files. The concrete file-type examples (screen recording, reference photo/video, music) make it unmistakable versus siblings like generate_image or make_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?

Explicit trigger ('use it whenever the user has a file on their device and no https link for it') plus a named follow-up workflow (call list_uploads, then pass ids to recording_upload/photo_upload/driver_upload/music_upload). When-to-use and the alternative path are both 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?

Despite annotations already marking this as a non-destructive, non-open-world write, the description adds real behavioral context the annotations cannot: the prior failure refunded credits, this retry recharges the same amount, credits_charged reports the figure, and the agent should tell the user. It also scopes ownership and notes the player card refreshes on its own.

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 terse sentences, front-loaded with the action and its cost consequence; nothing is padding. A couple of phrases ('say so', 'the player card checks on its own') are compressed to the point of slight ambiguity, but each sentence carries distinct information.

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

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

For a one-parameter mutation with an output schema and full annotations, the description covers the credit-charging consequence, the ownership restriction, and the fact that no polling is needed. Return details are left to the output schema, which is appropriate, so nothing critical is missing.

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

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

There is a single parameter ('clip') and schema coverage is 100%, so the schema already documents it fully. The description's mention of 'credits_charged' refers to a response field rather than an input, adding no parameter-level meaning beyond the schema. 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 (retry) and resource (failed clip), and the resource word 'clip' distinguishes it from the sibling retry_image and retry_video. However, the opening sentence largely restates the title, so it doesn't do much beyond naming the operation.

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 by 'try a failed clip again' plus the exclusion 'Only the user's own clips', which tells the agent the clip must be failed and owned. But it never names an alternative (e.g., create_clip for a fresh clip) or states when not to call it.

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

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

With annotations only declaring readOnlyHint=false and destructiveHint=false, the description adds real behavioral context: the prior failure refunded credits and this retry charges 2 again, plus that the result surfaces on a card. The instruction 'say so' usefully tells the agent to disclose the cost to the user, though the phrasing is terse.

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, front-loaded with the core action and cost consequence. The telegraphic 'say so' is efficient but borders on cryptic; otherwise 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?

An output schema exists, so the description needn't explain return values, and it nonetheless covers cost, ownership, and result presentation. It omits what happens if the retry fails again, a minor but real gap for a retry 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% with a single 'image' param already documented as 'the failed look id', so the baseline is 3. The description adds only the ownership constraint, not additional parameter semantics.

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

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

The description states the action ('Try a failed look again') and the resource is identifiable from the tool name retry_image. It does not, however, explicitly distinguish itself from the sibling retry_clip and retry_video tools, and the term 'look' is used instead of 'image', which leaves the resource slightly ambiguous.

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?

'Only the user's own looks' gives a scoping constraint, which implies when the tool is applicable. But no alternatives (retry_clip, retry_video) or failure conditions are named, so the agent must infer the boundary conditions.

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?

Adds real behavior beyond the annotations: no credit cost ('Free'), an ownership/authorization scope ('Only the user's own'), the 48-hour retention constraint on the underlying footage, and that status updates arrive without manual polling ('The player card checks on its own'). The last phrase is terse and slightly opaque about whether the caller must poll, which keeps this short of 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?

Front-loaded with the action and kept to a handful of short sentences with no filler. The telegraphic, fragment-heavy style ('Free.' / 'Only the user's own.') reads as clipped rather than fully structured, costing a little clarity.

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 tool with an output schema, the description covers the decisive facts: what is rebuilt, cost, ownership, the retention deadline, and the fallback tool. Return-value behavior is correctly left to the output schema, 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?

There is a single parameter with 100% schema description coverage ('The failed video id.'), so the schema already carries the semantics. The description adds nothing about the id's origin or format beyond what the schema states, 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 ('Rebuild a failed finished video') and narrows it further by naming the inputs reused ('same clip, hook and footage'), which cleanly separates it from make_video and from the sibling retry_clip/retry_image 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?

Gives both the when ('a failed finished video', footage still stored) and the when-not ('otherwise make_video again with fresh footage'), naming the alternative tool explicitly. The 48-hour footage window is stated as the concrete condition that selects between the two.

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 only covering the safety profile (non-readOnly, non-destructive, closed-world), the description adds real context: the exact cost ('the whole cost, exactly the total the plan showed'), autonomous execution ('puts ... on every clip as it lands, on its own'), and progress monitoring ('The plan card shows progress; do not poll'). These are traits structured fields 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-loads the action and stays to three sentences, each carrying content (effect, gating condition, monitoring). The parenthetical asides and conversational tone cost it a little crispness but nothing is wasted.

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

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

An output schema exists, so return values need not be described, and annotations cover the mutation safety profile. The description covers cost, autonomy, and the no-polling rule, leaving only failure/refund behavior unstated, which is minor 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 coverage is 100% and each parameter is self-documented ('The plan id from plan_content', 'True only after the user agreed to the total', the max_credits ceiling). The description largely repeats the confirm semantics and only loosely ties the cost statement to max_credits, adding little 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?

States a specific verb and resource ('Run a plan from plan_content') and clarifies the effect: it makes the plan's clips and attaches hooks and footage. It implicitly distinguishes itself from the sibling plan_content (which creates the plan), but the phrasing 'puts each day's hook and the footage on every clip as it lands, on its own' is a touch vague for an agent to parse.

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 gating condition ('Only with confirm true after the user agreed to the total') and operational guidance ('do not poll'). It sets the context in which this tool rather than plan_content or make_videos is chosen, though it does not name alternatives explicitly.

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 readOnly, non-destructive, closed-world behavior, and the description adds material context beyond them: the operation costs no credits and returns a set of candidates from which one is chosen. It doesn't describe count or format of returned hooks, but the output schema covers that.

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 dense sentences with the output, the selection constraint, the downstream tool, and the cost all front-loaded; no filler whatsoever.

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 suggestion tool with a full output schema, everything an agent needs is present: what it returns, how to use the result, and that it is free. 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 the schema cannot: the context parameter is optional because the app profile may already be on file. That clarifies the required=0 situation rather than just restating it.

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

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

States a specific verb (suggest) and resource (short hook lines) with a precise scope: the first frame of a UGC video. It is clearly distinguishable from the other suggest_* siblings (suggest_influencers, suggest_reactions) 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 explicit downstream routing: pick one line and pass it to make_video, plus the 150-character constraint. It doesn't name an alternative or a when-not-to-use condition, but for a suggestion helper the 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond that: 'Costs no credits' and the fact that results are ready to hand to create_character plus a first scene. It does not describe volume/rate behavior, but that is minor.

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-loads the core purpose and covers input, usage, and cost in a compact block with no filler sentences. The parenthetical color ('the paying user, not the prettiest creator') is slightly prose-heavy but still carries meaning, so it is not 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?

With an output schema present, return values need not be described, and annotations carry the safety profile; params are fully covered by schema. The description supplies cost, usage, and the create_character hand-off, leaving nothing critical for an agent to call it correctly.

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

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

Schema coverage is 100% (baseline 3), but the description adds real meaning: it explains the semantic of the 'attractive' flag (accounts whose job is to draw an audience come first) and the fallback behavior for 'app'/'category' when omitted. Only 'count' is left entirely 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 and resource ('Three to five ready castings for a new AI influencer') and clarifies the output form ('plain-words description ready for create_character and a first scene'). It implicitly distinguishes itself from siblings like create_character (it feeds it) and suggest_hooks/suggest_reactions, though it doesn't name those alternatives directly.

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 gives use contexts: 'Use it to suggest, to interview ("younger? a man? a different country?"), or to pick for the user,' and explains the input fallback ('with nothing, the user's app on file is used'). No explicit when-not-to-use or named sibling 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?

Annotations already cover the safety profile (readOnly, non-destructive, closed-world). The description adds behavior beyond that: selection rotates families and keeps loud reactions rare 'the way a believable feed does,' and it explicitly states 'Costs no credits' – meaningful 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?

Front-loaded with what it does, then usage, then routing and cost. The ten-family enumeration is dense but serves selection; only minor tightening is possible.

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, return values needn't be explained, and the description covers cost, selection logic, and downstream wiring. Adequate for a read-only suggestion tool, with no significant gaps.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds relational meaning: mood 'overrides purpose,' purpose defaults to feature_reveal when the user has an app, and exclude exists so 'the next post feels like a different day.' That is more than restating 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 and resource: 'Ready clip prompts from ClipUGC's reaction library,' with concrete scope (about forty silent reactions in ten families). An agent can distinguish this from suggest_hooks/suggest_influencers and knows exactly what artifact it produces (copy-ready prompts with the mouth closed).

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 how to drive it (ask for count + purpose, or a single mood) and routes the output forward ('Pass a key as reaction to create_clip, or several to create_clips'). It gives clear context but never states when NOT to use it or contrasts it against sibling suggestion tools.

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

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

Annotations declare a non-destructive mutation, and the description adds useful context beyond them: no credit cost and the consequence of going public ('anyone can use its finished looks and clips'). It doesn't state whether previously published material stays public on revert, but coverage is good.

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 primary action and followed by constraint and cost. 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?

Output schema exists so return values need no explanation, and annotations cover the safety profile. The description covers ownership, effect, and cost; only edge behavior (e.g., renaming while public) is left unstated.

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% (baseline 3), and the description still adds meaning: the 'public' flag's effect is spelled out as sharing finished looks and clips, and reverting to private is described. Name and character semantics align with 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 specific verbs (rename, make public/private) and the exact resource (one of the user's own AI influencers). Distinguishes itself clearly from create_character, delete_character, get_character and list_characters in the sibling set.

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 scope constraint: 'Only the user's own; the public cast belongs to ClipUGC,' which tells the agent when this tool will not apply. It doesn't name a sibling alternative for non-owned characters, but the when-not condition is clear.

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