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

Annotations declare readOnlyHint=false, idempotentHint=true and destructiveHint=false; the description goes far beyond that with credit cost, hold-and-charge-on-success semantics, hourly rate limit, one-hour cache reuse, ~20s latency, and get_creator_profile fallback. Null-vs-zero handling and the untrusted_content warning add real behavioral context. Minor deduction only because the relationship between idempotentHint=true and the 'held at the start' charge isn't fully reconciled.

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?

Despite being dense, it is front-loaded with the payload then moves to input formats, cost/latency, and response fields. The main waste is the credit price stated twice ('20 credits, held at the start' and 'Price: 20 credits per call'), which is redundant padding in an otherwise tight paragraph.

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

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

With no output schema, the description must explain returns and does: per-video metrics, median and x_median, top flags, author fields, cadence, display_markdown/display_hint, and untrusted_content. Cost, timing, polling, caching, and failure-cost behavior are all covered, so an agent can call this correctly without further information.

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 single parameter has 0% schema description coverage, so the description carries the full burden and does so: it enumerates instagram.com/<handle>, /reel/<code>, /p/<code>, tiktok.com/@<handle>, /video/<id>, and vm.tiktok.com/<code>, plus the negative case (YouTube refused). The schema's pattern/maxLength constraints are complemented with the semantics an agent actually needs.

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 ('Profile a creator from a link') and immediately enumerates the return payload (12 videos, views/likes/comments/shares, median views, x_median flagging, author fields, cadence). This distinguishes it from siblings like quote_creator_profile (pricing) and get_creator_profile (polling).

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

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

Explicitly states accepted URL shapes per platform, that a video link profiles its author, that YouTube is refused, that quote_creator_profile should be used first for a price quote, and that get_creator_profile with wait_seconds is the polling path. It also names the cache window where a repeat call is free, which is genuine routing guidance.

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

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

Annotations only give readOnlyHint=false, idempotentHint=true and destructiveHint=false; the description adds the credit hold-and-charge model (70 full / 10 data, charged once it succeeds, failed analysis free), per-account rate limits, async queue state with retry_after_seconds, and idempotency exceptions ('a short vm.tiktok.com link always starts a new one'). It also discloses that the asset is not changed and that the profile copies no face, voice, music or brand, which is behavior beyond any structured field.

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

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

The content is dense but poorly structured: it opens with an input cross-reference ('the same fields as quote_analysis') rather than the tool's purpose, and mixes output contents, URL formats, pricing, polling and idempotency into one block. There is also duplication — the 70/10 credit price is stated twice and the 'quote first' instruction appears at both beginning and end.

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

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

For a complex, multi-mode, asynchronous tool with no output schema and three undocumented parameters, the description covers inputs, the shape of both answers, the polling loop, pricing, rate limits, idempotency, failure handling and redo semantics. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 0% and the schema gives no enums or descriptions, so the description carries the full burden — and does: asset_id must be an MP4 from create_asset with kind: "video", at most 120 s and 100 MiB; source_url is restricted to Instagram reel/post and TikTok video URL shapes; mode: "data" versus full is spelled out. This compensates completely for the empty schema.

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

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

States a specific verb and resource: 'Read a reference ad into a reference_profile', then enumerates exactly what that profile contains (beats, graphics, captions, palette, music, transcript). The 'data' mode is clearly distinguished as a lighter variant that 'skips beats and graphics and answers data instead of a profile', so an agent can tell the two outputs apart 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?

Explicitly says 'Quote first with quote_analysis', names get_reference_analysis with wait_seconds: 50 as the follow-up, and tells the agent what to do with an unsupported YouTube link ('upload its MP4 with create_asset'). It also sets the when-to-use boundary between full mode and data mode ('a reel with no speech gives an empty transcript and a warning'), leaving little 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description adds real behavioral facts: the call is free, it stores approval state but starts no run, and it is distinct from quoting and launching. It omits whether re-approval overwrites prior approval, whether the digest must match current content, and any permission requirements.

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

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

Four short sentences, front-loaded with the action, then cost, then prerequisite, then the disambiguation. No sentence is redundant.

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

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

For a three-parameter mutation with no schema descriptions and no output schema, the definition covers intent, cost, and side effects but leaves gaps: where the digest comes from, what happens on a mismatch, and what the response contains. Adequate but not complete.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it only restates 'plan revision and content_digest' by name. It never explains that content_digest pins the exact approved content, how to obtain the digest, or what plan_id refers to, leaving all three required parameters semantically thin.

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 ('Explicitly approve the chosen plan revision and content_digest') and distinguishes that action from the neighboring concepts of quoting and running: 'Approval is separate from a quote and a paid launch.' An agent can tell this apart from quote_workflow_plan and run_workflow_plan without opening any schema.

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

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

It gives a clear precondition ('Read all issues and warnings first') and positions the call before a paid launch. It does not name sibling tools such as get_workflow_plan or run_workflow_plan explicitly, nor does it state when not to approve, so it is strong but not exhaustive.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries most of the load and does so well: async run_id with polling contract, credit charging per published image, free refusals and unusable portraits, the actor_generation_disabled error, and face-match verification for from_actor_id. The main gap is that it never states what happens to an existing actor with the same name or whether a failed run leaves partial state.

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

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

The content is valuable but the writing is a dense wall of run-on sentences mixing usage, errors, derivation semantics, and a full price table. Front-loading is decent (the create-and-return-run_id contract comes first), yet the enumerated per-format pricing largely duplicates what list_prices and quote_actor provide and hurts scannability.

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 explains the return contract (run_id, then created_actor.actor_id on the get_run result) and covers cost, failure, and derivation behavior. Missing pieces are the semantics of the plain descriptive fields (name, gender, approximate_age) and whether billing occurs only on success, which an agent creating an actor would benefit from knowing.

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 0% across 11 parameters, so the description must compensate and does so only partially: it clarifies from_actor_id, holding (image asset with rights_confirmed), framing ('wide'), quality tiers via the price table, and the 9:16 default for aspect_ratios. Name, gender, description, approximate_age, attempt, and setting values remain unexplained, leaving several parameters ambiguous.

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 ('Create a personal actor for this account') and immediately scopes it with concrete constraints: a 9:16 portrait with exactly one face plus derived formats. It also distinguishes itself from siblings by naming quote_actor (for pricing) and make_ugc (consumer of the resulting actor_id), and explains the from_actor_id variant.

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 workflow routing: quote first with quote_actor, poll get_run until succeeded, then pass created_actor.actor_id to make_ugc. It also names the failure mode when generation is disabled. It stops short of saying when to prefer this over make_faceless or how it relates to list_actors/get_actor_defaults, so it is clear but not fully exclusionary.

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 supply readOnlyHint=false and destructiveHint=false; the description adds far more: async verification for url/PUT sources yielding state "processing"/"awaiting_upload", a 15-minute PUT window with an explicit curl invocation, MP4 h264/hevc limits of 120s and 100MB, base64 cap of 700000 bytes, the fact that assets are free, and hard quotas (2000 assets / 1 GB, 20 GB with credits, 100 creations per day). This is exactly the behavioral context annotations 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?

Purpose is front-loaded and nearly every sentence carries operational information, but the definition is a single ~250-word paragraph with no breaks, and the trailing quota/cost sentence is secondary to the call mechanics. Slightly denser than it needs to be, though the density is largely earned by six source shapes.

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 non-read-only creation tool with no output schema, the description still tells the agent what comes back (upload.put_url, put_headers, state: "processing"/"awaiting_upload"), what to do next (PUT then get_asset), and what limits apply. Nothing needed to call it correctly or interpret the response 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 only 20%, so the description must compensate, and it does: all six source variants (run_id, upload_id, url with optional kind:"video" for MP4, {base64, media_type}, {put:{media_type,bytes,sha256}}, {path} on a local server) are explained with formats and limits, plus the meaning of role, name, rights_confirmed and analysis_only. Almost nothing about a parameter's semantics is left to inference.

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

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

States a specific verb+resource ("Save a picture or a clip as an asset of this account"), enumerates the roles (character, location, style, prop, other) and immediately distinguishes itself from neighbors like delete_asset by noting assets are "kept until you delete it". An agent can tell exactly what this creates versus get_asset/list_assets.

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 routes between modes: rights_confirmed:true "for your own material", analysis_only:true for "a reference you only want analysed, such as someone else's ad for analyze_reference", and points to upload_image/create_upload for obtaining an upload_id and to get_asset for checking background processing. Downstream usage (asset_id in references/first_frame/last_frame of quote_image, generate_image, quote_video, generate_video) is spelled out with the caveat that clips are not yet a generation reference.

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

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

