FXI Studio

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

Goes well beyond the annotations (readOnly=false, destructive=true, idempotent=true) by disclosing the race-condition outcome (finishing just before the cancel lands means you keep the result and no refund), the no-double-refund guarantee, and that upstream compute spend is not clawed back. These are exactly the mutation consequences an agent needs before calling.

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

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

Front-loaded with the core action and refund, then layered with edge cases in short sentences; nothing is filler. The single cryptic lifecycle_status sentence is the only slightly wasteful/ambiguous element.

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

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

For a one-parameter mutation with annotations covering the safety profile and no output schema, the description supplies everything an agent needs: refund behavior, race semantics, idempotency, and the shape of the return ('its current state').

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 single parameter already documents its origin (generate_image or generate_video), so the baseline is 3. The description adds no format, validity, or lookup guidance beyond what the schema states.

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 ('Cancels one of your generations that is still running') plus the side effect (full credit refund). An agent can distinguish it from get_generation or generate_image without opening a schema.

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

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

Implies when to use it (running generations, expecting a refund) and explicitly says calling it on a terminal generation is safe, which prevents wasted agent caution. It stops short of naming an alternative tool for inspection or recovery, and the 'Prefer lifecycle_status over the legacy status word' hint is unexplained.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false, so the description must add the behavioral context — and it does: this 'Spends credits', it returns a task id, and progress is checked via get_task. It doesn't explain failure/refund behavior or what wait_for_completion's 'short while' means. Note the idempotentHint=false annotation is not contradicted: the description's idempotency_key is an opt-in per-request safety mechanism, not a claim of tool-level idempotency.

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, each doing distinct work: what it makes, its cost and async return path, and the alternative tool. The cost and task-id facts are front-loaded where they matter.

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

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

For a 9-parameter, credit-spending, async generation tool with no output schema, the description covers the essentials an agent needs: cost, task id return, and the polling tool. It omits error/partial-failure behavior and the interaction of wait_for_completion with polling, which keeps it short of 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?

With 100% schema description coverage, the schema already documents all 9 parameters, including character_ids limits and the atmosphere_id/opening_image_upload exclusivity. The description adds only light reinforcement ('up to 4 of your saved characters', 'saved or uploaded images'), which is baseline 3 territory rather than new 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?

States a specific verb and resource ('Generates one short video clip from a written brief') and immediately bounds the optional inputs (up to 4 saved characters, one image as opening frame). It explicitly distinguishes itself from the sibling generate_video, so an agent can route without opening either schema.

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

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

Names two concrete alternates and their conditions: use generate_video for 'full control over a single shot', and use get_task to check the returned task id. The guidance is clear, though 'full control over a single shot' is a somewhat fuzzy criterion and no other siblings (frame_chain, generate_image) are addressed.

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 declare destructiveHint=true, and the description usefully scopes that destruction — only 'a file that fails the check is deleted' — which is real context beyond the annotation. It also confirms idempotent-style behavior implicitly. It stops short of describing error semantics (does a failed check raise or return a status?) or what happens to the upload_id afterward, so it is 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?

Four compact sentences, front-loaded with what is checked and what is returned, followed by the deletion caveat and the optionality note. Every sentence carries distinct information; nothing 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 compensates by naming the returned fields (media type, size, dimensions, duration, asset_url). Combined with the optionality and deletion notes, an agent has everything needed to call this 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 100% for the single parameter (upload_id, with a description pointing back to create_upload_url), so the schema already carries the semantics. The description adds no syntax or format detail beyond it, making the baseline 3 correct.

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 ('Checks an upload started with create_upload_url') and enumerates exactly what is verified — arrival, size limit, declared type — plus what it reports. It is clearly distinguishable from siblings like create_upload_url and upload_media_data.

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 the ordering precondition (must follow create_upload_url), the purpose (obtain asset_url for generation tools), and explicit when-not guidance: 'Generation tools run the same check themselves, so this call is optional.' An agent can decide whether to call it without 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 mark this as non-read-only, non-idempotent and non-destructive; the description adds substantial behavior beyond that — the URL is short-lived, bytes go via HTTP PUT with the returned upload_headers, and asset_url is verified automatically. It still omits how long the URL lives and whether repeated calls create duplicate uploads.

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, downstream tools, return usage, and limits are packed into one front-loaded paragraph with no filler. It is dense but every clause carries operational information; a small readability cost for the run-on handoff sentence.

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 returned fields (upload_url, upload_headers, asset_url) and explains exactly how to use each, plus size/duration limits. Nothing needed to complete the upload-then-generate flow 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 both parameters are documented, so the baseline would be 3. The description earns extra credit by giving per-type limits (images 20 MB, video 200 MB/30 s, audio 50 MB), which supplies meaning to size_bytes and constrains content_type beyond the enum list.

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 plus resource ('Starts an upload of your own image, video or audio') and immediately names the downstream consumers. It is clearly distinguishable from the other upload siblings (upload_from_url, upload_media_data, confirm_upload) because it produces a URL to PUT bytes to rather than accepting an existing URL or inline data.

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 concrete usage context (own media for generate_video, generate_image, frame_chain, compose_scene) and the full handoff sequence to a generation tool. What is missing is explicit routing versus upload_from_url and upload_media_data, which an agent must otherwise infer from names alone.

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 behavior beyond the annotations: credit spend per clip, the rule that a clip which cannot start is not charged, the async task-id model with get_task as the polling sibling, and the fact that output is unjoined clips. These are exactly the side-effect and output facts an agent needs and the annotations do not 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?

