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

With no annotations, the description carries the full behavioral burden. It usefully discloses ordering, default append behavior, and that IDs may be media or generation workflow IDs, but it does not state permissions, reversibility, effects on existing clips, or what happens on conflicts.

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

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

Three short, front-loaded sentences with zero wasted words. The core operation and key defaults are presented 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 4-parameter mutation tool with no annotations, only 25% schema description coverage, and no output schema, the description is too thin. It omits index semantics, permission requirements, and return or failure behavior, leaving the agent with gaps before invocation.

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

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

Schema description coverage is only 25%, so the description must compensate. It clarifies the critical 'ids' parameter by saying it accepts media IDs or generation workflow IDs, but leaves the 'index' parameter largely unexplained beyond an implied append-by-default behavior.

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: placing videos on a scene timeline, in order. It also names the accepted ID types and default append behavior, making the tool's purpose clear without needing to open the schema.

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

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

There is no explicit guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. The only usage-adjacent detail is 'Appends by default,' which is behavioral rather than a usage rule.

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 discloses meaningful behavior: character_ids become mentions, credit spends are gated by max_credits with a default of 0 meaning 'never', and a denied spend leaves the request pending for flow_agent_respond. It omits return format and session semantics, but the approval gating logic is unusually well explained for an unannotated 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?

Three dense sentences, front-loaded with the core action before the mention and credit mechanics. Near-optimal, though the mid-sentence parenthetical and the credit clause are slightly compressed.

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 side-effecting, unannotated, output-schema-less tool, the description covers purpose, the credit-approval branch, the pending handoff, and the mention behavior. The only real gap is the unexplained new_session parameter, which a caller could trip over.

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 20% (project_id only), so the description must compensate, and it does for two of the three undocumented params: character_ids ('attached as mentions') and max_credits (approval threshold, default 0 = never). The new_session boolean remains unexplained in both schema and description.

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

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