Beyond the annotations, it discloses the full consequence model: a delivered candidate is charged its unit whether kept or discarded, failures are free, identical requests are idempotent, per-original concurrency and failure limits apply, and closed editing yields editing_disabled with no charge. It also explains post-call behavior: use the run's poll.arguments with get_run, then inspect candidate.preview_url.

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 definition, then grouped into pricing, idempotency, limits, and return handling. It is long and packs several ideas per sentence (the run-handoff and preview sentence in particular), but nearly every sentence carries distinct operational value such as cost, idempotency, or limits.

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 paid, stateful generation tool with no output schema, the definition covers cost, refusal modes, idempotency, and the follow-up call needed to retrieve the result. The only material omission is what the required `operation` object should contain, forcing a cross-tool lookup.

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 0%, so the description must compensate. It does explain `take` thoroughly and implies run_id/shot_id via 'of a run made by make_faceless' and 'for one shot,' but delegates the required nested `operation` object entirely to another tool with 'the same fields as quote_candidate.' An agent must open a sibling's schema to know what to pass, which is a real gap for the most complex required parameter.

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 names a specific verb and resource ('Make a shot candidate of a run made by make_faceless') and immediately defines the underlying operation: 'a NEW run of skill edit_shot that generates one picture or clip for one shot.' It clearly separates this from siblings like quote_candidate (pricing preview) and revise_run (later revision).

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 prerequisite: 'Call quote_candidate first and show the user the price.' It also covers edge cases that would otherwise confuse an agent: repeat calls are idempotent, 'pass take 2' to force a duplicate, and a refusal or editing_disabled is returned when shot candidates are closed. Alternatives and their selection conditions are both named.

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=false and destructiveHint=false, so the description's main added value is the operational envelope: one-time PUT URL, 15-minute window, 24-hour upload_id lifetime, free, 20 uploads per day cap, and the upload_not_finished error state. That is genuinely useful context beyond the annotations. However, it never says what the call itself returns (upload_id, put_url are only implied by usage), leaving the response shape and the consequences of a failed or expired PUT unstated. A 3 reflects solid added context over an already-covered safety profile.

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

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

Front-loaded with the action and the selection condition, then the required inputs, then the exact curl invocation, then downstream integration and limits. It is dense and runs as a single long paragraph with heavy parentheticals, which slightly hurts scanability, but essentially every clause carries operational information an agent needs.

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

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

For a multi-step, time-boxed upload handshake this covers the full lifecycle: required declarations, the exact PUT command and header-matching requirement, the 15-minute and 24-hour deadlines, the required get_upload confirmation step, and the rate cap. No output schema exists, yet the description still names the ingredients the caller will need downstream (put_url, upload_id, content_digest, width, height).

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

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

With only 50% schema coverage, the description compensates well: it explains that bytes must be the exact size, that sha256 must be supplied and even gives the shell commands to produce it, and that media_type must match the content-type header sent with the PUT. The fourth parameter, filename, is never mentioned in either the description or the schema, which keeps this below 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 specific verb and resource (upload a LOCAL PNG/JPEG) plus the exact mechanism (one-time presigned PUT, 10 MB cap), which distinguishes it from sibling paths like upload_image and create_asset. The parenthetical scoping condition ('remote server and you have a shell') further pins down what this tool is for.

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

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

Gives an explicit when-to-use condition ('use it when this server is remote and you have a shell') and sequences the follow-up actions: run the PUT within 15 minutes, then call get_upload before any tool that consumes an upload_id, and use the id within 24 hours. It also names the failure mode (upload_not_finished) that tells the agent the prerequisite step was skipped.

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

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

Goes well beyond the destructive=true annotation by disclosing what survives (existing videos), what breaks (new runs cannot use it), and an in-flight-run refusal condition. This is exactly the pre-call context an agent needs before a destructive operation.

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

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

Four short sentences, front-loaded with the action and id, then side effects, then the refusal rule, then the catalog exclusion. No wasted wording.

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 reversibility implications and blocking conditions well. It stops short of stating permission requirements or the response payload, but nothing essential for a correct call 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% and the property already points callers at list_actors; the description restates 'by actor_id' without adding format or lookup detail. Baseline 3 since the schema does the work.

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

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

States a specific verb and resource ('Delete a personal actor of this account by actor_id') and immediately scopes it against catalog actors, which siblings like create_actor and list_actors do not overlap with. An agent can tell exactly what this removes.

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 conditions: not usable for catalog actors, refused while an unfinished run references the actor. It doesn't name a sibling alternative (e.g., where to manage catalog actors or how to inspect runs), but the inclusion/exclusion context is strong.

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 destructive=true; the description goes well beyond by disclosing that the asset leaves the list immediately, that new generations can no longer reference it, that the underlying file is purged by a daily job after 7 days, and that existing runs are unaffected. The cost signal ("Free") is an extra operational detail not present in any structured field.

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

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

Four short, front-loaded clauses covering action, immediacy, delayed file purge, and side-effect scope, with the cost note last. Nothing is redundant and the most decision-relevant fact (it disappears from the list at once) comes early.

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 destructive mutation with no output schema, the description covers consequences, timing, and blast radius well. The only gaps are reversibility (no undo mentioned) and whether any permission or confirmation is required before an irreversible delete.

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% and the only property is asset_id, but the description does no more than name it — the ast_ pattern and type live entirely in the schema. For a single obviously-named identifier this is adequate, though it adds no meaning (e.g. where to obtain an asset_id) beyond the structured field.

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 pair ("Delete an asset") and immediately names the identifier used (asset_id), so an agent can distinguish it from update_asset or delete_actor without consulting the schema. The rest of the description reinforces scope by describing what is and is not destroyed.

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

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

Usage is implied by the destructive semantics and the "runs made with it stay as they are" note, which helps an agent decide deletion is safe with respect to history. However, there is no explicit when-to-use/when-not-to-use guidance, no mention of prerequisites or permissions, and no pointer to a sibling (e.g. update_asset for reversible changes) despite ~40 sibling tools.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description goes well beyond them by disclosing billing (charged per delivered image, failures charged nothing), idempotency (an identical request returns the pre-existing run rather than starting a new one), and per-model pricing. These are exactly the behavioral facts an agent needs before spending user credits.

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

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

Dense and front-loaded — scope, cost, then the follow-up flow — with almost no filler. It loses a point for redundancy: the quote-first instruction appears twice ('Call quote_image first and show the user the price' and 'Quote first with quote_image; list_prices names every price'), and the price list crowds the middle of the paragraph.

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

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

With no output schema, the description still tells the agent how to retrieve results (get_run with poll.arguments) and what to read (generation.url, run_id as a reusable reference), plus the failure and duplicate-call cases. Nothing essential for a correct paid invocation 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%, so the description carries the burden. It explains 'attempt' thoroughly and reveals valid model values through the price list (seedream-5.0-flash, flare), but 'prompt', 'aspect_ratio' and 'references' are never described, and 'the same fields as quote_image' forces an indirect lookup in a sibling tool rather than stating the semantics directly.

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

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

States a specific verb and resource ('Generate one image from a prompt (paid): a NEW run of skill generate_image') and scopes it against siblings by contrasting with quote_image (pricing only) and by noting the output feeds get_run. An agent can distinguish it from quote_image, generate_video and quote_video without opening any schema.

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

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

Explicit sequencing is given: 'Call quote_image first and show the user the price', then 'Call get_run with its poll.arguments'. It also names the retry path (pass attempt 2 for an intentional duplicate) and the failure semantics, so both when-to-use and how-to-recover are covered.

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 and destructiveHint=false; the description goes well beyond by disclosing cost (charged unit_credits per second of duration_s once delivered), that failed generations are free, and the idempotency behavior that an identical request returns the prior run. That idempotency detail is critical and cannot be inferred from any structured field.

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

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

Dense but front-loaded, opening with the input contract and the core action before modes, cost, polling and idempotency. Some pricing sentences repeat the same number set twice ("charged unit_credits..." and "Price: 3 to 90 credits per second"), which is mild redundancy rather than bloat.

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 paid, mutating, 11-parameter generation tool with no output schema and faint annotations, it covers cost model, failure billing, polling path, result location (generation.url) and idempotency. The only residual gap is that model/resolution enumerations live in sibling tools, which the description points to.

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 0% across 11 parameters, so the description does real work: it explains attempt as the duplicate-suppression bypass, defines mode variants and their required companions (first_frame with optional last_frame, 1 to 4 references), and dimensions duration_s into the price model. It leaves model, resolution, camera and prompt semantics only indirectly implied via list_prices and list_generation_models, so a gap remains.

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

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

States a specific verb and resource ("Generate one silent clip") and immediately clarifies it is a paid, NEW run of skill generate_video, which distinguishes it from the sibling quote_video. It also enumerates the three generation modes (text, first_frame, reference), so an agent knows precisely what the tool produces.

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 instructs calling quote_video first and showing the user the price, then get_run with poll.arguments, and names list_prices for the full price list. It also gives an explicit retry rule: pass attempt 2 to intentionally repeat an identical request. This is when-to-use, prerequisites and alternatives all in one place.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description still adds "Free, spends nothing," confirming no credit consumption. It also discloses downstream behavior (make_ugc refused while debt_outstanding, holds settling when runs finish) that annotations cannot express. It stops short of describing freshness or whether credits update in real time, a minor gap.

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

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

