Flow Workspace MCP

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description discloses the key non-blocking behavior: it returns instructions immediately and never waits for a click. It does not describe state mutation details or auth requirements, but adds meaningful operational context that the annotations alone do not convey.

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

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

The critical instruction ('FIRST CONNECTION STEP') is front-loaded and every sentence serves the workflow. However, the closing stop-and-wait directives slightly overlap ('STOP and tell the user...' vs 'Do not call the completion tool until the user replies'), adding minor redundancy.

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

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

Even without an output schema, the description states what the response contains (instructions and extension path) and lays out the full begin → user action → completion lifecycle. Nothing an agent needs to invoke and sequence this tool correctly is missing.

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

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

Schema coverage is 100%, so the schema fully documents both optional parameters. The description does not add syntax or format detail for label/accountId, so the baseline of 3 is appropriate when the schema carries the 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?

The description opens with a specific verb+resource marker ('FIRST CONNECTION STEP') and states exactly what the call returns (user instructions and extension path). It is clearly distinguished from the sibling flow_complete_account_connection by naming it as the later step that must not be called yet.

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 ('first connection step'), when-not-to-call ('Do not call the completion tool until the user replies'), and an alternative-avoidance rule ('never substitute generic browser/computer-use automation on the Flow website'). The sequencing constraint 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 openWorldHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is mostly covered. The description still adds real behavioral context beyond the structured fields: a temporary Google chooser will appear, the user must select an account, and the call fails immediately (non-blocking) if the session wasn't sent. It could go further on rate limits or what happens on partial success, but it is well above the baseline.

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

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

The critical routing information ('SECOND CONNECTION STEP', call only after confirmation) is front-loaded, and every sentence carries requirements or user-facing instructions. It is slightly denser than necessary, with some redundancy between the confirmation precondition and the userConfirmedSessionSent semantics, but nothing is wasted.

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

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

With annotations covering the mutation/open-world profile and no output schema to explain, the description still supplies the full orchestration story: ordering relative to the begin step, the user interaction required mid-call, the timeout behavior, and the ban on falling back to generic browser automation. 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?

Schema description coverage is 100%, so the schema already documents every parameter including connectionId provenance, the const on userConfirmedSessionSent, and the wait timeout. The description reinforces that connectionId comes from the begin step and that user confirmation is required, but adds no new syntax or format detail, making 3 the correct baseline.

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

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

The description opens with 'SECOND CONNECTION STEP' and names the specific verb+resource (complete the Google Flow account connection), explicitly positioning it against its sibling flow_begin_account_connection by requiring the begin-step connectionId. An agent can distinguish it from flow_begin_account_connection and the flow_* automation tools without opening any schema.

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

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

It states the exact precondition ('Call only after the user confirms they clicked Connect Flow and the extension popup says Session sent') and an explicit exclusion ('never substitute generic browser/computer-use automation on the Flow website'). The when-to-use condition is fully specified rather than implied.

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 non-readOnly, openWorld, non-idempotent, non-destructive. The description adds substantive behavior: saves to a configured absolute directory, validates files, writes manifests, fails rather than guessing a mismatched asset, and does not trigger generation. It does not state overwrite/idempotency behavior on repeat calls, which is the main remaining gap.

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 tool's role and single-sentence constraint, then behavior. Slightly redundant in restating exactness ('exact asset identities' / 'fails instead of guessing'), but every sentence carries usable 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 one-parameter tool with no output schema, the description covers scope, side effects (directory writes, manifests), failure mode, and the non-generation guarantee. An agent can call it correctly; only idempotency/overwrite semantics on repeated downloads are unaddressed.

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

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

Schema coverage is 100% and the single jobId parameter is fully documented in the schema itself (UUID format, pattern, 'exact UUID returned by the generation'). The description reinforces exactness but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('download an existing Flow job') and immediately differentiates the mechanism from siblings/categories: it uses recorded asset identities rather than gallery order, and explicitly rules out generic browser/computer-use 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?

Gives a clear condition for use ('the exclusive path to download an existing Flow job') and an exclusion ('never download through generic browser/computer-use tools', 'does not start a generation'). It does not name the specific flow_generate_image/flow_generate_video siblings that produce the jobId, but the surrounding guidance is strong.

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

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

Annotations declare destructive/openWorld/non-idempotent, and the description materially extends them: one persistent job that returns briefly and must be polled rather than re-invoked, local downloading, credit consumption, and the prohibition on browser automation. It discloses the destructive risk (credit spend, non-idempotent job creation) in operational terms the annotations cannot express.

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

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

