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

Annotations only indicate non-read-only and non-destructive; description adds the async behavior (returns run_id immediately, poll get_run), cost/refund semantics, and failure modes (actor_generation_disabled, actor_prompt_refused). These are substantive behavioral disclosures beyond annotations.

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

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

Four dense sentences, front-loaded with purpose and output, then async flow, pricing, and failure modes. No filler; each sentence carries operational information needed for correct use.

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 the major operational facts an agent needs: async polling, success data flow, pricing, refusal/no-charge behavior, and disabled-generation failure. Lacks any explanation of the attempt parameter (also undocumented in schema), which is the main completeness gap given no 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 already covers 6 of 7 parameters with descriptions, so the baseline is 3. The description adds semantic color by tying description to 'fictional adult', aspect_ratios to '9:16 portrait...edited from it', and quality to per-image pricing. It doesn't clarify the undocumented attempt parameter, so not a 5.

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

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

States a concrete action (create a personal actor) and specifies inputs (words describing a fictional adult) and outputs (9:16 portrait plus formats, run_id). Clearly distinguished from siblings: it is the creation counterpart to list_actors/delete_actor, and its async flow is explicitly routed to get_run and make_ugc.

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

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

Provides clear usage context, including the asynchronous polling workflow and how results connect to make_ugc. Does not explicitly state when not to use it or name alternatives such as quote_actor for price estimation before creation, so it stops 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 already flag the operation as destructive, but the description adds meaningful behavioral consequences beyond that: existing videos remain intact, new runs can no longer use the actor, and in-progress runs block deletion until completion. This substantially exceeds the annotation baseline.

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

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

Three sentences, all providing essential information: the action, the side effect on existing videos, and the blocking condition for ongoing runs. Nothing is wasted, and the most critical information is front-loaded.

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

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

For a single-parameter destructive tool with no output schema, the description covers the deletion scope, persistent effects, failure condition, and non-deletable catalog actors. An agent has everything needed to invoke it safely and interpret outcomes.

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 the only parameter clearly documented as 'Personal actor id from list_actors.' The description itself only restates 'by actor_id' without adding new semantic detail, so the baseline of 3 applies 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 begins with a specific verb and resource: 'Delete a personal actor of this account by actor_id.' It clearly distinguishes personal actors from catalog actors and clarifies that catalog actors are not deletable, which differentiates this tool from any catalog-related operations.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: it applies only to personal actors ('Catalog actors belong to Clipwright and are not deletable'), and it states a temporal restriction ('An actor used by a run that has not finished is refused until that run ends'). This gives the agent clear conditions without needing to inspect siblings.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral context: 'Free, spends nothing,' and detailed semantics for debt_credits, balance_credits, holds_credits, and grants. This goes well beyond what the annotations provide.

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

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

The description is compact yet information-dense, with the core purpose front-loaded in the first sentence. Every subsequent sentence explains a meaningful field or behavioral nuance without redundancy.

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

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

Despite having no output schema, the description explains the return semantics of every key field (debt_credits, balance_credits, holds_credits, grants) and connects them to make_ugc refusal behavior. Nothing an agent needs to interpret the result is missing.

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

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

The tool has zero parameters, so there are no parameter semantics to explain. The description correctly focuses on behavior and return field meaning instead. Baseline 4 for no-parameter tools is appropriate.

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

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

The description opens with 'Read this account's credits,' a precise verb and resource that clearly states what the tool does. It also distinguishes itself from siblings by explaining that it provides the underlying numbers behind quote_ugc's warnings.

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

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

The description explicitly differentiates this tool from quote_ugc: quote_ugc warns when make_ugc would be refused, while get_account gives the underlying figures. This gives the agent clear guidance on when to use this tool versus the sibling alternative.

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

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

Annotations already mark readOnlyHint and non-destructive, and the description enriches them by defining the policy values (anyone/no_actor/no_people), stating the setting only affects B-roll and not actor-only videos, and noting that run override wins with no_people as fallback. No contradiction with annotations.

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

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