Front-loaded with the core purpose, then layered by importance: blocking condition first, spendable balance second, secondary lists last. The semicolon-chained sentences are dense but each clause carries distinct information. Slight cost in readability from packing many field explanations into one paragraph.

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

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

With no output schema, the description must explain return values — and it does so field by field, including cross-tool linkage (request_id is the feedback_id from send_feedback). For a read-only, parameterless tool whose complexity lies entirely in interpreting its response, 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 takes no parameters, so the baseline is 4 and there is nothing to mis-specify. The description instead spends its space on return-field semantics (debt_credits, balance_credits, holds_credits, grants, support_replies, request_id), which is the right use of a zero-parameter definition.

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 ("Read this account's credits") and immediately clarifies the distinction from the nearest sibling: "quote_ugc already warns when make_ugc would be refused; this tool gives the numbers behind it." An agent can separate this read-only balance tool from quote_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?

Explicitly routes between this tool and quote_ugc, naming the alternative and the condition that selects it (quote_ugc for the warning, get_account for the underlying numbers). It also states the practical consequence of the returned values — debt_credits above zero blocks make_ugc — so the agent knows what to do with the result.

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?

Consistent with readOnlyHint=true and destructiveHint=false, and it adds genuinely useful context beyond annotations: the setting is stored-only and never affects actor-only videos, and run-level overrides take precedence over the account actor default. It does not cover auth/scope requirements or what happens when no default is saved.

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

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

Front-loaded with the purpose and generally economical, but the policy enumeration ('anyone/no_actor/no_people including hands') and the isolated 'Segmented media generation is closed.' sentence are dense and partly unclear rather than efficiently informative.

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 no output schema, the description covers value semantics and fallback precedence ('override wins; otherwise no_people'), which is close to complete. It still leaves open the behavior when the actor has no saved default.

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 0% and the description never mentions actor_id, so the single required parameter is documented only by its self-explanatory name. With just one obvious identifier this gap is minor, but the description adds no meaning beyond the schema.

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

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

States a specific verb and resource: 'Read this account actor's saved B-roll default.' That is clearly distinct from the sibling set_actor_defaults, though the description never names that sibling to make the read/write split explicit.

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

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

Explains how to interpret the stored value but gives no guidance on when to call this versus set_actor_defaults or get_run/get_run_shots, and states no preconditions or exclusions.

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

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

Goes well beyond the readOnly/non-destructive annotations: discloses that the signed URL expires in an hour, enumerates the terminal and intermediate states (awaiting_upload, processing, failed, asset_not_found), and notes the call is free. The state machine and error semantics are exactly the behavioral context an agent needs before deciding to poll.

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

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

One dense, front-loaded paragraph where each clause supplies actionable facts (returned fields, states, error codes, cost). The field enumeration makes the first sentence long, but nothing is truly 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?

With no output schema, the description must describe returns, and it does so thoroughly, including clip-specific fields and state-dependent response shapes. For a one-parameter read tool this leaves nothing an agent needs 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 0% and the single parameter has no inline description, so the description carries the burden. It identifies asset_id as the lookup key but adds no format detail (the ast_ + 32 hex pattern exists only in the schema) or guidance on where an asset_id comes from.

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 ('Read one asset by asset_id') and enumerates the returned fields (role, name, media_type, bytes, width, height, content_digest, plus clip metadata). This clearly separates it from list_assets and the mutating siblings update_asset/delete_asset.

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

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

Gives concrete operational guidance for in-progress assets: on awaiting_upload, PUT the file then read again; on processing, read again in a few seconds; on failed, inspect error.code. It does not explicitly route to siblings (e.g. create_asset to obtain an asset_id, or get_upload for an upload session), leaving some 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?

Beyond the readOnlyHint and destructiveHint annotations, the description discloses status-dependent return behavior, failure codes (timed_out, profile_unavailable, source_failed, enqueue_failed), retry_after_seconds for unfinished answers, display_markdown handling, untrusted_content fields, and credits_charged behavior. This gives the agent substantial operational context for a read-only polling 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?

The description is dense but front-loaded with the core purpose and lifecycle states. Every clause adds useful information about waiting, failure modes, display output, untrusted fields, or credits, with no filler.

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

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

With no output schema, the description carries the burden of explaining return states and important response fields. It covers queued/analyzing, succeeded, failed, retry_after_seconds, display_markdown, untrusted_content, and credits_charged, which is complete for an agent to call and interpret this polling tool.

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

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

Schema description coverage is 50%, so the description must carry extra meaning for the remaining parameter. It explains wait_seconds well, including the 50-second cap, hold behavior, and retry_after_seconds follow-up, and it implies profile_id comes from analyze_creator. It does not restate the profile_id pattern, but the added semantics are still meaningful.

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 uses a specific verb and resource: 'Read a profile started by analyze_creator.' It also enumerates the possible lifecycle states (queued, analyzing, succeeded, failed), which clearly distinguishes this retrieval tool from the sibling analyze_creator tool that starts the profile.

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

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

The description clearly situates the tool after analyze_creator and explains that wait_seconds can hold the answer until the profile finishes or the wait ends. It does not explicitly name when not to use it or mention alternatives such as quote_creator_profile, but the lifecycle context is strong enough for correct tool selection.

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

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

Annotations only declare a safe read, and the description goes far beyond them: it lists error codes returned (timed_out, analysis_failed, asset_gone, enqueue_failed), the 24-hour link expiry, credit accounting (charged on success, 0 on failure, free overall), and explicitly flags untrusted_content as data rather than instructions. That is exactly the behavioral context annotations 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 content is front-loaded and nearly every clause earns its place, but it is delivered as one long semicolon-chained sentence that is harder to scan than a short state list followed by paging, media, and safety notes. Dense rather than bloated.

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 full burden of explaining return values and does so thoroughly – states, payload shapes per mode, frames/sheets/scenes/video, display_markdown, untrusted_content, credits. Minor gaps remain: it does not describe 'source' payload shape in detail or how frames relate to sheets, but an agent can call and interpret results 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?

At 80% schema coverage the baseline would be 3, but the description adds real meaning per parameter: wait_seconds holds the answer until finish and yields retry_after_seconds otherwise, frames_from/frames_to define a one-a-second page capped at 60 frames with page.next for paging, and frames_as 'images' returns up to 8 key frames hook-first. These are behaviors the schema's terse field descriptions do not convey.

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, 'Read an analysis started by analyze_reference', which immediately separates it from the sibling that starts analyses. The rest of the first clause enumerates the concrete terminal states (queued/analyzing, succeeded, failed) so an agent knows exactly what this call resolves to.

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?

Establishes the create/read pairing with analyze_reference and explains that wait_seconds blocks until completion or the wait expires, with retry_after_seconds for the unfinished case – effectively a polling protocol. It stops short of stating when NOT to call (e.g. after a terminal state, or that repeat_note signals the cost of re-asking), so it is clear context without explicit exclusions.

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

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

Annotations only declare readOnly/non-destructive; the description adds substantial behavior beyond that — the long-polling hold via wait_seconds, the IN_PROGRESS/poll.arguments retry contract, terminal states SUCCEEDED and FAILED, and where the artifact lands (video_url, or generation.url for image/video runs) plus display_markdown. For a tool with no output schema, this is the disclosure that matters most.

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

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

Front-loads the purpose, then the call contract, then the return states — a sensible order. It is somewhat dense in a single run-on sentence with parentheticals, but essentially every clause carries information an agent needs.

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

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

Despite no output schema, the description covers return shape (status values, artifact fields, display_markdown) and the retry protocol, which is what an agent needs to drive a polling loop correctly. Nothing material is missing for a two-parameter status tool.

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

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

Schema coverage is 50%: wait_seconds is already documented in the schema, and the description largely restates it ('wait_seconds to hold the answer until the run ends'). run_id is only constrained by a pattern in the schema and gets no format or provenance explanation in the description. Adequate, but not meaningfully additive over the schema.

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

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

States a specific verb+resource ('Check the status of a video generation') and enumerates exactly which upstream tools produce runs it can poll (make_ugc, make_faceless, generate_image, generate_video). This distinguishes it clearly from other run-related siblings like get_run_shots or revise_run.

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

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

Gives concrete usage context: call it after starting a generation, pass run_id, and re-call with poll.arguments while status is IN_PROGRESS until a terminal state. It does not explicitly exclude or compare against alternatives (e.g., get_run_shots), but the polling loop guidance is unambiguous.

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

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

Adds substantial context beyond readOnlyHint: free to call, signed preview_url links are large and expire so must be re-fetched rather than stored, fields named in `withheld` are nulled, and editable/paid_edits/media_available_until gate downstream actions. That is exactly the behavioral surface an agent needs before deciding what it can do next.

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 read-only status are front-loaded, and nearly every sentence carries a distinct fact. It is dense and long-winded in places, but the length is justified by return-value detail that no output schema supplies.

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 takes on the full burden and delivers: frame size, frame rate, narration words with timing, per-shot id, span, kind, words, description, preview_url, plus withheld fields and editability flags. Nothing an agent needs to interpret the response 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?

