openFlow

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

Annotations only cover safety hints (readOnly=false, idempotent=false, openWorld=true), and the description adds substantial behavior beyond them: the token is SINGLE-USE and must never be retried, the account binds to the key's owner group and is picked up by a worker within ~30s without restart, adding is always permitted even after free quota is spent, and a master token grants full account access. It also documents failure and edge paths ('need_email', 'submitted':true).

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?

Purpose is front-loaded and the PREFERRED/FALLBACK headings give useful structure, but at ~350 words this is far longer than needed — it embeds runbook content such as OS-specific curl/irm commands and a literal success string for a separate script, which does not help an agent select or invoke this specific tool.

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, non-idempotent, 0%-schema-coverage tool with no output schema, the description is thorough: it explains the return JSON line, the 'submitted' flag, the 'need_email' branch, propagation timing, and permissions. The only real gap is the undocumented reset_day parameter.

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 coverage the description must carry the burden, and it explains email (the Google address just signed into, with a recovery path if it cannot be read) and oauth_token (single-use, obtained from the local script) in rich detail. However reset_day is never mentioned anywhere in the description, leaving one of three parameters fully undocumented.

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 states a specific verb+resource: 'Attach one of YOUR OWN Google accounts to the pool using an oauth_token'. It further scopes it as 'the self-serve onboarding path — no server-side browser, no SSH', which cleanly separates it from all generation/list siblings and from the flow_status workflow it references.

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

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

Explicit when-to-use and when-not: the PREFERRED PATH is to call flow_status and run its command yourself and NOT call this tool afterwards; this tool is the FALLBACK only if flow_status has no command or the script fails to submit. The distinction between the two paths and the preconditions ('Node 22+', 'no ticket') is fully spelled out.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds valuable context beyond annotations by warning that the tool returns only the project list and not real credit numbers, preventing a likely misinterpretation based on the tool name.

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 filler; the core purpose comes first trailing by a clear caveat. Every word contributes, and the note about flow_dashboard is essential and tightly worded.

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: one optional parameter, no output schema, and read-only/idempotent annotations. The description fully covers its limited scope—what it does, how to scope it, and why it might be confused with a sibling—so 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?

Schema coverage is 0%, so the description must clarify the account parameter. The phrase 'for a Google account (or all)' conveys that the optional account parameter selects a specific account or includes all projects, adding meaning beyond the raw schema. It could more explicitly link 'account' to the parameter name, but the intent is clear.

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 identifies the operation: checking/list projects for a Google account or all accounts. It also distinguishes itself from flow_dashboard by explicitly stating that this tool only returns the project list, not credit balances.

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 names flow_dashboard() as the preferred alternative when credit balances or an at-a-glance overview are needed. This gives the agent a clear selection rule: use check_credits for project lists, not for credit numbers.

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 discloses key behavioral traits beyond the annotations: the portrait slot is written exactly once and cannot be regenerated, calling again with the same name fails fast with a clear message rather than a raw HTTP 500, and the return includes a hint for future use. These details add significant context that the annotations alone do not provide.

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 well-structured, with the core purpose front-loaded, followed by parameter guidance, behavioral notes, and return/next-step info. It is moderately verbose but each sentence carries useful information, so it earns a high conciseness score without being overly terse.

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 complexity (7 params, no output schema), the description covers the essential aspects: purpose, key parameter semantics, one-time behavior, failure mode, return values, and the correct next step. It misses some parameter details and does not explain the 'hint' field, but it is sufficiently complete for an agent 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, the description must compensate by explaining parameters. It thoroughly explains the three required ones (name, description, account), but omits explanations for model, aspect, display_name, and portrait_prompt, which have no schema descriptions. The enums for model and aspect are given but their roles are not 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 clearly states the tool's purpose: invent a character from a text description and generate its portrait in one call, explicitly contrasting with the alternative of gluing together create_character + update_character + generate_character_image. It uses a specific verb and resource and distinguishes itself from the photo-based 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 tells when to use this tool (the 'no photo involved' path) and explicitly names the alternative multi-call approach, as well as directing future image generation to generate_with_face. It does not explicitly mention create_character_from_photo, but the phrase 'no photo involved' implies that exclusion.

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?

Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false), the description discloses substantial behavioral nuance: results are usable immediately, the project may not appear in the web UI (registered: false), account rotation for generation continues, and media_ids remain account-bound. These details are essential for correct agent behavior and are not present in the annotations or schema.

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 serves a purpose: purpose, usage guidance, parameter semantics, and edge-case behavior. It is well-organized with clear paragraphs and no repetition or filler. The length is justified by the tool's nuanced behavior, and the most important usage context is 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?

For a tool with no output schema, the description states the exact return format ({"project_id", "account", "registered"}), while also covering prerequisites, immediate usability, and the UI registration caveat. It is complete enough for an agent to know when to call it, how to call it, and what to expect back.

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

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

