openFlow

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

Annotations only cover safety hints (readOnly=false, idempotent=false, openWorld=true), and the description adds substantial behavior beyond them: the token is SINGLE-USE and must never be retried, the account binds to the key's owner group and is picked up by a worker within ~30s without restart, adding is always permitted even after free quota is spent, and a master token grants full account access. It also documents failure and edge paths ('need_email', 'submitted':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?

Purpose is front-loaded and the PREFERRED/FALLBACK headings give useful structure, but at ~350 words this is far longer than needed — it embeds runbook content such as OS-specific curl/irm commands and a literal success string for a separate script, which does not help an agent select or invoke this specific 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?

For a complex, non-idempotent, 0%-schema-coverage tool with no output schema, the description is thorough: it explains the return JSON line, the 'submitted' flag, the 'need_email' branch, propagation timing, and permissions. The only real gap is the undocumented reset_day parameter.

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

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

With 0% schema coverage the description must carry the burden, and it explains email (the Google address just signed into, with a recovery path if it cannot be read) and oauth_token (single-use, obtained from the local script) in rich detail. However reset_day is never mentioned anywhere in the description, leaving one of three parameters fully undocumented.

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 opening states a specific verb+resource: 'Attach one of YOUR OWN Google accounts to the pool using an oauth_token'. It further scopes it as 'the self-serve onboarding path — no server-side browser, no SSH', which cleanly separates it from all generation/list siblings and from the flow_status workflow it 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?

Explicit when-to-use and when-not: the PREFERRED PATH is to call flow_status and run its command yourself and NOT call this tool afterwards; this tool is the FALLBACK only if flow_status has no command or the script fails to submit. The distinction between the two paths and the preconditions ('Node 22+', 'no ticket') is fully spelled out.

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

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

Annotations only declare the safety envelope (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false); the description adds that it performs an OAuth initiation, returns authorize_url and state, and requires an out-of-band user browser action before proceeding. That is real behavioral context beyond the annotations, though it doesn't state that repeated calls yield fresh state values or the lifetime of the returned state.

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

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

Purpose and the disambiguating 'not a Flow account' caveat are front-loaded in the first sentence, followed by a compact, ordered next-step paragraph. Every sentence carries information an agent needs to drive the flow; nothing is padding.

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

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

With no output schema, the description correctly compensates by naming the return values (authorize_url, state) and describing the full two-step handoff to the user and back into add_antigravity_submit. An agent has everything required to drive this tool and its follow-up correctly.

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

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

Zero input parameters, so the baseline is 4. The description does supply the meaning of the state value that must be threaded into the follow-up add_antigravity_submit call, which is useful even though this tool itself takes no arguments.

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

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

Names a specific verb+resource ('Begin connecting a Google ANTIGRAVITY account') and immediately scopes it away from the crowded Flow-account siblings ('not a Google Flow account') and disambiguates from Claude/Gemini model options. An agent can tell this is the OAuth initiation step for the antigravity credential flow without opening any schema.

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

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

Explicitly sequences the workflow: call this to begin, hand the user next_step wording plus the URL, have them sign in and press Accept, collect the code=... value from the callback page, then call add_antigravity_submit(code, state). The next tool is named with its exact arguments, so routing is 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?

With annotations already declaring this is a non-readonly, open-world, non-idempotent write, the description still adds rich context: the return fields, the default one-step GCP project creation, the deferred path, the failure shape with requires_project/onboard_error, and specific error strings. This goes well beyond what the 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?

The description is front-loaded with the purpose, then parameters, return shape, default behavior, and errors. Despite handling a multi-step OAuth flow, every sentence adds actionable information; the repetitive 'start again' is confined to distinct error cases and is not wasted.

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

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

With no output schema, the description supplies the return shape and failure modes. Annotations cover safety, so the remaining burden is on behavior and parameters, both of which are complete for an agent to call this 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 0%, so the description carries the full parameter burden. It defines `code` as the `?code=...` value from the callback page, `state` as the value returned by add_antigravity_start, and `complete` as controlling immediate GCP project creation vs deferral. All three parameters are explained with enough meaning to invoke correctly.

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+resource ('finish connecting a Google Antigravity account') and immediately ties it to the sibling 'add_antigravity_start' that starts the flow. An agent can distinguish this from both the start and completion tools 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?

It explicitly says when to use this tool ('started with add_antigravity_start'), names the alternative ('complete_antigravity_account') and the condition for using it ('pass complete=False to defer'), and gives recovery instructions for each error. No inference 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?

Beyond the annotations, the description discloses that the tool routes through Anthropic or Google Vertex subscriptions, surfaces 'tool_calls' when the model elects to invoke tools, and enumerates failure conditions (invalid key, subscription not connected, quota exhausted). These auth and error specifics add real value over the annotation set.

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 Args/Returns/Raises structure is front-loaded and easy to scan, with the core purpose in the opening sentence. It is slightly verbose, but every section carries distinct information, so little is wasted.

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

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

With no output schema, the description compensates by specifying the return shape ({text, usage}, plus tool_calls) and the error surface. Combined with the auth/subscription context, it is nearly complete for a chat tool; only explicit selection guidance versus the Gemini siblings is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it documents all six parameters (messages, system, max_tokens, tools, account_email, account_tag) with meaning and optionality. It notably clarifies the Anthropic tool_use format for 'tools' and the filter semantics of account_email/account_tag, which the schema does not.

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 ('Запрос к Claude Sonnet 4.6' — a chat request to the Claude Sonnet model) and names the exact model, which distinguishes it from siblings like chat_gemini_flash and chat_gemini_pro. An agent can identify the tool's action and target 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?

It notes the tool requires an Anthropic subscription (or falls back to Google/Vertex) and supports tool_use, which frames usage, but it never states explicitly when to choose this over the sibling chat_gemini_* tools. The routing guidance is only implied by the model name, so it sits at minimum-viable.

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 annotations, the description discloses important behavior: calls go through the user's Google subscription rather than consuming platform tokens, quota/connection failures raise MCPError, and Gemini thinking tokens count toward max_tokens causing truncation. This adds meaningful operational context not present in the structured annotations.

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

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

The purpose is front-loaded, followed by structured Args, Returns, and Raises sections. Although detailed, every sentence carries useful semantics for a seven-parameter LLM call, 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?

The description supplies return shape, error conditions, account selection, token-limit behavior, and thinking controls. Since there is no output schema, the explicit Returns section is especially valuable and makes the definition complete for correct 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?

With schema description coverage at 0%, the description fully documents all seven parameters: messages format, optional system prompt, max_tokens default/range and truncation caveat, thinking_budget values, thinking_level values and priority, and account forcing via email or tag. It compensates completely for the bare 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 names the specific model (Gemini 3 Flash) and concrete use cases (short queries, classification, field extraction), which clearly distinguishes it from siblings such as chat_gemini_pro and chat_claude_sonnet. An agent can identify both what the tool does and where it fits.

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 use-case guidance (short requests, classification, extraction) and notes the cost/billing advantage, but it does not explicitly state when not to use it or name preferred alternatives for longer or more complex tasks. The context is clear, but sibling routing is only implicit.

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?

Goes well beyond the annotations: it discloses that calls bill against the user's Google quota, that the account must be connected first, the exact failure modes (invalid key, Google not connected, quota exhausted), and the return shape. It also flags a non-obvious behavior — thinking tokens count against max_tokens, so a low limit truncates output with finish_reason 'length' — which an agent could not infer from the schema.

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

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

Front-loads the model identity and the billing/routing distinction before the Args block, so an agent gets the decisive information in the first two lines. It is long, and the Args section partially duplicates schema field names, but with 0% schema coverage that repetition is doing real work rather than padding.

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

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

For a 7-parameter open-world LLM call with no output schema, the description supplies return structure, error behavior, quota implications, and full parameter semantics — nothing essential for calling it correctly is missing. The only shortfall is the absence of model-selection guidance relative to the flash/sonnet siblings.

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 0%, so the description must carry the full burden and it does: every one of the 7 parameters is documented, including the messages role/content shape, the max_tokens range 1..65536, thinking_budget's special values (0 / -1 / N), thinking_level's allowed values and its precedence over thinking_budget, and the error semantics of account_email when the account is absent from the pool.

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 — a chat request to Gemini 3 Pro — and immediately qualifies the routing model: it runs through the user's own Google AI Pro subscription and Google account. This lets an agent tell it apart from chat_gemini_flash and chat_claude_sonnet without opening any schema, since the model and billing path are named 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?

