agent-media

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

Beyond the annotations (which only flag non-readonly, open-world, non-idempotent, non-destructive), the description discloses credit cost (16 per 1,000 characters, rounded up), the async job model, and a detailed retry-safety contract for request_id including that replay returns the original job without recharging. That idempotency nuance is especially valuable given idempotentHint=false.

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 the sibling comparison are front-loaded, and the retry-safety block is clearly separated from the core description. It is long and repeats the voice list already present in the schema, but nearly every sentence carries operational information (pricing, polling, audio_ref chaining).

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 explains the return value (a job id to poll via get_run_status for the mp3 URL) and that the resulting URL can be chained into generate_video as an audio_ref. For a 5-parameter async generation tool, nothing an agent needs to call and follow up correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond it: the voice roster with gender/age characterizations, the cloned-voice Hebrew limitation, and the request_id reuse-vs-new-generation distinction. The tone enum and model parameter are left to the schema, and the voice list is partly duplicated from the schema description, keeping it from 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?

The description opens with a specific verb+resource ("Speak text in a named voice") and immediately enumerates the voice options. It explicitly distinguishes itself from the closest sibling by stating generate_video renders native speech when words are in the prompt, so an agent can route correctly 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?

It states both when NOT to use it ("for a talking-head clip you usually do NOT need this") and when to use it instead ("voiceover over b-roll or a standalone audio file"), naming the alternative tool explicitly. Constraints like the Hebrew/cloned-voice rule further narrow correct usage.

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

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

Beyond annotations, it discloses credit spending per image, model choices, return behavior ('Returns a job id, poll get_run_status'), and nuanced retry safety via request_id reuse to avoid duplicate charges. These are material behaviors an agent needs and are not captured by readOnlyHint, destructiveHint, or idempotentHint.

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 organized into sections, but it is extremely long for a 5-parameter tool and includes extensive upload-panel instructions that primarily belong to sibling tools. It is not disorganized, but it is well beyond what is needed for this tool alone.

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 credit-spending generation tool with no output schema, the description covers return values, polling, model selection, reference handling, upload prerequisites, and retry semantics. An agent has enough information to invoke it correctly and recover safely from failures.

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 model IDs, clarifies refs as editing/composition references, and explains how to pass URLs in arguments rather than prompts. It repeats some schema text, but the workflow context around refs and request_id gives extra meaning.

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

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

The description opens with a specific verb and resource: 'Render one image from YOUR prompt.' It immediately distinguishes behavior with and without refs, and explicitly explains how it differs from generate_video by describing the portrait-first workflow. An agent can identify this as the direct image-generation tool without opening the schema.

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

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

