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 already declare readOnlyHint true and destructiveHint false. The description adds beyond this by detailing the response states (IN_PROGRESS, SUCCEEDED with video_url, FAILED) and the polling behavior via next_action. It does not mention timeouts or error specifics, but the disclosed behavior is substantial.

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, tightly written with no fluff. The purpose is front-loaded, the polling instruction is actionable, and every word contributes to understanding how to use the tool.

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 status checker with no output schema, the description covers the essential workflow: what to pass, what to expect (IN_PROGRESS vs terminal states), and how to poll. It omits futher details like next_action format or retry limits, but these are non-critical for an agent to use 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 description coverage is 0%, so the description must compensate. It mentions 'Pass the run_id' and implies it originates from make_ugc, but does not elaborate on the format beyond the schema's pattern. This adds minimal but useful context, just enough to infer the parameter's role.

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

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

The description clearly states the verb 'Check the status' and the resource 'video generation started by make_ugc', which precisely identifies the tool's function and ties it to a specific producing tool, distinguishing it from siblings like list_actors or 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?

It explicitly specifies when to use this tool (after make_ugc, to check a run) and provides concrete polling guidance: repeat every ~5 seconds until reaching SUCCEEDED or FAILED. This gives clear context and no ambiguity about usage.

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 mark this as read-only and non-destructive, and the description goes well beyond them. It discloses voice ordering, refusal of unknown filter values, default voice selection based on actor gender, preview URL expiry (never store it), pricing ('Free'), and per-model script character 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?

The description is long but densely packed with non-redundant information, and the most important details are front-loaded. Every major section (filtering, selection, defaults, previews, limits) earns its place, though a slightly tighter structure would improve readability.

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 tool with no output schema and five optional parameters, the description is remarkably complete: it covers output ordering, default behavior, preview URL semantics and expiry, pricing, script limits, and character counting rules. An agent has enough context to call the tool and correctly interpret its results.

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

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

Schema coverage is 100%, so the baseline is 3. The description mostly restates what the schema already documents, such as language being a filter rather than a limit and unknown values being refused; it adds little new semantic information about the five parameters themselves.

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 the voices for make_ugc's `voice` field' and immediately distinguishes the tool's scope from siblings like list_actors. It adds meaningful structure (presets first, then catalog voices in 31 languages) rather than merely restating the title.

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

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

The description gives explicit operational guidance: how to filter, how to pick a voice by name, when to use voice_id as an escape hatch, what happens without voice/voice_id, and when to play preview_url before a paid render. It even tells the agent when to ask the user for actor_gender instead of guessing, which is highly actionable.

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 clearly discloses that the tool is asynchronous: it starts the run and returns a run_id immediately without waiting for the video. It also explains that failed runs may later requeue and succeed, that retries should use attempt=2,3,..., and that certain parameters are not honored yet. This goes far beyond the minimal readOnlyHint/destructiveHint annotations and gives the agent an accurate mental model of the tool's behavior.

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?

Though the description is long, the tool is genuinely complex with 20 parameters and asynchronous behavior. The most important facts are front-loaded: what it creates, how the actor is chosen, the default resolution, and the immediate-return behavior. Every sentence adds operational value, including the warning about NOT HONORED YET fields and the retry semantics.

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 tool's complexity, absent output schema, and sparse annotations, the description is remarkably complete. It covers quoting, polling, retries, warnings, unsupported fields, default behaviors, error conditions that avoid charges, and when to use upload_image. An agent has everything needed to invoke make_ugc correctly and follow up on the run.

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 already covers 85% of parameters in detail, so the baseline is 3. The description adds meaningful cross-parameter guidance: script limits depend on the speech model, actor comes from actor_id/image or defaults, format and resolution default to 1080x1920, captions are opt-in, and attempt starts a new run. This supplements the schema rather than repeating it, which justifies a score above baseline.

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

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

The description opens with a specific verb and resource: 'Start generation of a lip-synced UGC video.' It clearly names the actor inputs (actor_id, image, or default actor) and distinguishes the tool's role from siblings like quote_ugc and get_run. An agent can immediately understand what make_ugc does and how it differs from related tools.

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

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

The description gives explicit operational guidance: call quote_ugc first and show the cost, poll get_run with the returned run_id until succeeded or failed, and use upload_image for files on disk. It also tells agents that captions are opt-in and to ask the user first, and to read NOT HONORED YET field descriptions rather than guessing. This is exceptional when-to-use and how-to-sequence 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, 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?

The description adds a key behavioral detail beyond the annotations: the call does not spend credits. This is a specific guarantee about side effects (cost). However, it doesn't describe the response format or any validation behavior, though annotations already cover the read-only, non-destructive nature.

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

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

Two short sentences, front-loaded with the core purpose and followed by an actionable usage instruction. Every word earns its place.

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

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

For a quote-only tool, the description is complete: it names the action, the cost side-effect, and the required workflow step. The extensive input schema handles parameter documentation, and the output (price) is implied by the tool's purpose.

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 description itself contains no parameter-specific information. With 89% schema description coverage, the baseline is 3; the schema already documents all parameters in detail, so the description needn't add more.

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 explicitly states the tool's function with a specific verb ('Estimate') and resource ('credit cost of a make_ugc call'), and distinguishes it from the actual generation call by emphasizing 'WITHOUT spending credits.' This clearly separates it from make_ugc and other 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 an explicit directive: 'Always call this first and show the user the price before make_ugc.' This tells the agent exactly when to invoke it relative to make_ugc and what to do with the result, leaving no ambiguity.

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.