AI Gateway MCP

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

With no annotations, the description carries the full behavioral burden. It discloses that this is a read-style lookup, that it is team-scoped, and that spend is measured over a 30-day window, but says nothing about auth/permission requirements, caching or freshness of the numbers, or whether the call itself consumes anything.

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

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

Two sentences, zero waste: the first defines the payload, the second defines the trigger. The purpose is front-loaded before the guidance.

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 lookup with no output schema, the description compensates by naming the returned facts (credits remaining, 30-day spend). It is nearly complete; only freshness/permission caveats are absent.

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 and the schema is an empty object, so there is nothing to document; per baseline this warrants a 4. The description correctly implies no input is needed.

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 ('Show how many AI Gateway credits are left') plus the exact data window for spend ('last 30 days'). It is unmistakably distinct from every sibling, which are all generative/edit operations.

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

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

Explicitly tells the agent when to call it: 'Use it before big jobs (many videos) to check there is enough.' No alternatives or when-not conditions are named, but there is no sibling that overlaps this function, so the omission is minor.

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 no annotations, the description carries the full burden. It does disclose input constraints (https links, links from this server are valid) and mask color semantics, but says nothing about cost, credit consumption, whether the call is synchronous or queued, or whether edits are non-reversible. Useful but incomplete for a paid generation endpoint.

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 practical usage details, then parameter hints. Every sentence carries information; the model-id list is slightly dense but directly actionable 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?

No output schema exists, yet the description covers inputs, model selection, and mask usage, and the schema documents all seven parameters. The remaining gap is behavioral: nothing about latency, async behavior, or billing, which an agent invoking a paid image edit 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 100% so the baseline is 3, but the description adds value beyond it: it names specific model ids to use for model, and clarifies the mask convention (white = area to change) and the models that accept a mask, which the schema only states generically.

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 (change/edit) and resource (existing images) and enumerates the concrete edit operations supported: background removal/replacement, add/remove objects, restyle, outpaint, reframe, and multi-image combine. The word 'existing' plus the operation list separates it cleanly from the sibling generate_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 actionable guidance: supply https links (and notes that links returned by this server work), recommends concrete good models, and explains when to pass mask_url with which model. It does not explicitly state the negative case (use generate_image for brand-new images), so it stops 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?

With no annotations, the description carries the full burden and does so: it discloses the double-charge/idempotency hazard on retry after timeout, the job_id handoff to get_video, resolution and shape-preservation guarantees, and the https constraint on inputs. This is unusually strong behavioral disclosure for a mutation 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 purpose and example, then constraints, then the critical retry-safety warning last. Every sentence contributes distinct information (examples, model, output shape, return value, link rule, retry hazard) 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?

No output schema or annotations exist, so the description must cover the essentials alone, and it does: what it does, return value (job_id for get_video), input constraints, output characteristics (720p, length/shape preserved), and failure handling. An agent has everything needed to call it correctly and safely.

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 value beyond the schema by giving concrete prompt examples and stating that links must be https and that server-returned links are valid, which clarifies the video_url contract; estimate_only and model remain schema-only.

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 (edit an existing video) with concrete prompt examples ('give the person sunglasses', 'make it snow') and names the backing model. This clearly separates it from generate/start/extend/motion_control siblings, which create rather than modify an input 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?

Provides rich contextual guidance: result preserves input length/shape at up to 720p, returns a job_id for get_video, links must be https and server-returned links work, and explicit when-not-to-act behavior on timeout (do not retry, tell the user). It does not name sibling alternatives (e.g., extend_video vs edit_video) for disambiguation, so it stops short of 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?

With no annotations the description carries the full burden and does so well: it discloses the return mechanism (job_id consumed by get_video, result is the new part), the underlying model, URL provenance constraints, and a cost-safety warning that a timeout retry pays twice. Cost, failure handling and output routing are all covered.

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 layers model, return value, constraints and failure handling in a logical order, with every sentence carrying information. Minor redundancy: the hard-coded model string and the estimate_only 'nothing is charged' point are already present in the schema descriptions.

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 and no annotations, so the description must explain returns and mutation-side effects; it does both by routing results through get_video via job_id and warning about double-billing on retry. Nothing an agent needs to invoke 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?

Schema coverage is 100% so the baseline is 3, but the description adds real meaning beyond the schema: 'Links must be https; links returned by this server work' clarifies acceptable video_url values, and the get_video/job_id note frames video_url as an existing job artifact. It does not add much for duration or prompt beyond what the schema already 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 with a concrete behavior: 'Continue a video from its last frame, so a scene keeps going', plus an illustrative example. This operationally separates it from start_video (new video), edit_video (alter existing), and upscale_video/motion_control without needing to name 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?