Gives a prerequisite ('подключите на /connect-google') and the cost implication ('Расходует вашу квоту Google, не наши токены'), which implies usage context but never states when to pick this over chat_gemini_flash or chat_claude_sonnet, nor any when-not-to-use condition. Usage is inferable from the model name rather than guided.

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 openWorldHint, so the safety profile is covered. The description adds valuable context beyond annotations by warning that the tool returns only the project list and not real credit numbers, preventing a likely misinterpretation based on the tool name.

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 with no filler; the core purpose comes first trailing by a clear caveat. Every word contributes, and the note about flow_dashboard is essential and tightly worded.

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?

The tool is simple: one optional parameter, no output schema, and read-only/idempotent annotations. The description fully covers its limited scope—what it does, how to scope it, and why it might be confused with a sibling—so nothing critical is missing for correct 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?

Schema coverage is 0%, so the description must clarify the account parameter. The phrase 'for a Google account (or all)' conveys that the optional account parameter selects a specific account or includes all projects, adding meaning beyond the raw schema. It could more explicitly link 'account' to the parameter name, but the intent is clear.

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 operation: checking/list projects for a Google account or all accounts. It also distinguishes itself from flow_dashboard by explicitly stating that this tool only returns the project list, not credit balances.

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 flow_dashboard() as the preferred alternative when credit balances or an at-a-glance overview are needed. This gives the agent a clear selection rule: use check_credits for project lists, not for credit numbers.

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 idempotentHint, and the description adds substantial behavioral context beyond them: progress fields, queue semantics, URL expiry, and server-copy reclamation. This fully discloses what happens to results over time, which is valuable for a polling 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?

Although longer than average, every section earns its place: what fields are reported, how to interpret them, and what to do on completion. The critical 'done' action is explicit and 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 a tool with no output schema, the description covers the response shape well, including progress fields, download_urls, save_as, and URL expiration. The main gaps are the undocumented include_preview parameter and explicit status enum values, but overall it is nearly 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 0%, so the description must compensate. It gives real semantic meaning to job_id ('previously returned by...'), but it never mentions include_preview, the optional boolean parameter. This is partial compensation rather than complete parameter 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 uses a specific verb ('Check') and a clear resource ('status/result of a job'), and it explicitly scopes the job to those previously returned by four named generator tools. This makes it easy to distinguish from sibling generator tools and other status-type 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 clearly states when to use it: only for jobs previously returned by the listed generators. It also gives concrete post-completion actions (save download_urls into the project). It does not explicitly name an alternative tool or state when not to use it, but the context is sufficient for a poll-type tool.

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 idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely new context beyond them: what actually happens (GCP project creation) and the return behavior for already-onboarded accounts (project_id).

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

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

Three short sentences, front-loaded with the core action and consequence, then the idempotency guarantee. No filler; every sentence adds an operational fact.

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

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

No output schema exists, yet the description covers the meaningful return case (project_id for onboarded accounts) and the idempotency contract. The only remaining gap is the identity/format of account_id, which is left entirely to the bare schema.

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

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

One required parameter (account_id) with 0% schema description coverage, so the schema does not explain it and neither does the description. The text implies an account context but never clarifies what account_id is or where to obtain 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?

Specific verb and resource ('Finish an Antigravity account') with a named sibling as the antecedent ('started with add_antigravity_submit') and the concrete downstream effect ('Creates the GCP project'). An agent can distinguish it from add_antigravity_submit/add_antigravity_start without opening a schema.

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

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

The description establishes the prerequisite workflow step by referencing add_antigravity_submit and the condition under which the tool is needed (before the account can serve LLM requests). It does not name an explicit alternative or a when-not case, but the sequencing is 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 already declare that this is a non-read-only, open-world, non-idempotent operation. The description adds useful context: no Telegram account is required, a human responds usually within hours, and replies must be read via support_replies. It does not mention authentication or rate limits, but with annotations covering the safety profile, this is solid.

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. The main action is front-loaded, and the reply-reading instruction follows immediately.

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?

The tool is simple, has no output schema, and annotations cover key safety traits. However, the optional context parameter is not explained, which leaves an agent guessing about its purpose when composing the message.

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 0%, so the description must compensate. It does not explain the optional context parameter at all, and only minimally implies what message should contain. The required message parameter is inferable, but the context parameter is left undocumented.

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 — sending a message to the openFlow human operator — and explicitly distinguishes this from reading replies via the sibling tool support_replies. An agent can tell exactly what the tool does 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?

It clearly indicates when to use the tool: contacting a human operator. It also routes follow-up behavior to support_replies for reading responses. It does not explicitly list exclusions or other alternatives, but the sibling relationship 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?

Goes well beyond the annotations by explaining the exact side-effect scope: it only returns an entity_id with no portrait/body/description. It also discloses execution context ('Plain HTTP, no browser involved') and the non-obvious constraint that each character image slot accepts exactly one write, with a second call 500ing rather than overwriting.

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?

Although substantial, every sentence carries operational value: it front-loads the core behavior, then routes to the sibling, then gives a clearly ordered numbered list of follow-up calls. The format is efficient and scannable, with no filler or redundant restatement of the tool name.

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

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

The description is nearly complete: it states the return value (entity_id), the sibling alternative, and the required follow-up sequence. The only material gap is the undocumented 'account' parameter, which prevents the description from being fully self-sufficient for a correct first call.

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

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

Schema description coverage is 0% and the description never mentions the required 'account' parameter. With one required parameter and no schema documentation, the description was expected to compensate, but it provides zero guidance on what account means, where to get it, or what format it should take.

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 action ('Create a new, empty Flow character') and resource, and explicitly delimits what it does not do: 'no portrait/body, no description yet'. It clearly distinguishes itself from the higher-level sibling create_character_from_description, so an agent can tell which tool to invoke.

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 routing guidance: 'for "make me a character from a description and generate its portrait", call create_character_from_description instead of this'. It also provides a numbered next-step sequence after obtaining entity_id, including the warning that reversing the order causes 500s, which is directly actionable.

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=false, idempotentHint=false, openWorldHint=true, destructiveHint=false, but the description adds critical non-obvious behavior: the portrait slot is written exactly once and cannot be regenerated, and re-calling with the same name fails fast rather than surfacing an HTTP 500. It also documents the return payload shape, going well beyond what the annotations cover.

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 the value proposition in the first sentence, then uses labeled parameter notes and a return/next-step block. It is on the long side, but the labeled structure makes it scannable and most sentences carry needed 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?

For a 7-parameter, no-output-schema mutation tool, the description compensates well by explaining the return fields and the mandatory follow-up workflow (use generate_with_face, never entity_id). The main gap is the four undocumented optional parameters (model, aspect, display_name, portrait_prompt), which an agent cannot reason about from the description.

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 0%, so the description carries full burden. It documents name (uniqueness scope), description (dual use for card and portrait, concrete-prompt guidance), and account (Google account/project) well. However, 7 parameters exist and model, aspect, display_name, and portrait_prompt are left entirely undocumented in both schema and description, so it only partially compensates.

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 ('Invent a new character from a text description and generate its portrait') and explicitly positions it as the 'no photo involved' path, distinct from create_character_from_photo. It also names the sibling tools (create_character, update_character, generate_character_image) it replaces. An agent can tell immediately what this does and how it differs from 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?

Explicit when-to-use ('make me a character, no photo involved'), names the alternatives it replaces, and provides a clear next step (generate_with_face) plus a when-not condition ('Want a different look? Use a new name'). 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?

The description goes far beyond the basic annotations: it discloses the ~15-30s Chrome boot cost, that no image generation occurs, that no Android/recaptcha is involved, that name clashes do not fail the call but produce a registration_error, and the fidelity limitation that 'genuinely consistent' means internally consistent rather than an exact match to the real person. This is rich, accurate behavioral context that complements the annotations without contradicting 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 description is front-loaded with the core behavior and has useful per-parameter structure, but it is overwrought. It includes dated editorial notes and corrections ('CORRECTED same day as this tool was first built', 'Fidelity note added 2026-07-11'), which add historical context but could be condensed without loss of operational meaning.

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

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

For a 5-parameter tool with no output schema, the description is exceptionally complete. It covers the full workflow after the call (update_character, generate_character_turnaround, generate_character_expression_sheet), the failure mode for duplicate names, the latency expectation, the exact-photo versus consistent-with-itself distinction, and when to route to generate_video_with_reference instead. An agent has everything needed to call this correctly and interpret the result.

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

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

With 0% schema description coverage, the description carries the full burden, and it largely succeeds: it explains that photo_base64 is raw base64 without a data: URI prefix, describes body_photo_base64 as optional and ideally full-body, gives a detailed example for physical_description, and explains the uniqueness and registration behavior of name. Only the required account parameter is not explained, and even that gap is minor.

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: 'Create a new Flow character whose portrait (and optionally body) is a REAL PHOTO.' It immediately distinguishes itself from text-description or generation-based creation, which differentiates it clearly from siblings like create_character and create_character_from_description.

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 and alternatives. It tells the agent to use generate_video_with_reference when a recognizably real person is the goal, and to use generate_character_turnaround or generate_character_expression_sheet when further generated panels are wanted, while noting when to skip them if a real body photo was provided.

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 annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false), the description discloses substantial behavioral nuance: results are usable immediately, the project may not appear in the web UI (registered: false), account rotation for generation continues, and media_ids remain account-bound. These details are essential for correct agent behavior and are not present in the annotations or 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?