Only 'Pass the run_id' is said about the sole schema parameter, and the run_ prefix pattern lives only in the schema. Worse, the description switches to a `planned=true`/`planned=false` framing that has no counterpart in the input schema, forcing the agent to work out whether that is a parameter or a response shape.

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 ('Read the shots of a video') and anchors it to the producing siblings ('made by make_faceless or make_ugc'), which cleanly separates it from get_run and the quote/make 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?

Says to pass the run_id and explains the planned=true vs planned=false branches, including that planned=false is a normal answer rather than an error. It doesn't explicitly name get_run as the alternative for run-level status, so routing guidance is implied rather than stated.

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

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

Annotations only declare this a safe read; the description goes much further, disclosing that the URL is freshly signed (hence per-call), the terminal failure states and their trigger conditions, the 24-hour expiry window, and that the call is free. Those are exactly the operational facts an agent needs beyond readOnlyHint/destructiveHint.

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 what is read and what comes back, then the polling caveat. Dense but readable; the field list is long, though every field earns its place since there is no output schema.

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

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

With no output schema, the description must enumerate return values and it does, including usable_until, plus the error states and cost. For a single-parameter read tool, an agent has everything needed to call it and interpret the response in a polling loop.

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 sole parameter carries no inline explanation. The description names upload_id and ties it to a single-record read, but adds no format or origin guidance; the ^upl_[a-f0-9]{32}$ pattern is only machine-readable in the schema, so a baseline 3 is right.

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 ("Read one upload by upload_id") and immediately enumerates the returned fields (signed url, content_digest, media_type, bytes, width, height, usable_until). That detail separates it cleanly from create_upload and upload_image in the sibling list without the agent needing to open a schema.

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

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

Gives an explicit use case: call it after create_upload to confirm the PUT landed. The polling semantics (upload_not_finished until the file exists, upload_expired after 24 hours) tell the agent when to call again and when to stop. It does not name a competing sibling or say when not to use it, which keeps this just below a 5.

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

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

Annotations already cover readOnlyHint/destructiveHint, yet the description adds non-redundant context: the call is free (cost behavior) and reports "current availability," warning that the underlying method state can vary. Aside from a redundant "read-only" restatement, it discloses meaningful behavior 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?

Two compact sentences with the scope front-loaded and no filler. Minor friction: "capability digests" appears in the usage sentence but not in the enumerated return list, so the reader has to infer it is part of the payload.

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 no output schema, the description usefully sketches the return payload, which is the right use of the space. The gap is upstream: an agent is told to supply method_id but not how to discover a valid one, which matters given the many sibling list_* tools.

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 single method_id parameter has 0% schema description coverage, so the description must carry the semantics and largely does not: it never says what a method_id is, where to obtain one (presumably from list_workflows), or that it is a bounded-length string. Naming the parameter is not the same as explaining 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 ("Read one workflow method by method_id") and enumerates the returned facets: required inputs, script rules, evidence, limitations, availability. It is clearly distinguishable from list_workflows and get_workflow_plan by the singular 'one ... by method_id' scope, though no sibling is named explicitly.

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

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

The closing sentence gives forward guidance ("Use the returned method and capability digests in a plan"), which orients usage, but there is no explicit when-not guidance and no named alternative such as list_workflows for discovery or get_workflow_plan for plan retrieval. Usage is implied rather than routed.

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 annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds useful context beyond that: account-owned scope, free cost, readiness issues and warnings, and a caveat that the document is intent rather than a delivered video or creative acceptance.

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 two tight sentences, front-loaded with what is read and what is returned. Every sentence adds value, including the semantic caveat about intent versus delivered output.

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 does a good job enumerating the returned fields and clarifying the document's meaning. The main gap is that it does not explain the required plan_id parameter, which keeps it from being fully complete.

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

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

There is one parameter, plan_id, with 0% schema description coverage, and the description never explains what plan_id represents, how to obtain it, or how it should be formatted beyond the schema pattern. The phrase 'account-owned plan' gives only weak implicit context.

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 uses a specific verb and resource: reading the current account-owned workflow plan, including revision, content digest, readiness issues, and warnings. It is clear what the tool returns, but it does not explicitly distinguish this from siblings like get_workflow, list_workflows, or prepare_workflow_plan.

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 this is the retrieval tool for an existing workflow plan and notes that it is free and read-only. However, it gives no explicit guidance on when to use this versus get_workflow or list_workflows, and no when-not-to-use conditions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds non-obvious behavior the annotations cannot: preview URLs expire while actor IDs stay reusable, and actors without a voice fall back to a gender-based default voice.

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 tight sentences, front-loaded with what is listed. The closing note about default voices is tangentially about actors rather than listing them, but it is short and materially useful for downstream calls.

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 zero-parameter, read-only listing tool with no output schema, the description covers what comes back, ID reusability, and the key composition rule with image/person inputs. Only the exact response shape and ordering are unspecified, which is minor here.

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

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

The tool takes zero parameters, so the schema baseline is 4. The reference to actor_id, image, person, and actor_gender is about sibling tools rather than this tool's inputs, which is useful but does not deepen this tool's own (empty) parameter surface.

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

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

Specific verb+resource (list saved Clipwright actors) plus the exact fields returned: stable IDs, gender, age, verified image formats. This clearly separates it from create_actor, delete_actor, and get_actor_defaults in the sibling set.

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

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

Explicitly routes the agent downstream: use actor_id for quote_ugc and make_ugc, and never combine actor_id with image, person, or actor_gender. It stops short of stating when to prefer create_actor or get_actor_defaults instead, so there is no full alternative-selection 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 destructiveHint=false, so safety is covered; the description goes further by disclosing that URLs are 'freshly signed' (short-lived, fetch-time sensitive), results are newest-first, and that quota ceilings exist (2000 assets, 1 GB or 20 GB with credits) and the call is 'Free'. Those are genuinely useful facts not present in the structured fields. The 'pending'/'usage' sentences, however, describe behavior with no corresponding parameter, leaving the agent unsure whether such views are reachable here.

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

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

The primary sentence is front-loaded and dense with useful detail via semicolons, which works. The two following sentences about 'pending' and 'usage' consume roughly a third of the text but map to no parameter in the schema, so they cost tokens without helping the agent act. A tighter version would drop them or fold them into a real filter 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 usefully enumerates returned fields (url, role, name, size, content_digest) and the ordering guarantee, which is exactly the compensation needed. Pagination, filters, and quota context are present. The gaps are the undocumented limit parameter and the dangling pending/usage references that suggest capabilities the schema does not expose.

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 only 25% (only cursor is documented), so the description must compensate and it partially does: it names role and kind as filters and explains cursor should be the 'next_cursor' of the previous page, reinforcing the schema's own wording. It says nothing about limit — no default, no mention that it is capped at 100 — leaving one of four parameters with meaning only from its JSON-Schema bounds. Enums make role and kind values self-evident, so the added value is modest.

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 opening clause gives a specific verb and resource plus ordering and return fields: 'List the assets of this account, newest first, each with a freshly signed url, its role, name, size and content_digest.' That clearly separates it from get_asset (single asset) and list_actors (different resource). The trailing 'pending lists...' and 'usage says...' sentences describe behaviors no parameter in the schema exposes, which muddies rather than sharpens the purpose.

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

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

It gives concrete usage mechanics — 'filter by role and kind' and 'pass next_cursor as cursor for the next page' — which tell the agent how to drive the tool. It never states when to prefer this over get_asset for a single item, nor when a caller should stop paginating or how to combine filters. The unexplained 'pending' and 'usage' clauses add implied modes the agent cannot actually invoke.

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

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

Beyond the readOnly/non-destructive annotations it discloses cost ('Free'), the failure mode for unmeasured combinations (unsupported_combination refused before any charge), and the unit of cost ('unit_credits: credits per image, or per second of a clip'). That is exactly the behavioral context an agent needs to reason about pricing and error handling.

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

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

Three tight sentences: what it returns, the validity constraint, and the cost. The returned-field enumeration is dense but front-loaded and every clause carries information the agent would otherwise have to guess.

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

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

With no output schema, the description carries the burden of describing returns and does so explicitly (modes, aspect ratios, resolutions, durations, output width/height, unit_credits). Combined with the free-cost and refusal semantics, nothing needed to call this correctly is missing.

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

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

Zero parameters, so there is nothing to disambiguate; the baseline applies. The description does not need to compensate for any schema gap because the input schema is empty.

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

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

Specific verb ('List') plus resource ('the models generate_image and generate_video take'), and it names the exact sibling tools it feeds. An agent can distinguish this from list_prices or list_assets 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?

Implicit but strong routing: the models listed are the ones generate_image and generate_video accept, and 'Only measured combinations are listed; any other is refused with unsupported_combination before any charge' tells the agent to consult this before choosing a combination. It never states an explicit 'call this before generate_image/generate_video', so it stops short of full when-to-use phrasing.

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

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