Gives clear context for when to reach for it (continuing an existing scene) and an example, and adds explicit retry guidance for timeouts. It does not, however, explicitly contrast itself with siblings like start_video or edit_video, leaving some selection inference to the agent.

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?

No annotations are provided, so the description carries the full burden. It usefully discloses return behavior (images returned inline; expiring private download links when a Blob store is connected), but says nothing about cost/credits, latency, permissions, or failure modes for what is a charged external generation 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?

Two tight sentences with the core purpose front-loaded and output behavior second; the examples earn their place by clarifying valid model ids. No wasted preamble.

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 annotations and no output schema, the description must carry behavioral and return semantics. It covers return format adequately, but cost/credit implications and when-not-to-use are left to the schema's estimate_only field, leaving real gaps for a multi-sibling generation 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 80%, so the baseline is 3. The description's model examples ('bfl/flux-2-pro', 'openai/gpt-image-2') add slight context for the required model param, but it adds no syntax or format detail for prompt, n, size_or_aspect, or estimate_only.

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 ('Generate images') and distinguishes two accepted model classes (AI Gateway image models vs image-capable LLMs) with concrete ids. It is clearly separable from edit_image/upscale_image by verb, but never names those siblings 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?

No when-to-use guidance: it never says when to pick this over edit_image, upscale_image, or which model class to choose for a given task. Only the schema's estimate_only param hints at a preview workflow, and that is not surfaced in the description.

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?

No annotations exist, so the description carries the full burden, and it does disclose two real behaviors: audio is returned inline, and a private, expiring download link is produced only if a Blob store is connected. It omits cost, text-length limits, latency, and whether the link's expiry/size is configurable, leaving meaningful gaps for a no-annotation 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?

Three sentences, front-loaded with the core action, then return behavior, then model/voice discovery. No filler, no restatement of the tool name, and the list_models pointer is placed exactly where model selection becomes relevant.

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 describing the return (inline audio plus conditional expiring Blob link). Combined with a fully-described 7-param schema, an agent has enough to invoke correctly; only cost/length/rate expectations 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?

Schema coverage is already 100%, so the baseline is 3, but the description adds genuine selection value: it enumerates concrete model ids ("openai/tts-1-hd", "google/gemini-3.8-flash-tts", etc.) and voice examples ("alloy", "nova", "onyx") that the schema only describes generically. It stops short of explaining interactions like model-dependent support for "instructions" or "language".

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 ('Turn text into spoken audio') and immediately scopes the domain with concrete use cases (narration, voice-overs, audiobook chapters, podcast intros). It is unmistakably distinct from siblings generate_text, generate_image, transcribe, and start_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?

It routes the agent to list_models with type "speech" to discover models and prices, and warns that voices are model-specific with per-model examples. However it gives no explicit exclusions or when-not-to-use guidance relative to siblings like transcribe (speech-to-text) or generate_text.

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 no annotations, the description carries the full burden and does meaningful work: it discloses billing against the deployment owner's credits, that only https links are accepted, and that links returned by this server are valid. It omits return shape, latency, and rate/limit behavior, which keeps 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?

Front-loaded with the core action and cost, and every sentence carries information. The second half is one long run-on with stacked parenthetical examples, which costs some readability without adding waste.

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 5-param, no-annotation, no-output-schema tool it covers purpose, cost, model selection, and the media-input path. Remaining gaps are return format and failure behavior, which are secondary for a single-shot generation call.

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 60%, so the schema documents model, system, and file_urls but leaves prompt and max_tokens bare. The description compensates by explaining what file_urls actually does (media the model reads, per-model capability) and pointing at list_models for valid model ids, adding real semantics 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 (generate text) plus the concrete mechanism (AI Gateway language models) with an example model id. It is immediately distinguishable from siblings such as generate_image, generate_speech, and transcribe.

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 to list_models for model discovery and explains the file_urls branch (use it when the model must read media). It does not state exclusions against siblings, but the text-generation scope is unambiguous from the verb.

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 no annotations, this description carries the full load and does so well: it discloses the two outcome states ('still generating' vs done), that returned download links are private and expire, and that calling again reissues fresh links. It also mentions billing attribution (AI Gateway billed), so the agent knows the cost-inspection aspect is bundled into the 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?

