Server Quality Checklist

Tool Scores

• flow_generate_imageA
  3.5/5.0
  Behavior4/5

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

  It adds meaningful behavioral detail beyond the annotations by disclosing the credit-spending side effect and the 'prepares and verifies without sending' dry-run mode. This complements the destructiveHint/readOnlyHint 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.

  Conciseness5/5

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

  Three compact sentences front-load the core action and then cover credit spending, dry-run behavior, and resume behavior. Every sentence carries operational weight with no filler.

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

  Completeness3/5

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

  For a 10-parameter open-world tool with destructive and cost implications, the description conveys the most important operational semantics and benefits from annotations and an output schema. Still, required-parameter meanings and prerequisites like an active Flow connection/project are left to inference, leaving clear gaps.

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

  Parameters2/5

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

  Schema description coverage is only 20%, and the description compensates mainly for auto_confirm and resume. It does not explain required parameters like prompt, project_url, and output_dir, nor does it add context for model, ratio, count, job_id, or reference_images beyond what their names/defaults imply.

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

  Purpose4/5

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

  The description opens with a specific action—generate and download images—and names the Flow agent composer (Nano Banana models) as the resource. It clearly separates image generation from the sibling video generation tool, though it does not explicitly distinguish itself from a download-only sibling like flow_media_download.

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

  Usage Guidelines3/5

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

  The description gives useful mode-based guidance: auto_confirm=false validates without spending credits, auto_confirm=true sends and spends, and resume=true only waits for/downloads an in-flight generation. However, it does not explicitly state when to prefer this tool over flow_media_download or what preconditions like an active Flow connection/project are needed.

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

• flow_media_downloadA
  3.9/5.0
  Behavior4/5

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

  Annotations already carry the safety profile (idempotentHint=true, destructiveHint=false, openWorldHint=true), and the description adds a genuinely behavioral detail beyond those hints: the operation relies on the logged-in browser session, signaling an authenticated-session dependency rather than an API-key path. No contradiction with readOnlyHint=false since downloading writes a file to output_dir.

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

  Conciseness5/5

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

  Two sentences with zero filler. The action, scope, and mechanism are front-loaded in sentence one; sentence two contributes only the ID provenance. Every word earns its place.

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

  Completeness3/5

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

  The output schema documents return values and annotations cover idempotency and destructiveness, so the description doesn't need to repeat those. Its real gap is the required output_dir parameter — completely unexplained — plus unstated file-extension and overwrite behavior. For a 3-parameter tool that is a meaningful omission, though the workflow context is otherwise sufficient.

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

  Parameters3/5

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

  Schema coverage is 67%: media_id and filename are documented in the schema, and the description reinforces media_id provenance by noting the item type and source tools. However, the required output_dir parameter has no description in either the schema or the tool description — the agent is left guessing whether it is a directory path or full path and whether it gets created. The description partially compensates for the coverage gap but not fully.

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

  Purpose4/5

  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 — 'Download one Flow media item (video or image) by its media id' — making the operation unambiguous and scoped. The second sentence grounds the identifier ('Ids come from the generation and scene tools or from flow_project_open'), positioning this tool as the retrieval step alongside generation/scene siblings. It stops short of explicitly contrasting with a similar sibling, but the verb alone separates it cleanly from generate/screenshot/inspect tools.

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

  Usage Guidelines4/5

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

  The description provides clear usage context: the 'logged-in browser session' clause implies a flow_connect prerequisite, and the ID-provenance sentence tells the agent this tool is used downstream of generation/scene tools. However, it never explicitly states when not to use it or names an alternative path, so it lacks exclusions and stays below a 5.

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