The description is dense but every sentence serves a purpose: purpose, usage guidance, parameter semantics, and edge-case behavior. It is well-organized with clear paragraphs and no repetition or filler. The length is justified by the tool's nuanced behavior, and the most important usage context is front-loaded.

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

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

For a tool with no output schema, the description states the exact return format ({"project_id", "account", "registered"}), while also covering prerequisites, immediate usability, and the UI registration caveat. It is complete enough for an agent to know when to call it, how to call it, and what to expect back.

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 0%, so the description must carry the full semantic load. It explains account in depth: which Google account creates it, that project_id is a label accepted by all accounts, and that media_ids are still account-bound. It also explains name as an optional human-readable title, e.g., the client's name. This fully compensates for the schema's lack of 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 opens with a specific verb and resource: 'Create a NEW Flow project on one of your Google accounts and return its project_id.' It clearly distinguishes this from generation and account-management siblings by tying it to per-client namespaces and explicitly referencing when to use it with generate_image/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 explicitly says when to use it: 'Use this to give every one of YOUR OWN clients their own namespace: create a project per client once, then pass that project_id to generate_image / generate_video.' It also points to sibling tools for account emails (flow_dashboard / check_credits) and explains the operational distinction between account-bound media_ids and project_id grouping.

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 give readOnly/destructive/openWorld flags; the description adds real substance — credit costs (20, 10 for 360p), the upload mechanism via Flow's Scotty resumable upload, the 10-second span limit, that the result is ONLY the piece, that it's not a mask tool and mask/style image types are not honored, and that seed detail may not carry across resolutions. This is exactly the extra context annotations don't supply.

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

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

Front-loads the purpose and examples, then organizes source/piece/reference/credits/template in scannable blocks. The prompt template is long but earns its place for this model. Minor: the Scotty/Web Ingredients parenthetical reads as internal jargon that an agent doesn't need.

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?

A 10-parameter, no-output-schema, mutation tool; the description covers source selection, span limits, reference images, costs, and the model-key workflow. Gaps are small (seed behavior partially covered, aspect/include_preview unmentioned) and no return-shape explanation is strictly needed since the tool implies a video result, but a line on output would help.

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 0%, so the description must carry parameter meaning and it does: media_id vs. video_base64 semantics and constraints (mp4/mov/avi/3gp, 60s/1GB), start_sec/end_sec must be both or neither and at most 10s, reference_images_base64 up to 5 raw base64 with no data: prefix, prompt template guidance. Only seed, aspect, include_preview, and video_model_key are unmentioned.

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 (rewrite/edit) plus resource (video) and gives four concrete example prompts showing the kind of transformation. It is clearly differentiated from siblings like generate_video, recast_video, and extend_video because the examples all describe modifications to existing footage.

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 says a source is required and lists the two mutually exclusive source types (media_id from a previous generate_video result vs. own video_base64). Gives credit costs and a draft-on-360p-then-final workflow. It doesn't contrast against recast_video or extend_video, which would be the natural alternatives to name.

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?

Goes well beyond the annotations by disclosing cost (10 credits, adds 8 seconds), the default model, the account-pinning behavior ('the job is pinned to that account instead of rotating'), and the failure mode for an unrecognized id ('a clear error, not a mystery failure'). Annotations only give the generic mutation/open-world profile; the description adds real operational 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?

Front-loaded with the purpose and organized into labeled paragraphs per parameter, so an agent can scan it. A few phrases are slightly embellished ('not a mystery failure') but nothing is truly wasted; it is a touch longer than strictly necessary.

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

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

No output schema exists, so the description must cover returns, and it discloses the cost/added-duration and error behavior instead. Combined with annotations covering the safety profile, the main gap is that four schema parameters (seed, aspect, include_preview, alternate model keys) get no descriptive treatment.

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

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

With 0% schema coverage the description must carry parameter meaning, and it does for the critical ones: media_id is explained down to the format gotcha ('the bare id, not the /v1/media/... path') and project_id is explained with an omit-if-unsure default. It also names the default video_model_key and its credit cost, though seed, aspect, and include_preview are left entirely to the bare schema.

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

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

States a specific verb+resource: 'Continue a video this service already generated — Flow writes what happens next.' This clearly distinguishes it from generate_video (fresh generation), edit_video, and recast_video, all of which are siblings with overlapping surface area.

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 when to use it ('shots that need to run longer than one generation, or to keep a scene going without re-describing it') and contrasts it against the alternative ('a fresh text-to-video call cannot do' this). It also states the prerequisite constraint: only videos made through this service can be extended.

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

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

Annotations only mark it read-only/idempotent; the description adds substantial behavior: default refusal of large files, token-cost math for base64 text vs. image, account-group scoping, disk-cache eviction order, `retry_after_s` retry semantics, `reconnect_url` on disconnect, and the 410 fallback. This is far beyond what the annotations 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?

Purpose and the 'expensive path' warning are front-loaded, which is correct. It is long and somewhat repetitive (the 'text/context dies' cost point is made twice), but the storage/error paragraph earns its place for a tool with this much failure surface.

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

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

No output schema exists, so the description supplies the return shape `{"filename", "media_type", "base64"}` and documents the failure modes (size refusal, retry_after_s, reconnect_url, 410). An agent has everything needed to call and recover 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 0%, so the description must carry all parameter meaning — and it does: `path` (which job-result field it comes from, example format, bare filename allowed), `max_kb` (ceiling plus its default and token equivalent), and `force_bytes` (when to set it and its cost). Full compensation.

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 (download) and resource (generated media file, video/frame) and the return shape (base64 bytes), and explicitly contrasts itself with `download_url` and `check_job`. An agent can tell exactly what this is 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 and when-not: prefer `download_url` as the cheap path, pass `force_bytes=True` only when the bytes are genuinely needed in-conversation, and use `check_job` rather than this tool to poll status. Alternatives and exclusions are all named.

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 indicate readOnly/idempotent behavior; the description adds genuinely useful context by disclosing that credit balances are live via Flow's /v1/credits and that the refresh date is only an estimate because the upstream API does not expose a hard date. This is information an agent could not infer from the schema or 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 output, then gives the use case, then the data caveat; each sentence earns its place. There is minor stylistic repetition of the dashboard/control-panel metaphor, but no substantive bloat.

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 parameters and no output schema, the description still tells the agent what will come back (`summary`, `accounts`, `totals`) and enumerates the account-level fields. It also flags the one caveat (estimated refresh date), so nothing needed to call and interpret the result 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 there is nothing for the description to add. Per the baseline for no-parameter tools, this is fully adequate.

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 a concrete verb ('returns') and a clear resource: an account-pool dashboard covering per-account credit balance, tier, project count, health, plus totals. It positions itself as the operator's dashboard scoped to 'EVERY Google account,' which implies differentiation from narrower siblings like check_credits, but it never names an alternative 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 explicit when-to-use guidance: 'Use this to answer "how many accounts, how many credits on each and in total, what projects"' and highlights that it is a single call. It does not state when not to use it or which sibling to prefer instead, so it stops short of full routing 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 cover read-only/idempotent/closed-world, so the safety profile is handled. The description still adds real value by enumerating what the response contains (queued + warming + running, disk free_gb/below_target/below_floor/refusing_jobs) and defining the 'degraded' status condition, plus noting the Android emulator is off so warming jobs no longer imply a warm-up delay.

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 keeps the payload enumeration tight. The closing 'Android emulator is now OFF' note is a bit of a changelog aside that doesn't directly help an agent decide or call, but it is short and defensible context.

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

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

No output schema exists, so the description carries the burden of describing returns — and it does reasonably well, listing queue composition, disk fields, and the degraded threshold. It omits any reachability field/boolean and error-signalling behavior, which are small but real gaps for a health-check 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?

The tool takes zero parameters, which is the baseline-4 case. The field names listed (disk sub-fields, status) describe the response rather than inputs, so there is nothing further for the description to add on parameter semantics.

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

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

Names a specific action (health check of the Flow generation backend) plus the exact payload it inspects — queue depth and disk state. It does not, however, differentiate itself from close siblings like flow_status, flow_dashboard, or check_job, which an agent could easily confuse it with.

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?