The purpose sentence is front-loaded and the remaining sentences explain policy semantics and precedence with little fluff. It is slightly dense—'Segmented media generation is closed' is cryptic—but each sentence contributes useful context.

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

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

For a one-parameter read tool with a readOnly annotation, the description covers policy meaning, scope, and fallback behavior. However, with no output schema, it does not mention return format or what happens when no default is set, leaving some ambiguity about the tool's output.

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

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

The schema provides only actor_id as a required string with no description, so coverage is 0%. The description refers to 'this account actor's' default, which implies actor_id identifies an account actor, but it does not elaborate on format, ownership validation, or the exact role of the parameter beyond that.

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

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

The description opens with 'Read this account actor's saved B-roll default,' which names a specific verb, resource, and scope. It clearly differentiates from the write-oriented sibling set_actor_defaults and from other actor tools by focusing on the saved B-roll policy.

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

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

It gives clear context for when this tool matters: reading the saved B-roll default for an account actor and understanding that run overrides take precedence. It does not explicitly name alternatives like get_run or set_actor_defaults, but the read-vs-write and override semantics make the intended use obvious.

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 readOnlyHint=true and destructiveHint=false, and the description is consistent with that. Beyond annotations it discloses the return values that matter (IN_PROGRESS with a next_action, SUCCEEDED with video_url, FAILED) and the polling cadence, which is exactly the behavioral context an agent needs since there is no 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?

Two tight sentences, front-loaded with the purpose and followed by the polling procedure and terminal states. 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 no output schema and no annotations covering behavior beyond safety, the description carries the load well: it explains inputs, the polling loop, and every terminal outcome including the returned video_url. Nothing needed to call or interpret this tool is missing.

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

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

Schema description coverage is 0%, but the single parameter is nearly self-documenting and the schema carries the run_ pattern. The description adds the useful provenance detail that run_id comes from make_ugc or make_faceless, connecting the parameter to its source 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 and resource ('Check the status of a video generation') and immediately anchors it to the sibling tools that create the run (make_ugc, make_faceless). An agent can distinguish this polling tool from its generation siblings without opening any schema.

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

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

Gives explicit operational guidance: pass the run_id, poll every ~5 seconds while status is IN_PROGRESS, and stop when a terminal state is reached. This tells the agent exactly when the tool applies and how to sequence repeated calls, which is the critical usage question for a status-polling tool.

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

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

Annotations already cover read-only/no-destruction, yet the description adds substantial behavioral context beyond them: preview_url is a large, expiring signed link that must not be stored, withheld fields are nulled, planned=false is a normal outcome, media_available_until limits storage, and paid_edits.enabled gates edit-based video creation. This is the kind of disclosure that changes how an agent behaves.

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

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

Purpose and required input are front-loaded, and with no output schema the detailed field rundown earns its space. It is delivered as one dense unbroken block of prose, which makes the later return-shape details harder to scan than they need to be.

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

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

Because there is no output schema, the description must explain the return payload, and it does so thoroughly: frame size/rate, narration timing, per-shot fields, preview_url semantics, withheld, editable.state/reason, media_available_until, and paid_edits.enabled. An agent has everything needed to interpret both success and empty states.

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

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

Schema description coverage is 0% for the single parameter, so the description carries the burden, but it only says 'Pass the run_id' without format or provenance detail (the run_ prefix pattern lives only in the schema). Minimal compensation for the coverage gap, hence the baseline 3.

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

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

Opens with a specific verb+resource ('Read the shots of a video') and names the exact producer tools (make_faceless, make_ugc) plus the required input. This distinguishes it cleanly from the sibling get_run, which returns run-level data rather than shots.

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: call it after make_faceless/make_ugc, pass the run_id, and expect planned=false as a legitimate no-shots answer rather than an error. It does not explicitly contrast the choice against the sibling get_run, so the boundary between run-level and shot-level retrieval is only implied.

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

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