Four tight sentences, front-loaded with the chaining definition, then cost, then return/next-step, then output shape. No sentence is redundant with another and none restates the tool name.

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 the return contract (task id, retrieve URLs via get_task, separate clips) and the billing model. Combined with a fully documented schema, an agent has everything needed to invoke and follow up correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real semantic value by explaining how initial_frame_uri relates to the scenes array (it seeds the first clip) and that scenes are ordered and chained, which the schema structure alone does 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?

States a specific verb and resource plus the defining mechanism: 2-8 clips where each starts from the last frame of the previous one. This clearly separates it from sibling generate_video (single clip) and compose_scene without requiring the schema to be opened.

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

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

Gives clear operational context (first clip seeds from your image, check progress with get_task, output is separate clips not a joined file). It never explicitly says when to prefer this over generate_video or compose_scene, so it stops short of full alternative 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?

Adds substantial context beyond the annotations: it spends credits, typically resolves within ~25 seconds, and returns either an image URL or a generation id for polling via get_generation. It even steers the agent to lifecycle_status over the legacy status field. Nothing here contradicts the declared non-read-only, non-idempotent 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-loads what it does, then cost, then return/async behavior and model default in three tight sentences. The parenthetical about lifecycle_status is slightly tangential but is actionable guidance rather than 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 correctly takes on return-value explanation (URL vs. generation id) plus cost and latency. It covers what an agent needs to invoke and follow up, though it leaves failure behavior and the estimate_only/idempotency interactions entirely to the schema.

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

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

Schema coverage is 100%, so the schema already documents all ten parameters including the model enum and the deprecated model_id alias. The description restates the prompt/reference-image/aspect-ratio surface and the default-model behavior, adding prose framing but little new parameter meaning. Baseline 3 applies.

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

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

States a specific verb and resource (generates one image from a prompt), names the optional inputs, and states the persistence target (your FXI library). It also distinguishes itself from generate_video and compose_scene by scoping to a single still image.

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 routing context: prefer the fast default model unless the user names another, and poll with get_generation when only a generation id comes back. It does not explicitly cover when to prefer estimate_only or idempotency_key retries, though those are documented in the schema.

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

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

Annotations already cover readOnly=false, openWorld=true, idempotent=false, destructive=false. The description adds important behavioral context: it spends credits, returns a generation id, typically takes 1-3 minutes, and recommends checking lifecycle_status. It also notes the need to upload files first. It does not mention idempotency_key or voice_consent requirements, which the schema covers.

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

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

Front-loads purpose in the first sentence, then efficiently covers optional inputs, prerequisites, cost, and next steps. Every sentence is informative with no 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 complex 20-parameter tool with no output schema, the description provides the essential context: what it does, required uploads, cost implications, return value (generation id), and how to check status. The rich schema fills in parameter details, so the description is complete enough for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters. The description only lists optional input categories (start/end frames, reference images, reference video, reference audio) without adding syntax, format, or usage details beyond what the schema provides. Baseline 3 is appropriate when schema does the heavy lifting.

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 ('Generates') and resource ('one video clip from a prompt'), and clarifies the output destination ('saves it to your FXI library'). Distinguishes from sibling generate_image by specifying video, and from compose_scene/frame_chain by focusing on a single clip from a prompt.

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

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