There is no explicit when-to-use guidance, no preconditions, and no mention of flow_status/flow_dashboard/check_job as alternatives. Use is only inferable from the word 'check', which is the same situation as the MID calibration example that scored 2.

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 cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false), and the description adds substantial context beyond them: it spends nothing, it returns a single most-blocking next_step with text/text_en/url/command, and it explains that sign-in steps occur in the user's own browser. This is rich behavioral disclosure that an agent needs to act correctly.

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 guidance is front-loaded and clear, but the description sprawls across several paragraphs and drifts into tangential territory (the 'support' Telegram paragraph, and detailed Antigravity routing instructions) that is not essential to selecting or invoking this 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 carries the return-value burden and does so: it names the important next_step field, its subfields, and the weekly limit. It also tells the agent what to do with the result, so nothing needed to call and use this tool 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 takes zero parameters, so there is nothing for the description to clarify and the baseline of 4 applies. The description instead documents the returned fields, which is a different concern handled under contextual completeness.

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 preflight-check purpose: 'What this key still needs before it can do everything', plus a one-shot enumeration of what it reports (Google account, free trial, GitHub link, weekly limit). It implicitly distinguishes itself from siblings by naming add_account_token as the fallback and add_antigravity_start/submit as the alternate path.

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 trigger conditions: 'Call this BEFORE the first generation of a session, whenever a call is refused, and whenever the user asks why something does not work.' It also names the concrete alternatives and when to prefer each (run the command, add_account_token only as fallback, add_antigravity_* for Antigravity accounts).

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 explicitly states 'this overwrites the existing portrait image with the expression sheet', which is a destructive action on the existing image. This directly contradicts the annotation destructiveHint: false. The contradiction is severe and undermines the agent's ability to assess risk, warranting a score of 1. Other behavioral details (pure HTTP, unverified consistency) are provided but overshadowed by the 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 front-loaded with the core purpose but then launches into a lengthy historical narrative with specific dates (2026-07-11, 2026-07-26) and technical details that are not directly relevant to invoking the tool. This reduces conciseness and may distract the agent from the essential operational details. The structure could be improved by moving historical context to a separate section or removing it.

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?

The description covers most operational aspects (how to specify expressions, which slot to write) but misses the entity_id parameter entirely, which is required. It also includes extraneous historical context that does not aid invocation. The description is not fully complete for an agent to call it correctly without guessing what entity_id refers to, and it lacks any mention of the output format, though no output schema exists. Overall, it is adequate but has 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?

With schema description coverage at 0%, the description must explain all parameters. It explains account (Google account that owns the project), expressions (list with default and recommended count), and character_slot_index (which slot, default 0, overwrites). However, it fails to explain the required parameter entity_id, leaving it undefined. This is a significant gap for a required parameter, so the description only partially compensates for the schema's lack of 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 generates a single image of the character's face with multiple labeled expressions in a row, explicitly naming it an 'expression sheet'. It also distinguishes itself from the sibling generate_character_turnaround by noting same job type but different output, making the purpose 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 provides context on when to use this tool by referencing generate_character_turnaround and explaining the historical reason for its existence. It also offers usage guidance on the expressions parameter (keep to 3-5) and character_slot_index (0 overwrites portrait). However, it does not explicitly state when not to use this tool or compare it to other sibling image generation tools, leaving some inference.

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

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

Annotations only give readOnly=false/idempotent=false/destructive=false; the description adds substantial behavioral detail beyond that: one-shot-per-slot semantics, HTTP 500 on a second write with no overwrite, a 500 on first write without personality_notes, server-side slot consistency, and per-account ownership/scoping. It is consistent with idempotentHint=false.

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

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

Front-loaded with the core purpose, then parameter notes, then caveats — a sensible structure. It is long and the live-confirmation dates and repeated 'this caveat mainly matters if...' framing add some bulk, but each block carries actionable information rather than filler.

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

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

For a complex, non-idempotent, 6-parameter generation tool with no output schema and zero schema descriptions, the description covers preconditions, failure modes, alternatives, and account scoping thoroughly. The main omission is any indication of the return shape (job id, media handle) or latency, which an agent might want.

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 0%, so the description must carry the load. It documents the non-obvious parameters well: entity_id's provenance (create_character / create_character_from_photo / create_character_from_description slot 0), character_slot_index (0=portrait, 1=body), and account (optional, auto-looked-up). prompt, model, and aspect are left undocumented, though their names and enums are largely self-describing.

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 gives a precise verb+resource+scope ('Generate a portrait or body image for an existing Flow character') and immediately bounds it against siblings by stating it 'DOES NOT PLACE A CHARACTER INTO A NEW SCENE' and naming generate_with_face instead. An agent can distinguish it from generate_image, generate_with_face, and generate_video_with_reference without opening a schema.

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

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

Explicit routing: use generate_with_face for 'character doing X' scenes, use generate_video_with_reference for real-person identity. It states prerequisites (call update_character with personality_notes before the first write on a fresh entity_id) and the when-not (second write into a filled slot fails). Very few gaps 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?