Annotations already mark this as read-only, and the description adds meaningful behavior beyond that: preview URLs expire while actor IDs remain reusable, and the default-voice behavior when no voice is supplied. These are useful operational details an agent would not infer from the annotation.

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

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

Five short sentences, each carrying distinct information: what is listed, how to use the ID, a URL-lifecycle caveat, a combination prohibition, and voice default behavior. No filler or redundancy.

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

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

For a parameterless read-only list tool with no output schema, this description is complete: it names the output fields, explains ID reuse, warns about expiring previews, and covers interactions with related tools. 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?

The tool has zero parameters, so the schema has nothing to document; the baseline for this case is 4. The description compensates by explaining the significance of actor_id (reusable, suitable for quote_ugc/make_ugc) and what output fields are present.

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

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

The description opens with a specific verb and resource ('List saved Clipwright actors') and enumerates the returned attributes (stable IDs, gender, age, verified image formats). It also ties the tool to downstream use in quote_ugc and make_ugc, making its role distinct even among siblings.

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

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

It gives clear context for when to use the result: choose actor_id for quote_ugc and make_ugc, and provides two prohibitions/constraints (do not combine actor_id with image/person/actor_gender; no voice means default gender voice). It does not explicitly contrast with an alternative such as get_actor_defaults, so exclusions are absent.

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

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

Annotations already cover the read-only/no-destruction profile, and the description adds genuinely useful behavior: the list is free, a voice is refused by the other skill before any charge, a voice with preview_url has an expiring sample, and defaults follow the actor's gender. However, a large block of behavioral text (per-model character limits, break tags, emoji counting, duration/price estimates) describes make_ugc rendering, not this listing tool, so it is contextual noise rather than transparency about this 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?

The purpose is front-loaded, but the text balloons into a multi-hundred-word block mixing voice listing, default-voice resolution, preview handling, and unrelated script/character-limit rules for downstream speech models. Many sentences (break tags, emoji counting, word-count limits) do not earn their place in a listing tool's description.

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

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

With no output schema, the description carries the burden of describing the returned shape, and it does cover the meaningful fields (skill, kind, language, gender, preview_url, preview_expires_at). It is therefore complete enough to call and interpret, though the completeness is diluted by tangential rendering-limit content and references to parameters this tool does not accept.

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 six filters are already documented in the schema (including enum lists and 'unknown value is refused'). The description largely restates these and instead spends its parameter discussion on `voice`/`voice_id`/`actor_id`/`actor_gender`, which are not parameters of this tool, so it adds little 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?

Opens with a specific verb and resource ('List the voices for the `voice` field of make_ugc, or of make_faceless with skill=make_faceless'), and immediately distinguishes the two skill-scoped lists. An agent can tell what this returns and how it differs from the sibling make_ugc/make_faceless tools 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 clear operational context: filter by language/gender/age/use_case/model, pick by name, use `voice_id` as an escape hatch, and re-call for a fresh preview link rather than storing it. It routes between skill modes but never states explicitly when *not* to call this tool or names a sibling list tool as an alternative.

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 tell the agent this is a non-read-only, non-destructive call; the description adds the critical async trait (returns a run_id IMMEDIATELY rather than waiting), the polling contract, the paid/quote-first cost behavior, the caption default, and the attempt-based re-run semantics. That is substantial 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-loaded with the core action and the async/cost caveats, and every sentence carries operational weight. The duration sentence is somewhat convoluted and partly duplicates the duration_seconds schema text, costing a little efficiency.

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

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

With no output schema, the description correctly supplies the return contract (run_id now, video_url on success) and the full async lifecycle. Combined with the high-coverage input schema, an agent has everything needed to call and follow up correctly.

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

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