Two dense sentences, front-loaded with the action and source tool list, followed by the return semantics and expiry caveat. 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 single-input polling tool with no output schema, the description covers the call trigger, the two possible return shapes, link expiry behavior, and re-issuance behavior. Nothing an agent needs to invoke 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 value by indicating job_id must come from one of the specified video tools, which reinforces the dependency beyond the schema's generic 'returned by a video tool' phrasing.

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 (Check) and resource (a video job) and explicitly names all five sibling tools that produce the job (start_video, motion_control, upscale_video, edit_video, extend_video), so an agent can route unambiguously.

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 identifies the source of the job_id via the named sibling tools and explains the re-call behavior for expired links. It does not explicitly state when NOT to use it (e.g., use start_video for launching new jobs), but the input dependency makes the trigger condition 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?

With no annotations, the description carries the full burden, and it discloses three non-obvious traits: results are ordered newest first, the returned links are freshly minted and expire, and a Blob store connection is required. It omits auth requirements and anything about pagination beyond the limit cap already 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?

A single dense sentence front-loads the resource and scope, then appends the two operational caveats (link expiry, Blob store requirement). Nothing is padded and nothing important 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 two-optional-parameter read tool with 100% schema coverage and no output schema, the description supplies what the schema cannot: ordering, link volatility, and the connection prerequisite. Return-value detail beyond 'links' is thin, but adequate for this complexity level.

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 'kind' and 'limit' are already documented with enum values, defaults, and bounds. The description only restates the media kinds and the newest-first ordering, which the schema already conveys — 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?

Specific verb (list) plus a tightly scoped resource — the media assets this connector previously generated — with ordering ('newest first') and payload shape ('fresh private links'). It is easily distinguished from siblings like list_models, which enumerate models rather than generated files.

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 a hard prerequisite ('Needs a connected Blob store'), which tells the agent when the call is even viable, and implies the retrieval use case for prior outputs. It does not name an alternative or an explicit when-not-to-use condition, but no sibling competes for this job.

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?

No annotations are present, so the description carries the full behavioral burden. It does add real value by disclosing the return shape ('one line per model: id | type | capabilities | price'), which is not in any schema. It omits anything about ordering, pagination, or read-only/auth characteristics.

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 earning its place: purpose, filters, and return format. The core purpose is front-loaded and nothing is repeated from the schema verbatim without added 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-optional-parameter list tool with no output schema, the description is nearly self-sufficient: it names the filter axes and describes the returned line format. Only minor gaps remain (ordering, result limits, whether an empty filter returns everything).

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%, which sets a baseline of 3, but the description goes beyond it: it decodes the ambiguous enum values ('speech for text-to-speech, transcription for speech-to-text') and explains the query semantics ('case-insensitive match on model id or name'). That is genuine semantic uplift over the raw 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 ('List') and resource ('AI Gateway models this server can call'), and the filtering dimensions make clear this is a discovery/catalog tool. This cleanly distinguishes it from every sibling, which are all generation or file-manipulation actions.

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 makes the tool's role and its two filter dimensions clear, so usage is implied (discover available models before invoking generate_*). However, it never states when to reach for this versus an alternative, nor any prerequisite such as needing a resolved model id before generation.

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 no annotations present, the description carries the full behavioral burden and does so well: it discloses the default model, that output length is tied to the reference video (up to 10 s with orientation "image"), that only https links are accepted, that server-returned links work, and a non-obvious timeout/retry hazard that would otherwise cause double billing. That retry warning is exactly the kind of trait structured fields cannot express.

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

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

The purpose sentence is front-loaded, followed by default model, output length, return value, and the retry caveat in roughly priority order. Every sentence carries information an agent needs; 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?

For an 8-parameter generation tool with no annotations and no output schema, the definition covers inputs, defaults, output (job_id for get_video), duration, link requirements and failure behavior. Remaining gaps are modest – no cost framing outside the schema's estimate_only, and no permission or async-polling detail – but nothing essential to 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 description coverage is 100%, so the baseline is 3 and the schema already documents every parameter including defaults and enums. The description adds practical meaning beyond the schema by explaining the https constraint on both URLs and that links produced by this server are acceptable, plus the duration consequence of the orientation choice.

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 – animate the character in an image using the motion from a reference video – and implicitly separates itself from siblings like start_video, extend_video and edit_video by naming both inputs (image_url + video_url). The agent can identify exactly what the tool produces 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 operational guidance: it names get_video as the follow-up for the returned job_id, and explicitly says not to retry on timeout because a job may already be running and a retry pays twice. It does not explicitly contrast itself with start_video or other video siblings, so the when-to-use-vs-alternative story is clear from context 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?

With no annotations present, the description carries the full burden and does so well: it discloses the async job model, expected polling cadence (~30s) and duration (1-5 min), the fact that retries are charged twice, the https-only URL constraint, and that estimate_only starts nothing and charges nothing. Almost no behavioral gap remains for a job-launching 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 start-and-poll instruction is correctly front-loaded and every sentence carries non-redundant information - no filler. It is dense and parenthesis-heavy, though, which slightly hurts scannability for an agent parsing modality branches.

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 and no annotations, yet the description covers the return value (job_id), the polling loop, typical completion time, the timeout/retry hazard, and cost caveats. For a 9-parameter async-launch tool, nothing needed to call it correctly is missing.

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

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