Beyond annotations, the description discloses the exact mechanism (pure HTTP, image_inputs using the character's portrait_media_id), that it uses a third mechanism rather than either compared path, that it has not been re-verified live, and what the recommendation does and does not prove. This is unusually candid about limitations.

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 the length is earned: the history, mechanism change, and reliability caveat are essential for correct use. It is organized into clear sections and front-loads the core purpose before the detailed backstory, though it could be trimmed without losing meaning.

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

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

The description covers purpose, mechanism, reliability status, prerequisites, slot behavior, and account ownership. It does not describe the output format or how to retrieve the image, and it leaves some parameter definitions to inference, so it is not fully complete, but it is strong given 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?

With 0% schema description coverage, the description helps by defining account and character_slot_index with explicit semantics and defaults. However, it does not explain entity_id beyond 'entity_id's project' and completely omits outfit_description, leaving two parameters under-specified.

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: 'Generate a single image showing the character's FULL BODY from 3 angles (front/side/back) in one row, labeled — a turnaround sheet.' It also explicitly distinguishes this path from plain generate_character_image, making the tool's unique role clear.

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 explains when this tool exists: plain Android-bearer generation was inconsistent for multi-view prompts, while a browser-composer path was consistent. It also gives a prerequisite recommendation (save a detailed physical description first) and warns that the new mechanism's multi-view reliability is unverified, which is critical usage context.

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?

Goes far beyond the annotations: per-model latency, a separate daily per-account quota on GEM_PIX_2 with 429 account rotation, HTTP 400 on bad ids with no silent fallback, ~0.1% reproduction with a fixed seed, URL expiry within the hour, and server copies subject to reclamation. Crucially it also discloses silent degradation paths — preview failure falls back to the plain result rather than erroring, and a slow job returns a job_id instead of blocking.

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

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

Front-loads purpose, then walks parameters in a stable order with the operational save instruction placed after them. Almost every sentence carries non-obvious information, but it is long and occasionally discursive ("worth doing in a loop of many generations, where the previews would fill the context"), and the all-caps save paragraph is stylistically heavy.

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

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

For a 9-parameter generative tool with no output schema, it covers return shapes ({urls, media_ids} or job_id, plus the three-block preview form), polling handoff, file persistence, and preview-vs-media_id authority. The only meaningful omission is aspect ratio handling, which is a parameter issue rather than a missing call-critical behavior.

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

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

With 0% schema coverage the description carries the full burden and mostly succeeds: it gives exact model ids with aliases, destination semantics, and rejection behavior, explains seed ranges plus why a seed is needed for honest comparison, and defines image_inputs vs control_images (mediaIds vs base64 bytes without data: prefix, up to 10) and idempotency_key's 24h window. The notable gap is `aspect`, which is never mentioned despite being an enum parameter.

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

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

Opens with a specific verb+resource+provider ("Generate an image from a text prompt via Google Flow") and immediately differentiates scope by routing whole-scene layout work to generate_scene. An agent can distinguish it from generate_character_image or generate_with_face 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?

Explicit routing to siblings: control_images are for spatial layout but "For whole-scene layout control prefer generate_scene", and image_inputs with a reference frame's mediaId is named as the fix when seeds stop holding the character. create_project, check_job, and upscale_image are each given a condition for use. It stops short of saying when to use this tool versus generate_character_image or generate_with_face, which is the main unresolved fork among siblings.

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 (only readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false), so the description carries the burden and does so richly: control_png's context cost in characters, palette leakage from the guide ('light' background workaround), calibration cutting framing drift ~4x, measured sensitivity (2-20cm translations ignored, 15-60° rotations honored), and the caveat that a fixed seed only repeats an unchanged control image.

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?

Long but front-loaded and information-dense — the core mechanism comes first, then per-parameter semantics. Nearly every sentence contributes a non-obvious fact (rotation-as-pose, depth-ControlNet use, legend in the return), though a few parentheticals run longer than needed.

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

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

No output schema exists, but the description documents the return shape ('urls', 'media_ids', 'legend', 'control_png_kb') and explains what legend maps. Combined with the nested scene_layout structure and the control_png cost warning, an agent has everything needed to invoke 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 0%, so the description must compensate, and it largely does: it documents the scene_layout shape, camera_id, the full aspect value list absent from the schema, style/extra placement, seed/image_inputs, depth, calibration, background, and control_png. Only project_id is left undocumented, a small gap against a 12-parameter tool.

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 ('Build a location... and generate its plate') and immediately identifies the mechanism: rendering a control image from a scene-layout/v2 map. It explicitly distinguishes itself from the prose-driven sibling path ('instead of describing the room in prose'), so an agent can separate it from generate_image without opening either schema.

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

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

Names when to use this path (geometry must be pixel-exact, same room across shots) and when the prose path fails (furniture drifts, depths change). It also gives routing rules for adjacent parameters: sequence frames should pass a reference frame's mediaId in image_inputs, and seed is explicitly called out as insufficient for identity.

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?

Goes well beyond the annotations: discloses the 1-3+ minute runtime and job_id-then-check_job polling loop, credit costs per model tier, seed reproducibility semantics and its limitation, and 24h idempotency dedup. These are exactly the operational facts an agent cannot get from readOnlyHint/openWorldHint.

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

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

Front-loaded with the purpose, then organized around parameters with clear labels. It is long, but nearly every sentence carries non-obvious operational guidance (beats physics, seed caveat, polling cadence); the cost annotations in the model list are the only mildly redundant portion.

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 long-running, credit-spending mutation with no output schema, it covers the critical missing pieces: async job lifecycle, cost tiers, dedup, and reproducibility. The main gap is the audio/voice parameter family, which an agent would have to guess at.

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 0% and there are 11 parameters, so the description must carry the load. It gives rich semantics for video_model_key, project_id, beats, seed and idempotency_key, but leaves voice, voice_text, voice_style, aspect and include_preview entirely unexplained, and it documents only 4 of the 11 model keys (the 6s/8s/10s/360p variants go unmentioned). Substantial added value, but under half the surface covered.

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 from a text prompt via Google Flow (Veo models)'), which implicitly separates it from the image/frame/reference-based video siblings. It never names those alternatives explicitly, so an agent must infer that this is the text-only path, but the resource qualifier is enough to disambiguate.

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 covers when to use (text prompt), how to attach output to a project ('one project per end client'), when to set beats vs leave it out, when to use idempotency_key ('when you may retry after a timeout or a busy error'), and it routes the agent to edit_video instead of a fixed seed when the prompt changes. Alternatives and exclusions are both present.

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 cover the safety profile (non-readonly, open-world, non-idempotent), and the description adds substantial context on top: images must be raw base64 with no data: URI prefix, the default model is the 10-credit/8-second cheap one versus a 100-credit key, and the model STRETCHES described action over the requested duration (with a measured example). This is exactly the kind of cost/behavior disclosure that helps an agent invoke the tool well.

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

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

The purpose and the beats semantics are well front-loaded, but the description is padded by near-verbatim duplication: the 'beats' paragraph and its 31.08.2026 stretching measurement appear twice, and the project_id sentence repeats the beats explanation. A tight edit would cut roughly a third of the text with no loss of meaning.

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

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

For a 9-parameter, 0%-schema-coverage tool with no output schema, the description covers the critical semantics (beats, cost/model choice, image encoding, project scoping) but silently omits seed, aspect, and include_preview, and never enumerates what the eleven video_model_key values mean beyond the default. Adequate, with clear remaining 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 0%, so the description carries the full burden. It explains beats in depth (distinct action phases, ~two per second, server picks length, adjectives don't count), the two image params (raw base64, no prefix), and project_id (must come from create_project). It leaves seed, aspect, and include_preview entirely unexplained, so it doesn't fully close the 9-param gap.

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 the transition between TWO given frames') and immediately scopes it: video starts at first image, ends at second. It explicitly contrasts with the sibling generate_video_from_image ('only pins the FIRST frame'), so an agent can pick between them 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 explicit when-to-use conditions with concrete examples ('a logo that must resolve exactly', 'two stills from a storyboard'), names the alternative tool, and explains the mechanism difference that selects it. Nothing about tool selection 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 only supply the generic write/openWorld profile, so the description carries the real burden and delivers: the chained job 'runs on the account that made the source clip', start_image_base64/start_media_id are mutually exclusive with r2v, the model 'STRETCHES' described motion over the requested length (with a measured example and a 15% movement loss), and voice only works with speech-capable Veo 3.1 i2v models.

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?

Long but front-loaded: the core rule and the exclusive-argument choice come first, then chaining, then the r2v steer, then beats guidance. Nearly every sentence carries actionable content, though the dated measurement anecdote and the cross-reference to another tool's docstring could be trimmed.

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 13-param generation tool with no output schema, the description supplies return-relevant details anyway (finished videos carry last_frame_path and a media_id, and the server reports the picked length and why). Only the unexplained model/aspect/seed options keep it short of 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 coverage is 0% across 13 params, so the description must compensate and largely does: it defines start_image_base64's raw-bytes/no-prefix format, start_media_id's origin and server-side frame default, the frame enum's 'last' default, beats semantics, and project_id's purpose. It leaves seed, aspect, include_preview and the video_model_key enum choice unexplained, which is the only real gap.

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 precise verb+resource and an explicit acronym expansion ('Generate a video that starts from a given image (i2v — image-to-video)'), and actively distinguishes itself from siblings generate_video_with_reference (r2v) and, by implication, generate_video_between_frames. An agent can pick this tool without opening any other schema.

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

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

Explicitly names the alternative for identity preservation ('prefer generate_video_with_reference'), states the condition where i2v wins ('continue visually from this exact frame', chaining clips), and gives a concrete multi-clip chaining recipe with argument examples. Both when-to-use and when-not-to-use are covered.

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 covering the classic hints, the description adds rich behavioral context beyond them: the entity_id/veo_3_1_r2v_lite binding, the historical 500 error, the fact that the job runs on the character's own Google account, mutual exclusivity rules, and model-capability constraints. This is well above 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?

Purpose is front-loaded, but the description is bloated with internal testing anecdotes ('confirmed live 2026-07-11', 'same-day testing found') and tangential parentheticals that dilute the signal. Several sentences do not directly aid tool selection or invocation.

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

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

For a complex 11-parameter generation tool with no output schema, it covers behavior, edge cases, and how to retrieve results (via check_job / first_frame_path). Only the un-explained parameters (seed, aspect, include_preview) leave minor 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 coverage is 0%, so the description must compensate. It documents the trickiest parameters well (reference_images_base64 format/limits, entity_id, voice/voice_style/voice_text, project_id), but leaves seed, aspect, prompt, and include_preview undescribed. Solid but incomplete for an 11-parameter tool.

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 using up to 7 reference images') and immediately names the technique (r2v) and its purpose (consistent character/subject). It actively distinguishes itself from siblings like generate_image, generate_character_image, and generate_character_turnaround.

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 declares itself 'THE RECOMMENDED WAY' for a specific goal (real person from a real photo) and contrasts it against named alternatives that were 'confirmed to drift'. It also states mutual exclusivity with start-image (i2v) generation and notes the image-only fallback via first_frame_path.

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?

Goes well beyond the annotations: discloses latency (~15-25s), quota cost (no image/video quota), async rendering that returns a job_id, the fact that Google's `audio_url` EXPIRES while `download_url` is owned by the service, and that the preview is only the first 8 KB yet costs context. The annotations give only readOnlyHint=false/destructiveHint=false/openWorldHint=true, so this added behavioral layer is exactly what the description should supply.

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 essential verb/artifact sentence and then organizes the rest into tight per-parameter notes and a returns block, with no filler sentences. It is on the long side, but every line carries information an agent needs; the only mild redundancy is restating param names that also appear in 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 6-param mutation tool with no output schema and 0% schema coverage, the description covers everything: return shape ({audio_url, download_url, download_path, media_id, duration_sec_estimate, size_bytes, voice}), the async job_id path, expiry semantics, and retry safety via idempotency_key. An agent can call this correctly and handle the response without further discovery.

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 0%, so the description carries the full burden and does so for all six parameters: text (5000 char cap), voice (default Algieba, plus list_voices()), style (empty = neutral, with examples), project_id (omit for default), include_preview (off by default, what it contains and its cost), and idempotency_key (same key within 24h returns the SAME job). This is meaning the schema titles alone cannot convey.

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

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

Opens with a specific verb+resource and the exact output artifact: 'Speak `text` aloud with a Gemini TTS voice and return a WAV (24 kHz, mono, 16-bit).' This is unmistakably distinct from sibling generation tools (generate_image, generate_video, music_generate) and even names its helper sibling list_voices for voice selection.

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 guidance: use list_voices() to pick a voice, omit project_id for the account default, turn include_preview off to save context and instead use download_url or fetch_media(path=..., force_bytes=True), and call check_job when a job_id is returned. It also names when to supply idempotency_key (retry after timeout or busy error). Missing is any explicit 'do not use this for X' exclusion versus a sibling, which keeps it from 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?

Goes well beyond the annotations by disclosing a hard failure mode (combining entity_id with an image reference returns HTTP 500) and the deliberate design decision to always generate from the reference image alone. It does not cover cost/credit consumption or rate-limit behaviour for a non-idempotent generation call, so it stops short of full coverage.

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 uses bullets and headers so a reader can scan it. It is long, and the aside about entity_id being 'deliberate, not a workaround to fix later' is close to editorial padding, but for a 7-parameter tool with mutual-exclusion rules the length is largely earned.

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

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

For a complex generation tool with no output schema, it covers purpose, when-to-use, mutual exclusivity of the reference inputs and project routing. It omits any description of the generated output or the meaning of model/aspect/include_preview, which leaves minor gaps an agent must resolve by inference.

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

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

With schema coverage at 0%, the description carries the parameter burden and does so for the four critical params: it distinguishes character vs photo_media_id as mutually exclusive, explains the lookup source for character, and describes prompt's expected content and project_id's effect. The model, aspect and include_preview params remain unexplained in both schema and description, leaving a gap.

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

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

States a specific verb and resource with precise scope: 'Generate a NEW image of the SAME PERSON/character as an existing photo or portrait.' It explicitly separates itself from generate_image, generate_character_image and generate_scene by claiming to be 'the ONLY tool for generate another picture of <character I already made>'.

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

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

Gives a concrete when-to-use scenario ('here is my photo, now put me in a suit / in a park') and an explicit routing rule: pass exactly one of character or photo_media_id, with each branch explained and tied to a setup path (create_character_from_description, create_character_from_photo, list_characters). It even states when NOT to use entity_id/character_slot_index and why.

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), yet the description adds substantial non-obvious behavior: two parallel upstream requests, a ~5-minute ETag cache on /v1/me, and that force_refresh adds Cache-Control: no-cache. It also documents the failure mode (MCPError when the key is invalid). This is meaningfully more than the annotations 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?

The purpose is front-loaded as the first sentence, followed by mechanism, returns, and error. The Returns/Raises blocks are long but earn their place because no output schema exists. Slightly verbose for a one-parameter read 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 correctly supplies the return shape (accounts, models, quota) and the error case, plus caching semantics for the sole parameter. The main omission is routing guidance versus the several sibling listing tools, which is minor for a read-only discovery call.

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

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

Schema coverage is 0% for the single force_refresh parameter, so the description carries the full burden and does so well: it explains the ETag cache window and exactly what force_refresh=True changes. An agent can set the parameter correctly without reading any schema 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?

The opening line states a specific resource and outcome in plain terms: which LLM models this key can use right now and the key's quota. It also names the two upstream endpoints it aggregates (GET /llm/models and GET /v1/me), making the scope concrete. It stops short of distinguishing itself from near-siblings such as list_models, list_live_models, or refresh_llm_models, so the agent must infer the boundary.

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 implied (call it to discover available models and quota) and the caching/refresh behavior is explained, but there is no explicit 'use this instead of X when Y' routing against list_models, list_live_models, or check_credits. No prerequisites or exclusions are stated.

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

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

Annotations already declare readOnlyHint, but the description adds substantial behavior: characters are scoped to 'YOU created', the response is ordered oldest first, source values are semantically defined, and the critical caveat that portrait_media_id null means no usable reference yet. This goes far beyond the annotation 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?

The description is compact and front-loaded: the core action and scope appear in the first sentence, followed by the read-only benefit, return shape, and field semantics. Every sentence adds operational value with no filler.

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

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

Although there is no output schema, the description fully documents the return object, field names, ordering, source semantics, and the null-reference caveat. With zero parameters and read-only annotations, nothing essential is missing for an agent to call this 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?

The tool has zero parameters and the schema is empty, so the baseline is 4. The description does not need to explain any parameter details, and it compensates by precisely explaining the output fields that matter, especially portrait_media_id.

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 uses a specific verb and resource: 'List the characters YOU created', and immediately distinguishes this from creation tools by naming create_character_from_description and create_character_from_photo. It also explains how the result connects to generate_with_face, making the tool's role in the workflow unmistakable.

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 communicates when to use this tool: when you need to see your existing characters or find a reference for generate_with_face. It also states read-only behavior and that no credits are spent, but it does not explicitly list alternative tools to choose instead under certain 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 cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), yet the description still adds non-obvious traits: no credits are spent, results are cached ~1 minute server-side, and at least one connected Google account is required. It also describes the partial-failure shape ({statuses: ... {"error": ...}}).

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

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