Annotations already establish readOnly and non-destructive, so the bar is lower; the description nonetheless adds real context that the call is free and spends nothing, plus a description of the return entries (tool name, REST route, per-unit price lines, minimum_credits, or a formula when input-dependent). It does not cover output size, ordering, or whether prices are live versus cached.

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

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

Front-loaded with the core purpose and the free-cost fact, then the entry format. Slightly redundant ('Free, spends nothing' and 'Free tools cost 0') and the parenthetical unit list is dense, but every sentence still carries pricing 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?

With no output schema, the description carries the burden of explaining returns and does so by detailing the per-entry structure including minimum_credits and formulas. A zero-parameter read tool needs little more; only pagination/ordering and freshness of prices are unaddressed.

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

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

The tool takes no parameters, so there is no per-argument meaning to add; a baseline 4 applies. The description correctly does not waste space on parameter discussion.

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?

A specific verb and resource: 'List what every Clipwright tool costs in credits' — a pricing catalog. It also distinguishes itself from the many quote_* siblings by stating that exact paid amounts come from 'the quote tool the entry names,' so an agent can tell catalog lookup from per-call quoting.

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 (browse costs before committing) and when-not-to-use (for the exact number of a paid call, use the named quote tool instead). The alternative is named and the condition that selects it is stated, leaving little 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?

Beyond the read-only and non-destructive annotations, it explains default playback, opting out, the conditional edit beat, and the fact that sound choices never affect price. The final “Free” also adds cost context, and none of these statements contradicts the annotations.

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

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

The description is front-loaded and packs the catalog contents, override controls, edit condition, and pricing into a short paragraph with little filler. Phrases such as “every name it takes” and the isolated “Free.” are somewhat compressed and ambiguous, preventing perfect clarity.

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

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

Despite having no inputs or output schema, the definition supplies what the result contains, how defaults work, how to override or mute sounds, the edit-sound prerequisite, and cost behavior. An explicit output shape or discovery-before-make_ugc instruction could help, but neither omission prevents correct selection or invocation.

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

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

There are no inputs, so no invocation parameters require explanation and the zero-parameter baseline applies. The concrete syntax and values for the related make_ugc controls are useful additional semantics, although they document the downstream tool rather than this empty 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?

“List the sounds make_ugc templates play” supplies a specific verb, resource, and owning workflow, while “by beat” and the promised defaults and names define the listing's scope. This clearly distinguishes it from generic asset, voice, and price listings without relying on the tool name alone.

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

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

The description provides strong downstream-use context: defaults apply automatically, template_sounds { beat: name } customizes a run, false disables sounds, and edit sounds require edit_sounds=true. It stops short of an explicit directive to call this before make_ugc to discover valid overrides, and provides no exclusions or alternatives.

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

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

Annotations only declare the read-only safety profile, and the description adds substantial behavior beyond that: the call is free, invalid filter values are refused with the allowed list, the other skill refuses a mismatched voice before any charge, and preview links are short-lived and must not be stored. These are charge- and correctness-relevant facts an agent would otherwise get wrong.

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

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

Dense and repetitive, and the closing block of script-character limits per speech model (eleven_v3: 5000, eleven_flash_v2_5: 10000, and so on) plus break-tag counting rules belongs to make_ugc, not to listing voices. The genuinely decisive facts, the skill split and the preview behavior, are buried mid-paragraph rather than 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?

With no output schema, the description usefully documents returned fields (skill, kind, language, gender, preview_url, preview_expires_at, words_per_second) and the faceless default voice, which is exactly what an agent needs. Its gaps are scope-related rather than missing information: the embedded script-limit section is off-topic and the name/voice_id references point at 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 coverage is already 100%, so baseline is 3, and the description still adds meaning: `language` is the voice's native language, not a capability limit; a model_voice belongs to its model and has no language of its own; gender is listed only where known. It loses a point for referencing `voice`, `voice_id`, and `name` as things to pick, none of which exist in this tool's schema, which blurs which parameters belong here.

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

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

States a specific verb and resource and immediately scopes it to the `voice` field of make_ugc versus make_faceless, including what the unfiltered list contains. An agent can tell what it gets from this tool and when the `skill` branch changes the result 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 concrete guidance: play `preview_url` before a paid render rather than judging by description, call again for a fresh link after expiry, keep any voice the user chose, and pass actor_gender instead of relying on the default. Missing an explicit statement of when NOT to call it (e.g. when a voice_id is already known, though the escape-hatch clause implies this).

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), yet the description adds substantive context: the exact cardinality (seven), that five use native executors, that website-proof-demo and kinetic-launch are execution_blocked, and that availability is not purchase permission. What it omits is only how the result is shaped, which is minor for a static enumeration.

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?

Short and front-loaded: the resource comes first, then cost/safety, then the executor and blocked-state details. 'Free and read-only' partially restates the annotations, a small redundancy, but no sentence is padding.

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

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

With no parameters and no output schema, the description carries the burden of telling the agent what the response contains, and it does so by naming the seven-item scope, the executor split, and two blocked entries. A brief note on the fields returned (e.g. method name plus availability flag) would close the remaining gap.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline applies. The text correctly spends no words on inputs.

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

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

States a specific verb (List) and resource (seven workflow methods plus their current availability), so the agent knows exactly what comes back. It does not explicitly contrast itself with siblings such as get_workflow or prepare_workflow_plan, so the boundary is inferable rather than stated.

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

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

The 'Free and read-only' line and the execution_blocked note imply this is a cheap discovery call to run before planning or quoting a workflow. No explicit when-to-use/when-not guidance or named alternative is given, so the agent must infer the placement from the sibling list.

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

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

Annotations only declare a non-read-only, non-destructive mutation; the description goes far beyond that. It discloses that this is a paid operation with a concrete price formula (7 credits/image, 49 credits/clip, 1 credit/second with a 50 minimum), that it is asynchronous ('does NOT wait ... returns a run_id IMMEDIATELY'), and exactly how to poll to completion. This is the behavioral context an agent needs before spending credits.

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

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

Dense and front-loaded: the immediate-return warning and the quote-first requirement appear early. Every sentence carries operative information (pricing, polling, attempt). The one weak spot is the leading 'Input: the same fields as quote_faceless, plus attempt', which is a slightly awkward cross-reference before the actual purpose is stated.

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 asynchronous paid generation tool with no output schema, the definition still supplies the return handle (run_id), the state contract (succeeded/video_url, failed), and the polling path via get_run. Combined with the annotation pair it is nearly complete; the remaining gap is that ten of the twelve parameters are only described by reference to a sibling tool.

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

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

Schema coverage is 0% across 12 parameters, so the description must carry the semantic burden. It does explain duration_seconds carefully (30-90s selection, ends at narration, 25s floor, at most a quarter past selection, 90s cap), captions defaulting on, and attempt's new-run semantics. However, it defers the other fields wholesale to 'the same fields as quote_faceless', leaving brief/script/voice/transitions/style_reference/character_* unexplained here.

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

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

States a specific verb and resource: 'Start a paid finished faceless video from a script or brief.' It also names the sibling it depends on (quote_faceless) and distinguishes itself from quoting by the fact that it actually starts a run, so an agent can tell it apart from quote_faceless 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?

Explicit sequencing: 'Call quote_faceless first and show the user the price', then 'call get_run with its poll.arguments until the state is succeededed or failed'. It also tells the agent when to pass attempt=2,3 to deliberately create a new run, and points to list_prices for the full catalog. When-to-use and alternatives are both covered.

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 and destructiveHint=false; the description adds genuinely useful behavior far beyond that: it does NOT block, it returns a run_id immediately, and a 'failed' run may requeue and later succeed, surfaced in warnings[]. That is strong async-lifecycle disclosure, but the credit pricing block is long, duplicated, and largely restates quote_ugc/list_prices rather than adding new 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?

The critical async fact is front-loaded, but the text is a dense run-on that mixes input guidance, polling protocol, a caveat about field descriptions, retry semantics, and two nearly identical multi-clause pricing paragraphs. The pricing recitation in particular is repeated verbatim structure-wise and duplicates siblings' responsibilities, so several sentences do not earn their 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?

Covers the async contract, return value (run_id), retry semantics, and cost-check flow, which are the essentials for calling it correctly. But for a 40-parameter tool with no output schema and 0% schema coverage, most parameters remain unexplained, and the advice to consult per-field 'NOT HONORED YET' notes is misleading in their absence.

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 0% across 40 parameters, so the description must compensate and it only partly does: it explains attempt, captions (opt-in), actor_id vs image and the default actor, script length limits, and the 1080x1920 format default. The remaining ~30 parameters (voice_id, overlays, segments, layout_windows, presenter_gaze, broll_policy, etc.) get no semantic coverage, and its instruction to read 'NOT HONORED YET' notes in each field's description is unhelpful when no field descriptions exist.

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') and immediately anchors it against the sibling quote_ugc via 'the same fields as quote_ugc, plus attempt'. The agent can tell this apart from quote_ugc (quoting) and get_run (polling) 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?