Schema description coverage is 0%, so the description must carry the full semantic load. It explains account in depth: which Google account creates it, that project_id is a label accepted by all accounts, and that media_ids are still account-bound. It also explains name as an optional human-readable title, e.g., the client's name. This fully compensates for the schema's lack of descriptions.

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

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

The description opens with a specific verb and resource: 'Create a NEW Flow project on one of your Google accounts and return its project_id.' It clearly distinguishes this from generation and account-management siblings by tying it to per-client namespaces and explicitly referencing when to use it with generate_image/generate_video.

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

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

The description explicitly says when to use it: 'Use this to give every one of YOUR OWN clients their own namespace: create a project per client once, then pass that project_id to generate_image / generate_video.' It also points to sibling tools for account emails (flow_dashboard / check_credits) and explains the operational distinction between account-bound media_ids and project_id grouping.

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 cover mutation and non-idempotency; the description adds meaningful context beyond them: 20-credit cost, account/project pinning, whole-clip behavior, and free-form prompt style. It could be slightly clearer that abra_edit_360p also exists despite the 'only model' wording, but this is not an annotation contradiction.

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 not bloated; examples, constraints, and cost are front-loaded and every clause carries information. The centered block of examples is slightly heavier than needed but still useful.

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, it covers prerequisites, ownership, cost, prompt style, and scope. It does omit the return/job-checking behavior, but that is a modest gap given the detailed usage guidance and existing check_job sibling.

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 the most important parameters: media_id's provenance/ownership and prompt intent with concrete examples. It does not explicitly describe aspect or include_preview, though their names, defaults, and enums make them largely self-explanatory.

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 ('Rewrite a video this service already generated') and immediately distinguishes this from generation tools by requiring a previous generate_video* result. The 'not a mask tool' line plus whole-clip scope removes ambiguity with any region-editing interpretation.

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

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

Gives a clear precondition: media_id must come from a previous generate_video* result and can only be one of the service's own videos. It also states a when-not case ('not a mask tool'), though it does not name a specific sibling tool as the alternative for new-video generation.

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 media_id must be a bare id from a previous generate_video* result, that the job is pinned to a specific Google account's project, and that unknown ids produce a clear error rather than a mysterious failure. It also adds cost/credit details, the default model, and the 8-second extension 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 well-structured and front-loaded: purpose first, then the most critical constraint (media_id), then usage guidance, then pricing/default model, then project_id. Every sentence adds necessary context; 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?

For a complex 6-parameter tool with no output schema, the description covers the subtle and non-obvious areas agents would most likely get wrong: bare media_id format, account pinning, invalid id behavior, and optional project_id semantics. The remaining parameters (aspect, include_preview) are self-explanatory or adequately covered by schema 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?

The input schema has zero property descriptions, so the description carries the full burden here. It thoroughly explains media_id and project_id, including subtle behaviors like account pinning and error handling, and names the default video_model_key with credits. However, prompt, aspect, and include_preview receive no dedicated explanation, leaving some minor gaps in an otherwise strong effort.

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

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

The description opens with a specific verb and resource: 'Continue a video this service already generated.' This clearly distinguishes it from siblings like generate_video and edit_video by focusing on extending an existing output rather than creating or modifying from scratch.

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 the tool: 'Use for shots that need to run longer than one generation, or to keep a scene going without re-describing it.' It also contrasts with the alternative, a fresh text-to-video call, explaining why this tool is the right choice when continuation should inherit the source clip's world.

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 indicate readOnly/idempotent behavior; the description adds genuinely useful context by disclosing that credit balances are live via Flow's /v1/credits and that the refresh date is only an estimate because the upstream API does not expose a hard date. This is information an agent could not infer from the schema or 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 main output, then gives the use case, then the data caveat; each sentence earns its place. There is minor stylistic repetition of the dashboard/control-panel metaphor, but no substantive bloat.

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

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

With no parameters and no output schema, the description still tells the agent what will come back (`summary`, `accounts`, `totals`) and enumerates the account-level fields. It also flags the one caveat (estimated refresh date), so nothing needed to call and interpret the result 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, so there is nothing for the description to add. Per the baseline for no-parameter tools, this is fully adequate.

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

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

The description names a concrete verb ('returns') and a clear resource: an account-pool dashboard covering per-account credit balance, tier, project count, health, plus totals. It positions itself as the operator's dashboard scoped to 'EVERY Google account,' which implies differentiation from narrower siblings like check_credits, but it never names an alternative explicitly.

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

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

It gives explicit when-to-use guidance: 'Use this to answer "how many accounts, how many credits on each and in total, what projects"' and highlights that it is a single call. It does not state when not to use it or which sibling to prefer instead, so it stops short of full routing 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 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?