Front-loaded with the value proposition and the routing hint, then scoping and return shape. Slightly padded by the 'READ-ONLY: nothing is generated and no credits are spent' line, which partly restates the annotations, but every sentence still carries useful 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?

No output schema exists, but the description still sketches the return object and the account/auth prerequisite, plus cache behavior and the failure branch. Nothing an agent needs to call this correctly is missing.

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

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

The tool takes zero parameters, so there is no per-parameter semantics to document; the description correctly spends its words on behavior instead. Baseline for 0 params is 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?

States a specific verb+resource (reads Google Flow's live model catalog with usage keys, prices, durations) and explicitly distinguishes itself from the sibling list_models, which returns the curated accepted-id list. The agent can route correctly 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 explicit when-to-use framing ('use to answer is this model still working?'), names the alternative ('Use list_models instead for the short curated list of ids'), and states the selecting condition ('use this one when you need Google's ground truth'). No inference required.

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 read-only/idempotent/open-world, but the description adds real context: refresh=True triggers a live re-check of the tier with Google (relevant to the open-world hint), and account selection can be overridden via a header.

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 compact sentences, front-loaded with the resource and the return shape, then the flag behavior and header hint. No filler, though the header sentence is slightly tangential to the listing action itself.

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

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

No output schema exists, and the description adequately describes the return (accounts with tiers). For a single-optional-param read tool with annotations covering safety, this is nearly complete; a note on ordering or empty results would be the only 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?

Only one parameter with 0% schema description coverage, so the description must compensate, and it does: 'refresh=True re-checks the tier with Google' explains both the meaning and the side effect of the flag; the default of false is left to the schema. The X-Account-Email guidance also clarifies how callers target an account.

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

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

Names a specific verb and resource ('List the Google accounts you connected for the LLM relay') plus the returned attribute (tier Free/Pro/Ultra), which distinguishes it from siblings like list_available_llm and list_models.

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?

Explains the refresh flag's purpose, states the model is chosen per request, and tells the agent how to pin a specific account via the X-Account-Email header. It does not explicitly say when to prefer this over list_available_llm, 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?

While annotations already declare readOnlyHint=true and idempotentHint=true, the description adds substantial behavioral context beyond them: zero credit cost, no external calls, null-semantics ('a null does NOT mean free/instant, it means unconfirmed'), defaults-stability assurance for existing callers, and the honest caveat that service/api.py accepts rarer values this tool deliberately omits. These are exactly the non-obvious behaviors an agent needs and none of them contradict 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?

The description is long but every sentence earns its place: safety profile, usage directive with failure consequence, three-section return contract, null handling, defaults stability, and the curation caveat. It is front-loaded with the most decision-relevant facts, and the Returns block is scannable; only minor tightening of the final note would improve it.

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 and no parameters, the description fully carries the burden of documenting return values — and it does so exhaustively: the images/videos/defaults sections, the t2v/i2v/r2v mode enum, null behavior, and the scope boundary versus the underlying HTTP layer. Nothing an agent needs to invoke it correctly or interpret its output 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 and the schema reflects that at 100% coverage, so the baseline 4 applies with no deduction. The description adds cross-tool parameter value by mapping its output keys to sibling parameters: `model` values for generate_image/generate_character_image and `video_model_key` values consumed via the generate_* tools' Literal types.

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 up front: 'List every valid model id this service accepts,' followed immediately by the safety profile (READ-ONLY, spends no credits, calls nothing outside this service). It distinguishes itself from sibling generation tools by naming generate_image/generate_video directly, so an agent can tell them apart without opening any other 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 guidance: 'Call this BEFORE generate_image/generate_video if you're unsure of an exact id,' and reinforces it with the concrete failure cost of guessing (a hard HTTP 400 on a call that already committed to a task). It also names the alternative tools that this one is meant to precede, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: it discloses the returned fields (name, gender, short description) and the important caveat that gender/description are only a rough guide and any voice reads any language.

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

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