Explicit when-to-use and sequencing: call quote_ugc before generating and show the cost, then poll get_run with its poll.arguments until 'succeeded' or 'failed'. It also states a deliberate retry path (attempt=2,3,... for a NEW run) and an opt-in rule (captions: ask the user first), plus a pointer to list_prices.

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

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

With readOnlyHint=false and destructiveHint=false already declaring a non-destructive write, the description adds the substantive facts: no payment, no run, no generation, script copied unchanged, warnings enumerating everything the plan fails to reproduce. It does not cover idempotency of recompiling or whether recompiling replaces the prior plan.

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 free/no-run constraint is front-loaded, and the follow-on workflow comes last, which is the right order. It is dense but nearly every clause carries information; the repeated "Free" after "without paying" is the only 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 10-parameter tool with nested objects and no output schema, the description explains the server's behavior well but leaves half the inputs unexplained, including the hazardous voice vs. voice_id distinction. It also never says what the returned plan looks like beyond containing warnings.

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

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

Schema coverage is 50%, and the description adds real meaning for reference_profile (sourced from get_reference_analysis and passed unchanged) and script (copied verbatim). But five parameters — call, message, audience, voice_id, site — get no mention, and "a voice" is ambiguous because both voice and voice_id exist.

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?

"Compile a reference remake into a new workflow plan" names a specific verb and resource, and the qualifiers "without paying or starting a run" and "Nothing is generated" immediately separate it from quote_workflow_plan, run_workflow_plan and generate_image/generate_video. An agent can place it in the pipeline 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?

It gives explicit when-to-use routing: separate generate_image or generate_video calls (each with its own quote) for missing media, then compile again, then approve/quote/run as usual. What's missing is any exclusion relative to prepare_workflow_plan, which sounds adjacent but is never mentioned.

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

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

Adds real information beyond the annotations: no charge and no run is started, the document is strict and bounded to 256000 JSON bytes, accepted narration must be preserved verbatim, and a failed save should be reconciled by reading rather than retried blindly. It does not explain version-conflict behaviour for base_version or any permission/auth requirements for a non-readOnly write.

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 and dense: the no-cost/no-run scoping comes first, then the create-vs-revise rule, then the recovery advice. Every sentence carries weight, though "Preserve exact accepted narration" is compressed to the point of being cryptic on first read.

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

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

Given a strict, deeply nested, zero-description schema and no output schema, the description covers purpose, cost, size limit, mode selection and error recovery. It leaves out what the call returns (plan id? version?), how version conflicts surface, and how an agent should obtain or derive a schema-valid document before calling — substantial gaps for a tool whose entire payload is one large object.

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% across a very deep nested document schema. The description does add critical meaning for the two optional parameters (plan_id/base_version form an all-or-nothing pair), which the schema cannot express, and flags the size bound. It says nothing about the many nested document sections (method digests, beats, claims, assets), so most parameter semantics remain undocumented.

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?

"Create or save a workflow plan without paying or starting a run" gives a specific verb and resource and pre-emptively rules out the paying/run-starting behaviour of its siblings (quote_workflow_plan, approve_workflow_plan, run_workflow_plan). It stops short of naming those siblings, so an agent must infer the boundary from the negation, but the distinction is still clear.

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 mode selection: "Omit both plan_id and base_version to create; supply both to save a revision," plus a when-not instruction ("do not automatically approve or purchase") and a recovery procedure after a lost save answer. No guidance on where a valid document comes from (e.g. from a prior quote or get_workflow_plan), which is the main missing when-to-use context.

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 annotations already declare readOnlyHint=true, so the zero-charge nature is partly pre-declared, but the description reinforces it with "WITHOUT spending credits" and adds genuinely new behavior: each requested format is billed as a separate image. It stops short of describing what the response contains (per-format breakdown, credits vs. currency), which matters for a pricing tool with 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 compact sentences with no filler; the core purpose is front-loaded and the call-ordering instruction follows immediately, with the per-format billing note as a compact trailing clause.

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 pricing tool whose schema is fully documented, the description covers purpose, safety, and the billing model, which is the essential context. The only real gap is the shape of the estimate returned (per-format totals, units), which an agent may need before formatting the answer.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds pricing semantics the schema does not: cost scales per requested format (aspect_ratios) and quality is flagged in the schema as price-affecting, which the description ties back to the quote. It does not explain how from_actor_id or holding affect cost, leaving some parameters' pricing impact unstated.

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?

"Estimate the credit cost of create_actor WITHOUT spending credits" states a specific verb (estimate cost) and a specific target resource (create_actor), and it distinguishes itself from the sibling create_actor and from the other quote_* tools by naming the exact operation it prices.

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?

"Call this first and show the price before create_actor" gives an explicit ordering rule and an explicit alternative, which is exactly the guidance an agent needs. It does not, however, say anything about when not to call it (e.g., re-quoting unchanged inputs) or how it relates to sibling quotes like quote_ugc.

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 reinforces this with 'Free; starts nothing' and the hold-then-charge semantics of credits_estimate. It additionally discloses refusal behavior for YouTube/unknown links and the zero-cost replay and stale-analysis cases, which annotations cannot convey. The heavy jargon (replays_analysis_id, the pre-frames-and-speakers edge case) is never unpacked, keeping it short of a 5.

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

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

The purpose is front-loaded, but the body is one very long sentence with stacked conditions ('0 when... and 0 when...') that is hard to parse on first read. The '70 full, 10 data' figures duplicate the mode enum description, so some text does not earn its place.

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

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

For a read-only pricing tool with no output schema, the description covers cost, hold/charge timing, zero-cost cases, and refusals — the things an agent needs to quote responsibly. It never states that exactly one of asset_id or source_url must be supplied, despite required parameters being empty, which is a small but real gap.

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

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

Schema coverage is 100% and the mode enum description already states '70 credits' and '10 credits', which the description largely repeats. The added meaning is about returned quote fields (credits_estimate, repeat_note, replays_analysis_id) rather than the three input parameters, so the schema still does the heavy lifting on inputs.

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 opening clause states a specific verb and resource ('Price analyze_reference') plus the inputs that drive the price (asset_id or source_url, and mode) and the timing ('before starting it'). The closing 'Free; starts nothing' separates it cleanly from the sibling analyze_reference, so an agent knows this is the dry-run quote, not the execution.

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 call it — before starting an analysis — and tells the agent to surface repeat_note to the user. It also names a when-not condition ('A YouTube or unknown link is refused here too'). It never explicitly says 'use analyze_reference to actually start', leaving the routing to inference from the name.

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=true and destructiveHint=false, so the description adds the real behavioral content: no credits are spent, a delivered candidate is charged whether kept or discarded, a failed one is charged nothing, and a closed shot returns editing_disabled with no charge. It also discloses the response fields (unit, credits, usable_until).

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 credit-free constraint is front-loaded in the first clause, and the remaining sentences cover ordering, billing outcomes and the closed state without filler. Nothing is repeated from the schema verbatim.

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?

Although there is no output schema, the description names the returned fields and their meaning, covers failure and closed-state paths, and ties the call to the create_candidate workflow. An agent has everything needed to call it and to explain the price to a user.

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

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

Schema coverage is already 100%, so the baseline is 3; the description adds a useful cross-tool equivalence ("Pass run_id, shot_id and operation, the same as create_candidate"), which helps an agent mirror a known call shape. The optional take parameter is left to the schema, so it does not fully transcend the structured data.

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

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

"Price one shot candidate of a run WITHOUT spending credits" gives a specific verb and resource, and immediately defines the unit (one picture or clip made for one shot). It is clearly distinguished from the sibling create_candidate, which is named as the paid counterpart.

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 states an explicit ordering rule ("Always call this first and show the user the price before create_candidate") and names the alternative tool it precedes. It also gives the closed-state condition under which the call returns editing_disabled instead of a price.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description explains credit behavior: a start holds and charges 20 on success, but 0 when a recent profile can replay. It also discloses refusal cases and that the tool starts nothing.

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 and every sentence contributes pricing, replay, or refusal detail. The nested colons and parentheticals make it denser than ideal, but it is not padded.

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

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

For a one-parameter quote tool with no output schema, the description covers the essential behavior: price, free/non-starting nature, replay discount, and refusal conditions. It explains the key return concepts without needing to spell out a full response 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 coverage is already 100%, so the schema documents the source_url format. The description still adds useful meaning by explaining replay handling and that a new reel or short link quotes full price because its author is unknown until the start reads 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?

The description states a specific verb and resource: it prices analyze_creator for a source_url before starting it. It also distinguishes this tool from the actual analysis start by emphasizing that it is free and starts nothing.

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

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

It clearly says to use this before starting analyze_creator and notes that YouTube or unknown links are refused. It does not explicitly compare against other quote siblings such as quote_analysis, but the intended timing is clear.

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

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

