mcp

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

The annotation readOnlyHint:true already indicates read-only nature. The description adds the currency (USD) and confirms no parameters, but does not mention potential errors, rate limits, or response format. Since annotations cover the safety profile, this meets the baseline but adds minimal extra behavioral 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 description is two sentences, front-loads the action ('Return the account's current balance'), and states currency and parameter absence. No unnecessary words.

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

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

For a simple read-only tool with no parameters and no output schema, the description is complete. It specifies the resource (account), the action (return balance), and the currency (USD). Nothing else is needed.

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

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

There are zero parameters, so the baseline is 4. The description explicitly states 'Takes no parameters,' which matches the empty schema. No additional parameter meaning 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?

The description clearly states the action ('Return'), the resource ('account's current balance'), and the unit ('in USD'). It is specific and unambiguous, distinguishing it from sibling tools like list_resources or generate_audio.

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

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

The description clearly states the tool's function but does not explicitly discuss when to use it versus alternatives. However, given the sibling tools are all unrelated (e.g., generate_video, upload_file), the usage context is obvious and no exclusions are needed.

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 set readOnlyHint=true, which covers the core side-effect-free behavior. The description adds further clarity by stating 'without creating it or charging the account,' reinforcing that no resource is created and no charge occurs. This is consistent with the annotation and adds value beyond it, though it does not delve into other potential side effects (e.g., rate limits or logging). No contradiction exists.

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

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

The description is two sentences, direct, and free of unnecessary jargon or repetition. It efficiently conveys the tool's purpose and required inputs without fluff. The structure is logical: first the action and constraint, then the input requirement. This is exemplary for conciseness.

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

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

Given the tool's simplicity and the comprehensive schema descriptions, the description is complete for an agent to understand when and how to use it. It clearly identifies it as a cost-estimation dry run, which is the core context. It does not specify the exact return format (e.g., the cost value), but there is no output schema to require that, and the name/title imply the output. The description covers the essential operational context adequately.

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 schema already provides detailed descriptions for both parameters (model and input), including nested fields and explicit guidance on raw field names and required translations. The tool description simply reiterates 'Pass the model and the full input payload,' which adds little beyond the schema's existing coverage (which is 100%). Since schema coverage is high, the baseline is 3, and no significant additional semantic insight is provided by the description.

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 clearly states the tool's function: it estimates the cost of a task without creating it or charging the account. This is specific and distinguishes it from the sibling generation tools (e.g., generate_audio, edit_video) that actually execute tasks. The verb 'estimate' and resource 'cost' are explicit, and the 'without creating it' directly contrasts with the execution-focused 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?

The description provides direct usage instructions: 'Pass the model and the full input payload.' It implies when to use this tool (before committing to a generation, to preview cost) and what to provide. While it does not explicitly mention alternatives or edge cases (e.g., 'use this when you need to check cost before generation'), the intent is clear from the context and siblings. It is a step above minimal guidance.

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

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

Annotations include destructiveHint: true, but the description goes beyond by detailing the default model (Gemini Omni), the wait/callback behavior (return immediately with task_id, webhook body structure), the requirement for public https URLs and the upload route for local files, and the confirm_cost behavior. This adds significant behavioral context beyond the annotations, especially 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?

The description is fairly concise given the tool's complexity (10 params, multiple models, callback behaviors). It front-loads the core purpose and usage, then covers model selection, distinguishes siblings, and ends with return value. Each sentence adds functional value—no redundancy—and the structure is logical, making it efficient for an agent to parse.

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

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

Given the tool's complexity (multiple models, async options, provider_options, cost guard), the description covers essential context: model choices, async waiting vs callback, URL constraints and upload path, and output as video URL. There's no output schema, but the description states the return is a video URL and references polling with get_task and webhook body structure, which is sufficient for an agent to anticipate outcomes.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches several parameters: explains the 'model' aliases and lists them, clarifies the 'video_url' requirement for public URLs and the upload process, explains 'image_urls' use for motion-control and omni models, and details 'wait' and 'callback_url' behaviors. This goes beyond the schema structure with practical usage details, but not all params get such enrichment (e.g., aspect_ratio, seed), so a 4 is appropriate.

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

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

The description clearly states the tool edits an existing video from a prompt or transfers motion onto a subject image, with specific resources (video_url, prompt) and mentions the default model and alternatives. It also distinguishes this tool from siblings by explicitly naming generate_video, extend_video, and upscale_media with the usage boundary ('changing an existing clip'), providing strong differentiation.

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 states when to use this tool (edit existing clip) and when not to (for new videos use generate_video, extend use extend_video, upscale use upscale_media). It also instructs how to pass the source (video_url) and the change (prompt), and mentions switching models, covering essential usage guidance with clear exclusions and alternatives.

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

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

Annotations provide destructiveHint and openWorldHint, and the description adds valuable non-obvious traits: Veo aspect-ratio inheritance, unofficial chaining, Grok preset/custom mode rules, and the fact that extenders only work on their own model's generations. It does not spell out what 'destructive' means for this operation, but it does not contradict the annotations and adds sufficient context beyond them.

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 description is a few dense, purposeful sentences with no filler. It front-loads the action and required input, then efficiently covers Veo behavior, Grok behavior, chaining, and the model-internal constraint. Every sentence adds value beyond 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?

Given 12 parameters, nested objects, and no output schema, the description covers the main workflow: required task_id, wait/callback vs immediate polling, model-specific modes, and the chaining caveat. The 100% schema coverage compensates for any parameter detail not repeated in the prose, but the description could be slightly stronger about return-value expectations and the meaning of destructiveHint.

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 by grouping parameters into Veo vs Grok modes, noting that prompt is required for Veo and for Grok custom mode, and explaining the relationship between prompt, extend_at, extend_duration, and video_preset. It still relies on the schema for individual parameter details, but the cross-parameter guidance earns a 4.

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

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

The description opens with a specific verb and resource: 'Extend a previously generated video by its own model's extender' and immediately identifies the required task_id. It clearly differentiates from generate_video, edit_video, and upscale_media by framing extension as a continuation of an existing generation, with distinct Veo and Grok behaviors.

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

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

The description gives explicit when-to-use guidance: pass the completed generation's task_id, use Veo with a prompt, use Grok preset/custom modes, and only extend within the same model family. It also provides a fallback if chaining fails: 'regenerate at the target length instead.' It effectively distinguishes Veo vs Grok usage and clarifies that extenders are model-internal.

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 description adds substantial behavioral context beyond annotations: the wait parameter behavior (returns task_id when false), callback_url behavior with webhook format, the confirm_cost spend guard, the duration pricing nuance for transcription ('the job is PRICED by this declared length...'), and provider_options restrictions. It also states the output (audio URL or transcript) and that it is not idempotent (implied by wait/callback). It does not contradict the annotations (openWorldHint, idempotentHint=false, destructiveHint=true).

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

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

The description is a single dense paragraph that front-loads the main purpose and then lists each mode with its distinguishing input. It uses semicolons to pack information without redundancy. Every sentence earns its place; it covers all modes, parameters, and behavioral notes in ~150 words.

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

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

Given the tool's complexity (12 parameters, no output schema, nested dialogue objects), the description is complete: it explains all model modes, specifies the return value ('Returns the audio URL (or the transcript for ''stt'')'), mentions the music alternative, and covers key behaviors (wait, callback, cost guard, duration pricing). Since no output schema exists, the description appropriately clarifies what the caller receives.

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 detailed per-parameter descriptions (e.g., model aliases, dialogue format, duration pricing, provider_options restrictions). The tool description mostly summarizes and reorganizes this info (e.g., 'voice_id from list_resources', 'pass audio_url for transcription') without adding new semantic layers. It adds a bit of cross-reference but no major new 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?

The description has a specific verb and resource: 'generate audio' with clear scope covering six sub-capabilities (text-to-speech, sound effects, dialogue, transcription, voice change, audio cleanup). It explicitly distinguishes from the sibling tool generate_music with 'For music, use generate_music.' This leaves no ambiguity about what the tool does.

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 explicit when-to-use guidance per model: e.g., 'sound effects (model ''sfx'', optional duration)', 'transcription (model ''stt'': pass audio_url, get text back)', and 'For music, use generate_music.' It also clarifies parameter usage like 'multi-voice dialogue (model ''dialogue'': pass the turns in the dialogue parameter, not prompt)' and mentions the alternative of polling or callbacks for long jobs. This is comprehensive guidance.

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

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

Annotations already mark destructiveHint, and the description doesn't add extra context about side effects beyond 'edit'. It doesn't elaborate on cost, webhook behavior, or other non-obvious traits.

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?

Concise single sentence plus a parenthetical note; no redundancy or unnecessary detail.

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?

Provides the essential high-level purpose and key differentiator, while leaving detailed parameter behaviors to the schema—appropriate for the tool's complexity.

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 description adds useful context like default model and clarification for image_urls, slightly enhancing parameter understanding.

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?

Clearly states it generates or edits an image from a text prompt, mentions the default model, and distinguishes from upscale_media.

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 explicit guidance on when to use image_urls for editing and when to use upscale_media instead, covering key alternative scenarios.

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 meaningful context beyond the destructiveHint annotation by detailing what each mode does to inputs (transform, split, layer, export) and stating the return value ('Returns the audio URL(s)'). It does not mention cost, rate limits, or wait/callback behavior, but those are covered by the schema and 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 with a strong front-loaded opener ('Full Suno suite'). Every clause carries operational information—modes, required params, and return value—with zero filler or repetition.

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

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

Given the tool's complexity (15 parameters, 10 modes, nested provider_options), the description provides a complete high-level map of all operation families and their prerequisites in a compact form. The return type is stated, while operational details like wait/callback and spend-guard live in the schema, so the description plus schema together form a complete picture.

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 schema's own parameter descriptions already encode mode-parameter relationships (e.g., clip_id 'required by stems/stems-all', continue_at 'required for extend'). The description's mode-to-parameter mapping is helpful but largely redundant with the schema, so it adds no significant 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?

The description opens with 'Full Suno suite' and then enumerates every mode with a specific verb and resource ('makes a new song', 'Transform an existing track', 'Split a prior clip', 'writes lyrics', 'makes a sound effect'). This clearly distinguishes the tool's broad but music-specific scope from sibling generate_* tools.

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

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

Provides explicit when-to-use guidance per mode: music is default, cover/extend/add-vocals/add-instrumental need audio_url, stems/stems-all/wav need clip_id, extend needs continue_at. It does not explicitly mention alternatives among sibling tools (e.g., when to prefer generate_audio), but internal mode selection is very clear.

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

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

Annotations already include openWorldHint, idempotentHint false, and destructiveHint true, so the description doesn't need to restate those. It adds valuable context: the waiting vs callback behavior, the cost confirmation mechanism, the mapping of image_url to model-specific fields, and the provider_options constraints. These go beyond the annotations and help the agent anticipate side effects and handling.

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

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

The description is relatively long, but it packs essential information into each sentence, with the primary purpose stated first. It could be slightly trimmed, but given the tool's complexity (12 parameters, multiple models, callback mechanics), the length is justified. The structure is logical, moving from purpose to model switching, then to waiting/callback behavior, and finally to special parameters.

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 tool with 12 parameters, one required, and no output schema, the description covers all necessary aspects: what it does, how to control models, when to use callbacks, cost handling, and how to pass model-specific options. It also addresses edge cases like local file uploads and provider_options restrictions. The combination of the schema (100% coverage) and the rich description leaves no major gap for an agent to use the tool effectively.

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 each parameter already has a definition. The description significantly adds to this by explaining the default model, the image_url mapping logic, the exact webhook body format for callback_url, the confirm_cost flow, and the restrictions on provider_options. It also lists model aliases and points to list_models for the catalog. This goes well beyond the schema, providing critical operational details.

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 clearly states the tool's primary function: generating a video from a text prompt, with optional start/end frames. It also specifies the default model and distinguishes it from other media-generation tools (audio, music) by focusing on video output. The verb+resource are specific and the purpose is immediately understandable.

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

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

It gives clear practical guidance on when to use callback_url versus waiting, and how to switch models. It implies usage for text-to-video generation but does not explicitly state when not to use this tool compared to siblings like generate_image or generate_audio. However, the context is sufficient for an agent to decide correctly, so a 4 is appropriate.

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

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

The annotations already declare readOnlyHint=true, so the description does not need to repeat that. It adds valuable behavioral context: it describes the waiting behavior (block until done) and that the output URL is only present if completed. This goes beyond the annotations without contradicting them, giving a 4.

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

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

The description is concise, two sentences, with no filler. The main purpose is front-loaded in the first sentence, and the second sentence gives quick usage guidance. No 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 simple tool with two parameters and no output schema, the description provides all essential information: what it returns (status and URL), when to use it, and how to control blocking. The sibling tools do not introduce ambiguity. The description is fully self-sufficient.

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 schema has 100% parameter description coverage for both task_id and wait. The description re-iterates the wait behavior but does not add new semantics beyond schema. Since the baseline is 3 at high coverage, this score is appropriate.

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

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

The description explicitly states the tool's function: 'Get the status and (if completed) output URL of a task by id.' It includes the verb 'get' and the resource (task status), and goes beyond to mention the output URL condition. This clearly distinguishes the tool from list_tasks and 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?

The description provides explicit scenarios for when to use the tool: 'Use it to resume after a webhook, a poll, or a generation started with wait:false.' It also instructs on the wait parameter usage with 'Pass wait:true to block until it finishes.' However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of a perfect 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 readOnlyHint=true, the read-only nature is already annotated. The description adds valuable behavior: caching with hourly refresh and the ability to bypass via the 'refresh' parameter. It does not mention rate limits or additional side effects, but given the annotations cover safety, this is sufficient. Credit is given for adding cache behavior.

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

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

The description is concise, two sentences, with zero fluff. It packs purpose, usage, and caching info efficiently. No redundant phrasing or unnecessary 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?

For a read-only listing tool, this description is complete. It explains what is listed, how to filter, how to use the results, and the refresh behavior. No output schema is present, but that is not a gap here. All necessary context for tool selection and invocation is provided.

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%, with each parameter described. The description goes further by explaining the practical use of aliases for 'model' and that provider accepts both stable keys and human-readable names. This extra context enriches the schema and helps correct usage, so a high score is warranted.

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 clearly states the tool lists the model catalog, specifying the categories (video, image, audio, upscale) and that it provides aliases to pass as 'model'. It distinguishes itself from sibling generation tools by explicitly connecting to them. This is specific and unambiguous.

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 instructs to use returned ids/aliases on generation tools, indicating when to call this tool. It also mentions filtering by category/provider and the hourly refresh. While it doesn't explicitly state when not to use it, the context with siblings makes it clear this is the pre-generation lookup tool. No exclusions are given but the usage context is strong.

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

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

Annotations declare readOnlyHint=true, so the description's burden is lighter. It adds value by explaining return data (id and name) and the scope of resources covered. It also disambiguates from protocol resources, which is useful. No contradictions found.

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

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

The description is concise, front-loaded with the main purpose, and includes essential clarifications (default, scope, and protocol distinction) without any fluff. 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?

Given the tool's simplicity (read-only, optional params, no output schema), the description fully covers the necessary context: what it returns, the providers it covers, and how to use the results. It also correctly distinguishes from the protocol's resources/list, making it self-contained.

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%, but the description enriches parameter meaning by tying them to usage: it explains how to pass the returned ids to generation tools (e.g., 'use the voice_id in generate_audio'), clarifies the 'resource' options, and notes that 'category' applies only to ElevenLabs. This goes beyond the schema's basic field definitions.

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 clearly states the tool's purpose: listing a model provider's voices to supply ids for generation tools. It specifies the default provider (elevenlabs-voices) and differentiates from the MCP protocol's resources/list, making it distinct from sibling tools like list_models and list_tasks.

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 context is provided via the default and the explicit link to generation tools (e.g., 'the voices for generate_audio'). It also tells users not to confuse this with the MCP protocol's resources/list. However, it lacks explicit 'when not to use' guidance or alternative tool references beyond that distinction.

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

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

Beyond the readOnlyHint annotation, the description reveals behavior including newest-first ordering, pagination, pending->processing status remapping, absence of an upscale category, and the OR/AND filtering semantics. These insights materially help an agent understand side-effecting behavior and response structure.

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

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

The description is compact and dense: three sentences cover the action, sort order, pagination, every filter dimension, the intended purpose, and filter combination rules. No words are wasted, though the long middle sentence packs a lot of related concepts into one breath.

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 a fully detailed schema and read-only annotation, the description successfully covers the main usage scenarios and important edge cases. It could go slightly deeper on pagination defaults or result shape, but as a filtered/lost listing tool, the information provided is highly 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?

The schema already provides 100% coverage with detailed descriptions for all eight parameters, so the baseline is 3. The description adds useful cross-parameter semantics ('Within one filter, comma-separated values are OR'd; different filters are AND'd') and clarifies category grouping, though the mention of 'text' alongside the schema's 'llm, video, image, audio' listing introduces slight ambiguity.

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

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

The description opens with a clear verb and scoped object: 'List the account's past generation tasks, newest first, with pagination.' It also differentiates itself by explaining it is for finding older task_ids for get_task, extend_video, or the veo/grok upscalers, which is distinct from sibling 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?

It explicitly names when to use this tool: 'Use it to find an earlier generation's task_id (for get_task, extend_video, or the veo/grok upscalers) or to review recent spend.' This gives concrete usage context and references alternative tools, making the choice 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?

Though annotations are minimal (only openWorldHint and non-destructive), the description carries a full behavioral disclosure: it explains the two-step flow (get upload_url, PUT file), that no API key is needed, CDN limits apply, and includes a security warning about not uploading credentials or sending files to third parties. This is far beyond what annotations reveal without contradiction.

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

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

The description is long but well-structured, front-loading the purpose and then providing concrete usage steps. Every sentence contributes essential information (workflow, security, limitations). It could benefit from tighter formatting (e.g., bullet points) but is not wasteful.

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 file upload tool with no output schema, the description fully covers the required workflow: how to obtain the upload URL, how to PUT the file, what to expect in the response (upload_url, file_url), and important caveats like CDN limits and security. It leaves no gaps for a complex operation with two distinct modes.

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%, but the description adds significant meaning: it explains that content_type is for local files and leads to a one-time upload_url, while url is for importing an already-online file. It also clarifies that only image/video/audio types are accepted and that there is no base64 option, which is not in 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?

The description explicitly states 'Get a public https URL for a file' and immediately contrasts with generation tools that only accept public URLs. It clearly distinguishes two modes: uploading a local file (via content_type) and importing an existing online URL (via url), and its purpose is obviously separate from sibling tools like generate_*.

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 explicit when-to-use guidance: 'the generation tools accept ONLY public https URLs', and gives step-by-step instructions for local upload with a curl example. It also mentions the alternative for existing URLs and states security constraints (e.g., never upload to third-party hosts). This goes beyond mere context and includes exclusions.

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

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

The description goes beyond annotations by explaining the wait behavior (with the wait parameter), the callback_url mechanics, and the confirm_cost guard. It also notes that provider_options has reserved keys. However, it does not directly address the meaning of destructiveHint: true, though it does not contradict it. The description adds substantial behavioral 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 description is dense but all information is useful and clearly organized with parenthetical examples. It front-loads the core purpose and then details input modes. While not extremely brief, it effectively packages necessary guidance without 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?

Given the complexity of 10 parameters, nested objects, and no output schema, the description covers essential aspects: it explains what each input mode does, how to wait or use callbacks, cost confirmation, and the provider_options escape hatch. It also details the webhook response format. It is complete for a tool of this complexity.

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 description adds significant meaning beyond the schema by clarifying the relationships between parameters, e.g., 'upscale_factor' is for images while 'resolution' is for videos, and how task_id pairs with model. It also explains provider_options as an escape hatch with restrictions. Even though schema coverage is 100%, the description enriches understanding of usage and constraints.

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 clearly states the tool's purpose: 'Upscale an image or a video.' It distinguishes three input modes (image_url, video_url, task_id with model) and specifically notes which to use for media not generated by Veo/Grok, which differentiates it from sibling generation tools like generate_image and 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?

The description provides explicit guidance on when to use each input: 'Pass exactly one source' and clarifies that model-internal upscalers 'ONLY work on their own model's completed generations,' directing users to URL inputs for all other media: 'For any media not generated by Veo/Grok, use the URL inputs — Topaz works on everything.' It also mentions waiting behavior and callback options.

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