Schema coverage is high (91%), so the baseline is 3, but the description adds meaning the schema lacks: attempt has no schema description and is explained here, captions on-by-default is reinforced, and the duration overrun behavior is spelled out. Most other params are already well documented in the schema, so it does not fully need to compensate.

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 paid finished faceless video from a script or brief') and immediately distinguishes the two input modes. The 'faceless' framing plus the named sibling quote_faceless lets an agent separate it from make_ugc 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 explicit sequencing: call quote_faceless first and show the user the price, then start the run, then poll get_run until 'succeeded'/'failed'. It also explains when to pass attempt=2,3 (to deliberately start a NEW run for the same input). This is close to a complete workflow prescription.

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

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

Annotations only say readOnlyHint=false / destructiveHint=false; the description adds substantial behavior beyond that: immediate run_id return with required polling, the failed→queued→succeeded recovery path surfaced in warnings[], retry via attempt, pre-charge refusals, and an explicit non-honored-field protocol. Nothing about how the tool behaves is left implicit.

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, the immediate-return contract, and the required polling loop, then the retry semantics. It is long, but this is a 19-parameter asynchronous generation tool; a few clauses (format/resolution defaults) duplicate what the schema already states.

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

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

No output schema exists, and the description compensates fully by naming the return value (run_id), the terminal states and their payloads (video_url / failed), and the warnings[] channel. For a complex async tool with a large schema, an agent has everything needed to call it and interpret the result.

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

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

Schema description coverage is already 89% and the parameter descriptions are unusually rich, so the baseline is 3. The description still adds cross-parameter semantics the schema does not: actor resolution precedence (actor_id from list_actors, else image, else default actor), the 1080x1920 default, and the captions opt-in rule. It does not restate most per-field constraints, which is appropriate given 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 specific verb and resource: 'Start generation of a lip-synced UGC video.' The async nature ('starts the run and returns a run_id IMMEDIATELY') distinguishes it cleanly from quote_ugc (cost only) and make_faceless (no actor), so an agent can route 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?

Explicitly orders the workflow: call quote_ugc before generating and show the cost, then poll get_run until 'succeeded' or 'failed', and use attempt=2,3,… for a deliberate new run after a failure. It also states the captions policy ('OPT-IN: ask the user first') and points to per-field NOT HONORED YET notes instead of guessing.

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 the description reinforces this by stating 'WITHOUT spending credits' and 'before any charge.' It adds substantial behavioral context beyond annotations: the per-format pricing model, the identity-check refusal before charge (actor_prompt_refused), and the note that failed formats are not charged. This gives agents a clear model of side effects and guarantees.

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

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

The description is exactly two sentences, front-loaded with the core purpose and key constraint, followed by a critical cost nuance. No filler, no redundancy, and every clause contributes to agent decision-making. It is a model of conciseness.

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

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

The description covers the essential behavior and usage, but it does not explicitly describe the shape of the quote response (e.g., whether it returns a total credit figure, per-format breakdown, or warnings). Given there is no output schema, a short mention of what the response contains would make this fully complete. Nevertheless, the agent can infer it returns a price, and the description already notes refusal behavior, so the gap is minor.

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

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

The input schema has 100% coverage; every parameter already has a description detailing constraints, defaults, and behavior. The tool description adds no additional parameter-specific semantics—it only mentions that formats are separately charged, which is already captured in the aspect_ratios parameter description. With full schema coverage, the baseline of 3 is appropriate.

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

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

The description states a precise purpose: 'Estimate the credit cost of create_actor WITHOUT spending credits.' It clearly identifies the action (estimate), the target (credit cost of create_actor), and immediately differentiates from the sibling create_actor by stressing it does not spend credits. This is specific and distinct from any other sibling.

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

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