The readOnlyHint=true annotation already establishes that nothing is mutated, and 'WITHOUT spending credits' largely restates that safety profile. The description does add the useful sequencing constraint and the instruction to surface the price to the user, but it never says the quote must be called with the same parameters as make_faceless, nor what the response contains (total cost, breakdown, currency estimate) — a notable gap 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 short sentences with zero filler; the cost-free nature and the mandatory call-order are both front-loaded before any caveat.

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 11-parameter quoting tool with nested objects and no output schema, the definition covers the decision to call it but not the mechanics: it doesn't state that arguments should mirror the eventual make_faceless call, nor describe what the returned estimate looks like or how it maps to pricing. Adequate to trigger the tool, thin for using 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 100%, so every one of the 11 parameters, including the nested scene_images and transitions anchors, is already documented inline. The description adds no parameter-level meaning such as 'pass the same brief/script/duration you intend to use' or how optional fields affect the quoted price, so it sits at the 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?

States a specific verb and resource — estimate the credit cost of make_faceless — and immediately distinguishes itself from the sibling that actually spends credits by noting it does so 'WITHOUT spending credits'. An agent can tell it apart from make_faceless and the other quote_* 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 an explicit, prescriptive ordering rule: 'Always call this first and show the user the price before make_faceless', which tells the agent both when to invoke it and what to do with the result. It does not cover when-not to use it or point to alternative quote tools (quote_video, quote_ugc) for non-faceless jobs.

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 goes well beyond that by disclosing that no credits are spent, that failed generations are charged nothing, and that closed-generation states return specific codes rather than erroring out. It also explains the reference lifecycle (reusable until reusable_until, rights confirmed at asset creation), which the annotations cannot convey.

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

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

Front-loaded with purpose and the mandatory call-first instruction, and every clause carries information. The reference sentence is a long run-on that could be broken into a short list of the three reference forms for faster scanning, which is the only structural weakness.

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, so the description must describe returns; it names credits, width/height, warnings, and the two closed-generation result codes, which is enough for an agent to act. The exact response shape (field names, how warnings are structured) is still left implicit, and the model/aspect_ratio compatibility rules are unstated.

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

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