Provides clear context for use: prerequisite upload via create_upload_url or upload_from_url, and follow-up check with get_generation. It also names optional input types. However, it does not explicitly compare to alternatives like compose_scene or frame_chain, nor state when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the account scoping ('signed-in FXI Studio account') and the two fields returned, which is modest added context beyond the structured 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?

A single front-loaded sentence with zero filler; the returned values are stated immediately after the scope qualifier. Nothing could be removed without losing 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 and does state both return values (credit count and plan name). What is missing is any indication of the value format (numeric vs formatted string) or behavior when credits are exhausted, but the definition is otherwise adequate for a zero-param read.

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 are no parameter semantics to document; the baseline for a zero-parameter tool is 4. The description correctly implies no input is required, matching 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?

Specific verb-and-resource statement: returns remaining credits and the plan name for the signed-in account. It is unmistakably distinct from every sibling, which are all generation/upload operations, and an agent can select it without opening the schema.

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

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

The use case is implied by the description ('check credit balance' for the signed-in account), but there is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives. For a trivial zero-parameter read tool the omission is minor, but the description provides no routing help.

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

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

With annotations already declaring readOnly/idempotent/non-destructive, the description adds real behavioral context beyond them: lifecycle_status enumerations with semantics ('expired - took too long, credits auto-returned'), the legacy status field distinction, UTC/ISO 8601 timestamps, and the 25s long-poll cap. This is unusually informative for a read tool.

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

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

Front-loaded with the return payload, then constraints, then sibling routing; nearly every clause carries information. Slightly dense with stacked parentheticals, 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?

No output schema exists, yet the description enumerates the return fields and explains status semantics, polling, and the cancel path, so an agent can call and interpret it. It omits error behavior (e.g. unknown or unauthorized id), a minor 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 description coverage is 100%, so both parameters are already documented, and the description's wait_seconds explanation largely restates the schema's long-poll text. Baseline 3 is correct; the added status vocabulary describes return fields, not 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 and resource ('Returns one of your saved generations by id') and enumerates the returned fields (media URL, prompt, type, model, lifecycle_status, credits), so the agent knows exactly what it gets back. It also names the sibling cancel_generation for the stop-a-run case, making it distinguishable from the other 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?

Gives concrete selection guidance: use wait_seconds to long-poll rather than getting an immediate 'running', and use cancel_generation to stop a running job. It doesn't state when NOT to use this tool (e.g. versus get_task), but the polling and cancel routing cover the main decision points.

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 readOnly, idempotent and non-destructive behavior, but the description adds useful return behavior: the exact fields returned and the possible status values. It does not cover auth needs, rate limits or error behavior, so a 4 is appropriate.

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

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

Two sentences, front-loaded with the return payload followed by the status enumeration. Every sentence earns its place 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?

There is no output schema, so the description carries the burden of return-value disclosure; it lists the key returned fields and all status values. With annotations covering the safety profile, this is complete enough for an agent to invoke the tool 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%, and the task_id parameter is already documented in the schema as the id returned by frame_chain or compose_scene. The tool description adds no further syntax, format or validation meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb, 'Returns', and concrete resources: status, per-clip progress, credits used and clip URLs. It scopes the tool to frame_chain or compose_scene tasks, which distinguishes it from siblings such as get_generation or cancel_generation.

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?

Identifies the applicable task types (frame_chain and compose_scene), giving clear context for when to use this tool. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the closing 'Changes nothing.' is largely redundant reinforcement. The description does add a modest behavioral fact by naming the fields returned (id/name, id/URL/date), but does not cover limits, ordering, or edge cases beyond that.

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

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

Two tight sentences: first the inventory of what is returned, then how to consume the ids, then the safety note. No waste and the key content is front-loaded.

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

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

With no output schema, the description correctly compensates by enumerating the returned fields (character id/name; image id/URL/date). Combined with the downstream id-usage guidance, an agent has everything needed to call this and use its output.

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

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

There is exactly one parameter (image_limit) and schema description coverage is 100%, including its default of 10 and 0-30 range, so the schema fully carries the semantics. The description never mentions image_limit or how it affects the result, so it adds nothing beyond the schema — the baseline 3.

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

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

