openFlow

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

Goes well beyond annotations by disclosing that the token is single-use, failed calls require a fresh login, successful binds are tied to the key's owner group, worker pickup takes ~30s, and no restart is needed. Also warns that a master token grants full account access. No contradiction with annotations.

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

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

The description is longer than average but every section earns its place: purpose, token acquisition steps, single-use warning, success behavior, and security boundary. It is well-organized with a clear 'HOW TO GET oauth_token' section and front-loaded purpose.

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

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

Provides nearly everything needed to call the tool correctly: how to obtain inputs, what happens on success, timing, failure behavior, and security constraints. The main gaps are the unmentioned reset_day parameter and the absence of any tool response details, though these are partially mitigated by the rich surrounding guidance.

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 description thoroughly explains email and oauth_token, including how to obtain them and the single-use behavior of oauth_token. However, reset_day is completely undocumented, and since schema description coverage is 0%, this is a real gap.

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

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

States a specific verb ('Attach'), a resource ('one of YOUR OWN Google accounts'), and the mechanism ('oauth_token captured on the USER'S OWN machine'). Clearly distinguishes this self-serve onboarding path from server-side browser or SSH approaches.

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

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

Explicitly identifies when to use it ('self-serve onboarding path'), how to obtain the required token via the local grabber, and critical constraints: the token is single-use, must never be retried, and should only be used for accounts the caller controls. Also notes that adding an account is always allowed even after quota is spent.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds useful behavioral context by warning that it does NOT return real credit numbers, only the project list, which is a meaningful limitation beyond the annotations.

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

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

Two sentences with no wasted words. The primary action is stated first, followed by a crucial caveat and routing to the alternative tool. The structure is ideal for quick agent parsing.

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 read-only tool with one optional parameter and no output schema, the description covers the essential behavior and the main limitation. It tells the agent what the tool does, what it does not do, and when to use a sibling instead.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies that the 'account' parameter refers to a farm account and that null/all is supported, but it does not specify the expected format or whether account is an ID, name, or other identifier. This is partial compensation for a single optional parameter.

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

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

The description states a clear verb and resource: 'Check projects for a farm account (or all).' It also explicitly distinguishes itself from flow_dashboard by noting it only returns the project list, not credit balances. This prevents confusion with a similarly named sibling.

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

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

The description gives explicit guidance: prefer flow_dashboard() when credit balances or an at-a-glance overview are needed, and use this tool only for the project list. This directly tells the agent when to choose an alternative and when to use this tool.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds substantial behavioral context beyond them: progress fields, queue semantics, URL expiry, and server-copy reclamation. This fully discloses what happens to results over time, which is valuable for a polling tool.

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

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

Although longer than average, every section earns its place: what fields are reported, how to interpret them, and what to do on completion. The critical 'done' action is explicit and front-loaded, and there is no filler.

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

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

For a tool with no output schema, the description covers the response shape well, including progress fields, download_urls, save_as, and URL expiration. The main gaps are the undocumented include_preview parameter and explicit status enum values, but overall it is nearly complete.

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

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

Schema description coverage is 0%, so the description must compensate. It gives real semantic meaning to job_id ('previously returned by...'), but it never mentions include_preview, the optional boolean parameter. This is partial compensation rather than complete parameter coverage.

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

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

The description uses a specific verb ('Check') and a clear resource ('status/result of a job'), and it explicitly scopes the job to those previously returned by four named generator tools. This makes it easy to distinguish from sibling generator tools and other status-type tools.

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

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

The description clearly states when to use it: only for jobs previously returned by the listed generators. It also gives concrete post-completion actions (save download_urls into the project). It does not explicitly name an alternative tool or state when not to use it, but the context is sufficient for a poll-type tool.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description adds important behavioral context beyond the annotations: the portrait slot is written only once and cannot be regenerated, calling with the same name fails fast rather than retrying, and the return shape is stated. This materially changes how an agent should plan calls and handle errors.

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

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

The description is long but well-structured and front-loaded: purpose first, then parameter semantics, then behavioral caveats, then return and follow-up. Every sentence adds practical information; there is no filler or restatement of the tool name.

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

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

For a complex creation tool with no output schema and no param descriptions, this description is unusually complete: it explains the one-shot portrait behavior, return fields, naming constraints, and the correct next-step tool. An agent has enough context to invoke it correctly and avoid the common misuse of entity_id-based image generation.

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

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

With 0% schema description coverage, the description carries the parameter burden and does a strong job on the three required parameters: name uniqueness, description-as-image-prompt guidance, and account ownership. It leaves optional parameters like display_name and portrait_prompt mostly implicit, but their titles/enums/defaults convey most of their meaning.

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

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

The description opens with a clear verb and resource: 'Invent a new character from a text description and generate its portrait.' It also differentiates itself from the photo-based sibling and from manually chaining create_character + update_character + generate_character_image, so an agent can immediately tell which tool matches the 'no photo involved' path.

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

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

It explicitly says this tool replaces the multi-step composition, references list_characters() as a prerequisite for choosing a unique name, and directs the agent to generate_with_face for any future image of the character. It also warns against using entity_id/character_slot_index for new scenes, giving clear routing beyond the call itself.

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

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

The description goes far beyond the basic annotations: it discloses the ~15-30s Chrome boot cost, that no image generation occurs, that no Android/recaptcha is involved, that name clashes do not fail the call but produce a registration_error, and the fidelity limitation that 'genuinely consistent' means internally consistent rather than an exact match to the real person. This is rich, accurate behavioral context that complements the annotations without contradicting them.

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

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

The description is front-loaded with the core behavior and has useful per-parameter structure, but it is overwrought. It includes dated editorial notes and corrections ('CORRECTED same day as this tool was first built', 'Fidelity note added 2026-07-11'), which add historical context but could be condensed without loss of operational meaning.

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

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

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

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

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

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

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

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

The description states a specific verb and resource: 'Create a new Flow character whose portrait (and optionally body) is a REAL PHOTO.' It immediately distinguishes itself from text-description or generation-based creation, which differentiates it clearly from siblings like create_character and create_character_from_description.

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

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

The description gives explicit when-to-use guidance and alternatives. It tells the agent to use generate_video_with_reference when a recognizably real person is the goal, and to use generate_character_turnaround or generate_character_expression_sheet when further generated panels are wanted, while noting when to skip them if a real body photo was provided.

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

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

The description goes well beyond the annotations, disclosing that projects may not appear in the Flow UI, that 'registered: false' only affects browsing in Google's interface, and that media_ids remain account-bound. It also states that the project is usable immediately, which is important operational context. No contradiction with annotations.

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

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

The description is longer than average but structured with clear breaks and focused paragraphs. It front-loads the core action and return value, then explains account semantics and UI caveats. Each paragraph earns its place, though the media_ids digression could arguably be trimmed for a shorter definition.

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 two-parameter creation tool with no output schema, this description is unusually complete: it documents both parameters, the return shape, immediate usability, account bindings, and a UI caveat. An agent has everything needed to invoke it correctly and set expectations for the response.

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

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

Schema coverage is 0%, so the description must carry the full burden of explaining parameters. It does so thoroughly: 'account' is explained in terms of which farm account creates the project and its relation to project_id/media_ids, and 'name' is described as optional with an example. This adds substantial meaning beyond the bare schema.

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

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

The description states a specific verb and resource ('Create a NEW Flow project'), names the return value, and clearly distinguishes this tool from the surrounding generation and character tools. It also explains the core purpose (giving each client their own namespace), which makes the tool's role unambiguous.

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

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

The description gives explicit when-to-use guidance: create one project per client once, then pass the project_id to generate_image/generate_video. It also clarifies account-vs-project behavior and the limitation that media_ids remain account-bound. It does not explicitly name alternatives or state when not to use the tool, but the use case is clear enough.

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

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

Beyond the annotations, the description adds meaningful behavioral context: edits are pinned to the farm account, only own videos can be edited, each edit costs 20 credits, the model choice is constrained, and the operation affects the whole clip. This goes well beyond the structured annotation hints and helps an agent predict 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.

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

The description is front-loaded with the core purpose and examples, then adds constraints and exclusions. Nearly every sentence contributes, though the farm-account and credit details are somewhat redundant and could be tightened without losing meaning.

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

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

For a mutation tool with no output schema, the description covers the operation, constraints, and costing well, but it omits what the response looks like, whether the edit is asynchronous/job-based, and the meaning of include_preview and aspect. It is adequate for basic invocation but not fully complete for an agent working without prior service knowledge.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It usefully documents media_id (must come from a previous generate_video* result) and gives examples for prompt, but aspect and include_preview are never explained. It also says 'abra_edit is the only model Flow offers here' while the schema enum includes abra_edit_360p, which is confusing for video_model_key.

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

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

The opening sentence, 'Rewrite a video this service already generated, from a plain description,' clearly states the verb, resource, and operation. It includes concrete examples and explicitly distinguishes itself from a mask/region editor, so an agent can tell it apart from generate/motion/upscale siblings.

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

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

It gives clear when-to-use context: editing only our own previously generated videos with whole-clip changes made through natural-language prompts. It also gives a strong exclusion: 'It is not a mask tool: describe the change, not the region.' It does not explicitly name sibling alternatives like extend_video or generate_video_from_image, but the boundary is clear.

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

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

Annotations only mark the operation as side-effecting, non-idempotent, and non-destructive. The description adds meaningful behavior beyond that: the job is pinned to the originating farm account instead of rotating, unknown ids produce a clear error, the continuation inherits the source world, and the default model costs 10 credits and adds 8 seconds. None of this appears in the structured annotations.

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

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

The description is front-loaded with the core purpose in the first sentence and each following paragraph earns its place: id provenance, use case, model default/cost, and project placement. It is compact for the amount of critical context it delivers and avoids boilerplate.

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

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

The description covers the tricky account pinning, id provenance, project placement, use case, and default model cost. However, with no output schema, it would be stronger if it stated what the call returns (e.g., a job id or media result), so it is not fully complete for an agent that needs to chain results.

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

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

Schema description coverage is 0%, so the description must compensate. It adds crucial semantics for media_id (bare id only, must come from this service, account-pinned) and project_id (pass the source project or omit it), and it explains the default video_model_key with cost and duration. It does not explain prompt, aspect, or include_preview in detail, but the most non-obvious parameters are well covered.

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

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

The opening sentence names a specific verb and resource: 'Continue a video this service already generated.' It also distinguishes itself from fresh text-to-video by explaining that a continuation inherits the source clip's world, and it ties the subject to a prior generate_video* result, so an agent can tell this from siblings.

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

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

The description explicitly states when to use the tool: 'Use this for shots that need to run longer than one generation, or to keep a scene going without re-describing it.' It also contrasts with 'a fresh text-to-video call' and gives concrete guidance about project_id, leaving little ambiguity about selection and call setup.

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 and idempotentHint=true, but the description adds substantial behavioral context: the default refusal of large files, the fallback to a download link, the storage semantics (no retention window, files never deleted until disk pressure, reclaimed files return 410 not 404), and the token-cost warning for base64 text. This goes far beyond the structured data and gives the agent real operational knowledge.

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?

Though long, every sentence earns its place. The critical warning (expensive path) is front-loaded in bold, then each paragraph covers a distinct aspect: usage, parameters, return format, storage, and error handling. It is structured with clear headers and no fluff or repetition.

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

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

For a tool with three parameters, no output schema, and a complex cost profile, this description covers every essential aspect: what it returns (with a JSON structure), when to use it, how to avoid the expensive path, what the error codes mean, and the persistence model. An agent can invoke it correctly with zero prior knowledge.

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

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

Schema coverage is 0%, so the description must carry full parameter documentation. It does exactly that: explains path as the download_path/first_frame_path from a job result or bare filename, max_kb as a size ceiling with a concrete token equivalent, and force_bytes as a deliberate override with cost implications. Each parameter's purpose and default behavior is clarified.

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

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

The description opens with a precise, verb-resource statement: 'Download a generated media file (video, frame) and return its bytes, base64-encoded.' It also names the two specific uses (save or show) and distinguishes itself from the sibling download_url by explicitly warning this is the expensive path. No ambiguity about what this tool does.

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

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

It explicitly states when to use this tool versus alternatives: 'prefer download_url from the job result', and 'not to check status (use check_job for that)'. It also clarifies when force_bytes is justified and when not, giving the agent actionable decision criteria. This is exemplary guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is clear. The description adds valuable non-obvious behavior: credit numbers are live from Flow's /v1/credits, the refresh date is not exposed by the API and is shown as an estimate note, and the response includes both a human-readable summary and structured accounts/totals. This is meaningful context beyond the annotations.

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

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

Three sentences, each carrying distinct information: what the tool returns, when to use it, and the response shape plus data caveat. The phrasing is slightly redundant ('account-pool control panel' and 'operator's dashboard'), but overall it is efficient and front-loaded with the most important content.

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

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

For a zero-parameter, read-only dashboard tool with no output schema, the description covers the key operational knowledge: output includes summary, accounts, and totals; credit data is live; the refresh date limitation is disclosed. It doesn't enumerate every field inside the accounts array, but the description conveys enough for an agent to invoke it correctly and set expectations.

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 input schema has zero parameters, which is the baseline-4 case. The description reinforces that this is a one-call, no-argument aggregate view ('one call', 'account-pool control panel'), so there is no parameter ambiguity to resolve.

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

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

The description uses a specific verb-like role ('control panel') and clearly states the resource and scope: every farm account's real credit balance, subscription tier, project count, health status, plus totals. It also gives example questions the tool answers ('how many accounts, how many credits on each and in total, what projects'), which makes it easy to distinguish from siblings like check_credits or flow_status.

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

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

The description explicitly tells the agent when to use this tool: when the user wants the operator's dashboard view or aggregate account/project/credit questions. It doesn't explicitly contrast with sibling tools like check_credits, flow_health, or flow_status, but it provides enough context to infer the dashboard is the intended high-level overview, not a specific health or credit lookup.

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

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

Annotations already declare readOnlyHint and idempotentHint, so no safety contradiction exists. The description adds valuable behavioral context beyond those hints: the Android emulator is off, generation uses a pure-HTTP token path, and there is no warm-up delay. This helps the agent interpret queue depth meaningfully.

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 two sentences with no filler. The core purpose is front-loaded in the first sentence, and the second sentence contributes useful operational context rather than repetition.

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

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

For a zero-parameter, read-only health tool, this description is complete: it states what is checked, what queue depth includes, and why the backend behavior has changed. No output schema exists, but the description gives enough of an expectation about the returned information.

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

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

The tool has zero parameters and 100% schema description coverage, so param documentation is trivially satisfied. The description reinforces the no-input nature by focusing entirely on what the read operation reports.

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

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

The description clearly states a specific action and resource: checking whether the Flow generation backend is reachable and viewing queue depth. It does not explicitly distinguish itself from sibling tools like flow_status or flow_dashboard, so it falls short of a 5, but the purpose is unmistakable.

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

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

The intended use is implied: call this to verify backend reachability and queue load. There is no explicit guidance about when to prefer this over related health/status tools or when not to use it, so the agent must infer the selection criteria.

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

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

Beyond the annotations' readOnlyHint and idempotentHint, the description discloses important behavioral details: `next_step` is the most blocking field, null means nothing is missing, and the output includes ready-made text in Russian and English plus a URL. It also explains the human support channel and the fact that no one will proactively contact the user, adding real context beyond the annotations.

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

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

The description is longer than strictly necessary but every sentence contributes value: usage timing, output interpretation, and user-facing action steps. It is front-loaded with the most important constraint ('READ-ONLY, spends nothing') and then flows logically from call timing to output meaning to required follow-through. Slightly verbose for a zero-parameter tool, but not padded.

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

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

For a simple status-check tool with no parameters and no output schema, the description fully compensates: it explains what the tool returns, which field matters most (`next_step`), how to interpret null, and what the agent must do with the result. Even the human-channel nuance is covered, making the description sufficient for safe and correct invocation.

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

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

The tool has zero parameters, and the schema is an empty object, so there is no parameter semantics to clarify. Baseline 4 applies because the description wisely invests no space on parameters and instead focuses on output behavior, which is the relevant semantic content for this 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?

The description opens with 'what this key still needs before it can do everything' and immediately labels the tool as 'READ-ONLY, spends nothing,' which clearly identifies its diagnostic purpose. It then enumerates the exact questions it answers (account connected, trial remaining, GitHub linked, video paid), making the tool's role unmistakable and distinct from sibling generation tools.

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

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

The description gives explicit trigger conditions: 'Call this BEFORE the first generation of a session, whenever a call is refused, and whenever the user asks why something does not work.' It also provides post-call guidance on how to surface `next_step` to the user, leaving no ambiguity about when and how the tool should be used.

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

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

The description is transparent about the new unverified HTTP path, the lack of browser involvement, and the fact that default character_slot_index=0 overwrites the existing portrait image. However, this contradicts the destructiveHint=false annotation, since overwriting an existing portrait is a destructive side effect; per the rubric this forces a score of 1.

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

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

The purpose is front-loaded, and parameter documentation is separated at the end. The historical/mechanism digression is long and somewhat run-on, making the description more verbose than needed for selection and invocation.

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

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

The description covers purpose, mechanism, parameter semantics for most fields, and the overwrite side effect, so an agent can likely invoke it correctly. It leaves gaps around the required entity_id, the actual return/job behavior, and relies on reading generate_character_turnaround's docstring for the full story.

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

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

With 0% schema description coverage, the description compensates for account, expressions, and character_slot_index by explaining ownership, label format, recommended count, defaults, and overwrite behavior. It does not explain the required entity_id property at all, and 'default if omitted' for expressions does not state the actual default list.

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

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

The opening sentence states a specific verb and resource: generating a single labeled image of the character's face with several expressions in one row. This clearly differentiates it from siblings like generate_character_turnaround and generate_character_image.

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

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

The description implies the expression-sheet use case and says it shares the job type and history with generate_character_turnaround, but it never explicitly states when to use this tool rather than generate_character_turnaround or generate_character_image. It also omits exclusions or prerequisites, instead deferring to the sibling's docstring.

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

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

The description adds substantial runtime behavior beyond the annotations: one-shot-per-slot semantics, HTTP 500 on already-filled slots, the personality_notes prerequisite, identity drift for real-photo seeds, and per-account ownership. These are high-value disclosures not visible in the structured metadata.

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

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

The description is long but dense with non-redundant caveats and routing rules, and the most important distinctions are front-loaded. Minor redundancy exists around the one-shot/'once' theme, but each paragraph earns its place.

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

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

For a mutating tool with no output schema, the description covers preconditions, failure modes, ownership constraints, and sibling alternatives exceptionally well. It does not state what the tool returns on success, but that omission does not significantly hinder correct selection and 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?

Adds crucial meaning for entity_id (provenance from create_character/create_character_from_photo/create_character_from_description) and character_slot_index (0=portrait, 1=body, plus server-side consistency). However, with 0% schema coverage, prompt, model, and aspect are not described in prose beyond what the schema enums/defaults already provide, so the compensation is partial.

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

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

Opens with a concrete verb and resource: 'Generate a portrait or body image for an existing Flow character.' It also explicitly contrasts itself with generate_with_face and generate_video_with_reference, and states what it does NOT do, making sibling differentiation strong.

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

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

Provides explicit when-to-use and when-not-to-use guidance: don't re-call for slot 0 after create_character_from_description, call update_character with personality_notes first on fresh entities, use generate_with_face for 'character doing X', and use generate_video_with_reference for real-person identity. This is exemplary routing.

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

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

Annotations are minimal (readOnlyHint=false implies mutation; destructiveHint=false), and the description goes well beyond them by candidly disclosing that multi-view reliability on the new image_inputs path is 'unverified-but-plausible', that the mechanism changed 2026-07-26, and that the old finding stands. This is honest, context-rich disclosure rather than repeating the annotations.

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

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

The actual purpose is front-loaded in the first sentence, but the description then unfolds into a long historical narrative (2026-07-11 finding, 2026-07-26 change, worker.py's BROWSER_JOB_TYPES, thread-by-thread disclaimers about what was and wasn't re-verified). This institutional memory is valuable for trust but is padded with redundant caveats that could be condensed to a sentence or two.

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 tools with no output schema and a complex mechanism history, the description covers reliability status, recommended prerequisites, and parameter semantics for 3 of 4 parameters. It is fairly complete, minus the unexplained outfit_description parameter, which is the one material omission for an agent trying to call it correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden for all 4 parameters. It explains account (farm account owning the entity's project) and character_slot_index (which slot, default 1), and references entity_id implicitly via 'this entity_id's project'. However, outfit_description is entirely absent from the description — a parameter with a non-trivial default that an agent would not know how to set meaningfully. With 0% coverage, this gap is significant.

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

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

The opening sentence states a specific verb (generate), resource (character turnaround), and output format (FULL BODY from 3 angles in one row, labeled). It also explicitly names the sibling it is not — 'a separate path from plain image generation' — so an agent can distinguish it from generate_character_image without opening schemas.

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

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

The description gives clear usage context: recommend saving a detailed physical description first via create_character_from_photo's physical_description param or update_character's personality_notes, and it distinguishes this path from plain generation. It lacks an explicit 'when NOT to use' statement, but the alternative tool names and conditions are supplied.

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

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

Annotations declare readOnlyHint=false and openWorldHint=true, and the description adds substantial behavioral detail: it writes files to the user's project, URLs expire within the hour, the preview silently falls back on failure, and GEM_PIX_2 has a separate daily quota. No contradiction with annotations.

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

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

The description is long but well-structured with distinct paragraphs per parameter and a front-loaded core (purpose and model selection). Every sentence adds value – model details, preview fallback, and saving instructions are not redundant. It balances detail with organization.

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 an 8-parameter tool with no output schema and minimal annotations, the description covers return dicts, job polling, fallback behavior, file saving, and quota notes. The only omission is aspect, which is covered by the schema enum. Nothing critical is missing for correct invocation.

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

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

With schema description coverage at 0%, the description compensates thoroughly: it explains model as exact IDs with defaults and rejection behavior, seed range and purpose, image_inputs and control_images encoding, project_id usage, and include_preview behavior. Only aspect is left to the schema's enum and default, a minor 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 opens with 'Generate an image from a text prompt via Google Flow' – a precise verb, resource, and input. It distinguishes itself from a key sibling by explicitly naming generate_scene as the preferred tool for whole-scene layout control, so the agent can tell when this tool is the right one.

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 clear operational guidance: when to use a fixed seed for comparisons, when to use control_images, and the explicit direction 'For whole-scene layout control prefer generate_scene.' However, it does not systematically contrast with all image-generation siblings (e.g., generate_character_image), so exclusions are only partial.

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

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

The description adds substantial behavior beyond the sparse annotations: it explains how the control image is rendered, how boxes are replaced with objects, how rotation/pivot transforms work, and includes a measured empirical note about motion ranges. It also discloses the cost of control_png and when it is off by default. No contradiction with annotations.

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

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

The description is long but tightly organized: each paragraph or labeled segment covers a distinct concern, and all content is actionable. Empirical details and return-format notes are placed where they matter, with the core purpose front-loaded.

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

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

Despite the complex nested scene_layout schema and no output schema, the description explains required layout fields, camera constraints, aspect behavior, rotation math, sequence-consistency guidance, output fields, and the control_png tradeoff. It leaves an agent with everything necessary to call the tool correctly.

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

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

With 0% schema description coverage and 12 parameters, the description fully compensates by explaining almost every parameter: scene_layout structure, camera_id, aspect/FOV behavior, style/extra, seed/image_inputs sequence semantics, depth, calibration, background, and control_png. Only project_id is not explicitly explained, but the major parameters are comprehensively defined.

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

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

The first sentence states a specific verb and resource ('Build a location precisely from a scene-layout/v2 map and generate its plate') and immediately distinguishes it from the prose-based alternative. The phrase 'exact location building path' makes it clear this tool is not a generic image generator.

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

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

It explicitly explains when to use this path over prose and gives concrete conditional guidance, such as using a light background for white plates and generating a reference frame first for sequences. Cross-referencing generate_image for seed/image_inputs also helps an agent choose correctly.

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

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

Annotations only say non-read-only, non-idempotent, non-destructive, so behavior is mostly undisclosed. The description compensates with concrete latency expectations (1-3+ minutes), the async job_id flow, credit costs per model, and a measured warning about how the model stretches motion over the requested length.

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

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

The description is long but dense and front-loaded with the purpose before model options. The extended beats paragraph could be tightened, yet every sentence carries behavior the agent needs (definition, default, measured warning, exclusion of adjectives), so nothing is filler.

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

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

For a no-output-schema tool with 6 params, it covers the non-obvious behavior: async job_id, polling, credits, beats semantics, and project scoping. It doesn't explain the full 12-value model enum or include_preview's effect, which are minor gaps; the agent can still call the tool correctly using defaults.

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

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

Schema coverage is 0%, so the description carries the burden. It goes beyond the schema for video_model_key (credit costs and quality tiers), project_id (per-client separation), and beats (definition, examples, measured behavior). It leaves aspect and include_preview unexplained, but those are self-describing enums/booleans.

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

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

Opens with a specific verb and resource ('Generate a video from a text prompt'), which clearly separates it from siblings like generate_video_from_image and generate_video_between_frames. The mention of Google Flow/Veo adds useful context without obscuring the core action.

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

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

A large portion of the description is practical guidance: use create_project to scope per client, expect a job_id and poll check_job, and supply beats to let the server choose clip length. It doesn't explicitly name sibling alternatives or say when not to use them, but the text-prompt scope plus these instructions give clear calling context.

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

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

The description goes well beyond annotations by disclosing the default model, credit cost, retry economics, measured motion-stretching behavior, and the fact that the server picks the clip length and reports its choice in the reply. It also clarifies that images must be raw base64 without a data URI prefix. No contradiction with 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.

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

The opener is strong and front-loaded, but the description becomes repetitive: beats is explained twice in nearly identical blocks, including the same measured date and 15% movement-loss detail. Several sentences could be merged or removed, so not every sentence earns its place.

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

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

For an 8-parameter tool with no output schema, the description provides the key mental model, cost context, retry guidance, input encoding constraints, and even what the server will reply. It is usable for correct invocation, though it does omit behavioral notes for aspect and include_preview; schema defaults help cover the basics.

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

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

With 0% schema description coverage, the description compensates substantially: it explains start/end base64 encoding, beats semantics with counting examples, project_id behavior, and the default video_model_key. However, aspect, include_preview, and the non-default enum values for video_model_key are not explained, leaving some parameters underdocumented.

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 concrete operation: 'Generate the transition between TWO given frames: the video starts at the first image and ends at the second one, Flow invents everything in between.' This is a specific verb + resource with a clear behavior, and it explicitly contrasts with the sibling generate_video_from_image, so an agent can distinguish the two tools.

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

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

It gives explicit selection criteria: 'Use this when the ending matters' with concrete examples like logos, poses, and storyboard stills, and directly explains the difference from generate_video_from_image, which lets the ending drift. This leaves little ambiguity about when to choose this tool.

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

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

Annotations are minimal (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description carries the burden of behavioral disclosure. It delivers substantial behavior: mutual exclusivity with r2v, server-selected clip length when beats is supplied, the model's stretching behavior with a measured timing consequence, and what happens when beats is omitted. No contradiction with annotations.

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

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

The description is front-loaded with a one-sentence purpose, then organized into parameter-focused paragraphs. The beats paragraph is dense but earns its length by explaining a subtle and important behavior. Every sentence adds useful information; there is no filler or redundancy.

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

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

Given the tool's input-side complexity, the description covers the core invocation concerns thoroughly: image format, beats semantics, alternative routing, and project scoping. The main gap is that there is no output schema and the description does not describe the general return shape beyond noting that the reply states the beat-based length choice. For a generation tool, that is a meaningful but not crippling omission.

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 has 0% description coverage, and the description compensates for the three non-obvious parameters: start_image_base64 (raw bytes, no data URI prefix), beats (phase-count semantics with concrete examples), and project_id (target project). It does not document aspect, include_preview, prompt, or video_model_key, though their enums/defaults reduce ambiguity. Strong but partial compensation.

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

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

Description opens with a specific verb and resource: 'Generate a video that starts from a given image (i2v — image-to-video).' It explicitly labels the mode and distinguishes it from the sibling generate_video_with_reference by naming the alternative and the use-case split. An agent can tell this tool apart from its siblings immediately.

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

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

Gives direct routing guidance: prefer generate_video_with_reference for 'make content that looks like this real photo of a person,' and use i2v for 'continue visually from this exact frame (e.g. chaining clips).' It also states that start_image_base64 is mutually exclusive with reference-image generation. This is explicit when-to-use and when-not-to-use guidance.

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

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

The description adds substantial behavior beyond annotations: reference-based generation conditions on actual pixels and preserves faces; character-system alternatives drift; generate_image silently ignores external references; and the result should be retrieved through check_job. Annotations already cover mutation/idempotence/safety, but this enriches the operational picture significantly.

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

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

The description is long, but each section earns its place: core definition, parameter encoding detail, routing guidance, workaround, and project scoping. The 'confirmed live' and 'same-day testing' material is verbose yet directly supports tool selection and prevents known failures. It is front-loaded with the primary purpose, though it could be tightened.

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

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

Despite having no output schema, the description tells the agent how to follow through—via check_job and first_frame_path—and gives enough context for selection and invocation. It does not explicitly explain the full return flow or all parameters, but defaults and enums lower the risk. Overall, it is near-complete for a tool with this much sibling confusion.

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 parameter-semantics burden. It adds genuinely useful detail for reference_images_base64 (raw base64, no data URI, max 3) and project_id (must be from create_project), but it leaves prompt, aspect, include_preview, and video_model_key unexplained beyond schema defaults/enums. Compensation is partial, not complete.

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

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

The opening sentence states a specific verb and resource: 'Generate a video using up to 3 reference images (r2v)'. It also clarifies the distinguishing purpose—consistent character/subject preservation—and explicitly separates it from i2v start-image generation. This clearly differentiates it from siblings like generate_video_from_image and generate_video_between_frames.

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 is unusually explicit about when to choose this tool: it is 'THE RECOMMENDED WAY' for real-person likeness preservation, and it names concrete alternatives (generate_character_image, generate_character_turnaround, generate_image) while explaining why they fail. It also gives a workaround for still-image output, plus the mutual exclusivity constraint with i2v.

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

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

Beyond the annotations, the description discloses important behavioral details: the tool generates from the reference image alone, never from entity_id, and that combining entity_id with an image reference fails outright. It also notes that photo_media_id remains account-bound. This is meaningful behavioral context that the annotations (readOnlyHint=false, destructiveHint=false) do not capture.

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 longer than average but well-structured with clear sections and bullet-like formatting. The core purpose is front-loaded, parameter semantics are grouped logically, and the 'why not entity_id' rationale earns its place because it prevents a known failure. Only minor redundancy keeps it from a 5.

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

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

For a 7-parameter tool with no output schema, the description covers the critical selection logic, the one-of requirement, failure modes, and project placement behavior. It does not discuss return values or job handling, but given that the tool has no output schema and openWorldHint=true, the description is sufficiently complete 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.

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

Schema description coverage is 0%, so the description carries the burden. It compensates well for the key parameters: character vs photo_media_id is explained in depth, prompt gets explicit guidance with an example, and project_id is clarified. Model, aspect, and include_preview are left to their enum/default values, which is acceptable but not fully documented.

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

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

The description states a specific verb and resource: 'Generate a NEW image of the SAME PERSON/character as an existing photo or portrait.' It gives concrete examples ('put me in a suit / in a park') and explicitly claims to be the 'ONLY tool' for generating another picture of a previously created character, clearly distinguishing it from siblings like generate_image and generate_character_image.

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

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

The description gives explicit when-to-use guidance ('This is the tool for...') and tells the agent exactly why not to use entity_id/character_slot_index, including a hard failure mode ('HTTP 500'). It also explains the two mutually exclusive input paths (character vs photo_media_id) and when to choose each, leaving little to inference.

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

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

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

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

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

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

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

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

Although there is no output schema, the description fully documents the return object, field names, ordering, source semantics, and the null-reference caveat. With zero parameters and read-only annotations, nothing essential is missing for an agent to call this tool correctly.

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

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

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

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

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

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

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

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

The description clearly communicates when to use this tool: when you need to see your existing characters or find a reference for generate_with_face. It also states read-only behavior and that no credits are spent, but it does not explicitly list alternative tools to choose instead under certain conditions.

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

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

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

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

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

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

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

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

With no output schema and no parameters, the description fully carries the burden of documenting return values — and it does so exhaustively: the images/videos/defaults sections, the t2v/i2v/r2v mode enum, null behavior, and the scope boundary versus the underlying HTTP layer. Nothing an agent needs to invoke it correctly or interpret its output is missing.

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

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

The tool has zero parameters and the schema reflects that at 100% coverage, so the baseline 4 applies with no deduction. The description adds cross-tool parameter value by mapping its output keys to sibling parameters: `model` values for generate_image/generate_character_image and `video_model_key` values consumed via the generate_* tools' Literal types.

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

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

States a specific verb and resource up front: 'List every valid model id this service accepts,' followed immediately by the safety profile (READ-ONLY, spends no credits, calls nothing outside this service). It distinguishes itself from sibling generation tools by naming generate_image/generate_video directly, so an agent can tell them apart without opening any other schema.

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

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

Gives explicit when-to-use guidance: 'Call this BEFORE generate_image/generate_video if you're unsure of an exact id,' and reinforces it with the concrete failure cost of guessing (a hard HTTP 400 on a call that already committed to a task). It also names the alternative tools that this one is meant to precede, leaving nothing to inference.

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

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

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

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

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

Every sentence earns its place. The core purpose is front-loaded, usage examples are compact but illustrative, and return-value semantics are structured clearly. Despite length, nothing is redundant or marketing-flavored.

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

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

For a stateful conversational tool with no output schema, the description is remarkably complete: it covers invocation, conversation continuity, asynchronous job behavior, return shape, and how to handle audio results. An agent has everything needed to call it correctly and interpret results.

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

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

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

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

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

States a specific verb and resource: 'Talk to the Google Flow Music Producer agent instead of one-shotting a track.' It clearly distinguishes its conversational scope from the one-shot generation path and names the sibling tool it is not, making selection unambiguous.

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

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

Provides explicit when-to-use guidance with concrete examples ('asking what it can do', 'having it write lyrics first', 'editing a track it already made') and explicitly identifies the alternative ('For a plain "make me a song about X", music_generate is the shorter path'). It also explains when to pass conversation_id versus omit it.

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

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

Annotations already establish that the tool is read-only, idempotent, and non-destructive. The description adds useful specificity about the scoped resource ('flowmusic credits') and what is reported (remaining balance and subscription tier), which goes beyond the annotations without contradicting them.

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

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

A single clear sentence with no filler. The core action and object are front-loaded, and every word contributes useful information.

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

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

For a parameterless read-only check, the description supplies the essential context: what resource is being queried and the two pieces of information returned. It doesn't describe exact output formatting or field names, but the low complexity and strong annotations make that a minor gap.

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

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

The tool has zero parameters and the schema covers everything about parameters; no parameter documentation is needed. The description adds no param-specific detail, but with no parameters there is nothing additional an agent could need, so the baseline of 4 applies.

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

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

The description uses a specific verb ('Check') and defines the exact resource ('remaining flowmusic credits') plus the second datum returned ('subscription tier'). It is immediately clear what this tool does and materially distinguishes it from generic siblings like check_credits.

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

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

The description clearly implies the use case: call when you need credit balance and tier information. However, it provides no explicit guidance on when to choose this over sibling tools such as check_credits, flow_dashboard, or flow_status, nor does it state any exclusions.

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

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

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

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

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

The description is a single, front-loaded sentence with no filler. Every word contributes to identifying the action, resource, format, and destination.

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

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

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

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

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

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

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

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

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

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

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

The description implies the tool is for obtaining a raw .m4a file onto the server, but it does not explicitly state when to prefer this over alternatives such as music_get or music_stems. No exclusions or when-not-to-use guidance is provided.

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

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

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

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

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

The description is dense but every sentence carries operational value, from the prompt brief to the output schema to the conversation_id follow-up. It is front-loaded with the core purpose and organized by parameter and result-handling concerns, with no filler.

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

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

The tool is complex: 4 parameters, no output schema, async behavior, and a large sibling set. The description provides the output JSON shape, field semantics, auth details, download guidance, and follow-up mechanism, making it complete for an agent to invoke and process the result correctly.

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

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

Schema description coverage is 0%, so the description fully compensates by explaining every parameter: prompt with an illustrative example, model with enum values and legacy status, lyrics with omission semantics, and conversation_id with follow-up behavior. It adds practical meaning that the raw input schema does not convey.

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

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

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

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

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

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

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

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

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

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

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

A single, front-loaded sentence contains the core purpose with no filler or redundant restatement of the tool name. Every word earns its place.

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

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

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

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

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

Schema description coverage is 0%, so the description must compensate for the undocumented clip_id parameter. 'Get metadata for a single music track' weakly implies clip_id identifies the track, but it does not clarify how to obtain the clip_id, its format, or that it likely comes from music_list or music_generate.

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

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

The description uses a specific verb and resource: 'Get metadata' for 'a single music track.' It clearly differentiates from siblings like music_list (lists tracks) and music_download (retrieves audio) by scoping to metadata retrieval for one item.

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

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

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

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is established. The description adds the 'user's music tracks' scope but says nothing about ordering, pagination, or how the limit parameter affects results, leaving behavior partially undisclosed.

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

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

The description is a single, front-loaded sentence with no wasted words. It is appropriately short for a simple list operation, though it is so terse that it omits useful usage and behavior context.

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

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

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

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

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

Schema description coverage is 0%, and the description does not mention the 'limit' parameter at all. With no parameter explanation in either the schema or description, the agent receives no help understanding how limit behaves beyond its default value of 20.

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

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

The description uses a specific verb, 'List', and a clear resource, "the user's music tracks." It conveys the basic operation without vagueness, though it does not explicitly contrast itself with sibling tools like music_get or music_download.

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

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

There is no explicit guidance on when to use this tool versus music_get, music_generate, or music_download. The phrase 'user's music tracks' implies enumerating existing tracks, but the description does not state exclusions, prerequisites, or alternative conditions.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Provides clear contextual guidance: the input must come from a previously generated track, and the operation is tied to the same account. It does not enumerate explicit exclusions or alternatives, but the usage context is strong enough for an agent to know when to invoke it.

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

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

Annotations already signal the operation is a write (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds value beyond annotations by explaining the consequence of not updating the character and emphasizing account ownership, which helps agents understand scope and authorization. No contradiction with annotations.

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

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

Two sentences deliver the core action, the consequence of neglect, and a critical prerequisite with no filler. The most important information is front-loaded and every clause earns its place.

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

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

For a simple update tool with annotations present and no output schema, the description covers purpose, ownership prerequisite, and why the tool matters. It omits an explicit return-value note, but that is a minor gap given the simplicity of the operation.

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

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

Schema description coverage is 0%, so the description must compensate. It explicitly names display_name and personality_notes and clarifies the account requirement, but it does not explain entity_id or how the parameters interact beyond 'and/or'. This is partial but adequate compensation.

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

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

The description states a specific action ('Save a character's display name and/or personality notes') with a clear resource, making it obvious this is an update operation on a character. It does not explicitly name sibling tools like create_character for differentiation, 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 gives useful context about when this is needed ('Without this, a character stays 'Untitled Character'...') and specifies a prerequisite ('account must be whichever farm account's project owns this entity_id'). It does not explicitly compare against create_character or other siblings, so it earns a 4 rather than a 5.

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

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

Beyond the annotations, the description discloses that the tool drives a real browser, takes ~15-30s, returns a job_id to poll with check_job after ~35s, and produces clean errors for unsupported or plan-limited cases. It also states the return shape, which is essential since there is no output schema. Nothing contradicts the annotations.

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

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

The information is front-loaded and each paragraph addresses a distinct operational concern: purpose, account semantics, resolution constraints, timing, and return format. Some UI-context detail like the "Download panel" and "1K/2K/4K picker" could be trimmed, so it is not maximally concise.

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 the lack of an output schema and no parameter descriptions, the description covers input semantics, expected output fields, polling behavior, error handling, and account prerequisites. No material detail an agent needs to invoke the tool correctly is missing.

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

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

Schema property descriptions are absent (0% coverage), but the description fully compensates by explaining account ownership, the source of media_id, and the target_resolution enum with its failure modes. An agent can correctly populate every parameter using only this description plus the schema's required/default flags.

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

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

The description opens with a specific verb and object: "Upscale an existing generated image... to a higher resolution", explicitly scoped to output from a prior generate_image call. This clearly distinguishes it from sibling tools like upscale_video or fetch_media without opening the schema.

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

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

It provides strong contextual guidance: the account must own the media_id, media_id comes from generate_image, and unsupported 4K cases should be reported rather than retried. However, it does not explicitly contrast alternatives (e.g., upscale_video) or give a when-not-to-use statement, so it falls just short of a 5.

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

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

The description adds substantial behavioral context beyond annotations: it drives a real browser, is slower than generation, returns a job_id for polling, and returns a clean error for 4K plan locks. It also discloses the return payload, which is valuable since no output schema exists. No contradiction with annotations.

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

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

The description is organized into clear thematic paragraphs: purpose, account semantics, resolution options, performance/polling behavior, and return value. Every sentence adds necessary operational detail without redundant filler.

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

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

Given the tool's complexity, lack of output schema, and 0% schema coverage, the description is remarkably complete. It covers what, from where, with which account, resolution choices, failure mode, latency behavior, polling approach, and the full return shape. Nothing critical is missing.

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

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

Schema description coverage is 0%, so the description must carry the parameter meaning. It fully explains media_id (prior generated video scoped to an account), account (must match the farm account owning the media), and target_resolution ('1080p' or '4K', with the caveat about paid plan locking). Every parameter is meaningfully documented.

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

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

The description opens with a specific verb-resource pair: upscaling an existing generated video to a higher resolution. It clearly scopes the input to prior generate_video output and distinguishes this from image upscaling and other generation tools.

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

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

It gives explicit prerequisites: reuse the farm account whose project owns media_id. It also tells the agent how to handle a 4K plan-lock error, and directs polling check_job when the job exceeds ~40s. This is actionable usage guidance with error-handling behavior.

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