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

Annotations declare destructiveHint=true, and the description adds context: deletion causes 404 errors for other references, mentions ~48h expiry, and explains the confirm parameter's role. No contradictions.

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

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

Two sentences, front-loaded with the primary action, no unnecessary words. Efficient and clear.

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 2 parameters and no output schema, the description fully covers purpose, usage, behavioral effects, and parameter semantics. Annotations complement well.

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 reinforces the required parameter (file_uri) and clarifies the confirm parameter's behavior (preview if false). Adds slight value beyond schema by explaining the '~48h expiry' context.

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 deletes uploaded files by file_uri, and distinguishes it from sibling tools (upload, list) by specifying the deletion action and its consequence (404 for references).

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 warns that deleting a file will cause other tool calls referencing it to fail with 404, advising to delete only references you are finished with. Provides clear when-to-use and consequence.

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 far beyond the annotations by explaining exactly what happens while the job is running, on completion, and on failure, including the killed-before-finished case. It also discloses durability differences between hosted and local servers, expiration behavior, and recovery of killed background jobs. This is rich behavioral context that the annotations alone do not provide.

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 not bloated; every sentence delivers useful information about retrieval, status, failure, durability, and recovery. It is not formatted with bullets, but the first sentence is front-loaded with purpose and usage. Slightly more structure would make the edge cases easier to scan, but there is no wasted wording.

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

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

There is no output schema, yet the description explains the return behavior clearly: status 'running', normal result with image URLs/paths and meta, and raised errors. It also covers the optional output_dir in the killed-job recovery flow and gives environment-specific behavior. For a tool with this complexity, the description is unusually 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?

Schema description coverage is 100%, and both parameters already have meaningful schema descriptions. The tool description reinforces them by explaining the job_id lifecycle and the output_dir fallback, but it does not substantially add semantics beyond what the input schema already states. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Retrieve a generation started with async: true or handed off by max_wait_ms.' This unambiguously distinguishes gemini_get_result from the sibling generation, editing, file-management, and interaction tools. It also specifies the exact input (job_id) and expected output shape, so there is no doubt 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?

The description clearly states when to use the tool: after a generation was started with async: true or after max_wait_ms handed off a job. This gives the agent actionable context. It does not explicitly name alternatives or say when not to use this tool, but among the siblings none serve the same result-retrieval role, so the guidance is sufficient.

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 and idempotentHint annotations, the description discloses valuable behavioral details: it resolves the credential the way real tools do, performs exactly one authenticated request, reports credential source and acceptance, measures round-trip time, and explicitly states it never returns the credential itself.

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 well-structured, starting with what the tool does, then what it reports, then when to call it, and ending with safety. It is somewhat dense but every sentence contributes useful information; no 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?

With no output schema, the description carries the full burden of explaining return semantics, and it does: it enumerates the reported items (credential source, acceptance, round-trip time, plain-English hint) and the three failure categories. Combined with zero parameters and strong annotations, nothing essential is missing.

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

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

The tool has zero parameters, so the baseline is 4. The description adds useful context by explaining that it resolves the credential the way real tools do, which gives the agent a mental model without needing any parameter documentation.

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: it 'makes one authenticated request to generativelanguage.googleapis.com' and reports health information. It clearly distinguishes itself from sibling tools by its diagnostic purpose, describing it as a healthcheck that determines which hop broke when a real tool fails.

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 an explicit usage condition: 'Call this when a real tool fails and you want to know which hop broke.' This is clear guidance for when to use the tool, though it does not explicitly name alternatives or provide when-not-to-use conditions.

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

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

The description adds a genuinely useful behavioral caveat beyond the annotations: 'Gemini over-preserves the input; there is no edit-strength control' and advises rerolling with a different seed or more forceful wording. With only readOnlyHint=false and openWorldHint=true in annotations, this behavioral disclosure materially helps the agent set expectations. It does not cover the full mutation/write surface, but it goes well beyond the structured data.

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, front-loaded with purpose, then usage routing, then a behavioral caveat. Every sentence earns its place: no fluff, no restatement of schema contents, and the most important selection guidance appears early. It packs a lot of useful orientation into a small space.

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 high complexity (24 parameters, no output schema, rich schema), the description provides the essential selection context, input requirements, and a key behavioral warning. It does not summarize output/return behavior or the async/confirmation flow, but those are well covered by the parameter descriptions. The description is not exhaustive, yet it covers the cross-cutting guidance an agent needs to choose and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3 even without parameter details in the description. The top-level description reinforces the core inputs (images, prompt) and mentions seed as a lever for structural changes, but it does not need to repeat the extensive per-parameter documentation already present in the schema. This is adequate value-added context, no more.

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?