Annotations already declare readOnlyHint and idempotentHint, and the description reinforces this with 'READ-ONLY, spends nothing,' adding the useful credit-consumption angle. It goes further than annotations by describing the next_step contract, the personal per-OS command that self-submits a token, and the support-only Telegram channel, though some of this overlaps with return-value detail.

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

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

Front-loaded with purpose and safety in the first line, and the later sentences carry genuine behavioral guidance rather than filler. It is nonetheless multi-paragraph and heavy on ALL-CAPS emphasis for a zero-parameter status call, so it is slightly more verbose than strictly necessary.

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

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

With no output schema, the description carries the burden of explaining returns and does so thoroughly, naming next_step, text/text_en/url, command, weekly, and support. An agent has everything needed to call it and act on 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?

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to clarify about inputs. The referenced add_account_token is a sibling tool, not a parameter, so it does not affect this dimension.

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 capability: it reports what the key still needs before it can generate, listing the concrete checks (Google account connected, trial remaining, GitHub link, weekly limit). A specific verb+resource is present, but the description never contrasts itself with close siblings such as flow_health, flow_dashboard, or check_credits, so the agent must infer the distinction.

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 triggers — call before the first generation, when a call is refused, or when the user asks why something fails. It also names add_account_token as the fallback alternative, but does not state when this tool should NOT be used versus other status tools.

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 explicitly states 'this overwrites the existing portrait image with the expression sheet', which is a destructive action on the existing image. This directly contradicts the annotation destructiveHint: false. The contradiction is severe and undermines the agent's ability to assess risk, warranting a score of 1. Other behavioral details (pure HTTP, unverified consistency) are provided but overshadowed by the contradiction.

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 but then launches into a lengthy historical narrative with specific dates (2026-07-11, 2026-07-26) and technical details that are not directly relevant to invoking the tool. This reduces conciseness and may distract the agent from the essential operational details. The structure could be improved by moving historical context to a separate section or removing 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?

The description covers most operational aspects (how to specify expressions, which slot to write) but misses the entity_id parameter entirely, which is required. It also includes extraneous historical context that does not aid invocation. The description is not fully complete for an agent to call it correctly without guessing what entity_id refers to, and it lacks any mention of the output format, though no output schema exists. Overall, it is adequate but has clear gaps.

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 must explain all parameters. It explains account (Google account that owns the project), expressions (list with default and recommended count), and character_slot_index (which slot, default 0, overwrites). However, it fails to explain the required parameter entity_id, leaving it undefined. This is a significant gap for a required parameter, so the description only partially compensates for the schema's lack of descriptions.

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 the tool generates a single image of the character's face with multiple labeled expressions in a row, explicitly naming it an 'expression sheet'. It also distinguishes itself from the sibling generate_character_turnaround by noting same job type but different output, making the purpose 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 provides context on when to use this tool by referencing generate_character_turnaround and explaining the historical reason for its existence. It also offers usage guidance on the expressions parameter (keep to 3-5) and character_slot_index (0 overwrites portrait). However, it does not explicitly state when not to use this tool or compare it to other sibling image generation tools, leaving some 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 only declare readOnly=false/idempotent=false/destructive=false/openWorld=true; the description goes far beyond by disclosing the one-shot-per-slot write semantics (second call 500s and does not overwrite), the personality_notes precondition, and the identity-drift failure mode for real-photo entities. These are exactly the operational traits annotations cannot convey.

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

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

Purpose is front-loaded and every paragraph carries a distinct, actionable caveat rather than filler. It is nonetheless long and dense, with dated provenance tags ('confirmed live 2026-07-25') that add ceremony more than decision-relevant signal.

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 and high failure complexity, the description covers ownership scoping, write-once semantics, prerequisites, and the correct alternative tools. Nothing an agent needs to invoke this safely and 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?

With 0% schema description coverage the description must carry the load. It defines the two genuinely ambiguous parameters well (entity_id provenance, character_slot_index = 0 portrait / 1 body) plus account scoping, but says nothing about prompt content, model choice, or aspect beyond what the enums self-describe.

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: 'Generate a portrait or body image for an existing Flow character.' It explicitly distinguishes itself from the two nearest siblings (generate_with_face and create_character_from_description) within the text, so an agent can route correctly without opening any schema.

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

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