Dense, front-loaded imperative prose; the exclusivity claim and the polling rule lead, and every sentence carries operational information. No filler or restatement of the title.

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, credit-consuming, non-idempotent mutation with no output schema, the description covers the full job lifecycle (submit, wait briefly, poll, download), the auth/credit gate, and the forbidden alternative approach. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema itself documents all 12 parameters and the baseline would be 3. The description still adds workflow-level meaning by tying the job-ID reuse and the 'explicit credit authorization' requirement to invocation, so it earns a step above baseline without duplicating field-level detail.

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 ('generates or edits' images), declares itself 'THE REQUIRED AND EXCLUSIVE PATH for every Google Flow image request,' and implicitly separates itself from the video sibling (flow_generate_video). An agent can identify the tool's remit 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 routing rules are given: on status=processing, poll flow_job_status with the SAME job ID and 'never generate again,' and never use browser/computer-use tools for Flow. It also states the credit-authorization prerequisite. This is a textbook when/when-not/alternative block.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavior: one persistent job, a brief wait then return, timeout leaving a pollable job, and credit spend requiring authorization. It stops short of describing the returned job/manifest shape, which the missing output schema would otherwise require.

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

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

Four tight sentences, front-loaded with the exclusivity claim and lifecycle, then routing, then the prohibition. Every sentence carries a distinct instruction 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?

For a 14-parameter, credit-consuming, non-idempotent tool with no output schema, the description covers the job lifecycle, the polling escape hatch, the timeout failure mode, and the authorization gate. It could say a bit more about what is returned on the initial call (job ID/manifest), but the essentials are present.

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

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

Schema description coverage is 100%, so each of the 14 parameters is already documented in the schema (model IDs, upscale IDs, durationSeconds visibility rules, etc.). The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('submits one persistent job' for a Google Flow video) and explicitly positions itself as 'THE REQUIRED AND EXCLUSIVE PATH for every Google Flow video request,' which cleanly separates it from flow_generate_image and flow_upscale_video. The submit-wait-return lifecycle is named up front.

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/when-not guidance: poll flow_job_status with the SAME job ID on status=processing, 'never generate again,' and 'Never open or control Flow with browser/computer-use tools.' It also names the precondition (explicit credit authorization), leaving almost 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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new context beyond them: no browser is launched and no credits are consumed, which lets an agent treat this as a free, side-effect-free fallback.

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 sentence with the trigger front-loaded and the return-value behavior trailing it; every clause earns its place and nothing is padded.

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

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

For a zero-param, annotation-covered helper with no output schema, the definition tells the agent when to call it and roughly what comes back. Only the shape/content of the guide itself is left unspecified, which is a minor gap given the tool's simplicity.

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 the baseline of 4 applies; there is no parameter surface for the description to clarify or for the schema to omit.

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 concrete return ('a concise multilingual-ready capability guide') and implicitly separates itself from all siblings by noting it works 'without opening a browser or spending credits' — i.e., every other flow_* tool does one of those. An agent can identify this as the zero-cost help entry point without inspecting any schema.

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

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

Gives explicit trigger conditions ('when the user asks what Google Flow MCP can do, how to use it, or for example requests'), which is exactly the routing information needed. No exclusion or alternative is named, but there is no sibling help/status tool to route against, so a 4 is appropriate.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely new behavioral content: the landing-page case returns workspaceAvailable=false with a stop instruction, and browsing/scrolling it is prohibited. It stops short of describing the capability map's contents or latency, keeping it at a strong 4.

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

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

Three sentences, no filler, and the highest-value constraint (MANDATORY before generation) is front-loaded. Each sentence carries a distinct instruction: mandate, return value, and exclusion.

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 naming the return shape (live capability map) and one key field (workspaceAvailable). For a zero-required-parameter read-only inspection tool this is close to complete, though it omits failure modes other than the landing page.

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

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

Schema description coverage is 100% and the single optional accountId is fully documented in the schema, including the default-to-most-recent behavior and when to supply it. The description adds nothing about parameters, so the baseline 3 applies.

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

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

The description states a specific action (verify the real Flow workspace) and a specific output (a language-independent live capability map), and identifies the tool as a mandatory pre-generation step. It also distinguishes itself from siblings and from generic automation, so an agent can tell what this tool is for 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 'MANDATORY before generation' establishes when to call it, and 'never substitute generic browser/computer-use automation on the Flow website' names the excluded alternative. The landing-page branch (stop, never browse or scroll) is a concrete when-not instruction.

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=true, openWorldHint=true and destructiveHint=false; the description adds the key missing context for why this poll is not read-only — it 'safely finalizes any download already authorized by the original request' — plus the idempotent polling expectation. It does not cover failure modes, rate limits, or how waitSeconds affects behavior, so it stops short of a 5.

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

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

Four short sentences, front-loaded with the routing rule and zero filler. The 'safely finalizes any download' sentence is slightly ambiguous about whether it retrieves content, which slightly muddies otherwise tight phrasing.

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 only two parameters and no output schema, the description carries more return-value burden, and it does name the terminal states ('completed or failed'). It stops short of describing the status response shape or what intermediate states exist, but for a polling tool this is close to complete.

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

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