The description explicitly instructs when to use the tool: 'Call this first and show the price before create_actor.' It also warns that each requested format is a separate charge, giving the agent operational context. Though it doesn't list when-not-to-use, the positive directive is unambiguous and sufficient for this tool's placement in the 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 already declare readOnlyHint=true and destructiveHint=false, so safety is covered structurally. The description adds the key non-obvious trait beyond the schema – that no credits are consumed – but does not describe what the quote response contains or how the cost is determined.

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 waste, with the purpose front-loaded and the mandatory call ordering placed second where it reads as the operative instruction.

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 mirror of make_faceless with fully documented schema, the description covers selection and sequencing adequately, and 'show the user the price' hints at the return value despite no output schema. Minor gap: it does not state that the same inputs as make_faceless are required for a valid quote.

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 all 10 parameters (including the script/brief mode coupling and the 30–90s duration rules) are already documented in the schema. The description adds no parameter-level meaning beyond that, 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?

Names a specific verb (estimate the credit cost) and resource (make_faceless), and explicitly distinguishes itself from make_faceless by being the non-charging precursor. An agent can place it against the sibling quote_ugc/quote_actor/make_faceless set immediately.

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?

"Always call this first and show the user the price before make_faceless" gives an explicit sequencing rule and names the exact alternative it must precede. The when-to-use condition is unambiguous rather than inferred.

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, but the description goes well beyond them: it discloses billing semantics (delivered revisions charged the quoted total, failed ones charged nothing even after paid work), the editing_disabled response while paid edits are closed, and the exact output fields (summary, billing.total_credits). That is rich behavioral context an annotation cannot carry.

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

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

The key value proposition ('WITHOUT spending credits') is front-loaded in the first clause, and each subsequent sentence adds distinct information: call shape, ordering requirement, billing outcome, and the editing_disabled case. No sentence is redundant with 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?

For a complex nested-input tool with no output schema, the description covers how to invoke it, the ordering with revise_run, the billing outcome, and the fields returned. Nothing an agent needs to call it correctly and report the price to a user is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a real constraint the schema does not enforce: 'exactly one of changes or document' (the schema only requires run_id and never expresses the mutual exclusion). It also names the return fields, but does not explain the modes or document structure further, so it sits just above baseline rather than at the top.

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 ('Price a revision of a run') and immediately scopes it as the no-credit quoting step, which distinguishes it from revise_run and from the sibling quote_faceless/quote_ugc/quote_actor tools. An agent can tell what this does and what it does not do 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 ordering rule: 'Always call this first and show the user the price before revise_run.' It names the alternative (revise_run) and the condition that selects it, leaving nothing to inference. This is exactly the when-to-use/when-to-use-something-else guidance the dimension asks for.

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 is consistent with them. It adds a genuinely useful behavioral fact beyond the annotations: the call performs cost estimation with no credit consumption. It does not state whether quote validates the whole request or how accurate the estimate is, which would round it out.

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

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

Two short sentences, zero filler, with the no-cost guarantee and the call-ordering rule front-loaded. 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 an 18-parameter, output-schema-less tool, the schema handles inputs well and the description covers purpose, safety, and ordering. The remaining gap is that with no output schema, the description never says what the estimate response contains (e.g., cost fields), leaving the agent to infer the return shape.

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 94% across 18 parameters, so the schema already carries the parameter burden; baseline 3 applies. The description adds nothing parameter-specific — notably it never states that the quote accepts the same inputs as make_ugc, which is the one parameter-level insight an agent would need.

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 (estimate) and resource (credit cost of a make_ugc call), plus the key differentiator that no credits are spent. An agent can immediately separate this from make_ugc, which it explicitly names.

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 ordering rule: 'Always call this first and show the user the price before make_ugc.' That is unusually actionable. It does not, however, mention the sibling quote tools (quote_faceless, quote_actor), so the agent gets no guidance on which quote variant applies to which creation tool.

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 far beyond the readOnlyHint=false/destructiveHint=false annotations: it documents idempotency (identical request reuses the same run), billing semantics (charged on delivery, nothing on failure), concurrency limits on revisions, expiry of paid edits, and the editing_disabled refusal code. This is unusually rich behavioral disclosure for a write 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?

Front-loads purpose and the quote-first rule, and nearly every clause carries distinct information (billing, idempotency, limits, output). It is nonetheless a dense semicolon-chained paragraph that could be tightened, but no clause 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?