Description opens with a specific verb+resource: 'Edit or compose images', then states the required inputs ('one or more input images (paths or base64), plus a text instruction'). It also distinguishes itself from gemini_interact by positioning itself for one-off edits or composing multiple distinct inputs, so an agent can tell it apart from its closest sibling 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?

Explicit when-to-use guidance is given: for a SERIES of successive edits it says 'prefer gemini_interact (multi-turn)' and explains why, while 'use gemini_image_edit for one-off edits or composing multiple distinct inputs' defines the boundary. This is direct, actionable routing guidance with no ambiguity.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true, so the agent knows this is a mutating, external-state-dependent operation. But the description adds almost no behavioral context beyond model naming: it does not mention that generation writes files to disk, can take 60–120s+ and risk host timeouts, requires confirm=true to actually generate, or bills a new generation. The rich behavioral details live in parameter descriptions (async, max_wait_ms, idempotency_key, timeout_ms) rather than in the tool description itself.

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

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

Two sentences, zero filler. The primary action is front-loaded in sentence one, and the conditional routing to gemini_interact occupies sentence two. Every word 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?

For a 27-parameter tool with no output schema, the description is very thin, but the schema compensates heavily with exhaustive parameter semantics. The main gaps are the lack of routing guidance toward gemini_image_edit (new generation vs. editing) and no mention of the confirm-gated preview flow, which is an unusual behavior an agent should be warned about. Adequate but with clear gaps.

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: every one of the 27 parameters already has a detailed schema description (e.g., orientation vs. aspect_ratio disambiguation, images_url vs. images_base64 tradeoffs, max_wait_ms semantics). The tool description itself contributes no parameter-level meaning, which is acceptable given the schema's depth.

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 ('Generate'), a precise resource ('image(s)'), the input type ('text prompt'), and the model family ('Gemini image model (Nano Banana / Nano Banana Pro)'). It is immediately distinguishable from siblings like gemini_video_generate, gemini_music_generate, and gemini_image_edit, and it names the closest ambiguous sibling (gemini_interact) as a different entry point.

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 an explicit routing rule with a condition: 'If the result will likely be refined iteratively, prefer gemini_interact (multi-turn) as the entry point.' This resolves the primary ambiguity (generate vs. interact). It does not, however, give any guidance on when to prefer gemini_image_edit, gemini_image_set, or the async/get_result path, so a bit 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?

With annotations only providing readOnlyHint=false and openWorldHint=true, the description adds substantial behavioral disclosure: scene generations run in parallel, the master seeds consistency, hosted-connector features like bundle_url zip downloads and pollable job handles, and max_wait_ms behavior when the budget expires. It also mentions the executor-lifetime constraint on the hosted connector. It doesn't detail every failure mode or auth requirement, but for a generative image tool the disclosed behaviors (parallelism, async vs bounded wait, zip output) are meaningful.

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 efficient: it front-loads the core 'consistent SET' purpose, then packs workflow, defaults, parallel execution, hosted features, bundle_url, and max_wait_ms into three sentences. Every sentence earns its place. It is slightly long relative to the number of behavioral details, but the information density is high and no filler is present. It earns a 4 rather than 5 because the length is near the upper bound and some details (one curl instead of N) are minor.

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 27 parameters and no output schema, the description captures the essential operational model: master-then-scenes, scenes vs count, parallel execution, hosted-connector features, and timeout/job-handle behavior. The absence of an output schema means the description could have described the return shape in more detail, but the input schema already documents parameters thoroughly. It is complete enough for an agent to call it correctly in the common hosted and local cases.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description adds value by explaining the relationship between scenes/count/master_prompt and the consistency workflow. It also contextualizes hosted-connector-only params like characters, style, and master_images_r2_keys. The description goes beyond the schema by clarifying defaults like reference_mode 'master' and when max_wait_ms is preferable to async. It doesn't restate every parameter, but it doesn't need to given full schema coverage.

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 phrase—'Generate a consistent SET of images'—and clearly distinguishes the tool from single-image generation by explaining the master-image-plus-scenes workflow. It also differentiates it from siblings like gemini_image_generate and gemini_image_edit by emphasizing consistency across multiple outputs. The mention of scenes, count, reference_mode, and bundle_url gives a concrete, non-tautological purpose.

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 says to provide `scenes` OR `count`, names the default reference_mode, and explains when to use hosted-connector features like saved characters/style and max_wait_ms. The `max_wait_ms` guidance also tells the agent when to prefer it over `async`, which is strong when-to-use guidance. This goes well beyond a vague 'use this for consistent sets' and includes concrete alternatives and conditions.

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

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