States a specific verb ('Send a message') and resource ('Flow's creative agent') and clarifies the agent's capabilities (brainstorms, writes prompts, generates). It is distinguishable from flow_agent_respond, which it names, but the differentiation is only partial since respond is a continuation rather than a competing entry point.

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

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

The description implies usage context and names flow_agent_respond as the follow-up for pending approvals, which is genuinely useful. However, it never states when to prefer this over flow_agent_respond to initiate work, nor when to flip new_session, so an agent must infer the entry-point conditions.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses that the decision concerns spending credits, but says nothing about consequences beyond the decision: whether approving is irreversible, whether credits are deducted immediately, whether the request expires, or what feedback the caller receives. For a mutation with financial impact this is thin.

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

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

A single front-loaded sentence with no filler, which is structurally good. It is arguably too terse for a financially consequential mutation, but there is no wasted text.

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 annotations, no output schema, and a mutation that spends credits, the description leaves too much unsaid: reversibility, timing, and the relationship between the answer and the project_id are all absent. An agent cannot confidently call this without guessing at the operational consequences.

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%, and the description adds no parameter meaning at all. The 'answer' enum is self-documenting in the schema, but project_id is only explained via a schema note ('from flow_list_projects'), and the description never clarifies that answering requires supplying the affected project or that only Approve/Reject are valid values.

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

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

The description gives a specific verb pair (approve/reject) and a specific resource (the agent's pending spend request), so the core action is unambiguous. It does not, however, explicitly differentiate itself from siblings like flow_agent_chat or flow_set_agent_instructions, which also configure agent behavior.

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?

Mentioning the 'pending request' implies the condition for use (a request must exist and be awaiting an answer), but the description states no explicit when-to-use/when-not guidance and names no alternative tool. 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 full behavioral burden. It usefully discloses that portrait generation consumes image credits and that the portrait is only generated when portrait_prompt is supplied — real value beyond structured fields. It does not cover permissions, name-uniqueness/collision behavior, or what identity/ID is returned for later update calls.

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

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

Three short sentences, front-loaded with the core action and the cost-bearing optional path. Every sentence carries information, though 'generates its look' slightly restates 'portrait'.

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

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

For a mutation tool with no annotations and no output schema, the description is adequate but leaves a gap: it doesn't indicate that the created character's id is needed for flow_update_character / flow_regenerate_portrait, nor describe failure modes. The cost disclosure partially offsets this.

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 80%, so the schema already documents voice, project_id, personality, and portrait_prompt. The description reinforces that portrait_prompt drives image generation and that voice/personality feed the Flow agent, but adds little syntax or constraint detail beyond the schema descriptions. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Create a reusable character') and even names the mechanism (Flow's character builder, Nano Banana). It does not explicitly distinguish itself from siblings like flow_update_character or flow_regenerate_portrait, but the verb 'create' plus 'reusable' makes the intent obvious.

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

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

The description implies usage through the conditional 'With portrait_prompt...' and the cost note about image credits, so an agent can infer that portrait generation is optional. However, it never says when to choose this over flow_update_character, or that flow_regenerate_portrait exists for updating an existing portrait.

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?

No annotations are provided, so the description carries the full behavioral burden. 'Empty' hints at initial state, but nothing is said about required auth, whether the title must be unique, what is returned, or any follow-up step to populate the project. For a mutation tool with zero annotation coverage this is thin.

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

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

A single, front-loaded sentence with no wasted words. Concise, though arguably under-specified rather than efficiently trimmed.

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

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

For a one-parameter creation tool with no annotations, no output schema, and an undocumented required parameter, the description leaves the agent without the information needed to invoke it confidently.

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 requires a 'title' parameter with 0% schema description coverage, and the description never mentions it or its constraints (format, uniqueness, length). With no schema text to fall back on, the description fails to compensate for the coverage 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 clear verb and resource: 'Create a new, empty Flow project.' The 'empty' qualifier usefully scopes the operation, and the create-verb distinguishes it from the flow_get_project / flow_list_projects siblings. It does not, however, differentiate itself from the other creation siblings (create_character, create_scene).

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

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

No when-to-use context, no prerequisites, and no mention of alternatives despite a crowded sibling set of creation tools. The agent must infer everything about when this tool is the right choice.

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. It usefully discloses that the created scene is empty, but says nothing about permissions, whether the operation is idempotent or reversible, whether it returns an id, or how it fails for an invalid project_id.

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

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

A single short sentence with the resource front-loaded and zero filler. It is appropriately sized, though the terse phrasing leaves room for a routing clause at no real cost.

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

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

For a one-parameter creation tool with no output schema and no annotations, the description covers the minimum: what is created and where. It omits the return value (no output schema to defer to) and any dependency or follow-up context, so it is adequate but thin.

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

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

Only one parameter exists and the schema already documents it at 100% coverage, including its provenance from flow_list_projects. The description adds no parameter detail, which is acceptable at this coverage level but earns no bonus.

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

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

The description states a specific verb and resource: 'Create an empty scene (timeline) in a project.' The parenthetical clarifies that a scene is a timeline, and the 'empty' qualifier separates it from sibling flow_add_clips_to_scene. It does not explicitly name siblings, but an agent can still tell it apart from flow_create_project and flow_create_character.

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

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

There is no when-to-use guidance, no prerequisites (e.g. does the project need to exist first?), and no mention of the natural follow-up sibling flow_add_clips_to_scene. Usage is only weakly implied by the word 'empty'.

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?

No annotations exist, so the description carries the full burden. It does disclose a side effect (writing a local file) and a return value (the path), which is useful, but it omits where files land by default, filename derivation, overwrite behavior, or failure modes for an invalid media_id.

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

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

Two short sentences with the action front-loaded and zero filler. It is arguably under-specified rather than wasteful, but the structure itself is efficient.

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

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

No output schema exists, and while the description states the return is a path, it leaves the optional out_dir parameter meaningless and provides no guidance on download scope or errors. For a tool with 0% param documentation, an agent cannot call it confidently.

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

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

Schema description coverage is 0%, so both media_id and out_dir are undocumented anywhere. The phrase 'local file' faintly gestures at out_dir but gives no semantics, default, or format, so the description fails to compensate for the coverage 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 (Download) and resource (image or video) and the destination (local file), which is clearer than most siblings. However, it never distinguishes itself from flow_get_media, which an agent would plausibly choose for the same media, so sibling differentiation is absent.

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

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

No when-to-use guidance, no prerequisites, and no mention of the closest alternative (flow_get_media). The agent must infer that this tool persists bytes locally while flow_get_media likely does not.

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 it does disclose a real behavioral trait beyond the schema: the operation SPENDS CREDITS, uses a costlier model, and the quote is checked against max_credits. However, it omits mutation semantics (does editing alter or replace the source clip?), permission/auth needs, and response behavior, leaving meaningful gaps for a credit-spending write 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?

Three short sentences, front-loaded with the core action and then the cost caveat; essentially no filler. The only minor inefficiency is restating the max_credits check that the schema already explains.

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

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

For a 9-parameter, credit-spending mutation with no annotations and no output schema, the description covers cost but leaves most parameters (character_ids, aspect, resolution, wait, dry_run) and the edit-vs-generate routing unexplained. An agent would still guess at invocation details.

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 should compensate, but it clarifies only 'prompt' (as 'instruction') and restates max_credits, which the schema already documents. It adds no meaning for character_ids, aspect, resolution, wait, or dry_run, which together represent most of the undocumented surface.

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 ('edit an existing clip') and adds a distinguishing trait versus the sibling: it uses an Omni edit model that is costlier than generation, implicitly separating it from flow_generate_video. An agent can tell what the tool does without opening the schema, though the sibling is never named explicitly.

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

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

The 'costlier than generation' note implies you should only edit when you already have a clip rather than generate, but it never explicitly names flow_generate_video or flow_video_status as alternatives, nor states the precondition (an existing media_id from a completed generation). Usage is implied rather than directed.

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 disclose real process behaviour: it downloads each clip, runs ffmpeg normalisation of size, fps and audio, joins them, and executes on the local machine. It does not cover auth/permission requirements, failure modes when a clip is missing, or expected runtime for large scenes.

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

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

A single front-loaded sentence states the operation and output first, then the mechanism in a compact parenthetical. Every clause earns its place, including the return value.

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

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

It fills the biggest gap by stating the return value ('Returns the path') despite no output schema, and clarifies the processing pipeline. However, with five parameters and only one documented, plus no statement of preconditions or failure behaviour, an agent still lacks enough to invoke it confidently in edge cases.

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

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

Schema description coverage is only 20% (just project_id), leaving width, height, out_dir and scene_id undocumented in both schema and description. The description's mention of 'MP4' and 'on this machine' faintly gestures at out_dir and dimensions but never maps them, so it does not compensate for the coverage 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?

The description names a specific verb ('Combine'), the resource ('a scene's clips') and the concrete output ('one MP4'), which naturally distinguishes it from sibling read/download tools like flow_download_media. It is a single-resource composite operation and reads clearly, though it does not explicitly name the siblings it is not.

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 only implied: a scene must already exist with clips (via flow_create_scene / flow_add_clips_to_scene) before this makes sense, and the description never states that precondition or any exclusions. There is no explicit 'use this when...' routing against alternatives such as exporting individual media.

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 delivers almost nothing behavioral: no mention that generation is asynchronous, that counts are capped, that the call may cost quota, or whether results must be fetched later via flow_get_media. Only the 'optional ingredients' framing hints at inputs.

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

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

A single front-loaded sentence covering purpose, engine, and optional inputs with no filler. It is tight, though brevity here shades into under-specification rather than economy.

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 generation tool with no annotations, no output schema, and six mostly undocumented parameters needs far more: async/polling behavior, where the returned media IDs go, and how optional ingredients change output. The description covers none of this.

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 17% — only project_id is documented in the schema. The description gestures at character_ids and reference_media_ids ('characters and reference images as ingredients') but says nothing about the required prompt, the count cap of 4, or the aspect enum, leaving most parameters undocumented in both places.

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 (generate) and resource (images) plus the engine (Nano Banana) and the mechanism (Flow's composer), which is enough to separate it from flow_generate_video or flow_regenerate_portrait. It lacks an explicit contrast with those image-adjacent siblings, so it stops short of a 5.

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

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

The description only states what the tool does, never when to reach for it versus flow_generate_video, flow_regenerate_portrait, or flow_create_scene. No prerequisites (e.g. needing a valid project_id from flow_list_projects) or exclusions are given.

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 provided, the description carries the full burden and does disclose the most decision-critical behavior: that it SPENDS CREDITS, that Flow's quote is gated by max_credits, and that dry_run returns only the quote. It leaves the async/result-retrieval behavior unstated, so it is strong but not complete.

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, front-loaded with the purpose and ingredient behavior before model selection and the credit warning. Nearly every clause earns its place, though the sentence structure runs long.

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

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

For a 14-parameter mutation tool with no annotations and no output schema, the description covers the highest-stakes gaps (credit spend, quote gating, dry_run, ingredient semantics, model selection). It omits how results are retrieved or polled, which is a meaningful gap for a video generation tool but not fatal.

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 71%, and the description adds cross-parameter meaning beyond the schema: character_ids/image_ids acting as 'ingredients' that preserve consistency, the model_key-vs-family/duration_sec/resolution alternative, and Omni's 360p/720p and 4-10s constraints. This exceeds the baseline for a mostly-documented 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 and resource ('Generate video clips through Flow's composer') and clarifies the ingredient mechanism, so the agent can tell it produces video rather than images. It does not explicitly differentiate from siblings like flow_edit_video or flow_generate_image by name, so it lands just below the top band.

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: it explains model selection via model_key or family+duration_sec+resolution and when to set dry_run, but never says when to prefer this tool over alternatives such as flow_edit_video or flow_generate_image. There are no explicit exclusions.

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

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

The readOnlyHint annotation already tells the agent this is a safe read, so the description adds little on the safety axis. The one genuinely useful nugget is that a signed URL is returned 'fresh' each call, implying the URL may expire and should be used promptly, but no expiry, auth, or error behavior is disclosed.

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

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

It is short, but brevity here comes from under-specification rather than economy. The single sentence spends its words on the return artifact instead of the tool's action, which is the wrong front-load for a selection decision.

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, no annotation coverage beyond readOnly, and 0% parameter documentation, the description carries the full burden and delivers almost none of it. An agent knows neither what the tool does with media_id nor what shape of 'signed URL' result to expect.

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

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

Schema description coverage is 0% and the description never mentions media_id, its format, or where it comes from (e.g. a prior generation response). With a single undocumented required parameter, the description must compensate and completely fails to do so.

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 sentence describes the return value ('An image or video with a fresh signed URL') rather than stating what the tool does. There is no verb and no resource action, so an agent cannot tell how this differs from the sibling flow_download_media. It is close to restating the title 'Get media' with output flavor.

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

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

No guidance whatsoever on when to use this tool versus flow_download_media, flow_get_project, or any other retrieval sibling. Neither prerequisites nor exclusions are mentioned.

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

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

The readOnlyHint annotation already establishes the safety profile, so the bar is lower. The description adds some value by enumerating the scope of data returned (characters, generations, media, scenes, clips, agent instructions, defaults), which tells the agent what to expect in the response. It does not, however, disclose any further behavioral traits such as error handling or access prerequisites.

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

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

The description is a single, compact phrase with no wasted words. It is front-loaded with the main categories of returned data. However, as a sentence fragment it is slightly less structured than a complete sentence would 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?

There is no output schema, so the description usefully enumerates the kinds of data the project contains, compensating for the missing return value documentation. The readOnlyHint annotation covers safety, and the schema fully covers the parameter. The definition is nearly complete for a simple read-only getter, though it could mention error cases or format.

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?

There is one parameter (project_id) and schema description coverage is 100%, so the schema fully documents the parameter. The description adds no information about the parameter beyond what is already in the schema, making the baseline score of 3 appropriate.

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

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

The description is a noun phrase listing contents ('Characters, generations and media, scenes with their clips, agent instructions and generation defaults') rather than a verb-led statement of what the tool does. The name and title supply the verb, but the description alone does not clearly state the action and does not differentiate from siblings like flow_list_projects or flow_get_media.

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

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

No guidance is given about when to use this tool versus alternatives. With many sibling tools that also retrieve project-related data, the description provides no selection criteria or context for invocation.

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 safety profile is covered. The description adds nothing further: no pagination behavior, no ordering, no volume expectations for what could be a long session list. For a bare read tool this is the minimum, but no value is added beyond the annotation.

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 a single short phrase with no waste, but it is not a well-formed sentence and is arguably under-specified rather than concise. Brevity here reflects missing content, not efficient packaging.

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

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

For a one-parameter read-only list tool with a fully documented parameter and no output schema, the definition is technically sufficient to invoke. However, it gives no sense of what a session is or what the listing contains, which would help an agent confirm this is the right tool.

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

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

Schema coverage is 100% and the single project_id parameter is fully documented in the schema, including its provenance (from flow_list_projects). The description adds no parameter detail, which is acceptable here since the schema does the work.

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 is a noun fragment ("Flow agent chat sessions in a project") that restates the tool title without stating an action verb. It does convey the resource and its project scoping, but it does not distinguish itself from the nearby flow_agent_chat sibling or otherwise clarify the operation.

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 indication of when to call this versus alternatives such as flow_agent_chat, nor any stated preconditions. The reader must infer usage entirely from the name.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description usefully discloses the shape of returned content and clarifies that credit cost means the 'highest tier price', which is real behavioral context. It says nothing about pagination, ordering, or whether the optional filters actually restrict the result set.

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

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

One compact sentence with no filler, and the resource is front-loaded. The tradeoff is that it is a noun fragment with no verb, which costs a little clarity in exchange for brevity.

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

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

With no output schema, the description correctly carries the burden of describing returned fields, and it does so. However, for a tool with two optional filter parameters it leaves the filtering semantics and result scope unexplained, so an agent cannot fully predict what it will get back.

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

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

Schema coverage is only 50% (mode has no schema description), and the description compensates by enumerating the mode values (text/references/start_frame/start_end_frames/edit/extend/upsample). That is meaningful information the schema lacks. It does not clarify whether mode/family act as filters or are merely returned fields, so it falls short of a 5.

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

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

The description names the resource (video models) and enumerates the attributes each entry carries (key, family, mode, duration, resolution, credit cost), which lets an agent distinguish it from siblings like flow_list_voices or flow_list_projects. It never states the verb explicitly (that it lists/returns these), so the purpose is inferred from the title rather than stated outright.

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 when-to-use guidance, no mention of the optional mode/family filters as narrowing criteria, and no reference to any alternative tool. The agent must guess whether this is a discovery call, a prerequisite for flow_generate_video, or something else.

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 tells the agent this is a safe read. The description adds only the word 'user's' as a scoping hint, and says nothing about ordering, pagination, whether archived projects are included, or result limits for a list 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?

A single short sentence with the resource front-loaded and no filler. It is efficient, though it is arguably too terse to earn a top score.

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 nested objects, and no output schema, the surface area is small, but the description still omits anything about what the returned project list looks like or how it is ordered. It is minimally viable rather than 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?

The tool takes zero parameters, so there is no parameter meaning to document; the schema is trivially complete and the description cannot add or omit parameter detail. Baseline 4 applies for a no-parameter tool.

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

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

States a specific verb (List) and resource (Flow projects) with the scope 'user's'. It is clearly distinguishable from flow_get_project or flow_create_project by the verb, but it makes no explicit sibling differentiation.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives such as flow_get_project for a single project or flow_create_project. The agent must infer the use case entirely from common sense.

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 safety profile is covered, but the description adds nothing beyond it: no note on whether the list is global or project-scoped, no ordering, no result size. The 'assignable to a character' clause is the only piece of extra context.

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

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

It is a single short fragment with no wasted words, but it is under-specified rather than genuinely concise, and it is not front-loaded with an action verb an agent can key on.

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 trivial read-only lister with one fully described parameter and no output schema, the minimal description is arguably sufficient, but it still leaves the agent guessing whether voices are global or scoped to 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?

The single project_id parameter is fully documented in the schema (100% coverage, including its origin 'from flow_list_projects'). The description adds no parameter meaning, so the schema carries the load and baseline 3 applies.

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

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

The fragment 'Voices that can be assigned to a character' identifies the resource but supplies no verb, so the agent must infer 'list' from the tool name. It does not differentiate this listing from siblings like flow_list_models or flow_list_projects beyond the resource noun.

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

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

No when-to-use guidance, no prerequisites, and no mention of any alternative tool. The only implicit hint is that the returned voices are character-assignable, which the agent could infer from the name alone.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It implies a mutation ('change') but does not state whether the existing portrait is overwritten, whether the change is reversible, what permissions are required, or what the response contains.

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

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

The description is a single, front-loaded sentence with no wasted words. It states the action, the target, the input style via an example, and the context, all efficiently.

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

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

Given no annotations, no output schema, and incomplete parameter documentation, the description is too sparse for a mutation tool. It omits usage alternatives, behavioral details about overwriting or reversibility, and semantics for one of three required parameters.

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 33%. The description adds some meaning for the prompt parameter via the instruction example ('give her a red scarf'), but character_id is undocumented in both the schema and the description. project_id is described in the schema only. The description does not compensate for the low coverage.

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

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

The description states a specific verb and resource: it changes an existing character's portrait using an instruction, within Flow's character editor. It is clear enough to distinguish this from general character creation or updates, but it does not explicitly name or differentiate against siblings like flow_update_character or flow_create_character.

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

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

The description gives a purpose but no explicit when-to-use guidance, prerequisites, or alternatives. It does not mention when to choose this over flow_update_character or other character-related tools, nor does it state any exclusions.

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

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

No annotations are provided, so the description carries the full burden. It discloses mutation semantics for each mode, including that 'replace' overwrites the whole list and 'remove' targets by id or title, but says nothing about permissions, reversibility of removal, or behavior of the undocumented 'enabled' flag.

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 dense sentence that puts the resource and purpose first and then the mode semantics. Every clause earns its place, though the parenthetical could be slightly cleaner.

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

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

For a mutation tool with no annotations, no output schema, and 25% schema coverage, the description covers the mode behavior reasonably but leaves the 'enabled' toggle and array item semantics unexplained, so an agent cannot fully model the call.

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

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

Schema coverage is only 25%, so the description must compensate. It usefully explains the mode enum values and how removal targets items (id or title), but the 'enabled' parameter and the instruction object's active/id/text fields remain undocumented in both schema and description.

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

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

Names the resource (project 'Agent instructions') and describes the effect (guidelines Flow's agent follows for style, format, tone). A specific verb+object pair, though it never explicitly contrasts with siblings like flow_set_generation_defaults or flow_agent_respond.

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 through the mode semantics ('add' appends, 'replace' sets the list, 'remove' deletes), so an agent can infer when each mode applies. There is no explicit when-to-use-this-instead-of-alternatives guidance or prerequisite statement.

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?

No annotations are provided, so the description carries the full behavioral burden. It adds useful context on the credit-approval stance ("whether it must ask before spending credits"), but for a mutation it never states whether existing defaults are overwritten or merged, whether partial updates are valid, or what permissions are required.

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

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

A single sentence with no filler, and the most consequential item (credit spend approval) is placed last for emphasis. The phrasing "Model defaults the agent uses" is slightly indirect but wastes no words.

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

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

For a mutation with nested objects, no annotations, no output schema, and 25% schema coverage, the description is thin: it omits project_id, says nothing about update semantics (replace vs merge), and gives no guidance on the required video fields. An agent could invoke it but would be guessing at behavior.

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

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

Schema coverage is only 25%, so the description must compensate by enumerating image (aspect/count/model), video (model/aspect/count), and clarifying credit_spend_approval. That enumeration is largely a restatement of the nested schema fields, and project_id plus the enum meanings are not elaborated, so it only partially closes the 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?

The description names the resource precisely (image/video generation defaults plus credit-approval policy) and its effect is unambiguous relative to generation siblings like flow_generate_image. It lacks a leading verb and never explicitly contrasts itself with those siblings, so it falls short of a 5.

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 when-to-use or when-not-to-use guidance. The description lists configurable fields but never says to call this before generating media, or how it interacts with the sibling generation tools, leaving the agent to infer the workflow.

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 goes further by disclosing what the call actually inspects and returns (sign-in state plus credit balance), which matters because there is no output schema. It stops short of saying what happens when the browser is not signed in (error vs. a boolean flag) or whether the credit read requires an authenticated call.

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 sentence, no filler, and the primary outcome (sign-in check) is front-loaded ahead of the secondary one (credit balance).

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

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

For a zero-parameter, read-only diagnostic with no output schema, the description covers both the purpose and the return content, which is the essential information. The only real gap is failure-mode behavior when the browser is unauthenticated, which an agent would likely need in order to handle the result.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No argument syntax or scoping options are relevant here.

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 (check) plus two concrete outcomes: sign-in state of the MCP browser and remaining Flow credit balance. This is clearly distinguishable from every sibling, which are all list/create/generate/edit operations rather than diagnostics.

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

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

No when-to-use or when-not-to-use guidance is given. A preflight intent (e.g., verify auth before calling flow_generate_video) can be inferred, but the description never says when an agent should call this versus simply attempting another Flow tool and handling an auth error.

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. It says the tool 'changes' fields but omits whether omitted fields are preserved, what permissions are required, whether changes are reversible, or what the response contains.

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

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

A single, front-loaded sentence with no filler. Efficient, though it is arguably too terse given the unaddressed behavioral and parameter gaps.

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 mutation tool with no annotations, no output schema, and 80% of parameters undocumented in the schema. The description should disclose mutability semantics, field-omission behavior, and identifier requirements but does none of this.

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 20%, so most parameters are undocumented. The description names the three updatable content fields (name, voice, personality), which maps meaning onto them, but says nothing about the required project_id/character_id beyond what the one schema description already provides.

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 ('Change a character's...') and enumerates the mutable fields (name, voice, personality). It is clear what the tool does, though it does not differentiate itself from the sibling flow_create_character.

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

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

No guidance on when to use this versus alternatives such as flow_create_character, nor any prerequisites (e.g. requires an existing project and character id). Usage must be inferred entirely from the name.

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

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

Annotations already establish readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: successful jobs return a signed URL that expires after a few hours, which affects how the agent must handle the result.

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

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

Two short sentences, zero filler, with the primary action front-loaded and the important output caveat immediately after. Nothing pads or buries the key 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 output schema and no parameter descriptions, the description should at least cover job states (queued/running/failed) and the wait/timeout interaction. It covers only the success-case URL, leaving the agent guessing about failure states and how blocking waits terminate.

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

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

Schema description coverage is 0%, so the description carries the full burden for media_ids, wait, and timeout_sec. It only loosely gestures at 'wait' and says nothing about the required media_ids array or the timeout_sec default/units, leaving two of three parameters unexplained.

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 ('Check') and resource ('video jobs'), plus an alternative mode ('wait for'). It is understandable, but it does not distinguish itself from the sibling flow_status, which an agent could easily confuse with this job-status tool.

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

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

The parenthetical '(or wait for)' hints that a blocking mode exists, but there is no guidance on when to poll versus wait, how this differs from flow_status, or what timeout behavior to expect. No alternatives are named.

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