Schema description coverage is already 89%, so the baseline is 3. The description adds real meaning beyond the schema by mapping parameters to model families and conventions - i2v for image_url, Veo/Kling/Seedance for end_image_url, r2v plus the 'character1, character2…' prompt convention for reference_urls, and audio-capable models for sound. It does not, however, add anything for duration or aspect_ratio 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 ('Start an asynchronous AI Gateway video') and immediately pairs it with the return contract ('return a job_id immediately'). The follow-up instruction to poll get_video makes it distinguishable from generate_image, edit_video, and extend_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?

Explicitly routes by modality: prompt-only for text-to-video, image_url for i2v, end_image_url for first-to-last-frame, reference_urls for r2v with named characters, and sound for dialogue. It also names the alternative action on timeout ('do not call it again... let them decide'), which is exactly the when/when-not guidance an agent needs.

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 no annotations, the description carries the full behavioral burden and delivers real constraints: the 25 MB upload cap and the https-link requirement. It also notes timestamps are returned only 'when the model returns them', which preempts a false expectation of guaranteed timestamps. It stops short of describing error behavior or output formatting.

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 compact sentences with the core purpose front-loaded, then the optional capability, then the operational constraint and model routing. Every sentence carries information; only slight density loss from the parenthetical use-cases.

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 3-parameter tool with no output schema and no annotations, the description covers purpose, input constraints, model selection path, and the optional timestamps behavior. A brief note on the returned text format would close the remaining gap, but nothing needed to invoke 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, but the description earns above baseline by enumerating concrete model ids ("openai/gpt-4o-transcribe", "openai/whisper-1", "google/gemini-3.5-transcribe") that the schema has no enum for, and by restating the 25 MB ceiling on audio_url that the schema omits.

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 (turn speech in audio/video into text) and immediately scopes it with the optional-timestamps variant, distinguishing it from audio-adjacent siblings like generate_speech (text→speech) and generate_text. An agent can tell exactly what this tool produces 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 invocation guidance: supply an https link, max 25 MB, and pick a model from list_models with type "transcription", explicitly pointing to the sibling that resolves the model argument. It does not explicitly state when-not to use it, but the transcription framing is unambiguous against the sibling set.

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?

No annotations, so the description carries the burden. It discloses the default model and the cost-free nature of estimate_only indirectly, but never states what a normal invocation returns (a URL? an image?), whether the real run is charged, or any latency/rate limit.

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, front-loaded with the core action and constraint before the model default and link requirement. Nothing is wasted.

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

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

With no annotations and no output schema, the description should explain what comes back from an upscale call; it does not. It is adequate for invoking the tool but leaves the agent guessing about the return shape and cost implications of a real run.

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

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

Schema description coverage is 100%, so the schema already documents model, prompt, image_url and estimate_only. The description adds only the model default and the provenance hint for image_url, which is a marginal gain 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 (sharpen and enlarge an image) and, crucially, the scope constraint 'without changing what is in it', which separates it from edit_image and generate_image 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 practical context (default model applies unless you name another; image_url must be an https link and 'links returned by this server work'), but never states when to choose this over upscale_video, edit_image, or 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?

With no annotations, the description carries the full burden and delivers: it discloses pricing is based on input video length, that a job_id is returned for get_video, the link scheme constraint, and the critical failure-mode warning that a timeout/empty response may mean the job is already running and a retry double-charges. This is exactly the behavioral context an agent needs before invoking a paid async job.

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 layers model choice, pricing, return value, link constraint, and the retry warning. Every sentence carries actionable content, though the paragraph is dense and could be slightly tighter.

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 asynchronous video job with no output schema, the description covers what it does, what it returns (job_id for get_video), how it is priced, the input constraints, and the retry hazard. An agent has everything needed to invoke it responsibly.

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 documents each parameter including the default model, so the baseline is 3. The description adds the alternative model name and the https-link constraint, but nothing about resolution syntax or the estimate_only semantics 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 set (sharpen, enlarge, denoise) on a specific resource (video), which cleanly distinguishes it from siblings like upscale_image and edit_video. It even names the underlying models used, so an agent knows exactly what this call 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?

Gives clear context: default vs alternative model choice, the https link requirement, and the explicit instruction not to auto-retry on timeout because a retry pays twice. It does not explicitly frame when to choose this over upscale_image or edit_video, 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.