It gives explicit when-to-use guidance, including routing to make_ugc for person/product photos, quote_ugc before spending, and composing direct generators otherwise. It also states when not to start reference-dependent generation and when to use the upload panel first. The alternatives and preconditions are clearly 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 only flag non-read-only, open-world, non-idempotent, non-destructive. The description adds real behavioral context beyond that: credit pricing per second by model/quality, the Hebrew path with its restrictions and alternate pricing, retry safety via request_id reuse without double charge, and the post-submit get_run_status polling loop.

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 generation contract is front-loaded and well organized with caps-labeled sections, but roughly half the text is an upload-panel and tool-discovery procedure that duplicates open_upload_panel/upload_image/get_uploads guidance and is not needed to invoke this tool. It bloats the definition and dilutes the video-specific instructions.

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 15-parameter, nested-object tool with no output schema, the description covers modes, per-model limits, pricing, the Hebrew special path, return handling (job id then get_run_status), and retry semantics. An agent can call it correctly and knows what comes back.

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 parameters are documented; the description nevertheless adds cross-field semantics the schema can't express well, such as mode selection following from which fields are populated and the rule that frames and refs cannot be mixed. The remaining per-enum details (aspect/quality support matrix) are deferred to list_models, which is reasonable but leaves some 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 precise verb+resource (render a video clip) and immediately enumerates the three operational modes derived from which fields are passed, which is exactly the distinction an agent needs. It also names sibling boundaries implicitly (generate_image, make_ugc) by routing image-only or UGC outcomes elsewhere.

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 rules: call `quote` first if cost matters, call list_models for per-model modes, use make_ugc when it fits the requested outcome, otherwise compose the direct generators. It also gives when-not rules (never mix refs with frame fields; don't start a reference-dependent generation before images are ready).

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces this with concrete negatives: no upload session created, no media generated, no credits refilled, no billing change. It also adds a genuinely useful caveat that a positive balance does not guarantee sufficient funds or provider availability.

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 read-only guarantee is front-loaded in the first sentence, alternatives and caveats follow in priority order. Every sentence adds decision-relevant information with no filler.

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

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

With no output schema, the description carries the burden of indicating what comes back, and it does so at a high level: auth state, credit balance, service configuration flags. Exact response shape and units are not specified, which is a minor gap for a 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies no inputs are needed by framing it as a read-only status check.

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 set: check authentication, available generation credits, and whether generation/upload services are configured. This is clearly distinct from siblings like get_run_status, get_uploads, and the generation 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?

Explicitly says to call it before the first generation and routes the agent onward: use quote_ugc for make_ugc or quote for a direct generator, then compare cost against balance. Both the when and the alternatives are 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 readOnly/idempotent/non-destructive, and the description adds the behavior that matters: the ~45 second blocking cap, the need to re-poll, and that videos take several minutes. It does not describe what a failed or errored run looks like in the response, which is the main remaining 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?

The purpose and output come first, then id semantics, then the polling guidance — good front-loading. The final parenthetical about median render times is long and slightly redundant with the wait advice, but it still carries useful 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 correctly takes on the return-value burden by naming the output URL and media types. It is nearly complete for a 2-parameter polling tool; only failure-state handling is left implicit.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real semantics the schema lacks: run_id accepts ids from ANY agent-media tool and resolves run id, skill run id, and job id interchangeably. The wait parameter's blocking behavior is reinforced beyond the schema's own wording.

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 a generation you already submitted') and the payoff ('get its output URL (video, image or audio)'). This is unambiguously distinct from the generate_* siblings, which create runs rather than inspect them.

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

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

Explicit conditional instructions: 'ALWAYS call this after submitting', 'Set wait:true to block', and 'if it is still running, just call again'. It even routes the agent to list_models `recent` to estimate render time, so the polling decision is grounded in another tool.

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

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

Annotations already declare read-only/idempotent/non-destructive, so safety is covered; the description adds non-obvious behavior: 24-hour expiry of sessions and images, the need to request a fresh upload when expired, and the guidance to reuse URLs without downloading, re-encoding, or copying. It also discourages polling, which is a real invocation trait not captured anywhere in structured fields.

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

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

Front-loaded with what is returned, then usage rules, then expiry and URL-reuse guidance — every sentence carries actionable content. It runs five sentences and is dense, but no sentence is redundant; slightly tighter grouping would make it scannable faster.

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

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

There is no output schema, yet the description names the return payload (native previews, original URLs, expiry times) and covers lifecycle (24h expiry, refresh path) and downstream consumption rules. Nothing an agent needs to call this correctly and interpret results 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 0% and the schema only declares a uuid-typed session_id with no meaning attached. The description supplies the crucial semantics: the parameter is optional, omitting it triggers a fallback discovery of recent unexpired sessions on the account, and the agent must select the matching session. It stops short of stating the expected format, which the schema already implies.

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?

"Retrieve uploaded images as native image previews plus original generation URLs and expiry times" gives a specific verb, resource, and return content in one clause. It is clearly distinguishable from upload_image and open_upload_panel siblings, which imply writing/opening rather than reading.

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 after the user finishes uploading, not in a tight polling loop"), an alternative discovery path ("Omit session_id to find recent unexpired sessions... if the session ID was lost"), and a disambiguation rule ("choose the session matching the user request, never silently mix unrelated uploads"). It also names the downstream use ("Inspect the previews before describing the image or writing a prompt").

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 this as read-only, idempotent, non-destructive, and non-open-world. The description adds useful behavioral context by describing the returned character identifiers and URLs and how they are consumed by sibling tools. It does not describe pagination behavior, but the single `limit` parameter is documented in the 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?

The description is front-loaded with the listing purpose, then efficiently covers returned fields and downstream usage. The final sentence fragment about the portrait/thumbnail URL is useful but slightly less tightly structured than the rest.

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

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

For a simple read-only list tool with no output schema, the description sufficiently explains what is returned (`character_id`, `character_sheet_url`, portrait/thumbnail URL) and how those values are used. Annotations cover the safety profile, and the schema covers the sole parameter.

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

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

Schema description coverage is 100%, and the only parameter (`limit`) is fully documented there with a default and maximum. The description does not add parameter-level semantics, so baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: "List the authenticated user's saved, reusable characters." It also explains the returned identifier formats (`character_id`, `character_sheet_url`) and distinguishes this listing tool from generation siblings by naming where its outputs are consumed.

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 states the downstream usage: pass a character_id or sheet URL as `make_ugc`'s `character`, or use the sheet/portrait URL in `refs` for advanced `generate_video` / `generate_image`. It does not explicitly say when not to use this tool versus alternatives like `get_uploads`, but the intended context is clear.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds value beyond them: 'Costs NO credits', it performs an authenticated balance check (an auth-adjacent side effect), the `recent` block covers the last 30 days of real runs with fail rate, auto-judge score, ratings and median render time, and candidates are explicitly not selectable. These are behavioral facts not derivable from the annotations.

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

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

Front-loaded correctly and zero fluff sentences, but it is a single very dense sentence packing modes, limits, stats, cost, auth and defaults together, making it hard to scan. Some of the selection guidance could be separated from the return-value inventory.

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

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

There is no output schema, so the description carries the burden of describing return contents, and it does so thoroughly (per-mode inputs/limits/quality/credits, pick-when, latency, 30-day run stats). Nothing an agent needs to decide whether and how to call it 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 only parameter, include_candidates, is already 100% covered by the schema and the description merely restates it. The instructions about passing the id as `model` or `model:"auto"` actually describe parameters of the generate_* tools, not of list_models, which risks confusing an agent about this tool's own signature.

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 ('List the generation models agent-media can use') and enumerates precisely what is returned per model: modes, exact inputs, limits, aspects, qualities, credits/second, pick-when line, latency, selection guidance, plus 30-day run statistics. This is clearly distinguishable from siblings like quote, get_account, or the generate_* 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?

Explicitly states timing and alternatives: 'Read this BEFORE choosing a model or a mode for generate_video / generate_image / generate_audio', plus compare the included balance with quote before generation, and use include_candidates:true only when planned models are relevant. It also names the default (seedance-2.5) so an agent knows when it can skip this call.

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

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

Beyond the annotations, the description discloses important operational behavior: quote_ugc should be called first at no credit cost, captions require user confirmation, get_run_status must be polled after submission, and intermediate files under 'So far' are not the final result. It also explains upload-panel behavior, image expiry, and that uploading does not automatically attach an image to a generation.

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 and alternatives are front-loaded well, but the definition is heavily bloated with general upload-panel instructions, fallback procedures, expiry rules, browser-panel caveats, and image-preview guidance. Much of that content is cross-cutting upload workflow rather than make_ugc-specific behavior, so many sentences do not earn their place in this tool definition.

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 15 parameters, no output schema, and sparse annotations, the description is complete enough for an agent to call the tool correctly. It covers the generation workflow, credit preflight, caption confirmation, polling, final-video retrieval, and the image/product upload path, including what happens when upload tools are unavailable.

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 73%, and the schema already documents the most important parameters such as script, image, product_image, character, scene, captions, and duration. The description reinforces some parameter roles and constraints, but it does not add much for undocumented fields like look, music, aspect_ratio, and caption_style beyond the enum values.

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 first sentence states the exact resource and outcome: a finished vertical UGC video from a script. It also distinguishes this convenience workflow from the direct generate_image, generate_video, and generate_audio tools, so an agent can recognize when make_ugc is the intended path.

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

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

The description gives explicit when-to-use guidance and explicit alternatives: use make_ugc when the server should choose takes and timing, but use the direct generators when the agent needs custom models, modes, shot structure, intermediate assets, or different composition. It further names quote_ugc as the zero-credit preflight and explains the image/product_image/character/scene roles.

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 the sparse annotations: accepted formats, 25 MB per-file and 10-image limits, 24-hour retention, no credit consumption, and a browser-link fallback for clients lacking inline panels. Missing only failure behavior (what happens if the panel is unavailable or the session expires mid-upload).

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 follow-up instructions — every sentence carries operational content. It is slightly dense, packing limits, cost, fallback, and chaining rules into one block, but nothing is filler.

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

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

With no input schema and no output schema, the description must carry the full contract, and it does: trigger condition, limits, lifetime, cost, return channels, and the exact next tool call. An agent can act correctly without any other 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?

Zero parameters, so the baseline is 4; the schema is a closed empty object. The description instead documents the outputs (session_id, image_url) and where to place them (refs, first_frame, skill image field), which is valuable but is return-value guidance rather than parameter semantics.

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

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

States a specific action (open a drag-and-drop image upload panel) and its resource (images), plus the user-facing intent (supply photos, portraits, products). It is clearly distinguishable from siblings like upload_image (direct upload) and get_uploads (retrieval after upload).

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 (user wants to supply image references), explicit anti-pattern ('Never ask the user to paste base64'), and an explicit next step ('After the user uploads, call get_uploads'). It also warns not to generate before images are ready, which routes the agent correctly relative to generate_image.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds value beyond them by stating the call is free ('Costs nothing'), that it returns credits at a stated conversion (1 credit = $0.01), the model that would run, and a breakdown. The 'Pass the same input' contract is also a behavioral rule not captured by 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?

Three tight sentences, front-loaded with the core action and the 'WITHOUT running it' distinction in the first line, followed by return shape and then usage triggers. 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 supplies the return contents (credits, model, breakdown) that would otherwise be unknown. It also covers cost and the input-passthrough contract, so an agent has everything needed for a 2-param preview 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%, with the `kind` enum and the `input` object already described structurally. The description reinforces the key semantic constraint that `input` must be exactly the arguments you would pass to generate_<kind>, and semantically ties kind to the corresponding sibling tool, which is meaningful 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 (price) and resource (a generate_* call) and explicitly distinguishes itself from the sibling generate_image/generate_video/generate_audio tools by saying it runs nothing. An agent can tell instantly what it does and what it does not do.

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 trigger conditions: before spending when the user asks about cost, when choosing between models, or before a clip longer than a few seconds. It also names the alternative behavior implicitly (call generate_* directly to actually run), leaving nothing to inference.

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

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

Annotations already declare readOnlyHint/idempotentHint true and destructiveHint false, and the description adds real context beyond that: no rendering, no credit consumption, and a balance check. It does not say whether a quote expires or what happens on invalid input, so it stops short of full 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?

Three short sentences, no repetition, and the safety-critical instruction (authorize before spending) lands at the end where it is most salient. Every sentence carries an instruction the agent must act on.

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 15-parameter, no-output-schema tool, the description correctly frames inputs as make_ugc's payload and mentions the 'returned price' as the output. Missing only edge-case behavior (quote staleness, error responses) for full completeness.

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 73% schema coverage the schema carries most of the burden, but the description adds a critical semantic the schema can't: the parameters are the exact make_ugc input, i.e. this call must mirror that tool's payload. Individual parameter behavior is left to the rich schema.

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

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

Opens with a specific verb+resource ('Price an optional make_ugc workflow and check the spendable balance') and explicitly distinguishes itself from make_ugc by noting it runs 'without rendering or using credits'. The only gap is the sibling 'quote', which is never mentioned, leaving the general-vs-UGC quoting split implicit.

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 workflow: pass the exact input intended for make_ugc, show the price to the user, and only call make_ugc after authorization. That is a when-to-use rule and a hard gate on the alternative, not an inference.

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

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

Annotations declare non-read-only, idempotent, non-destructive; the description adds things annotations can't convey: the call costs nothing, the run must already be finished, and ratings aggregate into list_models stats and model:"auto" selection. It stops short of saying what happens on re-rating an already-rated run or on an unknown run_id, so it's strong but not exhaustive.

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

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

Three sentences, front-loaded with the operation and scale, then triggers, then the incentive rationale. No sentence is redundant and nothing is buried.

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

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

For a three-parameter, non-destructive feedback tool with no output schema, the description covers cost, preconditions, triggers, and consequences of the data. An agent has everything needed to decide to call it and how to score honestly.

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 schema already defines the score anchors (1 unusable, 3 usable with edits, 5 shipped) and the note's one-line purpose, so the baseline is 3. The description adds only scoring-conduct framing ("an honest 2 helps more than a polite 4") rather than new format or constraint detail.

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

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

Names a specific verb (Rate) and resource (a finished generate_video/generate_image/generate_audio run), plus the 1-5 scale and the optional note. This cleanly distinguishes it from the generation siblings, which create runs rather than evaluate them.

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

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

Explicit triggers are given: the user reacts to an output (with quoted examples like "her face changed" or "too slow"), or the agent itself observes a defect. It also names the downstream consumer of the data, which tells the agent why and when the call matters.

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

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

Goes far beyond the annotations: no generation credits consumed, 25 MB ceiling (10 MB decoded for base64), 24-hour expiry on panel images, the two-phase put_url + upload_key handshake, and the fact that file bytes bypass the conversation entirely. It also warns that image previews are not to be used for generation and that the client renders tool arguments visibly, which is non-obvious and operationally important.

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?

Substantially over-long and poorly front-loaded: the tool's actual function appears only after paragraphs of guidance about sibling tools, generation orchestration, make_ugc, and polling. Several constraints (do not poll, never infer from filename, preserve image roles) are repeated or belong to other tools' descriptions. It reads as a merged system prompt rather than a definition.

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 does explain what comes back (put_url, upload_key, image_url, panel: keys, expiry) and covers limits, fallbacks, expiry recovery, and handoff to generators. It is nearly complete, losing a point only because the density makes the return-value contract harder to extract than it should be.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantic layering: the three input modes are ranked by preference, and the two distinct roles of upload_key (panel: key versus file-upload completion key) are explained. The only shortfall is that the file_bytes/curl round-trip sequence is described in prose that is longer than the schema 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?

The core purpose is stated, but only in the final third: "Store an image and get back a stable https URL you can pass to any agent-media tool." The first two paragraphs are routing instructions toward open_upload_panel and get_uploads, so an agent skimming the opening might conclude this tool's job is user-interaction orchestration rather than storing an image. The verb+resource is specific once found, but it is diluted by multi-tool workflow narration.

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 ordering is given: panel first if available, then file_bytes for a shell-accessible file, then image_url for a re-host, then image_base64 only as a last resort when 1 and 2 are impossible. When-not rules are equally explicit ("Do NOT paste base64 into other tool arguments or into the conversation", "never make a permanent copy", "do not build an upload page"). Alternatives and fallbacks are named with the conditions that select them.

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