• flow_scene_addA
  3.9/5.0
  Behavior4/5

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

  Annotations already indicate this is a non-read-only, non-idempotent operation. The description adds useful behavioral detail beyond annotations: it costs no credits and returns a scene URL. No contradiction with the annotations is present.

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

  Conciseness4/5

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

  The description is brief and front-loaded with the core action, then adds downstream context and cost info. The UI-menu navigation detail is somewhat unnecessary for an API agent, but it does not significantly bloat the description.

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

  Completeness3/5

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

  The output schema and description together explain the return value, and the description notes cost and downstream usage. However, one required parameter (project_url) is left undocumented in both schema and description, leaving a meaningful gap for correct invocation.

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

  Parameters2/5

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

  Only media_id is documented in the schema; project_url has no description. The description references a 'project media item', which hints at media_id, but it does not clarify what project_url is or provide enough compensation for the 50% schema description coverage gap.

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

  Purpose5/5

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

  Title and description clearly identify the operation as creating a scene from a project media item. It also distinguishes itself from sibling tools by noting the returned scene URL is meant to be passed to flow_scene_extend, flow_scene_status, or flow_scene_download.

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

  Usage Guidelines4/5

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

  The description provides clear usage context: this is the creation step that produces a scene URL consumed by related scene tools. It does not explicitly state when not to use it, but the downstream-tool mention gives an agent enough guidance to select it appropriately.

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

• flow_scene_statusA
  4/5.0
  Behavior4/5

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

  The description adds useful behavioral context beyond the annotations: it reports that the operation opens a view, exposes a performance tradeoff for with_media_ids, and states that no credits are consumed. It does not cover failure modes, but the additional context is meaningful.

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

  Conciseness5/5

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

  The description is compact and front-loaded: the main action and output are stated first, followed by the optional parameter behavior and cost detail. Every sentence adds value with no repetition.

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

  Completeness4/5

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

  For a two-parameter inspection tool with an output schema, the description covers the key context: what it reports, the optional flag's effect, and the cost. The main gap is explicit guidance on choosing it over related sibling tools, but that is not critical for basic invocation.

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

  Parameters3/5

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

  with_media_ids is well explained: it makes the tool read each clip's media id and is slower. scene_url is left to inference from its name and URI format, so the description only partially compensates for the 0% schema description coverage.

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

  Purpose5/5

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

  The description clearly specifies the action: open a Scene Builder view and report clips by index and duration, total length, and rendering status. This is specific enough to distinguish from sibling tools like flow_screenshot or flow_generate_video.

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

  Usage Guidelines3/5

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

  The purpose is clear enough to infer when it should be used, and the description notes that with_media_ids is slower and that the operation costs no credits. However, it does not explicitly compare against alternatives such as flow_status or flow_inspect, nor does it state when not to use it.

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

• flow_inspectA
  4.1/5.0
  Behavior4/5

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

  With annotations already signaling readOnlyHint=false and openWorldHint=true, the description adds meaningful behavioral context by explaining the snapshot-action-diff flow and the exclusion 'Never generates anything.' It could further disclose side effects of actions like click/type/goto, but the annotations and action list already imply mutability.

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

  Conciseness4/5

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

  The description is compact and front-loaded with the core behavior in the first sentence. The extra sentences about selector discovery and 'Never generates anything' are useful context, though the bug-report mention is slightly tangential.

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

  Completeness4/5

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

  The tool is complex with 12 parameters, but the schema covers most of them and an output schema exists. The description supplies the missing usage context and distinguishes the tool from generation/screenshot siblings, making it sufficiently complete for an agent to invoke correctly.

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

  Parameters3/5

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

  The input schema covers 83% of parameters with descriptions, so the baseline is 3. The description adds minimal parameter-level meaning beyond noting click/hover by text or aria-label regex and pressing keys or navigating, which mostly restates schema information already present.

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

  Purpose5/5

  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 snapshots interactive elements, optionally performs one action, and returns elements that appeared/disappeared. It also clearly differentiates from siblings like flow_screenshot and flow_generate_* by emphasizing selector discovery and 'Never generates anything.'

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

  Usage Guidelines4/5

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

  The description gives clear context on when to use this tool: 'This is how selectors are discovered when Flow changes its UI.' It lacks explicit when-not-to-use instructions or named alternatives, but the strong purpose statement and sibling context make the intended use evident.

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

