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

No annotations, so the description carries the full burden and does: it discloses that approve SPENDS credits, that rejection spends nothing, the max_credits gate, the 'Never choose Always approve' constraint, and that results include media that renders for 1-5 minutes. This is exactly the behavioral context an agent needs for a spend-affecting tool.

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

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

Front-loaded with the triggering condition, then the decision semantics, then the follow-up fetch step. Four dense sentences, no waste or redundancy.

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

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

There is no output schema, and the description explains what is returned (agent's reply and started media) plus the render timing and the sibling tool to fetch results with. For a spend-impacting mutation tool, nothing needed 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 50%, and the description compensates well for decision and max_credits by explaining their interaction (approve spends only when N <= max_credits). It does not describe include_thinking, though the schema itself documents it, so this falls just short of full.

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 (answer/approve) and resource (the agent's pending 'costing N credits?' request), and makes the approve/reject semantics explicit. An agent can distinguish this from flow_wait, flow_credits and other siblings 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 when-to-use: answer the pending cost request. Explicit when-not: approve only if N <= max_credits, otherwise reject and nothing is spent. Names the follow-up alternative (flow_wait with since/media) and rules out 'Always approve'.

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?

readOnlyHint=true already establishes the safety profile, yet the description still adds real behavioral detail: ordering ('newest first'), the full set of returned attributes, and how duplicate uploads are grouped with a keep-copy. It does not cover pagination limits, whether trashed items are excluded by default, or auth/sign-in requirements (cf. flow_sign_in sibling).

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 compact sentences with the core action and ordering front-loaded; the long field enumeration is justified because no output schema exists. Slight density in the middle clause ('uploaded/generated, model, prompt, size, duration and what each generated item was made from') but nothing is 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?

With no output schema and only two parameters, the return-shape enumeration is exactly the burden the description must carry, and it does. Gaps remain around the trashed-item behavior and result-set size, but nothing blocks a correct first call given the required project_id.

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 50%: include_trashed is documented in the schema itself, while project_id carries only format/pattern. The description reinforces that scope is 'a project's' media but never explains project_id's source or what include_trashed does to the results. Adequate baseline, no added meaning.

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

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

Opens with a specific verb+resource — 'Lists a project's images and videos' — and enumerates the returned fields (id, title, image/video, model, prompt, size, duration, provenance), which is far more informative than the title alone. It does not explicitly name a sibling it is not (flow_projects, flow_trash), so an agent must infer the boundary from the 'project's media' scoping.

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 downstream context: reuse listed items via media_ids instead of re-uploading, which tells the agent why it would call this tool. It also flags duplicateUploads aggregation. Missing explicit exclusions — e.g., when to use flow_trash instead, or when to skip this in favor of flow_projects.

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 readOnlyHint; the description adds genuinely new behavioral information – that the call is free, and that some features are only available on the Flow website rather than via any tool. That saves an agent from searching for a nonexistent tool. It stops short of describing return shape or size.

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?

One dense sentence with no wasted words, front-loaded with the verb and resource, then the payload details and the cost note. Every clause carries information.

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

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

With no parameters, no output schema and a read-only annotation, the description covers what an agent needs: what it returns, that it costs nothing, and that some features have no tool equivalent. A hint about the response format would make it 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?

Zero parameters, so there is nothing for the description to compensate for. Baseline applies; no parameter explanation is needed.

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

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

Specific verb and resource ('Lists Flow's features') with an explicit account of the content: feature-to-tool mapping, website-only features, costs and plan limits. It reads clearly as a discovery/meta tool, though it doesn't name which siblings it overlaps with (flow_status, flow_credits both touch status/credits territory).

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?

'Free' implies it's safe to call without burning credits, which is implicit guidance, but there is no explicit when-to-use statement or direction to flow_status/flow_credits for narrower questions. Usage is inferable rather than 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?

With no annotations, the description carries the burden and does well: it discloses that 'list' is the default action, that 'create' draws from an existing project image, that 'info' is consumed by the Flow agent, and that calls are free (cost transparency). It does not cover permissions/auth needs, whether 'update' replaces or merges unset fields, or what each action returns.

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 concept so the per-action clauses parse quickly, then one clause per action with no filler. The trailing 'Free' is short and adds genuine decision-relevant 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 4-action, 7-parameter tool with no annotations and no output schema, the description covers actions, prerequisites, cross-tool usage, and cost. The remaining gap is return-value shape (e.g. what fields a listed character includes), which matters somewhat since no output schema exists.

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

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

Schema coverage is 57%, and the description compensates by explaining image_id (a project image from flow_assets), character (name or id, for update), voice (a name obtained from action 'voices'), and how name/info/voice combine on create. Only project_id and the 2000-char limit on info go unmentioned, and both are self-evident or already in 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 states a concrete resource (Flow characters), defines what they are (reference image + name + notes + voice that persist a person across generations), and enumerates every action with its effect. It is clearly distinguishable from siblings like flow_assets or generate_image, which it references rather than overlaps 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?

Usage is spelled out per action, including prerequisites ('create' needs an image already in the project; 'voices' needs one character in the project) and the downstream path (use in generate_video, generate_image, or flow_chat with characters: [name]). What's missing is an explicit statement of when NOT to use it, e.g. versus managing assets in flow_assets.

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 no annotations, the description carries the full burden and does well: it discloses that the call blocks until the reply completes, that sending does not spend credits, that a pendingApproval with quoted cost halts progress, and that images are typically produced immediately. It leaves out error/timeout behavior and session-memory implications, which are only partly covered by the new_session parameter.

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?

It is dense but front-loaded: the core action and return shape come first, then the approval branch, then the media branch. A couple of clauses run long, but almost every sentence carries actionable 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 10-parameter tool with no output schema, the description explains the important return keys (messages, reply, media, pendingApproval) and the key branch decisions. It stops short of describing less common outcomes or the effect of new_session on conversation state.

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 90%, so the schema already explains message, media_ids, characters, attachments, confirm_rights, etc. The description adds behavioral meaning for the approval and media-id outcomes rather than new parameter detail, 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 concrete verb and resource (send one message to the Flow agent, return when the reply completes) and names the returned fields. It is clearly distinguishable from siblings such as flow_approve and flow_wait, which it explicitly 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?

Gives explicit routing: if pendingApproval appears, tell the user the cost and call flow_approve; download media via flow_wait; answer questions or refine in a follow-up send. It also tells the agent that sending itself never spends credits, which informs when it is safe to call.

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=true, so the bar is lower. The description adds genuinely useful domain context — the 50/day free allowance and the 10-credit cost of an 8 s Veo 3.1 Lite video — but says nothing about auth requirements (flow_sign_in sibling) or what the balance response looks like.

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 zero waste. The core action is front-loaded, and the supporting cost context 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?

For a zero-parameter, read-only balance lookup with no output schema, the description covers what is returned and the scale of the numbers. It could go slightly further by noting whether sign-in is a prerequisite, but nothing critical to 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 baseline is 4; there is nothing for the description to disambiguate. The pricing details it adds describe values, not parameters.

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: reads the account's remaining Flow credits. It is clearly distinguishable from generation siblings such as generate_video or flow_assets, though it does not explicitly contrast with flow_status or flow_capabilities, which could plausibly overlap.

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

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

Usage is implied rather than stated — an agent infers it should check credits before spending them, and the cost figure hints at budget checks. No explicit when-to-use or when-not-to-use guidance relative to flow_status or flow_capabilities 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?

Goes well past readOnlyHint=true: it discloses the side effect of writing a PNG, that a media id is downloaded first when project_id is given, that the rights confirmation prompt appears only at upload/reuse time, and that the operation costs no credits and runs locally. These are exactly the operational facts an agent needs before calling.

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

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

Four dense sentences, each earning its place: what it does, accepted inputs, the primary use case, and the cost/rights caveat. Front-loaded with the core action and no repetition of schema text verbatim.

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 three-parameter tool with full schema coverage and no output schema, the description supplies the output format (PNG), the input-source branching, the downstream consumer, and the credit/auth implications. 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 already 100%, so the baseline is 3; the description adds real meaning by explaining the project_id dependency ('with project_id' is required when video is a media id) and by restating the default. It stops short of clarifying time precision or behavior for out-of-range seconds.

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 and resource ('Saves one frame of a video as a PNG') and immediately delimits the three selection modes. It is clearly distinct from the generation siblings (generate_video, generate_images) and from asset-management tools like flow_assets.

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 primary workflow — 'pass the last frame of a shot as start_frame of the next generate_video, so characters and setting carry over' — which routes the agent to this tool and to the sibling it feeds. The default of the 'at' parameter is restated, removing ambiguity about the no-argument 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?

Annotations already declare readOnlyHint=true, so safety is covered; the description adds real value with the sort order and the caveat that purpose and upload count exist only for projects this tool created. It does not discuss result-set size or pagination, but with no parameters that risk is minor.

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 filler; the capability and ordering come first, and the decision guidance follows.

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 tool with no output schema, the description covers what comes back (ordering, purpose, upload count) and when to use it. A quick note on the shape of each entry or result size would close the last 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 takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly does not invent parameter guidance.

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 (lists) and resource (the account's Flow projects), plus ordering (most recently updated first) and the extra fields returned. No sibling tool lists projects, so it is easily distinguished from flow_status, flow_assets, and the generate_* tools.

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

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

"Use it to decide whether to continue a project or start a new one" gives a concrete decision context for calling it. It does not name an alternative tool or state when not to use it, so it stops short of explicit 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?

With no annotations, the description carries the behavioral burden and does well: it discloses what the read returns, that changes set and return a result, that approval can only be set to 'always' because the credit budget depends on it, that instructions replaces all standing instructions, and that the operation is free. It omits authentication/permission requirements and whether image/video updates are partial or full replacements.

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 around 'Without changes' and 'With changes', then packs return contents, constraints, and side effects into a compact paragraph with no filler. Every sentence supports correct invocation or safe use.

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 annotations, the description must carry most context, and it covers the read output at a high level plus key write constraints. It leaves gaps around auth, exact response shape, and partial-update semantics for nested image/video settings, so it is strong but not fully complete for a mutation 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 only 40%, so the description must compensate, and it partly does: it explains the approval constraint, replacement semantics for instructions, and gives examples for image count and video model. However, it does not clarify aspect choices, project_id semantics, or whether image/video nested objects are partial updates, leaving important parameter meaning to the schema.

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

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

The description states a specific verb and resource: it returns the project's agent settings without changes, or sets them with changes, and enumerates the settings covered. It is clear this is a Flow project settings read/write tool, though it does not explicitly contrast with siblings such as flow_capabilities or flow_status.

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 usage context: inspect settings without changes, set them with changes, and use it to avoid surprises such as image count defaults or video model choice. It does not name alternative tools or state when not to use it, so it falls short of explicit when/when-not/alternatives 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?

With no annotations, the description carries the full burden and does well: it discloses the visible side effect (a Chrome window opens and comes to the front), that the call blocks until user action, the early-return short-circuit, and that it consumes no credits ('Free'). It does not say what happens on timeout or what the failure mode looks like, which keeps it from 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?

Front-loaded with the core action, then the usage condition, then the user-facing pre-warning. The opening sentence is long and carries several clauses, but every clause (window start, foregrounding, waiting, return value) 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?

A single-parameter, zero-annotation interactive tool with no output schema; the description covers the interaction model, the trigger, the early return, and roughly what comes back ('the account'). Only the timeout/failure behavior and the exact return shape remain unspecified, which is a modest 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 single parameter wait_seconds has 100% schema coverage including bounds and default, so the schema does the work. The description never mentions the wait duration or how the bounded wait interacts with the blocking behavior, adding no meaning beyond the schema; 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 chain and resource: opens the Flow Chrome window, opens Google sign-in, waits for the user, returns the account. This is clearly an interactive authentication tool, distinguishable from siblings like flow_status (which only reports state) or flow_approve (which approves some other action).

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 trigger condition ('when flow_status says signed_out or on first use') and the alternative path ('returns at once if someone is already signed in'). It also prescribes an agent action before calling: tell the user a Chrome window will open and they should sign in.

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=true, but the description adds substantial behavioral context: it is free, takes about 30 seconds, and returns the signed-in account, credits, and a suggested fix. It also explains what each failure state means, which is exactly the transparency needed for a diagnostic tool.

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

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

The description is compact and front-loaded: it first states what the tool does, then lists the diagnostic states, then gives usage guidance. Every sentence adds useful information without repetition.

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

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

For a zero-parameter health-check tool with no output schema, the description is complete: it explains the possible states, what each means, what additional information is returned, and how long it takes. An agent has everything needed to call it correctly.

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

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

The tool has zero parameters, so there is nothing to document; the baseline for zero-parameter tools 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 and resource: it checks that everything works and names the problem if not. It enumerates the exact diagnostic states (ready, browser_down, signed_out, challenge, blocked, ui_changed), which an agent can use to tell this apart from sibling tools like flow_capabilities.

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 usage instructions: run it first, and whenever a tool fails unexpectedly. It does not name an alternative diagnostic tool to use instead, but the context is clear enough that an agent knows 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 already declare readOnlyHint=true, so safety is covered. The description usefully adds that both conversation sides, approvals, and pending state are included, and that the call is free (no credit cost). It says nothing about transcript size, truncation, or pagination, which matters for a 'whole chat' return.

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 compact sentence that front-loads the core content description before the secondary details. Slightly compressed phrasing ('both sides', trailing 'Free.') but nothing 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 does describe what comes back (full conversation, approvals, pending flags), and the read-only profile is covered by annotations. The main gap is the unexplained required project_id and no note on return format, but overall sufficient for a two-parameter read tool.

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

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

Schema coverage is only 50%: include_thinking is documented in the schema, but project_id has no description anywhere. The description never mentions either parameter, so it does not compensate for the undocumented required project_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?

States a specific verb and resource: returns the whole agent chat transcript of a project, including both sides and approval states. An agent can distinguish this read-transcript tool from siblings like flow_chat or flow_approve, though the alternatives are never named.

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 'use when' statement or exclusion against flow_chat/flow_status. The word 'Free' hints at a cost-free read path relative to credit-consuming siblings, implying a usage context, but the agent must infer 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?

With no annotations, the description carries the full burden and does well: it discloses the mandatory preview-then-confirm sequence, that the confirmation code is bound to exactly the previewed set, and that trashed media remains restorable in Flow. It omits permission/auth requirements and any limits on how long items stay recoverable, which keeps it 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?

Effectively front-loaded — the destructive scope and restorability land in the first clause, then the two-call protocol, then the alternative tool. Every sentence adds a distinct operational fact 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?

There is no output schema, and the description helpfully describes what the preview returns (title, type, what was made from them) plus the confirmation code. It doesn't cover failure behavior (e.g. mismatched set or expired code) or what happens to the trash afterward, but for a three-parameter tool 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 33%, so the description must compensate, and it does for the critical undocumented parameter: it explains that 'confirmation' is the code returned by the preview and that media_ids must be identical between calls. project_id is left entirely unexplained, which is the main remaining 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 ('Moves project media to Flow's trash') and immediately qualifies the outcome ('where it can still be restored'). It also distinguishes this cleanup path from the sibling route by naming duplicateUploads from flow_assets, so an agent can choose without opening another 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 an explicit when-to-use protocol: the first call is preview-only, the second requires the user's OK and the matching code. It also names the alternative tool (duplicateUploads from flow_assets) for the repeated-upload case, so both the main path and the escape hatch 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 no annotations, the description carries the burden and does disclose meaningful traits: 2K is free on every account, 4K requires a paid plan, and the listing includes locked sizes. It does not say whether an upscale is reversible, whether it consumes credits, or whether the result is a download URL versus an async job — notable omissions for a mutation-like operation.

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 dense sentences, front-loaded with what the tool does and followed by the no-size fallback and one usage caution. Nothing is redundant, though the final sentence reads more as agent-directed policy than definition and could be tightened.

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 the modes, tier gating, and user-facing etiquette for a three-parameter tool with no annotations and no output schema. The main remaining ambiguity is the return shape — whether the call yields a file, a URL, or an asynchronous upscale job — which matters for a tool whose title mixes 'upscale' and 'download'.

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 only 33%, so the description must compensate; it adds the plan-gating meaning of '2k' vs '4k' and confirms the omit-to-list behavior. The two remaining parameters are conventional UUIDs (project_id, media_id) whose purpose is unambiguous from their names, so the uncovered portion is low-risk.

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 ('Downloads a project's media at the chosen size, upscaling it in Flow') and explicitly covers the dual mode: with size it downloads/upscales, without size it lists available sizes. An agent can distinguish this from flow_assets or generate_image without opening any schema.

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

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

Gives clear conditional guidance ('Without size, lists the sizes...'), plan-tier context, and an explicit behavioral rule about offering the free 2K upscale to the user after new images rather than doing it unasked. It does not name sibling alternatives, but no comparable sibling exists for this operation, so the gap is minor.

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 no annotations, the description carries the full burden and does well: it discloses long-polling up to timeout_seconds, that finished media is downloaded as a side effect, that chat messages are returned, the three status values, and that the call is free. It stops short of saying where downloads land or whether repeated calls re-download the same media, so it is strong but not exhaustive.

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 action and the wait bound, then branches cleanly by status. It is a dense paragraph rather than a list, but nearly every clause carries operational instruction; the trailing 'Free.' is terse and useful 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?

No output schema exists, so the description must explain returns — it does, covering status, the failures message, and that finished media plus interim chat are returned. For a 4-parameter polling tool this is nearly complete; the only omission is the shape/location of downloaded media.

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 only 50% (since and timeout_seconds are documented; media_ids and project_id have no schema descriptions). The description compensates by explaining timeout_seconds as a wait bound and by clarifying the two selection modes — explicit media_ids, or 'since from the earlier result' to take all new media — adding meaning the bare 'created after it' schema text does not. project_id is never explained, leaving one 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 ('Checks on media the agent is making', downloads what is finished) and names the generating siblings (generate_video, flow_approve) as the source. It is clearly a media-collection poller, distinguishable from flow_status or flow_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?

Gives explicit routing for each outcome: 'completed' means done, 'pending' means tell the user and call again (with a 1-5 minute expectation), 'failed' means stop waiting and suggest flow_credits for the refund. It also tells the agent how to select media (media_ids vs since from the earlier result), so when-to-use and what-to-do-next are fully 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 no annotations, the description carries the behavioral burden and does well: it discloses that the agent may rewrite the prompt, may generate several images by default, returns what the agent said, uses no Flow credits, and takes 30-120 seconds. It does not cover authentication or rights-confirmation requirements, but the schema handles the latter.

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 action, then moves through editing, agent behavior, output, cost, and latency. 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?

For a nine-parameter tool with no output schema and no annotations, it is largely complete: it covers creation, editing, agent nondeterminism, result content, cost, and latency. It could be stronger by mentioning that local paths are returned or by naming which sibling tool handles non-agent image generation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful usage semantics for editing: it explains how attachments and media_ids differ, and that in the same project you can just name the image. It also adds prompt-steering advice for controlling output count, which is not captured by the schema.

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

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

The description clearly states a specific verb and resource: it asks the Flow agent for images and saves them locally, and it also covers editing existing images. However, it never distinguishes this tool from the sibling generate_images tool, leaving an agent unsure which image-generation path to choose.

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 useful in-context guidance for editing, such as attaching an image via attachments or media_ids, or naming an existing project image. It does not say when to use this tool instead of generate_images or generate_video, so the usage context is implied but not explicitly routed.

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 no annotations, the description carries the full behavioral burden and does well: it discloses the concurrency ceiling (3 tabs, each its own agent session), the ~3x speedup, that attachments are uploaded once per batch rather than per job, per-job success/failure reporting, and that the operation is free. It doesn't cover auth/sign-in prerequisites or what happens on partial batch failure beyond 'each job reports its own 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?

Five short sentences, front-loaded with what it does and why it's faster, then usage, then upload/error semantics, ending with the cost-relevant 'Free.' Nothing is padded and every sentence carries distinct 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 7-parameter batch tool with no annotations and no output schema, the description covers speed, concurrency, upload behavior, and per-job results, which is most of what an agent needs. It leaves gaps on prerequisites (sign-in, credits) and the overall batch return shape, which matter given the absent output 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?

Schema coverage is already 86%, so the baseline is 3, but the description adds real meaning the schema lacks — that attachments are uploaded once for the whole batch and that each job independently reports files or error, which clarifies the jobs array's semantics. The parallel and project_id parameters are not explained beyond what the schema already says.

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: it runs several separate image requests in parallel, capped at 3 Flow tabs, roughly 3x faster than serial generation. It implicitly distinguishes itself from the singular generate_image sibling via the 'several separate image requests' and 'one by one' framing, but never names the alternative, so the contrast is inferred rather than stated.

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 concrete when-to-use rule: 'Use it for a set of different images, e.g. one per scene or one per reference frame,' which tells the agent the batch shape it fits. It stops short of stating when NOT to use it — e.g. that a single image should go to generate_image — leaving that selection to inference.

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

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

With no annotations, the description carries the full burden and does so: it discloses credit spend, budget gating, the non-retry rule, and enumerates all four return states including which ones spend nothing ('over_budget' → nothing spent). The frames-vs-ingredients conflict path ('needs_answer, nothing spent') is exactly the kind of behavior an agent cannot infer elsewhere.

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 but nearly every clause carries decision-relevant information, and it is front-loaded with the shortcut framing and the credit warning. It is one long undifferentiated paragraph, though, so the return-state enumeration and the frames/ingredients rule are harder to scan than they should be.

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 16-parameter, no-annotation, no-output-schema mutation tool, the description covers cost, budget, return values, failure handling, follow-up tooling and parameter interaction rules. Nothing an agent needs to call this safely for the first time 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?

Adds genuine meaning beyond the 94%-covered schema: source_video is revealed to trigger an Omni video-to-video edit at 20 credits/720p, max_credits default is anchored to 'one 8 s Veo 3.1 Lite video', and role fields are explained as numbered to the agent. It does not touch model, characters, new_session, aspect_ratio or confirm_rights, but those are adequately described in 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 ('asks the agent for a video and approves its quote') and frames itself as a composite shortcut for flow_chat + flow_approve, which immediately distinguishes it from those siblings. The cost implication ('SPENDS FLOW CREDITS') is front-loaded in the second sentence.

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 prescribes pre-call behavior ('tell the user the expected cost and check flow_credits first'), an exclusions rule ('never call it again to retry'), and a preference between parameters ('prefer them to plain attachments'). It also names the downstream tools to use per outcome (flow_wait, flow_chat), leaving little to inference.

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