Schema coverage is 0%, so the description must compensate, and it does so for the hardest parameter: references is spelled out as three mutually exclusive shapes ({upload_id, rights_confirmed}, {run_id}, {asset_id}) with the meaning of rights_confirmed and the reusable_until window. Model is tied to pricing ('its model's unit_credits'), but prompt (length limit) and aspect_ratio semantics — including which ratios each model supports — are left entirely to the schema.

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

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

States a specific verb and resource — 'Price one generate_image call' — and immediately distinguishes itself from the sibling generate_image by adding 'WITHOUT spending credits'. It also names exactly what is returned (credits, width, height, warnings), so an agent can tell it apart from generate_image, quote_video, or quote_analysis 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 an explicit directive: 'Always call this first and show the user the price before generate_image', naming both the required ordering and the alternative it precedes. It also covers the when-not case: no charge for failed generations, and the generations_disabled / generations_marking_pending responses while generations are closed.

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 while adding real information the annotations cannot convey: the billing model (delivered revisions charged the quoted total, failed ones charged nothing) and the paid-edits-closed path that returns editing_disabled at no cost. It stops short of describing latency or whether the quote is stable over time, which keeps it below a 5.

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

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

Four tight sentences, each carrying distinct payload: purpose and cost model first, parameter rule second, workflow ordering third, edge-case behavior last. No restatement of the title or name, no filler.

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

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

For a read-only pricing tool with a deeply nested schema (oneOf on changes.operation, embedded document with shots/assets/timebase) and no output schema, the description supplies the return shape, the cost semantics, and the failure/disabled outcomes. Nothing an agent needs in order to call it correctly and 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?

Schema description coverage is 100%, so the baseline is 3, but the description adds a constraint the schema does not enforce: 'exactly one of changes or document' — the schema lists both as independent optional properties with no oneOf. That mutual-exclusivity rule and the 'same as revise_run' equivalence are genuine value beyond structured fields.

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/quote a revision of a run — and immediately scopes it as 'WITHOUT spending credits', which is the key distinguishing property versus revise_run. It also names the two return fields (summary, billing.total_credits), so an agent knows exactly what it gets back.

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 sequencing instruction: 'Always call this first and show the user the price before revise_run.' It names the sibling it precedes and the human-in-the-loop step required, leaving nothing to inference.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the description has an easier job. The one genuinely additive fact is 'WITHOUT spending credits', which tells the agent the call is free, a cost property the annotations do not spell out. Beyond that, it is thin: with 39 parameters and no output schema, it says nothing about whether the quote is a full validation of the render request, whether an invalid request fails here rather than at make_ugc, or whether the returned estimate is binding.

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, the free-estimate purpose is front-loaded, and the mechanical instruction ('call this first') follows. No filler.

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

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

For a very large, heavily nested request schema with no output schema, the description covers the decision (should I call it?) but not the result (what does a quote return, is it a number, a breakdown, if it is a dry run of make_ugc?). Given that the tool is the gatekeeper to an expensive render, a sentence about what it returns and whether it validates would have rounded the definition out.

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

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

Schema description coverage is 97% across 39 parameters, so the schema already carries essentially all parameter meaning. The description adds nothing about parameters, hence the baseline of 3. It would have been valuable to state that the parameters mirror make_ugc.

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

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

It names a specific verb and resource: 'Estimate the credit cost of a make_ugc call', which an agent can easily tell apart from make_ugc (which actually renders the video) and from the other quote_* siblings. It stops short of saying the quote takes the same parameter set as make_ugc, which is the implicit assumption the agent must make.

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 explicit when-to-use guidance: 'Always call this first ... before make_ugc', and a related display duty ('show the user the price'). It does not address when not to use it, or how it differs from quote_revision, quote_candidate, or quote_workflow_plan, which are near neighbours, though their names partly disambiguate them.

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

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

The readOnlyHint/destructiveHint annotations already mark this as a safe read, and the description adds substantive behavior beyond them: no credits are spent, failed generations are charged nothing, closed-generation states return named errors at no cost, and reference reuse is bounded by reusable_until. That is exactly the billing and side-effect context an agent needs before a paid-looking 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 key constraint (pricing without spending credits) and the ordering rule are front-loaded, and the rights_confirmed parenthetical is compact. The reference-source sentence is long and packs three cases into one run-on, but no sentence is padding.

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

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

With no output schema, the description usefully enumerates the returned fields (credits, width, height, warnings) and the free-error cases. For a 10-parameter, 0%-coverage tool it is still incomplete: the mode/model/resolution/aspect_ratio semantics that determine the quoted price are never explained, so an agent knows why to call it but not how to construct a valid request.

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 carries the burden, and it does explain the reference union well: {upload_id, rights_confirmed: true} from upload_image/create_upload, {run_id} of a succeeded generate_image run valid until reusable_until, and {asset_id} from create_asset. However it says nothing about the mode enum (text/first_frame/reference), which model to choose, or what aspect_ratio, resolution, and camera mean, leaving most of the 10 parameters unexplained.

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 one generate_video call WITHOUT spending credits', and names exactly what comes back (credits as unit_credits per second of duration_s, width, height, warnings). It is immediately distinguishable from the sibling generators (generate_video, quote_image, quote_ugc) because it is a pricing call that spends nothing.

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 generate_video,' which tells the agent both when to use it and what to do with the result. It also covers the degenerate case ('While generations are closed it answers generations_disabled or generations_marking_pending and charges nothing') so the agent knows what a non-standard response means.

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

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

Beyond the readOnlyHint/destructiveHint annotations, the description adds substantive behavior: no credit spend, the quote_id is time-limited, it pins an exact revision and semantic input, and the quote payload doubles as the launch body for run_workflow_plan with a fresh idempotency_key. These are non-obvious operational facts an agent would otherwise have to discover by trial.

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, front-loaded with the free/read-only fact that matters most, and nothing is redundant. The final sentence about the launch body and idempotency_key is compressed to the point of being slightly hard to parse on first read.

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

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

With no output schema, the description still tells the agent what comes back (native price, warnings, an expiring quote_id) and how that output is consumed downstream. For a one-parameter, non-destructive tool, nothing essential is missing.

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

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

Schema description coverage is 0% for the single plan_id parameter, so the description must carry the load. "The approved current plan" does add meaning by implying the plan must already be approved, but it never explains the wfp_ identifier format or what happens when the plan is not yet approved.

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 ("Quote the approved current plan") and immediately scopes it against the costly alternative by stating it spends no credits. An agent can distinguish this from run_workflow_plan, get_workflow_plan, and approve_workflow_plan from the text alone.

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 — quote first, then request a paid launch — and names run_workflow_plan as the follow-up path, so the sequencing is unambiguous. It does not explicitly exclude other siblings such as quote_revision or quote_candidate, leaving that routing to inference.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds substantial behavior beyond that: idempotency (an identical request returns the same prior run), money semantics (delivered revision charged its quoted total, failed revision charged nothing, editing_disabled charges nothing), and quota limits on the origin run. It also tells the agent exactly how to follow up ('call get_run with its poll.arguments') and when the new run becomes editable.

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?

Nearly every sentence carries real information, but it is delivered as one dense semicolon-chained paragraph that opens with 'Input: the same fields as quote_revision, plus attempt' — a cross-reference that duplicates and slightly blurs what the schema already shows. The actual purpose statement arrives only in the second sentence, and the pricing block could be separated from the usage rules for faster scanning.

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 paid mutation with no output schema and nested parameters, the description is unusually complete: it covers prerequisites (quote first), input exclusivity, idempotency, cost table, failure/refusal outcomes, and the exact next call to retrieve the resulting run. An agent has everything needed to invoke it correctly and handle its responses.

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 0%, so the description must carry parameter meaning, and it largely does: 'changes' is described as a shot plus what to generate for it, 'document' as the whole edited document with exactly one required, and 'attempt' as the deliberate-duplicate escape hatch. The gaps are that run_id's provenance/format is never stated and the nested shape of a 'changes' item remains vague ('a shot and what to generate for it'), leaving nested objects underspecified.

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 explains the outcome precisely: a NEW run that re-renders the video with only the changed shots. It explicitly distinguishes itself from make_faceless (original creation) and quote_revision (pricing only), so an agent can separate it from 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 ordering ('Call quote_revision first and show the user the price'), an exclusivity rule ('by changes ... or by document ...; pass exactly one'), and a deliberate override path ('to start a second revision with the same request on purpose, pass attempt 2'). It also names the refusal conditions (concurrent revision limit, failed/unfinished limit, editing edits closed) and the editing_disabled response, which is strong when-to-use/when-not-to-use coverage.

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

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

Annotations only say readOnly=false and destructive=false, but the description adds the real behavior an agent needs: this charges money, it sets the Idempotency-Key header for you, it returns immediately with a receipt and run_id rather than blocking, and reusing a new key can double-pay. That goes well beyond the annotation surface.

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

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

Front-loaded with the action, then constraints, then recovery, then pricing — good ordering with no filler sentences. It is very densely packed into a single block, so an agent must parse several distinct rules in one pass, which costs a little 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 paid, idempotency-sensitive mutation with no output schema, it covers pricing, follow-up polling, retry safety and approval semantics. The only shortfall is that plan_id and the digest fields are never explained, and the receipt's shape is only alluded to since no output schema exists.

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

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

With 0% schema description coverage, the description carries the load and does it well for most fields: it names revision, content_digest, semantic_input_digest, quote_id and idempotency_key, and tells the agent to pass the quote's launch object unchanged rather than reconstructing it. It does not explain plan_id (the first required parameter) or what each digest represents, leaving one documented 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?

Opens with a precise verb+resource+scope: 'Start one explicitly approved paid workflow run.' The word 'approved' and 'paid' plus the reference to the quote's launch object make it unmistakable versus quote_workflow_plan, approve_workflow_plan, and get_workflow_plan.

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 routing: quote first with quote_workflow_plan, then poll with get_run using poll.arguments. It also states prohibitions ('Never auto-approve, auto-quote or invent a new key') and the recovery path for uncertain delivery, which is exactly when-not/how 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 only supply a generic write/idempotent/non-destructive profile; the description adds the specific cost model (free, spends nothing), the rate limit (20/hour per account), and the dedup rule (same kind/text/run within 24h returns the same feedback_id), which corroborates idempotentHint with concrete semantics. It also discloses the reply path via get_account support_replies. Minor gap: no mention of what the immediate response contains (e.g. the feedback_id value itself).

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 trigger come first, then content guidance, then the follow-up path, then cost/idempotency/limit. Five short sentences, none of them filler; even the soft "We read every one" earns its place by establishing that the channel is monitored.

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

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

With no output schema, the description still covers what happens after sending (reply surfaced by get_account, dedup by feedback_id) and constrains cost and volume. For a three-parameter reporting tool this is everything an agent needs to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a genuine usage criterion beyond the schema by saying to pass run_id "when it is about a run" and prescribing the content of text (what the user wanted, what was tried, what came back). The kind semantics largely restate the enum descriptions.

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 opening line names a concrete action and recipient ("Tell Clipwright what is missing or wrong") and the tool is the only feedback channel among the siblings. An agent can tell instantly that this is the escape hatch for unmet or bad results rather than another content-generation tool.

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

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

It gives explicit trigger conditions keyed to each kind (no tool does the task, confusing answer, wrong result, too slow) and an explicit when-not: don't silently rephrase and give up. The alternative behavior (falling back to rephrasing) is named, which is exactly the routing decision an agent faces.

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

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

Annotations already declare a non-read-only, idempotent, non-destructive mutation, and the description adds genuine context on top: no credit spend, storage-only semantics, no effect on actor-only videos, and how a run override supersedes the default. The sentence 'Segmented media generation is closed.' is oddly placed and its relevance to this tool is not explained, which slightly muddies an otherwise strong behavioral disclosure.

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 core action and its credit/storage implications are front-loaded well, but the three-way policy enumeration duplicates the schema enum text, and 'Segmented media generation is closed.' reads as an unexplained aside that does not earn its place. Several sentences could be trimmed without losing meaning.

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

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

For a two-parameter idempotent setter with no output schema, the description covers the important things: cost, persistence semantics, downstream precedence, and which video types are unaffected. The main remaining gap is actor_id validity and error behavior, which an agent would want before calling.

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 only 50%: broll_policy already carries the enum meaning verbatim in the schema, and the description repeats that text word-for-word rather than adding anything. The other parameter, actor_id, is left entirely unexplained in both schema and description — no indication of whether it must reference an existing actor or how failures are surfaced — so the description does not compensate for the coverage gap.

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

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

The opening sentence states a specific verb and resource ('Save ... B-roll default') scoped to 'this account actor', which cleanly separates it from the read counterpart get_actor_defaults in the sibling list. It does not name that sibling explicitly, so differentiation relies on the save/read verb contrast rather than an explicit statement.

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?

'Without spending credits' and 'has no effect on actor-only videos' give clear conditions under which this tool is, and is not, worth calling. The precedence rule ('Run override wins over the account actor default; otherwise no_people') tells the agent how the saved value behaves downstream. It stops short of explicitly directing reads to get_actor_defaults, so it is clear context rather than full when/when-not routing.

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 non-destructive, idempotent mutation, so the description's key contribution is the explicit clarification that 'the picture itself does not change' — confirming only metadata is touched — plus the cost signal 'Free.', which is not represented anywhere in structured fields. It does not describe the response or permission requirements, keeping it below a 5.

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

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

Two compact sentences with the operation front-loaded and the most important behavioral caveat immediately after it. The one-word cost statement is a fragment but is high-value and wastes no words.

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

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

For a three-parameter metadata mutation with no output schema and safety already covered by annotations, the description supplies the essential missing pieces: what is not affected and what it costs. Ownership/permission expectations and the returned shape are the only notable omissions.

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 carry parameter meaning; it does convey that a name and a role can be set, mapping to two of three parameters. However, it says nothing about the fixed role vocabulary enforced by the enum, the 1–80 character name bound, or the asset_id format, leaving gaps that the schema only encodes structurally.

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 names a specific verb-and-resource pair ('Rename an asset') and extends it to a second operation ('change its role'), which an agent can distinguish from create_asset, delete_asset and get_asset. It stops short of explicitly contrasting itself with those siblings, so it is clear but not maximally differentiating.

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

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

Usage is implied by the two described operations (renaming, role change) rather than stated as 'use this when…'. There are no exclusions or pointers to alternatives such as create_asset or delete_asset, and no note on prerequisites like ownership of the asset.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description adds concrete behavior: 10 MB size ceiling, ~20 second download window, up to 3 redirects followed, 24-hour URL signature vs. 30-day upload_id lifetime, free of credits, 20 uploads/day and 30 downloads/hour quotas, and SHA-256 content_digest semantics.

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

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

Front-loaded with the purpose and tightly packed with useful facts, no filler sentences. It is a single dense block, though, and the trailing aspect_ratio advice belongs to downstream tools rather than this one.

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 no output schema, the description carries the return shape (upload_id + signed URL), lifetimes, quotas, and how both outputs are consumed by specific sibling tools. An agent has everything it needs to call this correctly and pick it over create_upload.

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

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

Schema coverage is already 100%, so the baseline is 3; the description still adds meaning, clarifying that `path` is only valid on a machine-local server while `url` is downloaded server-side with timeouts and redirect handling. The `aspect_ratio` instruction refers to a parameter this tool does not expose, which is mildly off-scope.

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: it returns an upload_id and a signed https URL for a PNG or JPEG up to 10 MB. It immediately distinguishes the two sources (local `path` vs. public `url`), and its difference from the sibling create_upload is made explicit later.

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

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

It states exactly when to use `path` (only when the server runs on your machine) and when to use `url`, then names the alternative: create_upload for a local disk file while this server is remote. It also explains how the outputs feed quote_ugc/make_ugc and the image/video tools.

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