• flow_project_openA
  4.3/5.0
  Behavior4/5

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

  The description adds concrete behavioral detail beyond the annotations: it navigates the owned tab, reports grid media count, and is invoked implicitly by generation tools. These behaviors are not captured by the structured annotations and help the agent understand what will happen.

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

  Conciseness5/5

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

  Two concise sentences deliver the core behavior and an important implicit-call note without wasted words. The key action is front-loaded and immediately understandable.

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

  Completeness5/5

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

  Given the single documented parameter, existing output schema, and annotations, the description covers what the tool does and when it is used implicitly. Nothing critical is missing for an agent to invoke it correctly.

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

  Parameters3/5

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

  The single parameter is fully documented in the schema with type, format, and an example URL pattern. The description adds no additional parameter semantics, so the baseline for high schema coverage applies.

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

  Purpose5/5

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

  The description names a specific action: navigating the owned tab to a Flow project URL and reporting the media item count. This clearly distinguishes the tool from siblings like flow_status or flow_generate_video.

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

  Usage Guidelines4/5

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

  It explicitly states that generation tools call this tool implicitly, which tells an agent when not to call it directly. It does not list alternative tools or precise when-to-use conditions, but the context is reasonably clear.

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

• flow_screenshotA
  4.3/5.0
  Behavior4/5

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

  The description discloses the key behavior: it saves a PNG file and returns its absolute path. Annotations already indicate the operation is read-only, idempotent, and non-destructive, so the description adds useful file-output context without contradicting 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.

  Conciseness5/5

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

  The description is two short sentences with no filler. The primary behavior is front-loaded, and the second sentence justifies the tool's usefulness without repeating the schema or title.

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

  Completeness5/5

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

  For a simple tool with zero required parameters, full schema coverage, an output schema, and comprehensive annotations, the description provides enough operational context. It states what happens, what is returned, and why an agent would use it.

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

  Parameters3/5

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

  Input schema coverage is 100%, with both 'label' and 'full_page' already described in the schema. The tool description does not need to add parameter meaning, so the baseline score of 3 applies.

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

  Purpose5/5

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

  The description states a specific action ('Save a PNG of the tab this server owns') and its result ('return its absolute path'). It clearly identifies the target resource as the screenshot of the Flow tab, and no sibling tool performs the same function, so differentiation is implicit.

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

  Usage Guidelines4/5

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

  The description offers a clear use case: 'Useful to see what the agent or Scene Builder is showing.' It does not explicitly state when not to use it or name alternatives, but the context is sufficient for a tool with no overlapping screenshot sibling.

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

• flow_connectA
  4.5/5.0
  Behavior5/5

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

  The description discloses behaviors beyond the annotations: it may launch Chrome if needed, opens a tab owned by the server, and can perform a one-time sign-in. These side effects align with the readOnlyHint=false and idempotentHint=true annotations and add meaningful 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.

  Conciseness5/5

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

  Three sentences, no filler. The primary action is front-loaded, the purpose is stated, and the conditional login behavior is included without redundant detail.

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

  Completeness5/5

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

  For a single optional parameter with a full output schema, the description covers what the tool does, when to use it, and key side effects. Nothing needed for correct invocation is missing.

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

  Parameters3/5

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

  Schema description coverage is 100%, so open_url is already well documented in the schema as a URL to open instead of the Flow home page. The description adds no extra parameter semantics, but the baseline of 3 is appropriate because the schema carries the full burden.

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

  Purpose5/5

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

  The description states a specific action: attach to the dedicated Chrome instance, open a server-owned tab, and load Google Flow. It also clarifies the tool's role as a warm-up and login check, distinguishing it from on-demand sibling tools.

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

  Usage Guidelines4/5

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

  The description explicitly says this is mainly a warm-up and login check while other tools connect on demand, giving clear usage context. It also provides the conditional action for logged_in being false, but it does not name specific sibling alternatives or explicitly state when not to use it.

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