Schema description coverage is 100%: jobId and waitSeconds are both fully documented in the schema, including format, defaults, and bounds. The description reinforces the job ID's origin ('jobs returned by a Flow generation tool') but adds no syntax or format detail beyond what the schema already provides, so the baseline 3 applies.

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

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

The description states a specific verb and resource (check/poll a job's status) and scopes it as 'the exclusive status path for jobs returned by a Flow generation tool.' It clearly separates this tool from the generation siblings (flow_generate_video/flow_generate_image) and from generic inspection tools, so an agent can distinguish it 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 when-to-use ('Poll the SAME job ID until completed or failed'), explicit when-not ('never resubmit generation'), and an explicit negative alternative ('Never inspect Flow with generic browser/computer-use tools'). This covers the main failure modes an agent would otherwise fall into.

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 destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond that: it discloses the two returned fields and the routing decision that follows from readyForGeneration. It stops short of describing what the caller should do when readyForGeneration=false, which is the one behavioral branch left implicit.

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, zero filler, and the imperative 'MANDATORY FIRST STEP' is front-loaded so the agent sees the gating role first. Every sentence carries either a precondition, a routing rule, or a prohibition.

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

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

For a zero-parameter read with no output schema, the description covers the essential contract: when to call it, what it returns, and how to branch on the result. The only gap is the negative branch (readyForGeneration=false), which must be inferred from the mere mention of the account-connection tools.

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 the baseline is 4. The description correctly references defaultAccountId as an output value rather than an input, so there is no risk of an agent trying to pass it as an argument.

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 Google Flow Accounts') and immediately names what it returns: readyForGeneration and the verified default account. This distinguishes it from the sibling account-connection and inspection tools without requiring the schema to be opened.

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 mandatory first step for Google Flow work, specifies the branch condition (when readyForGeneration=true, use defaultAccountId and DO NOT call either account-connection tool), and names an anti-pattern to avoid (generic browser/computer-use automation on the Flow website). This is about as prescriptive as usage guidance gets.

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, closed-world, so the safety profile is covered. The description adds genuinely non-obvious operational context: it is diagnostic-only, it probes a localhost bridge, and the agent must not open Flow with browser tools. It stops short of describing what the reported state looks like, but that is a minor gap.

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

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

Four short sentences, front-loaded with the key framing ('Login diagnostic only.'). Every sentence carries a distinct constraint or instruction, with only mild repetition between 'diagnostic only' and 'do not use this for generation'.

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

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

For a zero-parameter, read-only diagnostic with no output schema, the description covers purpose, constraints, and ordering. It could note what the reported bridge state values mean, but nothing critical for correct invocation is missing.

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

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

The tool takes zero parameters, so the schema is trivially complete and there is nothing for the description to clarify. Baseline 4 applies since no parameter semantics are needed.

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

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

States a specific resource and scope: it reports whether the localhost Flow Login Bridge is waiting for the Chromium extension. It also explicitly separates itself from generation siblings, so an agent can distinguish it from flow_generate_image/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 when-to-use ('login diagnostic'), when-not ('do not use this for generation', 'do not open Flow with browser tools'), and a sequencing prerequisite ('Normally call flow_list_accounts first'). Alternatives are implied and the preconditions are explicit.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is partly covered. The description adds genuinely new context beyond the annotations: it may consume credits, requires explicit authorization, and rejects unavailable/upgrade-only options rather than silently downgrading.

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, front-loaded sentences with no filler; the exclusivity claim, the guardrail, and the cost warning each carry distinct information. Minor slack in adjectives like 'real' that don't add selection value.

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 mutation tool with a 100%-covered schema and no output schema, it covers the key agent-facing risks: credit consumption, authorization, exclusivity, and rejection of bad options. It stops short of describing the return/polling flow (though timeout behavior is noted in the schema), which would fully close the loop.

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

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

Schema description coverage is 100%, so the schema already documents jobId, factor, timeoutSeconds and confirmCreditSpend in detail. The description adds no parameter-level syntax or format guidance (e.g. where factor values come from is only stated in the schema, not the description), so baseline 3 applies.

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

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

States a specific verb+resource ('Flow video upscaling') and frames itself as 'the exclusive path,' which separates it from flow_generate_video and similar siblings. It does not name any sibling explicitly, so differentiation is achieved via the exclusivity claim rather than routing language.

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 clear negative guidance rule ('Never right-click or control Flow with generic browser/computer-use tools') and a precondition (explicit authorization for credit spend). It implies the alternative path (this tool vs. generic automation) but never names a specific sibling tool to use instead in edge cases.

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