Two tight sentences with no waste. The count and resource are front-loaded, and the caveat sentence earns its place by preventing misuse of the gender field.

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 and zero parameters, the description does the needed work by naming the returned fields and warning that gender/description are approximations. It is essentially complete for a static 30-item reference tool, though it could state the intended workflow (fetch then pass a voice name to generate_voice) more explicitly.

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, so there is nothing for the description to compensate for, and 0 params maps to the baseline of 4. No parameter meaning is missing.

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_voices' returning the 30 Gemini TTS voices) and explicitly ties the resource to a sibling, generate_voice. An agent can tell this is a reference-listing tool rather than a generation or mutation tool 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?

The phrase 'usable with generate_voice' implies the workflow (call this to pick a voice for later generation) but never states it directly, and gives no when-not or alternative guidance. Usage is implied rather than spelled out.

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 richly discloses behavior beyond the sparse annotations: returns vary between conversation-only and audio-producing turns, `clips` is empty when the Producer only talks, and song-producing turns return a job_id to poll with check_job. It also explains the meaning of returned fields and how to treat filled `clips` identically to a music_generate result.

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 core purpose is front-loaded, usage examples are compact but illustrative, and return-value semantics are structured clearly. Despite length, nothing is redundant or marketing-flavored.

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 stateful conversational tool with no output schema, the description is remarkably complete: it covers invocation, conversation continuity, asynchronous job behavior, return shape, and how to handle audio results. An agent has everything needed to call it correctly and interpret results.

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 0%, so the description fully compensates by explaining all three parameters: `message` is what to say, `conversation_id` is omitted on the first message then passed for memory, and `model` is noted as matching music_generate's choices. The enum in the schema fills in the exact model values.

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: 'Talk to the Google Flow Music Producer agent instead of one-shotting a track.' It clearly distinguishes its conversational scope from the one-shot generation path and names the sibling tool it is not, making selection 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?

Provides explicit when-to-use guidance with concrete examples ('asking what it can do', 'having it write lyrics first', 'editing a track it already made') and explicitly identifies the alternative ('For a plain "make me a song about X", music_generate is the shorter path'). It also explains when to pass conversation_id versus omit 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 establish that the tool is read-only, idempotent, and non-destructive. The description adds useful specificity about the scoped resource ('flowmusic credits') and what is reported (remaining balance and subscription tier), which goes beyond the annotations without contradicting 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?

A single clear sentence with no filler. The core action and object are front-loaded, and every word contributes useful 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 parameterless read-only check, the description supplies the essential context: what resource is being queried and the two pieces of information returned. It doesn't describe exact output formatting or field names, but the low complexity and strong annotations make that 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?

The tool has zero parameters and the schema covers everything about parameters; no parameter documentation is needed. The description adds no param-specific detail, but with no parameters there is nothing additional an agent could need, so the baseline of 4 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 uses a specific verb ('Check') and defines the exact resource ('remaining flowmusic credits') plus the second datum returned ('subscription tier'). It is immediately clear what this tool does and materially distinguishes it from generic siblings like check_credits.

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 implies the use case: call when you need credit balance and tier information. However, it provides no explicit guidance on when to choose this over sibling tools such as check_credits, flow_dashboard, or flow_status, nor does it state any 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?

Annotations already indicate this is not read-only, is idempotent, and is not destructive. The description adds useful context by specifying the file format (.m4a) and destination (server), but it does not disclose details like overwrite behavior, authentication needs, or what happens if the clip_id is invalid.

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, front-loaded sentence with no filler. Every word contributes to identifying the action, resource, format, and destination.

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

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

For a one-parameter tool this is minimally adequate: the agent knows what action to take and where the file ends up. However, there is no mention of the response/result, file storage location details, or how clip_id maps to a track, which leaves some ambiguity for correct 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?

Schema description coverage is 0%, so the description carries the burden of explaining clip_id. It refers to 'a track' but never explicitly states that clip_id identifies which track to download, leaving the only required parameter under-explained.

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 uses a specific verb ('Download') and resource ('raw .m4a file of a track'), with a clear destination ('to the server'). This distinguishes it from siblings like music_get, music_list, and music_stems by focusing on the raw audio file and server-side download.

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 the tool is for obtaining a raw .m4a file onto the server, but it does not explicitly state when to prefer this over alternatives such as music_get or music_stems. No exclusions or when-not-to-use guidance is provided.

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 indicate readOnly=false and idempotent=false; the description adds crucial behavioral detail: the tool returns two variants, may become async with a job_id, produces ~2-3 minute tracks, and instructs the agent to save the result. It also discloses the public audio_url access model and the full set of returned clip fields, going well beyond annotation signals.

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 every sentence carries operational value, from the prompt brief to the output schema to the conversation_id follow-up. It is front-loaded with the core purpose and organized by parameter and result-handling concerns, with no filler.

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

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

The tool is complex: 4 parameters, no output schema, async behavior, and a large sibling set. The description provides the output JSON shape, field semantics, auth details, download guidance, and follow-up mechanism, making it complete for an agent to invoke and process the result 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 0%, so the description fully compensates by explaining every parameter: prompt with an illustrative example, model with enum values and legacy status, lyrics with omission semantics, and conversation_id with follow-up behavior. It adds practical meaning that the raw input schema does not convey.

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

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

The description opens with a specific verb, resource, and mechanism: 'Generate a full song from a text brief via Google Flow Music (Lyria).' It clearly distinguishes this from siblings like music_chat and music_stems by focusing on generation and the returned two variants. The scope and output expectation are unmistakable.

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 clear when-to-use context: pass conversation_id to continue from an earlier track and poll with check_job if the result is not ready. It does not explicitly list exclusions or name sibling alternatives, but the generation-vs-chat/download distinction is clear enough from the content.

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 state readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds that the result is metadata rather than audio content, but it does not disclose additional behavioral details like output shape or error conditions.

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

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

A single, front-loaded sentence contains the core purpose with no filler or redundant restatement of the tool name. 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?

The tool is simple and annotations cover most behavioral concerns, but the description leaves gaps: it does not mention where clip_id comes from, what metadata fields are returned, or how this relates to music_list/music_download. Some inference is required from the agent.

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 0%, so the description must compensate for the undocumented clip_id parameter. 'Get metadata for a single music track' weakly implies clip_id identifies the track, but it does not clarify how to obtain the clip_id, its format, or that it likely comes from music_list or music_generate.

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 uses a specific verb and resource: 'Get metadata' for 'a single music track.' It clearly differentiates from siblings like music_list (lists tracks) and music_download (retrieves audio) by scoping to metadata retrieval for one item.

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 implied by the phrase 'single music track' and the required clip_id parameter, suggesting the tool is for retrieving metadata about one existing track. However, the description does not explicitly mention when to prefer this over music_list or how to obtain a valid clip_id.

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, idempotentHint, and destructiveHint, so the safety profile is established. The description adds the 'user's music tracks' scope but says nothing about ordering, pagination, or how the limit parameter affects results, leaving behavior partially undisclosed.

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, front-loaded sentence with no wasted words. It is appropriately short for a simple list operation, though it is so terse that it omits useful usage and behavior context.

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

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

For a one-parameter list operation with read-only annotations, the description is minimally adequate. However, it does not describe the return shape, pagination behavior, or limit semantics, and there is no output schema to compensate for these omissions.

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 0%, and the description does not mention the 'limit' parameter at all. With no parameter explanation in either the schema or description, the agent receives no help understanding how limit behaves beyond its default value of 20.

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 uses a specific verb, 'List', and a clear resource, "the user's music tracks." It conveys the basic operation without vagueness, though it does not explicitly contrast itself with sibling tools like music_get or music_download.

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?

There is no explicit guidance on when to use this tool versus music_get, music_generate, or music_download. The phrase 'user's music tracks' implies enumerating existing tracks, but the description does not state exclusions, prerequisites, or alternative 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?

Discloses key behavioral traits beyond the annotations: the operation can return either a completed result or an asynchronous job_id to poll, the returned stems are public downloadable .m4a files, and the account-origin restriction. The annotations already mark it as non-read-only and non-idempotent, and the description adds the important async and output details without contradicting 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?

Every sentence earns its place, covering input origin, account scope, response shape, polling behavior, output format, and a concrete agent instruction. The description is dense yet compact and front-loads the core purpose.

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

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

For a single-parameter async operation with no output schema, the description explains the full lifecycle: where the clip comes from, what the response looks like in both completed and pending cases, how to download results, and what to do with them. No critical information is missing for correct 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?

Schema coverage is 0%, so the description carries the full burden for the single parameter. It fully explains clip_id: where it comes from, what kind of clip is valid, and the account restriction. This is more informative than the bare schema field.

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 action ('Split a track we generated into stems') and names the resource type, with an explicit pointer to where the input clip_id comes from (music_generate or music_video). This distinguishes it clearly from sibling music tools like music_download and music_get.

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

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