Specific verb+resource ('Lists your saved characters... and your most recent saved images') with the exact fields returned called out. It is clearly distinguishable from every sibling, all of which are generation, upload, or mutation tools.

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

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

The description explicitly tells the agent how the returned ids feed into downstream tools ('Use a character id for generate_video character_id or compose_scene character_ids, and an image id for compose_scene atmosphere_id'), which is strong contextual routing. It stops short of stating when not to use it or any prerequisite conditions, so it falls short of a 5.

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

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

Annotations already establish readOnly/idempotent/non-destructive/closed-world, so the lower bar applies. The description still adds non-obvious behavior: video cost estimates assume a 5s clip, and the listed credits are estimates only unless an exact quote is requested. That caveat materially affects how an agent should present costs.

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?

Roughly five front-loaded sentences with no filler, leading with what is listed and closing with how to act on the fields. Slight redundancy in listing cost/credits fields twice ('estimated credit cost' then 'credits') keeps it just short of 5.

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 return fields and does so thoroughly (grouping, type, cost, tier, latency, speed_tier, typical_seconds, best_for), plus the estimation caveat. An agent has everything needed to call it and use the result.

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

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

Schema description coverage is 100% with all three parameters enum-documented, so the baseline is 3. The description reinforces the filters and clarifies that sort 'cost' orders by estimated credits, but adds little beyond the schema text itself.

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 ('Lists available image/video models') and goes further by enumerating the shape of each entry (output type, credit cost, price tier, mode/latency, speed_tier, best_for). It also explicitly distinguishes itself from the generation siblings by saying each 'model' value passes to generate_image or generate_video.

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

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

Gives concrete usage context: filter by role or output_type, use sort 'cost' for cheapest first, and pass estimate_only to generate_image/generate_video for an exact quote. It routes the agent to the sibling tools that consume the output, though it does not state explicit 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 supply the safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), so the bar is lower. The description still adds real behavioral context the annotations lack: a 50 MB size cap, private-network refusal, and the fact that the file is validated ('checks it') before an asset_url is returned.

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

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

Two sentences, zero filler, front-loaded with what is copied and where it lands, then the size limit, fallback tool, and refusal rule. Every clause carries operational 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?

Covers the full call cycle for a one-parameter tool: source constraint, size limit, validation, return value (asset_url) and the tools that consume it. No output schema exists, but the description names the returned field, so nothing an agent needs is missing.

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

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

Schema coverage is 100% and the schema already warns 'not a web page about it,' so the baseline is 3. The description goes a step further by requiring a public https link that 'downloads the file directly,' reinforcing the same constraint for the single url 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?

States a specific verb and resource ('Copies an image, video or audio file from a public https link') plus the destination ('your FXI uploads') and the returned handle ('asset_url'). It also distinguishes itself from create_upload_url by naming the size threshold at which that sibling takes over.

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

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

Gives a clear condition for the alternative ('use create_upload_url for larger files') and names the four downstream tools that consume the resulting asset_url, which tells the agent when it should reach for this tool. It does not say when to prefer upload_media_data for local files, which is the one gap.

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; the description goes well beyond them by disclosing the effective size cap (3 MB, server-dependent), the fact that the file is validated ('checks it'), and the exact overflow error code plus escalation path. It stops short of stating auth requirements or that repeated calls are non-idempotent (each returns a new asset_url), which would be the remaining useful disclosures.

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

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

Two sentences, both fully loaded: the first front-loads the fallback role, size limit, validation, and return payload; the second handles the overflow case. No filler or restatement of the title.

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, and the description compensates by enumerating the return payload (asset_url, media type, size, dimensions, duration) as well as the failure mode and its successor tool. For a two-parameter, non-open-world upload tool, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning the schema cannot: the effective 3 MB server limit, which is far tighter than the schema's 45,000,000-character maxLength and is the value an agent actually needs to self-screen payloads. It adds nothing for content_type, which the schema already documents fully.

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 small file inline as base64) plus the scope constraint ('small', with the concrete 3 MB figure). It explicitly distinguishes itself from the sibling create_upload_url, so an agent can route without opening either schema.

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

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

Names the exact precondition for use ('Fallback for clients that cannot make network calls') and the alternative for the other case ('A larger file ... use create_upload_url for it'). It even supplies the discriminating error code (upload_too_large_inline) and field (max_bytes), 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.