Annotations are thin (readOnlyHint=false, openWorldHint=true), and the description carries the real burden with exceptional disclosure: client-side timeouts 'usually still complete' with a <image>.json sidecar, a re-issue is 'a second billable generation,' 404s recover via chain_recovered with a second 404 meaning the interaction id was not the cause, and output is JPEG. This goes far beyond the annotations and directly prevents double-billing and retry confusion.

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?

Every sentence earns its place — purpose, chaining rule, timeout recovery, 404 recovery, output format — and the core purpose is front-loaded. It is a dense block with several long sentences, so it could be more scannable, but nothing is redundant with 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 25-parameter tool with serious failure modes (double billing, broken chains), no output schema, and thin annotations, the description covers all operational essentials: how chaining works, what happens on timeout and 404, where artifacts land (output dir, .json sidecar), and the output format. Remaining return-value behaviors (job_id, status: 'running', reused: true) are already documented in the schema's parameter descriptions.

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 individually rich parameter docs, so the baseline is 3. The description adds genuine cross-parameter semantics not present in any single field: the chaining relationship among previous_interaction_id, continue_last, and images (do not re-attach the prior turn's output), and the timeout→sidecar→continue_last recovery flow. That earns one point above baseline, but the schema already does most of 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?

Opening sentence states a specific verb+resource: 'iterative or multi-step refinement of a single image — multi-turn generation/editing via Gemini's Interactions API.' The 'iterative/multi-step' framing distinguishes it from single-shot siblings like gemini_image_generate and gemini_image_edit, so an agent can tell them apart without opening schemas.

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 positioned as the 'Preferred tool for iterative or multi-step refinement,' giving clear when-to-use context, plus a detailed chaining protocol: capture the returned interaction id, pass it as previous_interaction_id, and 'do NOT start a new interaction or re-upload the image for each tweak.' It stops short of a 5 because it never names the when-not-to-use alternative (a single one-shot generation would go to gemini_image_generate/gemini_image_edit).

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 and openWorldHint. Description adds value by clarifying retention period and expiry behavior, which is beyond what annotations provide.

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 with no wasted words. Front-loaded with purpose, then key behavioral 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?

Covers purpose, returned fields, and retention. No output schema but description compensates. Parameters are covered. Complete for a list tool.

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

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

Schema coverage is 100% and the single parameter (page_size) is well described in the schema. Description adds no extra parameter info, but baseline 3 is appropriate.

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

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

Description clearly states the action (list) and resource (files, images, photos) along with returned fields (file_uri, MIME types, expiry times). Distinguishes from siblings like gemini_upload_file and gemini_delete_file.

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 context on retention (~48h) and explains that vanished files are expired, helping the agent understand behavior. No explicit when-not-to-use, but sibling differentiation is clear.

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

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

The readOnlyHint annotation already indicates no side effects. The description adds context that the tool lists models specific to the API key and includes the default model, but does not disclose additional behavioral traits beyond what annotations already provide. It confirms safe 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 a single, concise sentence that fully conveys the tool's purpose without extra words. It is appropriately sized and front-loaded.

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

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

Given the tool's simplicity (no parameters, no output schema, no nested objects), the description is sufficiently complete. It explains what is returned (models list and default model). However, it does not detail the structure of each model entry, which is acceptable for a list operation.

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 input schema has no parameters, so baseline is 4. The description adds meaning by specifying the model family (Nano Banana / Nano Banana Pro) and that the default model is included, which helps the agent understand what will be returned.

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 Gemini image-generation models available to the API key, including a specific model family (Nano Banana / Nano Banana Pro) and the current default model. This provides specific verb and resource, distinguishing it from sibling tools like gemini_image_generate or gemini_list_files.

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

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

The description implies usage for checking available models and the default, but does not explicitly state when to use it versus alternatives, nor does it provide exclusions or when-not-to-use guidance. Since it's a simple listing tool, it's adequate but could be improved.

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 well beyond the minimal readOnlyHint/openWorldHint annotations by disclosing side effects: results are written to disk as MP3/WAV or returned inline, generation runs long, model capabilities differ by preview tier, and a funded account is required. This is strong behavioral context for a mutation-style tool with no output schema.

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

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

Four sentences, front-loaded with the core action, then model details, output behavior, and long-run handling. Every sentence earns its place, and the most important invocation guidance appears early.

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 19 parameters and no output schema, the description gives a solid high-level workflow: models, output formats, async + gemini_get_result, and the funded-account prerequisite. It does not explicitly describe the sync return shape or the confirm gate, though the very rich input schema covers those details, so it is nearly complete but not fully 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 description coverage is 100%, and the individual parameter descriptions are detailed, so the baseline is 3. The description adds only a bit of extra model-level semantics, such as '~30s clips' for the default model and longer/WAV capability for Pro, but it does not need to compensate for schema gaps.

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: 'Generate music from a text prompt' via Lyria models, and it names the concrete models and their output characteristics. The resource differs clearly from sibling tools like gemini_video_generate and gemini_image_generate, so an agent can select it without ambiguity.

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 operational guidance: use async: true with gemini_get_result for long runs, or raise timeout_ms, and it warns that the preview model needs a funded account. It does not explicitly say when not to use this tool versus sibling generation tools, but the music-specific scope plus the async guidance makes the intended usage 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?

Beyond the readOnlyHint annotation, the description discloses that the tool accumulates session-wide totals, supports resetting the running total, estimates USD cost using each call's own model and rate-card date, and honors the GEMINI_RATE_CARD override. It also explains the external billing constraint that motivates the tool's design. The description is fully consistent with the readOnlyHint.

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?

Every sentence earns its place: the first defines what the tool reports, the second covers the two main invocation patterns, the third explains the cost/rate-card behavior, and the fourth justifies why no account-balance endpoint exists. It is dense but not verbose, with the core purpose front-loaded.

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

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

Even without an output schema, the description adequately tells the agent what the tool returns (tokens plus estimated USD cost), how to interpret it, how to use reset, and what limitations apply. Given the tool's simple one-parameter interface, this is sufficient for correct selection and invocation.

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 documents the reset parameter at 100% coverage, so the baseline is 3, but the description adds real interpretive value by explaining that reset zeros the total after reporting and lets you bracket a workflow without arithmetic. This goes beyond the schema's literal parameter 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 identifies the tool as a cumulative token-usage and cost reporter for the current session, with a specific verb implied by 'Call it' and 'Reports.' It is easily distinguished from the sibling generation, file, and model tools because it is the only one concerned with measuring spend rather than producing content.

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 usage patterns: call before and after a workflow and subtract, or call after a single generation to get that call's cost. It also explains why this tool is necessary by noting there is no account-balance endpoint and that Google Cloud billing data lags, making this the accurate way to attribute spend.

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 indicate readOnlyHint=false and openWorldHint=true, aligning with the write operation described. The description adds behavioral details: 'upload once,' reusability, and token cost of data_base64. It does not contradict 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?

The description is front-loaded with the main purpose and keywords. It is slightly long but every sentence adds value, covering usage, parameters, and behavioral notes. Minor redundancy (e.g., 'reuse across calls' repeated) but overall efficient.

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

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

Given no output schema, the description clearly states the return value (file_uri as files/<id>). It covers input sources and expiration. Missing details on error handling or size limits (except in url param), but for a file upload, this is 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?

Schema coverage is 100%, but the description adds significant value: it explains that exactly one of url, data_base64, or path must be provided, clarifies the confirm parameter's requirement, and warns about token cost for data_base64. This goes well beyond the schema's 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 clearly states the tool uploads a file to the Gemini Files API and returns a reusable file_uri. It lists supported file types (image, video, audio clip) and distinguishes from siblings like gemini_list_files or gemini_image_generate by focusing on upload-only functionality.

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 use cases: upload files to avoid base64 tokens and for reusability across calls. It mentions expiration (~48h) but does not explicitly state when not to use this tool or name alternative tools. However, the sibling context shows no direct upload alternative, so the guidance is adequate.

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 sparse annotations (readOnlyHint=false, openWorldHint=true), the description discloses that output is written to disk as MP4 with no inline MCP block, that generation runs long and can hit timeouts, that async returns a job_id immediately, and that the preview model requires a funded account. It also flags background retrieval as unreliable, which annotations would never 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?

Four sentences cover purpose, output, async behavior, and a prerequisite with zero filler. The most important scoping information (video generation modes) is front-loaded before the operational caveats.

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 21-parameter tool with no output schema and thin annotations, the description covers the high-risk aspects an agent must know before calling: funding requirement, timeout behavior, polling via gemini_get_result, background reliability, and output location. Parameter-level details live in the schema, so nothing critical for correct invocation 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 schema already documents each parameter; the description adds workflow-level meaning by tying task modes to input requirements, recommending async/timeout_ms for long videos, and explaining the disk/MP4 output semantics. It doesn't add much beyond the already-detailed schema descriptions, but the synthesis is useful, so a 4 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 names the exact operation—'Generate a short video via the Gemini omni model'—and enumerates the three input modes: text→video, image/reference→video, and editing a prior video. This clearly separates it from sibling image/audio generation tools despite not naming them explicitly.

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

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

It gives concrete selection criteria: use task edit with previous_interaction_id/continue_last, supply reference images for image-to-video, and use async or raised timeout_ms for long-running jobs, explicitly pointing to gemini_get_result for polling. It lacks an explicit 'don't use for still images/audio' exclusion, so it doesn't fully earn a 5, but the context is clear.

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