Provides clear contextual guidance: the input must come from a previously generated track, and the operation is tied to the same account. It does not enumerate explicit exclusions or alternatives, but the usage context is strong enough for an agent to know when to invoke 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 only declare readOnly=false, idempotent=false, openWorld=true. The description adds substantial context beyond that: credit costs (10 vs 20), resolution differences (360p draft vs 720p final), the counterintuitive fact that seeds do not carry a take across resolutions, and the licensing/consent constraint. This is exactly the kind of behavior annotations cannot 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?

Long but well-structured: labeled parameter explanations followed by a numbered two-step workflow, with the purpose front-loaded. Dense yet every section is relevant; minor redundancy between the parameter notes and the workflow narrative.

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, mutation-type, open-world tool with no output schema, the description covers source selection, character lookup, costs, resolution/seed behavior, and legal constraints. Only aspect and include_preview are left unexplained, which is a small gap 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?

Schema description coverage is 0%, so the description must carry all meaning, and it does for most parameters: character, media_id/video_base64 (as mutually exclusive sources), who, scene, extra, start_sec/end_sec (with the 10s cap), seed (repeat-a-final-take), and final. It leaves aspect (an enum) and include_preview undocumented, so not a full 5.

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 (re-make/recast) and resource (a video), then enumerates exactly what is preserved (camera, movement, gestures, timing, mouth movement) and what is swapped (the character's look). This clearly distinguishes it from siblings like edit_video 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?

Gives strong operational guidance: source must be ONE of media_id or video_base64, character comes from list_characters, and it lays out a two-step draft-then-final workflow with the condition selecting each. No explicit routing against named sibling alternatives (e.g., edit_video), 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?

Adds substantial context beyond the annotations: a hard relay-side rate limit of one live fetch per 10 seconds, the caching behavior, and the error condition (MCPError on invalid key or unreachable relay). This explains why idempotentHint=false is set, so there is no contradiction with 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?

Front-loaded with the purpose, then organized into Args/Returns/Raises blocks with no filler. It is somewhat verbose but every section contributes information the structured fields lack.

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 (models, aliases, last_refreshed_at, source) and the error case, which is exactly what an agent needs. Only the missing sibling differentiation keeps it from being fully 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 coverage is 0%, so the description carries the full burden and does so well: force_live=True passes ?live=1 and waits for a fresh catalog, force_live=False (default) returns cache. It also documents the concrete rate-limit cost of the live path, which the schema does not.

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: fetching the current LLM model catalog from OmniRoute, with the cache-vs-live distinction made explicit. However, it never differentiates itself from the strongly overlapping siblings list_models, list_live_models, and list_available_llm, so an agent cannot tell from the text alone which one to pick.

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 a concrete trigger ('useful when the client sees a 404 on a recently added model'), which is genuine usage context. But it names no alternatives and gives no when-not guidance, which is a real gap given three similarly named list_* siblings that could be confused with 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?

Goes well beyond annotations: discloses one-time-per-character semantics, overwrite-on-repeat behavior, and the non-obvious fact that the sample_text content is not used for later videos (only the audio is kept). These are meaningful behavioral traits an agent could not infer from the schema or 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?

Front-loads purpose, then setup/behavior details, then a per-parameter block. Every sentence is informative with no filler. It is somewhat long, but the length is justified by the 0% schema coverage it must compensate for.

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 6-param mutation tool with no output schema, the description covers inputs, side effects, idempotency-like overwrite behavior, and explicitly lists the return shape. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description must carry all parameter meaning and it does: it documents all six parameters—character_id (entityId from create_character*), account (owning email), voice (from list_voices, default Algieba), style (delivery hint with example), sample_text (default Russian sentence, null behavior), and project_id (default account).

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

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

Specific verb and resource: 'Attach a preset Gemini TTS voice to a Flow character for auto-lipsync.' It states the mechanism (synthesizes reference audio, attaches media_id to audio_references) and is clearly distinguishable from siblings like generate_voice and update_character.

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?

Clear context: it is a ONE-TIME setup per character, subsequent video generation auto-lipsyncs, and calling again overwrites. It points to list_voices() for valid voices. It does not explicitly contrast against the generate_voice sibling for one-off synthesis, but the when-to-use conditions are well stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds genuinely useful latency context ('from a human, usually within hours'), but says nothing about what happens when no thread exists, whether an empty result is normal, or how results are ordered.

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, no filler, with the resource definition front-loaded and the parameter note second. The missing explicit verb in the opening phrase is the only minor structural weakness.

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

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

No output schema exists, so the description bears the burden of describing returns; it names the thread and operator replies but not the message shape (fields, IDs, ordering, pagination). Adequate for a one-parameter read, but an agent still can't predict the response structure.

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 0%, so the description must carry the parameter. It does explain that `since` is a unix timestamp and that it filters to newer messages, which is real value beyond the bare 'number' type. It omits the default-null behavior — whether omitting `since` returns the whole thread — which is the main remaining ambiguity for a single-parameter tool.

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?

Identifies the specific resource (your support thread) and its distinguishing content (operator replies from a human). The verb is only implicit — the sentence is a noun phrase — but an agent can tell this is a read of the user's support conversation, distinct from the write-side sibling contact_support.

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

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

No explicit guidance on when to call this versus contact_support or check_job. The parenthetical 'usually within hours' hints at polling cadence but never states when to use this tool, when to re-poll, or what the alternative is.

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 convey mutation, idempotence, and non-destructiveness. The description adds useful behavioral context: without this call the character stays 'Untitled Character' and account must be the owning project, an access requirement not present in annotations. It doesn't explain overwrite/clearing behavior for nullable fields, but the main side effects are disclosed.

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: the action, why it matters, and the account prerequisite. Each sentence adds distinct, necessary information and the main operation is front-loaded.

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

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

For a simple update with only two required parameters and idempotent/non-destructive annotations, this is nearly complete: an agent can construct a correct call with entity_id, owning account, and one or both fields. It lacks explicit 'at least one optional field' guidance, but the overall context 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 description coverage is 0%, so the description carries the burden. It directly maps display_name and personality_notes, and explains that account must own the entity_id. All parameters get some semantic meaning, though it doesn't explain null semantics for clearing existing values.

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 and resource: 'Save a character's display name and/or personality notes.' It further clarifies the purpose by describing the default 'Untitled Character' state and tying the action to an existing entity_id, which distinguishes it from the create_* 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 gives a clear trigger context: use this when you need to set a character's name or personality notes, especially after portrait/body images already exist. It also specifies the account ownership prerequisite. It does not explicitly name create_character as the alternative for new characters, so it stops short of full exclusion 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?

Goes well beyond the minimal annotations: discloses 15-30s async behavior, the job_id polling mechanism, clean-failure cases for unsupported images or paid-tier locks, and the exact success response shape. This is exactly the behavioral context an agent needs and none of it contradicts 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?

Every sentence carries operational value. The purpose is front-loaded, parameters are clearly labeled, and the async/error/output details are organized without redundancy. It is long, but the length is justified by the tool's complexity.

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 precondition, selection, behavior, failure modes, timing, polling, and return structure despite lacking an output schema. An agent has everything needed to invoke this tool correctly and handle its results.

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 0%, but the description fully compensates: account is detailed with source and constraints, target_resolution is enumerated with caveats, and media_id is contextually defined as a prior generation result. This is more informative than the schema alone.

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 ('Upscale') and resource ('existing generated image from a prior generate_image call'), and clarifies the resolution options. It clearly differentiates from siblings like upscale_video by restricting to generated images.

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 context ('from a prior generate_image call'), warns against guessing or asking the user about account, identifies the account_used field as the correct source, and instructs to report clean errors rather than retry. It also names check_job as the polling alternative for the async case.

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 annotations, it discloses that the operation counts against the weekly free video limit, spends Flow credits, is slower than generation, may need polling via check_job after ~40 seconds, and returns a job_id when incomplete. It also describes clean errors for wrong-account media_id and locked 4K resolution, which is rich operational 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 long but front-loads the core purpose and then organizes constraints by parameter and operational behavior. Most sentences carry useful information, though a few parenthetical details could be tightened without losing meaning.

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

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

With no output schema and 0% schema description coverage, the description still explains inputs, return shape, polling behavior, credit/limit impact, and error conditions. An agent has enough to invoke it correctly and interpret the result.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so well. It explains that account must be the exact account_used value from the prior generate_video result, that media_id is scoped to that account's project, and defines each target_resolution value including the experimental from_360p option and possible 4K plan restrictions.

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: upscale an existing generated video from a prior generate_video call to a higher resolution. It distinguishes this from image upscaling and generation by tying it to generated videos and the same resolution choices Flow offers on download.

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 clearly states the prerequisite context: the video must come from a prior generate_video call, and media_id only exists inside the owning account's project. It also warns not to guess the account and to pass account_used verbatim. However, it does not explicitly compare against sibling video tools like edit_video or extend_video.

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