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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered structurally. The description adds the currency unit and the parameterless nature, which is genuinely useful, but says nothing about failure modes (missing account, auth) or freshness of the balance value.

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

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

Two short sentences, return value front-loaded and the invocation constraint second. Nothing is padded or repeated from the schema.

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

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

For a zero-parameter, read-only tool with an empty schema and no output schema, the description tells the agent what it gets back (current balance in USD) and that no inputs are needed. Nothing further is required 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?

The tool takes zero parameters, which is the baseline-4 case per the rubric. 'Takes no parameters' correctly confirms the empty schema without contradicting it.

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

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

States a specific verb+resource ('Return the account's current balance') and pins the unit to USD, so there is no ambiguity about what is fetched. No sibling among the media/task tools overlaps with it, so the agent can select it 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 only usage-adjacent sentence is 'Takes no parameters,' which is a schema fact rather than guidance. There is no statement of when to reach for this tool, no prerequisites (e.g., an account must be configured), and no alternatives mentioned.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the meaningful guarantee of no account charge, but says nothing about rate limits, validation failures, or how the estimate relates to actual billing.

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, zero filler, with the differentiating constraint (no creation, no charge) front-loaded ahead of the parameter instruction.

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

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

For a two-parameter read-only tool with a 100% documented schema and full annotation coverage, the definition covers purpose and the no-side-effect guarantee adequately. It stops short of noting what the estimate returns or how closely it tracks final billing, but those are minor given no output schema exists.

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

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

Schema description coverage is 100%, so both parameters are already thoroughly documented (the nested 'input' description is exceptionally rich, covering translations and docs lookup). The description's 'Pass the model and the full input payload' adds no meaning beyond that baseline.

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

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

States a specific verb+resource ('Estimate the cost of a task') and immediately scopes it against the generation siblings by clarifying it neither creates the task nor charges the account. An agent can distinguish it from generate_video/image/audio/music 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 phrase 'without creating it or charging the account' implies the use case (preview price before committing to a generation), but no alternative is named and no explicit when/when-not condition is given. Usage must be inferred from the contrast with the generation tools.

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

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

Annotations already declare a non-read-only, destructive, non-idempotent, open-world write, so the safety profile is covered. The description adds the default model and the return value ('Returns the video URL'), but says nothing about credit spend, per-model constraints on image_urls count, or what makes the operation destructive. Useful but thin beyond 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?

Four dense sentences, front-loaded with the core action and routing before the return value. Every sentence carries information, though the model-alias list and the sibling list together make it longer than strictly necessary for a tool whose schema already documents model aliases.

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

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

For a 10-parameter mutation tool with no output schema, the description covers the two operating modes, the routing alternatives, the default model, and the return value. It does not address long-job/polling behavior or cost confirmation, but those live in the schema parameter descriptions, so the agent has enough to call 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. The description reinforces the two required parameters ('Pass the source in video_url and the change in prompt') and ties image_urls to motion-control, but adds no format, syntax, or constraint detail beyond the schema's own descriptions.

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

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

States a specific verb+resource ('Edit an existing video') and covers the two distinct modes (prompt edit vs. motion transfer onto a subject image). It explicitly names the siblings it is not (generate_video, extend_video, upscale_media), so an agent can route without opening any schema.

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

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

Gives explicit when-to-use routing against three named alternatives, plus the intra-tool choice of model ('kling-edit', 'wan-edit', 'motion-control') and the condition that selects motion-control (subject image in image_urls). Nothing is left 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 the mutating/destructive/non-idempotent profile, so the description earns credit for adding real context: chaining is undocumented and may fail, extenders are model-internal, aspect ratio is inherited, and Veo requires a prompt. The main gap is it doesn't address cost or what a successful call returns in narrative form.

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 core purpose and mode differences in a compact span with little filler. Slight redundancy remains (the own-model constraint is restated in both the description and the task_id schema), but every sentence carries actionable content.

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 12-parameter, no-output-schema mutation tool with nested provider_options, this covers model selection, mode requirements, failure fallback, and inheritance rules well. It leaves the async/wait behavior mostly to the schema, which documents it thoroughly, so nothing critical 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 value by grouping parameters into model-specific modes (Veo requires prompt; Grok custom mode requires prompt + extend_at + extend_duration) and noting inherited aspect ratio — synthesis the schema alone doesn't provide.

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 (extend a previously generated video) and immediately scopes it with the model-internal constraint. It is clearly distinguishable from generate_video and edit_video siblings by being an extension of an existing generation via task_id.

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 conditions: pass the task_id of a *completed* generation, use prompt for Veo, preset vs custom for Grok, and it explicitly warns about the undocumented chaining case with a fallback ('regenerate at the target length'). It does not explicitly name sibling alternatives (edit_video/generate_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.

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

Annotations already declare destructiveHint=true and openWorldHint=true, and the description adds the return contract ('Returns the audio URL (or the transcript for \'stt\')') plus mode-specific input requirements. It does not itself mention credit spend, the confirm_cost quote flow, or async polling — those live only in the schema — so it adds value without fully covering the cost side of a billing-affecting 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-loads the general purpose, then walks the modes in a tight parallel construction, and closes with the return value and the music alternative. The single dense paragraph is efficient though it becomes slightly hard to scan at six modes; no sentence 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?

For a 12-parameter, nested-object, no-output-schema tool, the description covers mode routing, required inputs per mode, and the return value. The gaps (async/callback behavior, cost confirmation) are documented in the schema rather than the description, so an agent calling this correctly still has what it needs.

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; the description goes further by encoding cross-parameter relationships — dialogue turns go in 'dialogue' rather than 'prompt', stt/voice-changer/voice-isolation take 'audio_url', tts takes 'voice_id' from list_resources. That mode-to-parameter mapping is genuinely useful disambiguation beyond a flat field 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 concrete verb+resource ('Speech and sound') and then enumerates the six distinct operations (tts, sfx, dialogue, stt, voice-changer, voice-isolation) with the model alias that selects each. It explicitly separates itself from generate_music, so an agent can route 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 per-mode selection guidance ('model \'sfx\'', 'model \'dialogue\'', etc.) and names the sibling alternative with a condition ('For music, use generate_music'). It does not state exclusions for the neighbouring media tools (generate_video/image) or for when to prefer upload_file flows, so it stops just short of full when/when-not coverage.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotent=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact not in the structured fields — the return value is an image URL — but says nothing about credit spend, per-model limits, or the long-job polling path, so it adds only modest context beyond 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?

Three short sentences, front-loaded with the core capability, then the editing path, then the return value, then the sibling exclusion. No filler or redundancy.

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

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

With no output schema, stating 'Returns the image URL' closes the most important gap for a 12-parameter generative tool. The remaining complexity (cost confirmation, callbacks, provider_options) is fully handled by the schema, so the description is complete enough for correct invocation, though it could note the cost/credit dimension.

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 all 12 parameters thoroughly, including defaults, wait/callback semantics, and the provider_options escape hatch. The description only restates the image_urls editing usage and the default model, adding little beyond what the schema provides; 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 ('Generate or edit an image') and covers both modes (generation and editing) in one clause. It explicitly distinguishes itself from the sibling upscale_media, so an agent can route between the two 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?

Gives concrete usage conditions: pass image_urls to edit or supply reference images, and defer to upscale_media for upscaling. What's missing is guidance on when to prefer this over generate_video/edit_video or how the wait/callback flags change the calling pattern — but those are surfaced in the schema rather than 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?

Annotations already declare destructiveHint=true, openWorldHint=true, and non-idempotency, so the safety profile is covered. The description adds the useful output fact ("Returns the audio URL(s)") and describes what each mode does to the source audio (re-sing, lengthen, layer). It does not reconcile the destructiveHint=true annotation with a generation tool (credit spend), nor discuss async/callback semantics, so it adds only moderate context.

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

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

The key discriminator ("full Suno suite", default mode) is front-loaded, then modes are grouped by what they operate on. It is dense and somewhat run-on for a single paragraph, but every clause carries distinct operational information for a 10-mode, 15-parameter tool.

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

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

With no output schema, the description must say what comes back, and it does ("Returns the audio URL(s)"), plus instrumental/negative_tags behavior. Cost confirmation, wait/polling, and webhook behavior live only in the schema, so those aspects are not reinforced in prose — acceptable for a tool of this complexity but not exhaustive.

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 all 15 parameters and the baseline would be 3. The description earns an extra point by synthesizing the mode-to-input dependency graph in one place (audio_url for cover/extend/add-vocals/add-instrumental, clip_id for stems/wav, continue_at for extend), which is faster to act on than reading ten separate property descriptions.

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

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

The description states a specific verb and resource ("makes a new song", "Full Suno suite") and enumerates all ten modes with their effects, so the scope is unambiguous. It never names a sibling tool, though — an agent must infer on its own why this differs from generate_audio (speech/TTS) or generate_video, which is the only thing keeping it from a 5.

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

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

Usage is conditioned per mode: transform an existing track by passing audio_url, split a prior clip by passing clip_id, 'stems'/'stems-all' and 'wav' require clip_id, 'extend' needs continue_at. That is strong when-to-use guidance. What is missing is explicit when-NOT or alternative routing (e.g. use generate_audio for voice work), 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?

Annotations already declare destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description goes beyond that by disclosing synchronous-by-default waiting behavior, the callback webhook payload shape (including the non-obvious 'data' key rather than 'output'), and the spend-guard/confirm_cost retry flow, which annotations do not convey.

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

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

Three tightly packed sentences with zero filler: purpose first, then defaults and model switching, then return/wait semantics with the callback escape hatch. Front-loaded and each clause carries information.

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

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

For a 12-parameter generation tool with no output schema, the description still covers the result (video URL) and the async path (immediate task_id plus webhook payload). Combined with the exhaustive schema and annotations, an agent has everything needed 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 every parameter is already documented in the schema, including the model aliases and the callback body. The description largely restates that (default Veo 3.1 Fast, native audio, switch model with model), adding little new parameter-level syntax beyond the baseline.

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

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

States a specific verb+resource ("Generate a video") and immediately scopes the input modality ("from a text prompt (and optional start/end frames)"), which cleanly separates it from edit_video, extend_video, and generate_image. An agent can identify the 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?

Gives concrete routing conditions: default model, how to switch models via the model parameter, and explicitly when to prefer callback_url ("for long jobs to return immediately"). It does not, however, contrast with sibling tools like edit_video or extend_video, so the when-not guidance is absent.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower. The description adds meaningful behavior beyond them: the output URL is only present if the task completed, and wait:true blocks until a final state. It omits error/failed-state handling and any polling-timeout or rate-limit context.

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, zero waste, and the core purpose is front-loaded before the usage contexts and the wait hint. Every sentence earns its place.

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

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

There is no output schema, so the description rightly carries the return-value burden and does so by naming status plus the conditional output URL. It is nearly complete for a two-parameter status tool, though it does not sketch the status values or the shape of a failed 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%, so both parameters are already documented in the schema, including the exact semantics of wait. The description's "Pass wait:true to block until it finishes" essentially restates the schema's wait description, adding no new format or edge-case detail. Baseline 3 is correct when the 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?

The description gives a specific verb and resource ("Get the status ... of a task by id") and even states the conditional return value (output URL when completed). It is distinguishable from the sibling list_tasks by the "by id" framing, but it never names or contrasts a sibling explicitly, so it falls short of the top band.

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 provides concrete triggering contexts: resume after a webhook, after a polling timeout, or after a generation started with wait:false. That is real when-to-use guidance rather than implied usage. It stops short of a 5 because it does not state when not to use this tool or point to an alternative (e.g. list_tasks).

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds genuinely useful context beyond them: the catalog is refreshed hourly from a live source, and the schema's refresh flag bypasses that cache, which tells the agent about staleness and cost trade-offs.

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 what is listed, followed by filtering, then downstream usage and cache cadence. No redundant or filler text.

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

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

With no output schema, the description must hint at the return shape; it does so by naming the aliases/ids and categories, but does not describe the fields returned per model (e.g. provider, id, alias). Combined with full schema coverage and annotations, it is close to complete but leaves the return shape somewhat 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 description coverage is 100%, with per-parameter docs covering refresh, category enum, and provider key/name case-insensitivity and combinability, so the schema does the heavy lifting. The description only repeats the provider example ('google') and combinability, adding no new semantics 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 (list) and resource (model catalog), enumerates the catalog categories, and notes what is returned (short aliases usable as 'model'). This clearly separates it from siblings like list_tasks/list_resources and from the generate_* tools that consume its output.

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 category and/or provider, and use the returned ids/aliases on the generation tools, which implicitly positions this as the lookup step before generation. It stops short of stating when not to use it (e.g. that it should not be polled frequently because of the cache), so it is clear but not exhaustive.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds genuinely useful behavior: what the response contains ('each voice's id and name'), per-provider defaults, and the aliases. The Veo prerequisite (image/character reference) is a real constraint not visible in 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 primary purpose and the default resource, followed by what is returned and the disambiguation note. No filler and no repetition of schema details.

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 shape (id and name), the default and alias options, and the disambiguation from MCP resources/list. For a zero-required-parameter read tool, an agent has everything needed 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 all four parameters (limit, query, category, resource) are already documented in detail in the schema. The description reinforces the default resource and the id-vs-voice key difference, but adds little syntax or semantics beyond what the schema already provides.

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 a model provider's voices') and states the downstream purpose (passing the right id to a generation tool). It explicitly distinguishes itself from the MCP protocol's resources/list and, implicitly, from list_models by scoping to provider voice catalogs.

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 usage context: default resource 'elevenlabs-voices' feeds generate_audio, while Kling and Veo lists serve video generation, and it notes Veo voices require an image/character reference. It stops short of explicitly naming sibling tools like generate_video as the consumer or stating when not to call 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, idempotentHint and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: result ordering (newest first), pagination, and the OR-within-filter / AND-across-filter composition rule, which is not present in the annotations and only hinted at in the schema. It stops short of describing result shape, but with annotations carrying safety it is above baseline.

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

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

Three sentences, each load-bearing: scope+ordering, filter enumeration+use cases, and filter composition logic. The core purpose is front-loaded and there is 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 an 8-parameter, no-required-args read tool with no output schema, the description covers filtering, ordering, pagination and retrieval use cases, which is what an agent needs to call it correctly. It is slightly thin on what a returned task record contains (it only implies task_id and spend fields), but that is 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 the baseline is 3. The description contributes the cross-parameter combination rule ('comma-separated values are OR'd; different filters are AND'd') and enumerates the filter dimensions, which the schema only documents individually — genuine added meaning over the per-parameter text.

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 ('List the account's past generation tasks'), plus ordering ('newest first') and pagination. It distinguishes itself from sibling listers (list_resources, list_models) and links to the downstream consumers of the returned task_id (get_task, extend_video, upscalers).

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 two concrete use cases — recovering an earlier generation's task_id for get_task/extend_video/upscalers, and reviewing recent spend — which tells the agent when to reach for this tool rather than generating anew. Naming the alternatives that consume task_id makes the routing condition unambiguous.

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

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

Annotations only say readOnly=false, openWorld=true, idempotent=false, destructive=false. The description goes far beyond that: the returned upload_url is one-time/non-idempotent, the PUT requires plain curl and NO api key, the resulting file_url arrives in the same response, CDN upload limits apply, and there is no base64 fallback. It also discloses the security constraints (only user-selected files, never third-party hosts).

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 purpose and the local-file recipe are front-loaded well, but the entry is unusually long and repeats itself ('never local paths or inline data' vs 'There is no base64 option: never re-encode...' and the two separate warnings about third-party hosts). The inline curl block and caps-lock warnings are justified for a safety-critical tool, yet the whole could be trimmed without losing instruction.

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 return-value burden and does so — it names upload_url and file_url and says the latter comes back in the same response and is passed onward to the generation tool. Combined with mode selection, security rules, and upload limits, an agent has everything needed 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 coverage is 100%, so the baseline is 3, but the description adds what the schema cannot: the mutual-exclusion logic among the three optional params and the different return value each mode yields (upload_url for content_type vs file_url). It reinforces the MIME pattern with concrete examples.

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 a specific outcome — 'Get a public https URL for a file' — and immediately ties it to the consumer tools ('the generation tools accept ONLY public https URLs'). This cleanly separates it from the generate_*/edit_* siblings that consume the URL rather than produce it.

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

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

It explicitly routes all three invocation modes: content_type for a local file, url for something already online, file_path for reading this server's own disk. It also states the alternative is not viable ('never local paths or inline data'), and adds a security rule about which files may be uploaded and which hosts are off-limits.

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 destructive/openWorld/non-idempotent, and the description adds routing behavior plus the model-internal upscaler constraint (task_id only works on its own model's completed generations). It does not itself mention cost gating or the wait/webhook flow, but those are covered by schema descriptions, so the tool-level text adds real context without contradicting the hints.

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 core action and the key routing rule, then uses parentheticals efficiently to separate image, video, and task_id behavior. Dense but every clause carries routing or constraint information; only minor style inflation from the repeated 'Topaz' explanations.

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

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

For a 10-param, all-optional tool with no output schema, the description covers routing, wait behavior, and model restrictions, and annotations carry the safety profile. It does not summarize what a wait=true call returns, though that is a minor gap given the rich schema text.

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 earns above baseline by stating the mutual-exclusivity constraint not encoded in the schema (exactly one of image_url / video_url / task_id) and by clarifying that upscale_factor is a multiplier while resolution is a video target size. Cross-parameter semantics are made explicit.

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 ('Upscale an image or a video') and then enumerates the three mutually exclusive input paths with their routing targets. An agent can immediately distinguish this from generate_image / generate_video / edit_video siblings.

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

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

Explicitly states 'Pass exactly one source' and gives the selection rule for each path, including the exclusion 'For any media not generated by Veo/Grok, use the URL inputs — Topaz works on everything.' This is a genuine when-to-use/when-not decision matrix.

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