Despite a complex nested schema, no output schema, and four parameters, the description covers cost flow, idempotency, failure/refusal behavior, and the return path (new run polled with get_run, editable under its own run_id). An agent has everything needed 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?

Adds real meaning beyond the 75%-covered schema: it explains the changes vs. document distinction and, critically, the 'pass exactly one' exclusivity rule that the schema does not enforce. However, the nested operation modes (retake, new_picture, edit_picture, animate) and their description/instruction/motion fields are not explained in the description or schema, leaving that 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 revision of a run made by make_faceless') and immediately clarifies the output ('a NEW run that renders the video again'). It distinguishes itself from siblings by naming the originating tool (make_faceless) and the polling tool (get_run), so an agent can place it in the workflow without opening another schema.

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

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

Explicit when-to-use and prerequisites: 'Call quote_revision first and show the user the price', 'pass exactly one' of changes/document, and idempotency handling via attempt 2. It also names an alternative surface (get_run for polling) and a failure mode (editing_disabled), leaving nothing about 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 declare idempotentHint=true and destructiveHint=false, but the description adds substantial behavioral context: it notes the operation is stored only, has no effect on actor-only videos, explains the policy precedence, and clarifies that segmented media generation is closed. This goes well beyond the annotations and is crucial for an agent to predict side effects.

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

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

The description is moderately long but every sentence contributes meaning: the opening states purpose and cost, the middle defines policy semantics, and the end covers scope and precedence. It is logically ordered and front-loaded with the most critical 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 simple set operation with two parameters and no output schema, the description covers all essential aspects: the action, the policy meanings, cost implications, scope (stored only, no effect on actor-only videos), and precedence. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 50%: broll_policy has a full description in the schema, but actor_id has none. The description repeats and slightly elaborates the broll_policy enum values, and it references 'this account actor's' to give actor_id context. However, it does not explicitly define actor_id or its format, leaving half the parameters only implicitly documented.

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

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

The description opens with a clear verb and resource: 'Save this account actor's B-roll default'. It also adds a key differentiator, 'without spending credits', which separates it from potential alternatives. The policy enum is explained in detail, making the tool's purpose unambiguous.

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

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

The description implies usage context through the cost note and precedence rules ('Run override wins...'), but it does not explicitly state when to use this tool versus get_actor_defaults or other siblings. The absence of explicit exclusions is a minor gap, though the credit-saving angle provides practical guidance.

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

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

The description goes well beyond annotations by disclosing the URL's 24-hour expiration, the 20 uploads per day per account quota, the zero credit cost, and the rendering warning when aspect_ratio is omitted. These are non-obvious behaviors an agent needs to handle correctly.

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?

Each sentence carries a distinct, necessary fact: purpose, URL expiration, when to use, aspect_ratio consequence, zero cost, and daily quota. There is no filler, and the flow from action to constraints to caveats is logical and efficient.

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 one simple parameter and no output schema, the description covers everything required for correct invocation: the returned https URL, expiration, daily limit, downstream usage, and a formatting caveat. No significant behavioral information 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 schema already defines `path` as absolute/relative to a PNG or JPEG. The description adds value beyond that by emphasizing 'LOCAL' and introducing the 'up to 10 MB' size cap, which an agent cannot infer from the schema alone.

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

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

The description states a specific verb and resource: 'Upload a LOCAL image file' and the intended outcome, 'get an https url to pass as `image` to quote_ugc / make_ugc.' It clearly distinguishes itself from sibling tools, none of which handle image uploads, and additionally specifies accepted formats (PNG or JPEG) and size (up to 10 MB).

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

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

The description explicitly says when to use it: 'Use this whenever the user points at a file on disk — `image` itself accepts only public https urls.' It also provides workflow context by telling the agent to set `aspect_ratio` after uploading affects rendering, which reinforces when this tool is the required step.

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