• flow_statusA
  4.5/5.0
  Behavior5/5

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

  The description adds the explicit behavioral guarantee 'Never touches the page,' which is valuable beyond the annotations. It also clarifies that it reports in-flight jobs and the running tool, giving the agent a clear mental model of what the call observes without side effects.

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

  Conciseness5/5

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

  Two sentences with no fluff. The primary action and scope are front-loaded, and the safety note is appended efficiently. Every word contributes meaning.

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

  Completeness5/5

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

  Given that there are no parameters, rich annotations, an output schema, and a precise enumeration of reported state, the description is complete. An agent can confidently invoke this tool to assess connection, login, project, and job status without additional context.

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

  Parameters4/5

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

  The tool has zero parameters, so there is no parameter burden for the description to carry. The baseline of 4 applies, and the description appropriately focuses on behavior and output content rather than parameter details.

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

  Purpose5/5

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

  The description uses a specific verb ('Report') and names exact resources: browser connection, login state, current Flow project/scene, running tool, and in-flight jobs. It clearly distinguishes itself from sibling tools like flow_screenshot or flow_connect by stating what status information it provides.

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

  Usage Guidelines3/5

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

  The description implies when to use the tool: whenever an agent needs an overview of connection, login, project, and job state. However, it does not explicitly mention alternatives or state when not to use it, leaving some inference to the agent.

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

• flow_scene_extendA
  4.6/5.0
  Behavior5/5

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

  Annotations already mark it as non-read-only, destructive, and idempotent, and the description adds valuable specifics: it spends credits when auto_confirm=true, and when auto_confirm=false it opens the prompt, fills it, screenshots, and cancels. The retry behavior and 'download instead of generate again' logic meaningfully explain what idempotency means in practice.

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

  Conciseness5/5

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

  The description is three dense sentences with no filler: main action, side effects and spending behavior, then retry semantics. It is front-loaded with the operation and keeps important caveats compact and readable.

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

  Completeness4/5

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

  For a 7-parameter tool, the description covers the essential call path: last-clip target, continuation generation, download, credit spending, and retry behavior. The presence of an output schema means return values do not need to be described; the main remaining gaps are the roles of scene_url and job_id, which are relatively minor but not fully self-evident.

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

  Parameters4/5

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

  Schema description coverage is only 29%, so the description must compensate, and it does for several key parameters: auto_confirm, resume, after_clip_index, and the download behavior tied to output_dir. However, scene_url and job_id are never explained, so the compensation is incomplete.

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

  Purpose5/5

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

  The description opens with a precise action: 'generates a 7-second continuation of the clip at after_clip_index' using 'Veo 3.1 - Lite', then states it downloads the result as a separate media file. This clearly identifies the verb, resource, and scope, and distinguishes it from sibling tools like flow_scene_add or flow_generate_video.

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

  Usage Guidelines4/5

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

  The description gives clear context: the operation applies specifically to the last clip, and the auto_confirm true/false split tells an agent what will happen in each mode. It does not explicitly name alternative tools or exclusion cases, but the scene-builder extension purpose is unambiguous enough for selection.

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

• flow_generate_videoA
  4.9/5.0
  Behavior5/5

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

  Beyond the annotations, the description reveals that credits are only spent when auto_confirm=true, that the preparation phase sends nothing, and that resume skips the composer to wait for or download an in-flight job. These are important side-effect and recovery behaviors the agent needs to know before invoking the tool.

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

  Conciseness5/5

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

  Three sentences, each earning its place: the core action, the credit-safe preparation rule, and the resume recovery path. There is no filler, tautology, 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.

  Completeness5/5

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

  For an 11-parameter tool with an output schema and side effects, the description covers the full lifecycle: prepare, confirm/send, wait/download, and resume after failure. Sibling tools like flow_status and flow_media_download handle adjacent concerns, so nothing critical is missing.

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

  Parameters4/5

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

  Schema description coverage is 73%, so the schema already documents most parameters. The description adds meaningful scenario-level meaning to auto_confirm, resume, prompt, and reference_images, e.g. 'nothing is sent' at auto_confirm=false and 'skips the composer' for resume. This compensates well for parameters whose semantics are only partially covered.

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

  Purpose5/5

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

  The description opens with 'Generate one video through the Flow agent composer and download it,' a specific verb-resource-action combination that clearly distinguishes it from siblings like flow_generate_image. It also explains the two-phase generation flow, which further clarifies what the tool accomplishes.

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

  Usage Guidelines5/5

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

  The description explicitly instructs the agent to call with auto_confirm=false first to prepare and verify, then proceed to auto_confirm=true to spend credits and send. It also defines resume=true for recovering in-flight generations after a crash or timeout, giving clear when-to-use and sequencing guidance.

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