Gives explicit when/when-not and named alternatives: use generate_with_face for 'character doing X', use generate_video_with_reference for real-photo identity content, and do not re-call for slot 0 after create_character_from_description. It also states the sequencing prerequisite (update_character with personality_notes before the first write).

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 annotations, the description discloses the exact mechanism (pure HTTP, image_inputs using the character's portrait_media_id), that it uses a third mechanism rather than either compared path, that it has not been re-verified live, and what the recommendation does and does not prove. This is unusually candid about limitations.

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 the length is earned: the history, mechanism change, and reliability caveat are essential for correct use. It is organized into clear sections and front-loads the core purpose before the detailed backstory, though it could be trimmed 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?

The description covers purpose, mechanism, reliability status, prerequisites, slot behavior, and account ownership. It does not describe the output format or how to retrieve the image, and it leaves some parameter definitions to inference, so it is not fully complete, but it is strong given the tool's complexity.

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

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

With 0% schema description coverage, the description helps by defining account and character_slot_index with explicit semantics and defaults. However, it does not explain entity_id beyond 'entity_id's project' and completely omits outfit_description, leaving two parameters under-specified.

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 single image showing the character's FULL BODY from 3 angles (front/side/back) in one row, labeled — a turnaround sheet.' It also explicitly distinguishes this path from plain generate_character_image, making the tool's unique role clear.

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 explains when this tool exists: plain Android-bearer generation was inconsistent for multi-view prompts, while a browser-composer path was consistent. It also gives a prerequisite recommendation (save a detailed physical description first) and warns that the new mechanism's multi-view reliability is unverified, which is critical usage 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?

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 convey mutation, idempotence, and non-destructiveness. The description adds useful behavioral context: without this call the character stays 'Untitled Character' and account must be the owning project, an access requirement not present in annotations. It doesn't explain overwrite/clearing behavior for nullable fields, but the main side effects are disclosed.

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

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

Three sentences: the action, why it matters, and the account prerequisite. Each sentence adds distinct, necessary information and the main operation is 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?

For a simple update with only two required parameters and idempotent/non-destructive annotations, this is nearly complete: an agent can construct a correct call with entity_id, owning account, and one or both fields. It lacks explicit 'at least one optional field' guidance, but the overall context is sufficient.

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 directly maps display_name and personality_notes, and explains that account must own the entity_id. All parameters get some semantic meaning, though it doesn't explain null semantics for clearing existing 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?

Description opens with a specific verb and resource: 'Save a character's display name and/or personality notes.' It further clarifies the purpose by describing the default 'Untitled Character' state and tying the action to an existing entity_id, which distinguishes it from the create_* sibling 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 a clear trigger context: use this when you need to set a character's name or personality notes, especially after portrait/body images already exist. It also specifies the account ownership prerequisite. It does not explicitly name create_character as the alternative for new characters, so it stops short of full exclusion 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?

Goes well beyond the minimal annotations: discloses 15-30s async behavior, the job_id polling mechanism, clean-failure cases for unsupported images or paid-tier locks, and the exact success response shape. This is exactly the behavioral context an agent needs and none of it 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?

Every sentence carries operational value. The purpose is front-loaded, parameters are clearly labeled, and the async/error/output details are organized without redundancy. It is long, but the length is justified by the tool's complexity.

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

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

Covers precondition, selection, behavior, failure modes, timing, polling, and return structure despite lacking an output schema. An agent has everything needed to invoke this tool correctly and handle its 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 coverage is 0%, but the description fully compensates: account is detailed with source and constraints, target_resolution is enumerated with caveats, and media_id is contextually defined as a prior generation result. This is more informative than the schema alone.

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 ('Upscale') and resource ('existing generated image from a prior generate_image call'), and clarifies the resolution options. It clearly differentiates from siblings like upscale_video by restricting to generated images.

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 context ('from a prior generate_image call'), warns against guessing or asking the user about account, identifies the account_used field as the correct source, and instructs to report clean errors rather than retry. It also names check_job as the polling alternative for the async case.

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

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

Annotations only indicate non-readonly, non-destructive, non-idempotent behavior; the description adds essential details: it consumes the weekly free video limit, spends account credits, may be slower than generation, returns a job_id for polling, and reports 4K plan locks as clean errors. This fully compensates for the sparse 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?

Longer than average, but every block earns its place: purpose, usage constraints, per-parameter guidance, async behavior, and return shape are all addressed. The opening sentence says exactly what the tool does, and the parameter paragraphs are logically organized.

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 and zero schema coverage, this description is fully sufficient: required inputs, parameter semantics, error behavior, polling path, quota impact, and expected response structure are all covered. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 0%, but the description compensates exceptionally well. It explains account must come verbatim from account_used, why using another account errors, gives the exact allowed resolutions for target_resolution, notes the default and paid-tier caveat, and makes media_id's origin clear via the 'from a prior generate_video call' context.

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: 'Upscale an existing generated video' from a prior generate_video call to a higher resolution. It clearly distinguishes this from sibling operations like edit_video and extend_video by anchoring it to the output of generate_video and the download resolution options.

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 context: this is for a video produced by generate_video, uses the account from the prior result, and should be polled via check_job if it takes longer than ~40s. It does not explicitly name alternatives like upscale_image, but the lineage requirement makes the intended usage unambiguous.

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