Veltake Studio

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

With readOnlyHint=false already given, the description adds the crucial behavioral fact that this SPENDS the user's coins at expected_cost ('the number on the button the person pressed'). This is real context beyond the annotations. It does not describe return format or retry/idempotency behavior, which the schema covers instead.

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

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

Two tight sentences with zero waste; the scope constraint and the coin-spending warning are front-loaded where the agent will see them first.

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 an output schema exists and 100% parameter coverage, the description only needs to carry routing and cost guidance, which it does. The kind-specific argument semantics live in the schema, so nothing critical is missing, though a note on the estimate_generation prerequisite chain would strengthen it.

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 100%, so every parameter is already documented; baseline is 3. The description only echoes expected_cost ('the number on the button'), adding no syntax or semantics beyond what the schema provides.

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

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

The description states a specific verb (generate) and the scope (the Veltake app's own screens/composer), and explicitly distinguishes itself from the conversation path by saying 'not for a conversation'. It does not restate the resource being generated (image/video/speech/music), relying on the schema for that, so it falls short of a perfect 5.

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

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

It gives an explicit when-not-to-use: 'for the Veltake app's own screens only — not for a conversation', effectively routing the agent away from the conversation-oriented sibling. It does not name that sibling explicitly, so the alternative is implied rather than 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=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds a scope clarification but no additional behavioral context (no auth needs, no rate limits), and the output schema carries return values, so the added value is modest.

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 tightly worded sentences with the scope exclusion front-loaded, no filler. The phrasing 'Answers the home' is a touch informal but the structure is efficient.

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

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

For a zero-param, read-only tool with full annotation coverage and an output schema documenting return values, the description supplies enough to call it correctly. The only gap is that 'home' contents are listed rather than elaborated, which the output schema compensates for.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description adds no spurious parameter claims.

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 resource and spells out the data it returns (balance, recent work, workflows), and explicitly carves out chat as a non-use case, which differentiates it from chat siblings like get_chat/start_chat. The verb 'answers' is slightly loose, so it stops short of the clearest possible phrasing.

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 negative condition ('not for a conversation') that helps scope usage, but no positive when-to-use trigger and no named alternative among the many app_* siblings is offered. Scope is implied rather than fully guided.

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=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful scope context (app screens vs. conversation) but nothing about side effects, where the imported file lands, auth/permission needs, or any failure mode for an open-world write operation.

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

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

Two short sentences with the scope constraint front-loaded and no filler. The phrasing is fragmentary ('import_media for a file the person picked in the app') rather than a complete clause, which costs a point on structure but not on economy.

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

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

An output schema exists so return values need no explanation, and the single required parameter is fully documented in the schema. Still, for a non-read-only, open-world import operation the description omits what 'import' does to the target app screen and any success/failure behavior, leaving the agent with only the negative scoping rule.

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 100% and the nested file object documents file_id, file_name, mime_type and download_url individually, so the schema carries the burden. The description adds no parameter-level meaning beyond that, making the baseline 3 correct.

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 scopes the tool precisely ('For the Veltake app's own screens only') and explicitly separates it from conversation-context imports and from the sibling import_media. However, it never actually states the action — the verb 'import' and the resource 'attached file' live only in the name/title, so the description alone reads as a constraint rather than a purpose statement.

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 an explicit negative rule ('not for a conversation') and names the alternative to use instead ('import_media for a file the person picked in the app'), which is real routing guidance. The alternative clause is telegraphic and slightly ambiguous about which tool handles person-picked files, so it falls short of a fully unambiguous when/when-not pair.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only that results carry posters for grid rendering — useful, but thin context beyond the structured fields, and it says nothing about ordering or pagination behavior despite an offset parameter.

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

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

Two short sentences, no filler, with the scoping constraint front-loaded. The second sentence is compressed to the point of jargon ('list_generations with posters for the grid'), which costs a little clarity but not length.

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

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

A read-only, non-open-world list tool with an output schema, so return-value explanation is unnecessary and annotations cover safety. The description supplies the audience/context distinction that structured fields can't express; only result ordering is left unaddressed.

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

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

Schema coverage is 100% with inline descriptions for kind, limit, since and offset, so the schema carries parameter meaning. The description adds no syntax, defaults, or format detail beyond what the schema already states (defaults and caps are in the schema). Baseline 3 is appropriate.

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

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

The description identifies the resource (generations, rendered as a poster grid) and distinguishes it from both list_generations (this one includes posters) and conversation-scoped tools. The verb is only implied via the sibling name 'list_generations', and the phrasing is telegraphic, but an agent can tell what it returns and where it belongs.

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 exclusion: 'For the Veltake app's own screens only — not for a conversation.' That is a clear when/when-not split. It stops short of naming the conversation-side alternative (e.g. get_chat/list_generations in a chat context), so it's not a full routing statement.

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

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

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true) by disclosing the monetary cost ('this SPENDS coins'), the quote-locking mechanism via expected_total, and that results are reviewed only after the run finishes. These are exactly the behavioral traits an agent needs before invoking a spend-capable mutation.

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

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

Four tight sentences, no filler, and the cost warning plus quote-locking instruction are front-loaded right after the core action. Every sentence contributes distinct information an agent must act on.

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

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

For a mutation tool with no output schema, it covers the cost model, the safeguard, and the alternate cut_only path, and notes results surface after the run completes. It does not address reversibility even though a sibling undo_turn exists, which is a minor 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?

With only 40% schema description coverage, the description carries real weight: it explains run:true semantics, that expected_total should equal the turn's estimate.total_coins, and what cut_only does. turn_id and funding rely on the schema, leaving one gap, but the added meaning is substantial.

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 ('Apply a turn's proposed canvas') and clarifies that the action splits into three distinct behaviors: the base apply, the optional run start, and the separate cut_only path. This lets an agent distinguish it from siblings like start_run, interject_turn, and undo_turn without opening schemas.

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

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

Gives clear conditional guidance: use run:true to start the run, cut_only:true for a cut_proposal held for review, and always pass expected_total when spending. It lacks explicit routing against named alternatives such as estimate_run or start_run, so it stops short of full when-not 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds the scope constraint (app screens, not conversations) and notes the enriched picker payload (logo, badge, summary, default). It gives no pagination, ordering, or auth context, so this is a modest value-add.

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

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

Two tight sentences, with the scoping constraint front-loaded before the functional description. No sentence is wasted.

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

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

An output schema exists, so return values need not be explained, and the description still hints at the payload shape. Adequate for a single-enum read tool; only minor gaps remain around ordering or which models are included.

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

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

Only one parameter, and schema coverage is 100% with the enum values already documented in the schema. The description says 'for one kind' but adds no format or semantics beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb+resource (answers list_models for one kind) and immediately names the sibling it differs from, plus the scope ('the Veltake app's own screens only'). An agent can distinguish this from list_models without opening either 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 a clear when-to-use boundary ('for the Veltake app's own screens only') and an explicit when-not ('not for a conversation'), and implicitly routes conversational model listing to list_models by contrasting the two. It stops short of explicitly naming list_models as the alternative for non-app contexts.

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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds only a UI-scope note and discloses nothing else behavioral — not that this is a pure cost computation with no side effects, whether it consumes credits, or any auth/rate constraint.

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

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

It is very short and the scope constraint is front-loaded, so there is no wasted text. The problem is under-specification rather than verbosity — the second sentence is a fragment with no verb, which reads as truncated output rather than a deliberate concise statement.

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 18-parameter, four-modality pricing tool the description is far too thin: it never says it produces a cost estimate, never mentions that the required model id must come from list_models, and never explains how it relates to app_generate or estimate_run. An output schema exists so return values need no explanation, but the input-side and selection context are 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 100% and the schema itself is unusually rich, explaining per-kind applicability for all 18 parameters. The description adds no parameter-level meaning whatsoever, so the baseline 3 applies.

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

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

The description contains no verb stating what the tool does ("quote"/"estimate a price"); the purpose is only recoverable from the title "Price the composer (app)". It does supply a genuine scope boundary ("the Veltake app's own screens only — not for a conversation"), which distinguishes it from the conversation-oriented siblings, but the core action is left implicit.

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 names a sibling, estimate_generation, and draws a context line between app screens and conversations, which is real routing information. However, the phrasing "estimate_generation for the composer's settings" has no verb and is ambiguous about whether it is a recommendation, a contrast, or an unrelated note, so the agent cannot be certain which tool to pick.

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 destructiveHint=false, so the safety profile is covered. The description still adds domain-meaningful context: this answers the 'did the credit land?' question after an unconfirmed create, and explicitly reassures 'Never spends, never retries' — valuable in a credits context. It does not describe latency or behavior when the key is unknown.

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 compact sentences with the scope exclusion front-loaded before the core question and the read-only guarantee. No filler; every clause carries information.

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

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

With rich annotations and an output schema, the description does not need to explain return values, and it covers scope, semantics, and safety. The only gap is routing advice — what to do when the key is unknown or when the check is being made from a conversational context.

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 100% and the enum for 'tool' is fully documented, so the schema carries the parameter semantics. The description ties the two parameters to the 'unconfirmed spend' scenario, but adds no format, casing, or key-lifetime detail beyond what the schema states.

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 precise operation (checking whether an unconfirmed app_generate/app_upscale spend actually created a generation) on a precise resource (the idempotency_key). It immediately distinguishes itself from the app_generate/app_upscale siblings, which create the spend rather than report on it.

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 an explicit scope restriction and exclusion: 'For the Veltake app's own screens only — not for a conversation.' That tells the agent both where this belongs and where it does not. However, it never names the alternative an agent should reach for when checking generation status outside the app UI (e.g., get_generation or list_generations) or for confirmed spends.

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=false and destructiveHint=false, and the description adds the critical fact annotations cannot convey: this SPENDS the user's coins at expected_cost, and expected_cost is 'the number on the button the person pressed.' That cost/spend disclosure is exactly the behavioral context an agent needs before invoking. It stops short of covering funding rules or retry semantics, which only appear in the 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?

Two short sentences, with the exclusion ('not for a conversation') and the cost warning front-loaded. The 'upscale from the app:' fragment is mild filler but the rest 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?

An output schema exists, so return values need no explanation, and annotations carry the safety profile. The description supplies the two things structured fields cannot: the app-vs-conversation scoping and the coin-spend consequence. The estimate_upscale prerequisite is only implied via the schema, not the description, which is the one remaining 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?

Schema description coverage is 100%, so every parameter is already documented, making 3 the baseline. The description adds a small gloss on expected_cost ('the number on the button') that slightly re-frames the schema's 'coins estimate_upscale answered,' but it contributes no new semantics for kind, model, funding, or idempotency_key.

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

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

States a specific verb (upscale) plus the scope that matters most: 'For the Veltake app's own screens only — not for a conversation.' That negative scope is what separates it from the sibling `upscale`. The opening fragment 'upscale from the app:' redundantly restates the name, but the intent is 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?

Gives a clear selection condition — use only for the app's own screens, not a conversation — which implicitly routes the agent away from the conversation-oriented sibling. It never names that alternative (`upscale`) or the prerequisite quote tool (`estimate_upscale`) directly, so the guidance is clear but not fully explicit.

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, destructiveHint=false, and openWorldHint=false, so the agent knows this is a safe, repeatable, closed-world pricing call. The description adds the app-only scope constraint, which is genuinely useful context, but says nothing about cost/auth requirements or when estimates expire — acceptable but not rich.

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

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

Two short sentences with the scope constraint front-loaded, no filler. The terse sibling clause is the one piece that costs clarity rather than saving space.

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?

Output schema exists, so return values need not be described, and annotations cover the safety profile. What remains thin is the relationship to sibling pricing/upscale tools, which the garbled final clause does not resolve — leaving the agent to guess the boundary between `app_upscale_quote` and `estimate_upscale`.

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 100%, so the schema already documents `kind`, `model`, `resolution`, and `source_url` with meaningful hints (e.g., model id from a prior estimate_upscale, enum for kind). The description adds no parameter-level meaning beyond that, which is the expected baseline when the schema does the work.

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

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

The title 'Price an upscale (app)' and the opening scope note make it clear this returns a price for an upscale, scoped to the app's own screens. However, the closing phrase 'estimate_upscale for the app's Upscale card' is ambiguous — it is unclear whether it names a sibling tool to use instead or merely describes one, so the exact purpose versus the sibling `app_upscale`/`upscale`/`estimate_upscale` is not cleanly nailed down.

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?

'For the Veltake app's own screens only — not for a conversation' gives one real exclusion and implies that non-app (conversational) pricing should go elsewhere. But the guidance on when to pick this over `estimate_upscale`, `app_upscale`, or `upscale` is left to inference, and the trailing sibling reference is too vague to serve as routing.

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

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

Beyond the annotations (destructiveHint, idempotentHint), the description discloses the refund of held coins in full and the fact that the provider is never notified, so an in-flight result is silently discarded. Those side effects and the paid-resource implications are exactly the behavioral context 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?

Three short sentences with zero filler; the core action is front-loaded and each following sentence adds a distinct, load-bearing fact (refund, provider silence, ineligibility of finished jobs).

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 cancellation tool with no output schema, the description covers the eligibility rule, the cost outcome, and the side effect of discarding in-flight results. Nothing an agent needs to call 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 100% and the single 'id' parameter is documented in the schema as coming 'from generate or list_generations'. The prose adds no additional meaning about the parameter, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource ('Cancel a queued or running generation') and immediately scopes it to two lifecycle states. No sibling tool shares this resource, so an agent can pick it without ambiguity.

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 states both the positive condition (queued or running) and an explicit exclusion ('A finished generation cannot be canceled'), which is exactly the guidance an agent needs. It stops short of naming an alternative tool, though no sibling offers the same cancel capability.

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 cover the safety profile (readOnly=false, destructive=false, openWorld=false), and the description still adds real behavioral value: it discloses that a canvas is created alongside the project and that the response contains both the project id and the canvas id. It stops short of covering duplicate-name behavior or naming constraints.

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

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

A single front-loaded sentence with no filler; the action, its side effect, and its result are packed in without 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?

With no output schema, the description usefully states the return shape (project id and canvas id), and annotations plus a fully documented 2-param schema cover the rest. Only error/duplicate handling is unaddressed, which is minor for a tool this simple.

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 100% for both parameters, so the schema already documents 'name' and the 'kind' values with its default. The description adds nothing about parameter semantics, which is the expected baseline when the schema does the heavy lifting.

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 ('Create') and resource ('Studio project'), plus the non-obvious side effect of provisioning one empty canvas. The creation verb cleanly separates it from read siblings such as get_project and list_projects without needing to name them.

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

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

Usage is implied by the verb – you call this when you need a new project – but the description names no alternatives (e.g. app_import_file for bringing in existing work) and states no preconditions or when-not-to-use 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?

Annotations already cover read-only/idempotent/non-destructive, but the description adds real value: free, changes nothing, runs every validation generate runs, and mirrors generate's argument contract. It partly restates return content that the output schema already documents, which caps it below 5.

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

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

Front-loaded with purpose and safety, and each sentence carries information (contract, validation parity, workflow). Slightly long, and the enumerated return fields partly duplicate the output schema, so not perfectly tight.

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 pricing tool with an output schema and full annotation coverage, everything needed is present: it is safe/free, validated identically to generate, returns a cost, and feeds expected_cost into the subsequent generate call.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a meaningful contract fact beyond the schema: it takes the same arguments as generate without expected_cost. That mapping lets an agent reuse generate's parameter knowledge rather than re-deriving it.

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 ('Price a generation') and immediately distinguishes it from the sibling it could be confused with ('without making it'), i.e. generate. An agent can tell it apart from generate without opening either 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 a clear when-to-use: run it before generate so refused requests are caught early, then pass the returned coins as expected_cost. No explicit when-not-to-use versus estimate_run/estimate_upscale, but the workflow context is strong.

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 readOnly/idempotent/non-destructive, but the description adds real behavioral context beyond them: the call is free and spends nothing, and it explains the payer model (personal vs team, with team project runs always drawn from the team pool) plus the payer balance. That cost/payer semantics is not derivable from 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?

Single dense sentence with the free/no-spend qualifier front-loaded and the actionable handoff to start_run at the end. Every clause carries information (cost, payer, balance, per-node price, version) 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?

With no output schema, the description takes on the burden of describing the return shape, and it does so (total, payer, payer balance, per-node price and model, canvas version). Combined with the explicit start_run chain, an agent has enough to call and use it, though the exact response structure is only named, not shaped.

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 100%, so all four inputs (graph_id, force_nodes, scope_nodes, from_node_id) are already documented in the schema. The description instead elaborates on return fields and the start_run handoff, adding no meaning to the input parameters themselves; baseline 3 applies when the schema does the heavy lifting.

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 (price/estimate) on a specific resource (a canvas run) and immediately distinguishes it from write operations with '(free, spends nothing)'. The word 'canvas' plus the return-field list separates it from estimate_generation and estimate_upscale without opening either 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?

Clearly positions this as the pre-flight check for start_run and names the handoff explicitly ('Pass the total and the version to start_run'). The workflow is unambiguous, though it gives no explicit exclusion such as when to prefer estimate_generation or what to do if the price is unacceptable.

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 readOnly, idempotent and non-destructive, so the bar is lower. The description adds useful non-annotation context: the price is derived from the file itself (size, and for video length and frame rate), so the file is read first, and it discloses what the call returns (coins, balance, output size, offered targets).

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-loads the core purpose, then flows logically through cost semantics, return values, handoff and prerequisites. Sentences are short and mostly earn their place, though the parenthetical gloss and the return-value sentence are slightly more than strictly needed given the output schema exists.

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 annotations, an output schema and full schema coverage all present, the description only needs to supply the missing context, which it does: pricing model, free/non-mutating nature, prerequisite import step, and the handoff to upscale. Nothing an agent needs to call it correctly is absent.

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 100%, so all four parameters are already documented, giving a baseline of 3. The description adds only marginal meaning, explaining why file characteristics drive the price rather than clarifying the parameters themselves.

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 (price/estimate) and resource (upscaling an image or video) with a clarifying gloss on what an upscale is. It distinguishes itself from the sibling 'upscale' by explaining it computes a cost rather than performing the operation, and names the coin-passing handoff between the two.

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

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

Explicitly routes the agent: pass returned coins to upscale as expected_cost, and states the prerequisite 'the file must be hosted: import_media first'. It also declares it is free and changes nothing, which clarifies when it is safe to call. It does not, however, differentiate itself from the lookalike sibling app_upscale_quote.

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 cover safety (readOnlyHint=false, destructiveHint=false, openWorldHint=false); the description adds non-obvious behavior: no coin cost, an account-tier gate on quality/format rungs, and a daily export allowance (a rate limit). It also discloses the asynchronous nature by pointing to get_export for polling, though it doesn't cover failure/cancel behavior.

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 tight sentences: what is queued, the cost/allowance constraint, and the retrieval step. Front-loaded action statement with zero filler, and each sentence carries distinct information.

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

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

With no output schema, the description correctly supplies the retrieval path (poll get_export) and the resource constraints an agent needs before queuing. The only minor gap is that it never states what this call returns (e.g. the export/job identifier to pass to get_export).

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 100%, so the schema already documents fit, format, quality, aspect_ratio and aspect_ratios including defaults and the 'at most 4' cap. The description's 'one export per aspect ratio' merely echoes the schema's own wording, adding no new syntax or interpretation. Baseline 3 applies.

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

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

Specific verb+resource: 'Queue a render of a cut to a video file', with the multiplicity rule ('one export per aspect ratio') stated up front. It is clearly distinguishable from the read-only sibling get_export (which it names as the polling counterpart) and from get_cut/list_cuts.

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 strong context for when this is appropriate ('Rendering spends no coins', allowance applies) and explicitly routes the agent to the follow-up tool: 'Poll get_export for the file.' It stops short of naming alternative tools or stating exclusions/preconditions (e.g. when to prefer generate or upscale instead).

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/openWorld=true/destructive=false; the description carries far more weight by disclosing the coin-spend mechanics (exact expected_cost, nothing charged if price changed, reservation of at most that amount, full refund on failure, partial settlement), the hosting requirement for media, and the retry/idempotency behavior. These are the traits an agent genuinely cannot infer from the structured fields.

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

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

Front-loaded with the action, then cost, then media constraints, then result handling — a logical order with no filler sentences. It is dense and a couple of points (idempotency_key retry semantics, media hosting) are stated twice across the description and schema, which slightly dilutes the otherwise tight prose.

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 21-parameter, paid, long-running generation tool with an output schema, the description covers everything an agent must know before invoking: pricing contract, payment source constraints, media provenance, and how to obtain the result. Return-value detail is correctly delegated to the output schema.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: it pins expected_cost to the estimate_generation answer and explains the charge/refund consequence of a mismatch, and it states the idempotency_key retry contract rather than just describing the field. The per-kind semantics of the other 19 params are left to the schema, which already documents them well.

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 concrete verb+resource set ('Make an image, a video, a spoken script or a song') that maps directly to the kind enum, and it names the sibling tools it depends on (estimate_generation, get_generation, import_media). An agent can immediately separate it from estimate_generation (pricing only) and get_generation (polling).

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

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

Explicitly routes the agent: get the price via estimate_generation and pass it as expected_cost, poll get_generation for the result, import off-host media with import_media first, and repeat idempotency_key on retries. It also states when NOT to expect an exemption ('a Relax queue or an unlimited allowance does not apply through an agent').

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 fully cover the safety profile (readOnly, idempotent, non-destructive, not open-world), so the bar is lower. The description still adds value by disclosing the shape of the returned transcript (message, status, reply, proposed/changed content), which goes beyond what the annotations provide. It omits any mention of pagination limits, which live only in the 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?

A single front-loaded sentence with no filler; the verb and resource come first and the return-content detail follows compactly.

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

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

There is no output schema, so the description carries the return-value burden, and it does describe the transcript contents at a high level. Combined with fully annotated read semantics and complete schema docs, this is nearly complete, missing only pagination/truncation behavior.

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

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

Schema description coverage is 100%, with both chat_id (source: start_chat/list_chats) and last (newest N turns, default 20, max 50) documented in the schema. The description adds no parameter-level detail, so the baseline of 3 applies.

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

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

States a specific verb (read) and resource (one conversation) and enumerates what the transcript contains: each turn's message, status, reply, and proposals/changes. It is clear what the tool does, though it does not explicitly contrast itself with the sibling get_turn or list_chats.

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 phrase 'one conversation' implies this is the single-chat read versus the collection-oriented list_chats, and the schema ties chat_id to start_chat/list_chats. However, no explicit when-to-use or when-not-to-use guidance is given, nor is get_turn named as the alternative for reading a single turn.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description goes beyond them with a genuinely useful data-model explanation: a clip's source is a take, a text card, or an upload, `takes` and `uploads` carry the media, and a clip absent from both has no usable media. That tells the agent how to interpret a returned clip, which annotations cannot.

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, no padding, with the core action and returned contents front-loaded before the media-resolution caveat. The second sentence is dense but each clause conveys distinct information about clip sources and media availability.

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 describing the return value, and it does so concretely by enumerating the timeline fields. The single required parameter is fully documented in the schema, and existing annotations cover the safety profile, so the only real omission is error/empty-result behavior.

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

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

Only one parameter exists and schema description coverage is 100%, so the schema already documents cut_id (including its provenance from list_cuts). The description adds no format, syntax, or constraint detail beyond it. Baseline 3 applies when the schema does all the work.

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

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

States a specific verb+resource ('Read one cut') and enumerates what the returned timeline document contains (clips, voiceovers, music, captions, aspect ratio, version). The singular 'one cut' implicitly contrasts with the sibling list_cuts, but the description never names that alternative, so differentiation is left to inference.

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 when-to-use statement and no alternative is named. The only routing hint, that cut_id comes 'from list_cuts', lives in the input schema rather than the description. An agent must infer the list-then-get workflow on its own.

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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds the useful nuance that the export has an in-progress state ('when done'), implying polling, but does not describe possible status values, error states, or expiry of the resulting URL.

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

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

One compact sentence with the verb and resource front-loaded and the return values enumerated after the colon. Every clause carries information and nothing is padded.

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

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

With no output schema, the description must carry the return shape, and it does list the meaningful fields (status, film URL, frame size, frame rate) for a single-parameter read. Only the polling contract and status enumeration are 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?

There is a single parameter and schema description coverage is 100%, with the schema itself documenting export_id as coming 'from export_cut'. The description adds no syntax, format, or constraint detail beyond that, so the baseline of 3 applies when the schema fully carries the parameter.

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

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

States a specific verb (Read) and resource (an export), and enumerates the key return fields (status, film URL, frame size, frame rate), which lets an agent distinguish it from the write-oriented export_cut sibling. It stops short of explicitly naming the alternative, but the read-vs-create split is inferable.

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

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

Usage is only implied: 'when done' hints that this is an asynchronous result that must be polled until completion, but the description never says when to call it, how often, or how it relates to export_cut. The schema's 'from export_cut' note carries most of the linkage.

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 the safe read profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context beyond them: the status lifecycle values, that result fields only populate once succeeded, and the Music-specific 'one take per call, take_group ties the two' partial-result semantics. It stops short of stating polling expectations or what a failed/canceled response contains.

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

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

Two sentences, front-loaded with the core action and required id provenance before the return-value detail. The parenthetical status enum list adds length, but it earns its place by telling the agent which states to expect when polling. Minor density cost only.

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?

An output schema exists, so return values needn't be spelled out, yet the description usefully flags the conditional fields and the take_group relationship for Music. Combined with annotations covering the safety profile, an agent has enough to call it correctly; only explicit guidance on when to prefer list_generations is missing.

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

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

Schema coverage is 100% for the single id parameter, so the schema already documents its origin ('from generate or list_generations'). The description repeats that provenance without adding format, validation, or failure behavior for an unknown id. Baseline 3 applies when the schema carries the parameter burden.

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

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

Names a specific verb (Read) and resource (one generation) and immediately scopes it against the sibling list_generations by saying 'one generation'. It also enumerates the payload surface (status, progress, result URL, preview, size, length), so an agent knows exactly what it retrieves.

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

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

Usage is implied rather than stated: 'Read one generation' plus the id's provenance ('from generate or list_generations') tells the agent this is the single-item counterpart to the list tool. There is no explicit when-to-use / when-not-to-use guidance and no routing to get_run, get_cut, or cancel_generation for related follow-ups.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful content-level disclosure by enumerating what the response contains, which matters because there is no output 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?

A single front-loaded sentence with zero filler; the verb and resource come first and the payload detail follows. Every clause earns its place.

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

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

With no output schema, the description's field enumeration is the main source of return-value information and it delivers that. It stops short of noting failure behavior for an unknown project_id or the depth/nesting of the returned data, leaving 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?

Schema description coverage is 100% for the single project_id parameter, so the schema carries the semantics. The description adds nothing about the id's format, origin beyond what the schema states, or what happens if it is unknown, making the baseline 3 correct.

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

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

The description gives a specific verb+resource ('Read one project') and enumerates the payload (canvases, scenes and shots, cast, agent conversations). It implicitly contrasts with list_projects via the singular 'one project', but never names that sibling explicitly, so differentiation is inferred rather than stated.

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

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

Usage is only implied: the singular 'one project' plus the schema's 'from list_projects' hint suggest this is the follow-up to a listing call. The description itself offers no explicit when-to-use, prerequisites, or alternatives, so an agent must infer the workflow.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds real value by disclosing the return surface (status, cost, per-node state, model, result URLs), which is otherwise unavailable since there is no output 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?

One sentence, front-loaded with the action and resource, then the payload; nothing redundant or padded.

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

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

For a 1-param, no-output-schema read tool the description carries the return-shape burden well, but it omits error/lifecycle context (e.g. what a still-running run looks like, whether to poll after start_run), which an agent would benefit from.

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

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

Schema coverage is 100% and the single run_id is documented as coming 'from a turn or apply_turn'. The description adds nothing further about the identifier's format or origin, so the baseline 3 applies.

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

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

States a specific verb+resource ('Read a canvas run') and enumerates the payload (status, cost, node state, model, result URLs), which is more informative than the bare title. It does not, however, distinguish itself explicitly from near-siblings like get_turn, get_generation, or get_cut.

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

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

No guidance on when to call this versus get_turn, get_generation, or list_generations, and no mention of polling after start_run/apply_turn. The only flow hint ('run_id from a turn or apply_turn') lives in the schema, not the description.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's value-add is its disclosure of return content. With no output schema, it explains the status enum values, distinguishes step kinds ("call" carries a tool, "say" does not), and notes a step may also carry say content. That is real behavioral context beyond the annotations.

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

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

A single front-loaded sentence that opens with the verb and resource, then layers the return detail. It is dense and uses nested parentheticals, but each clause documents a distinct return field that has nowhere else to live without an output schema, so the length is largely justified.

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

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

For a one-parameter, read-only tool with no output schema, the description covers the important return surface: status values, reply, step structure, proposal, estimate, question, plan, and changes. Safety is handled by annotations. A brief note on error/not-found behavior would close the remaining 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?

There is a single parameter with 100% schema description coverage, so the schema already documents turn_id and its origin. The description adds no syntax, format, or constraint detail for turn_id. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource ("Read a turn") and enumerates exactly what a turn yields: status, reply, steps, proposal, estimate, question, plan, changes. The resource (turn) is clearly distinct from siblings like get_chat, get_run, and get_project. It lacks explicit sibling differentiation, 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?

There is no when-to-use guidance, no mention of alternatives such as get_run or get_chat, and no stated prerequisites. The only usage clue is indirect, via the turn_id schema description ("from send_message"), which implies sequencing but is not in the description itself.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true, so the write/network profile is covered. The description adds genuinely new lifecycle context ('The file is kept as a temporary upload'), which matters for a tool that persists state. No detail on size/format limits or failure modes.

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

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

Front-loaded with the action and its outcome, then the input rules, then the retention note — three sentences with no filler. The phrase 'answer a hosted URL' is slightly awkward but not ambiguous.

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

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

With no output schema, the description correctly carries the return value ('a hosted URL to pass to...') and downstream wiring, so an agent knows what to do with the result. Missing only operational limits (accepted formats, size caps, what happens when the temp upload expires).

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by constraining url ('a DIRECT link to an image, video or audio file, not a web page') and by scoping file to attachments from the current conversation, which the nested-object schema does not say.

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 ('bring a file into the account's uploads') plus the concrete outcome ('answer a hosted URL'). It routes the agent into the surrounding workflow by naming the consuming tools (generate with last_frame/reference_video/reference_audio, upscale, send_message).

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?

Explains the two input modes and when each applies ('either url... or file, a file the person attached in this conversation'), and warns that url must be a direct file link, not a web page. It does not, however, differentiate from the sibling app_import_file, which an agent could plausibly confuse with 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 only declare the safety profile, but the description adds the real behavioral payload: idempotent retry via message_id, deterministic derivation that collapses identical text into ONE message, the already_received:true signal, and refusal conditions. That is substantial context beyond structured fields.

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

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

Front-loaded with the core purpose and every sentence carries information, but it is one dense block with nested clauses and parentheticals (already_received, message_id derivation) that make it harder to scan than it needed to be.

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

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

There is no output schema, so the description must cover returns, and it does: the unread-message count plus the pointer to get_turn for the rest, and already_received on the dedupe path. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining what message_id actually does: derived from caller/turn/words when omitted, and the escape hatch for a deliberate repeat. turn_id is tied to its source (send_message or get_chat), which the schema does not say.

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 precise verb and resource: hand a message to an agent WHILE a turn is running, and it names the sibling it is not (send_message as the next message). An agent can distinguish it from send_message, retry_turn and apply_turn without opening any schema.

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

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

Explicit preconditions (only a running turn of a conversation you can message), explicit exclusion (refused once the turn has ended or already has messages waiting), and the named alternative (send_message) for that case. Nothing is left 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, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: result ordering (newest first) and that transcripts are deliberately excluded from the payload, plus the visibility scope of returned conversations.

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

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

One sentence, front-loaded with the action and resource, with qualifying detail (scope, ordering, exclusion) packed into parenthetical clauses. No filler 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?

There is no output schema, so the description must carry the return semantics, and it does: conversations are returned newest first and without transcripts. It stops short of clarifying pagination or result limits, which is a minor gap for a listing tool.

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

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

Schema description coverage is 100% and the single parameter is documented as 'from list_projects'. The description reinforces that the listing is project-scoped but adds no syntax, format, or cursor detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the agent conversations'), scopes it to a project, defines ownership coverage (yours plus teammate-shared), ordering (newest first), and an explicit payload exclusion (without transcripts). An agent can distinguish this from the singular sibling get_chat without opening either 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?

'Without their transcripts' implies that transcript retrieval is a different tool, but no sibling (e.g. get_chat) is named and there is no explicit when-to-use or when-not statement. The scope clause ('yours, and any a teammate shared') supplies helpful context but is not 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=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description goes beyond them by disclosing what each returned cut carries (length, clip count, newest export), which is genuinely useful since no output schema exists.

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

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

A single sentence with zero filler, front-loading the resource and then the return contents. Every clause earns its place.

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

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

For a simple one-parameter read with full annotation coverage, the description is nearly sufficient: it explains the resource and the returned fields. It omits any note on ordering, empty results, or pagination behavior, which keeps it just short of 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?

There is only one parameter and schema description coverage is 100% ('from list_projects' documents its origin), so the schema already does the heavy lifting. The description adds no additional meaning about the project_id format or constraints, making the baseline 3 appropriate.

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

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

States a specific verb (List) and resource (a project's cuts) and even disambiguates the domain term with '(edited films)'. The list-vs-get distinction against the sibling get_cut is clear from the name and phrasing, so an agent can select correctly without opening a 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?

Usage is implied: you call this to enumerate cuts within a given project, and the schema's 'from list_projects' hint tells the agent where project_id comes from. However, there is no explicit statement of when to use this versus get_cut for a single cut, or versus list_projects/list_generations, and no exclusions are offered.

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 the safety profile (readOnly, idempotent, non-destructive), so the description's added value is the newest-first ordering, the exclusion of logos and Studio takes, and the pagination chaining via next_offset. That is meaningful behavioral context beyond structured fields, though it says nothing about result size or whether generations are filterable by project.

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, zero filler, with the primary purpose and scope front-loaded ahead of the minor pagination detail. Every clause carries information.

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

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

An output schema exists, so return values need not be described, and pagination is already explained. For a simple read-only list tool, nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so all three parameters (including the kind enum and offset semantics) are already fully documented in the schema. The description restates the limit bounds and the next_offset chaining rather than adding new meaning, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (the account's Create generations) with the ordering rule (newest first) and explicit scope exclusions (logos and Studio takes are not listed here). An agent can tell this apart from get_generation or list_projects without opening the schema.

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

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

The exclusions carve out a clear scope boundary and implicitly tell the agent this is the enumeration entry point rather than a detail fetch. It does not explicitly name an alternative sibling (e.g. get_generation for a single item) or state when not to use it, so it stops short of a full when/when-not statement.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered structurally. The description adds real value beyond that by disclosing the return payload — accepted input types and the fact that a coin balance comes back alongside the models. Pagination and result-size behavior are still unstated.

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 dense sentences, front-loaded with the verb and scope; the enumerations are compressed into parentheticals and the workflow hint is a single final clause. 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?

No output schema exists, so the description carries the burden of describing the return value — and it does, listing id, name, maker, accepted aspects/resolutions/durations/voices and default coin cost plus balance. Combined with annotations that cover safety, an agent has everything needed to call it.

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 100% and the single enum parameter is fully documented, so the schema does the work. The description restates the same four enum values under the phrase 'one kind of creation' but adds no format or semantics beyond them. Baseline 3 applies when the schema carries the parameter meaning.

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

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

Specific verb (List) plus resource (models) with an explicit scope: 'one kind of creation — image, video, speech or music.' It goes further by enumerating the return shape (id, name, maker, accepted inputs, default coin cost). It does not differentiate itself from the sibling app_models, so it stops short of a 5.

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

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

The closing sentence 'Pass a model's id to estimate_generation and generate' states the downstream workflow, telling the agent exactly where this tool fits in the chain. There is no explicit when-not guidance or disambiguation from app_models, which keeps it out of 5 territory.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description usefully adds that results are ordered newest-first and include ids, but says nothing about pagination or result limits, which matters for an account-wide list.

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 tight sentence with the scope and ordering front-loaded and zero filler. Every clause carries information.

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

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

With no output schema, the description should carry more of the return-shape burden; "with their ids" only partially covers it. Pagination, limits, and per-project fields are unspecified, though the fully annotated read-only profile means an agent can still call this safely.

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 100% and the single optional `kind` parameter is already documented as "film | marketing — omit for both". The description's "(film and marketing)" merely restates that, adding no new syntax or semantics beyond the schema, so baseline 3 applies.

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

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

The description states a specific verb and resource ("List the account's Studio projects"), scopes it to the account, and adds ordering ("newest first") and return content ("with their ids"). It is clearly distinguishable from get_project (singular) and create_project, though it never names those siblings 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?

There is no when-to-use guidance, no mention of when not to use it, and no alternative tool named. The parenthetical "(film and marketing)" hints at the scope of results but does not tell the agent when this tool is the right choice over get_project.

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 safety (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real value beyond them: the 24-hour window, that entries are live and individually playable, and that it takes no arguments. It does not say whether this replaces or overlays the current UI view, which is the one behavioral detail still missing.

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

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

Three short sentences, each carrying a distinct payload: what is shown, when to use it, and the argument situation. The scope (24 hours) is 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 no-argument UI tool with full annotation coverage and an output schema, the description covers purpose, trigger and input expectations adequately. The only unaddressed point is how opening the tray interacts with the current view, a minor gap given the tool's simplicity.

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

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

Zero parameters, so the baseline is 4. The description reinforces this with 'Takes no arguments,' which matches the empty schema and additionalProperties:false, but adds no further parameter nuance because there is none to add.

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

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

States a specific verb+resource ('Show the person the generations') with a bounded scope (last 24 hours) and distinguishing traits (live, each one playable). It implicitly separates itself from list_generations by emphasizing a live playable display rather than a data listing, but it never names the sibling to make the contrast explicit.

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

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

Explicitly states the triggering context: 'Use it when they ask what is running or what was just made.' That is clear when-to-use guidance, but it offers no when-not condition or named alternative (e.g. use list_generations for a data query instead of opening the tray).

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 readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely new context: it takes no arguments, kind/prompt merely pre-fill, and the tool returns only a short summary to the agent while the home is rendered for the person — a non-obvious behavior worth stating.

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

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

The purpose and scope are front-loaded in the first clause, and each subsequent sentence (usage trigger, arguments, return behavior) adds distinct information. It is slightly dense but nothing is redundant with the schema or annotations.

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?

An output schema exists so return values need not be enumerated, and annotations cover the safety profile. The description still supplies the important detail that the agent receives only a summary while the person sees the home, leaving little 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 description coverage is 100%, so the baseline is 3 and the schema carries the parameter documentation. The description still adds meaning by clarifying that both parameters are optional pre-fills of the composer rather than required inputs, which reinforces their optionality and effect.

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 ("Open Veltake's home for the person") and immediately qualifies it as a composer for images, video, speech and music with coin pricing and recent work. That is far more specific than a tautology, but it never explicitly separates itself from the sibling app_home, which an agent must distinguish between.

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

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

Gives an explicit trigger condition: "Use it when the person wants to browse, pick a model or settings themselves, or start from a workflow." That implicitly contrasts with direct-generation siblings like app_generate, but no alternative is named and no when-not case is stated.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation profile is known; the description goes further by disclosing that the old answer is retained as an earlier version and drops out of the conversation, plus the blocking behavior ("waits like send_message"). The cross-tool reference for waiting is slightly indirect and nothing is said about permissions or failure output, so it stops short of a 5.

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

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

The two-mode choice is front-loaded and every clause carries information (scope limits, preconditions, remedy, blocking). It is dense to the point of being telegraphic — stacked dashes, semicolons and parentheses — which costs a little readability.

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 state-mutating regeneration tool with no output schema, the description covers preconditions, side effects on prior versions, and blocking behavior well. It never states what the call returns (the new turn, presumably), which is a modest gap given there is no output schema to lean on.

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

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

Schema coverage is 100%, so both parameters are already documented (baseline 3). The description adds meaning beyond the schema by explaining the consequence of each mode: omitting message regenerates, supplying message replaces the words and lets the agent answer the edit.

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 — regenerate the conversation's LATEST message, or replace its words — and explicitly separates the two modes. It is clearly distinguishable from siblings like send_message, apply_turn, and undo_turn because it constrains itself to the latest message only.

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/when-not conditions: only your own message, only the latest one, never while it is running, and refused while external changes are still in place — with the remedy named (undo_turn it and its reviews first). That is a full routing rule set, including the alternative tool to use first.

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 cover the safety profile (not read-only, open-world, non-destructive). The description adds genuinely new behavior: an approximate ~45s blocking wait, the fact that the agent works on a working copy, the four response shapes, and the polling fallback when the turn is unfinished. That is well beyond what annotations 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?

Three tight sentences, front-loaded with the primary action and timeout, followed by the outcome-to-next-step mapping. Every clause carries information; no filler.

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

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

There is no output schema, so the description carries the return-value burden and does so by enumerating the four response types. Combined with the timeout and polling guidance, an agent has everything needed to invoke and follow up 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 100%, so chat_id, message, attachments, and plan_approved are already documented in the schema. The description reinforces plan_approved's role in the plan workflow but adds no format/syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource (send a message to the Studio agent) plus the defining behavior (waits up to ~45s for the answer). It also names the sibling tools involved in the follow-up workflow (apply_turn, get_turn), so an agent can distinguish it from interject_turn/retry_turn without opening schemas.

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

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

Enumerates the four possible outcomes and the exact next action for each: proposal -> apply_turn, priced plan -> reply with plan_approved:true, and still-working -> poll get_turn. This is explicit when/next-step routing rather than implied usage.

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=false, destructiveHint=false, and openWorldHint=false, so the agent knows this mutates state safely. The description adds the return contract ('Answers the chat id'), which is valuable given there is no output schema, but it omits any note on permissions, idempotency, or what happens if a chat already exists.

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

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

Two short sentences with no filler, and the core action is front-loaded. The phrase 'Answers the chat id' is slightly awkward but does convey the return value efficiently.

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

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

For a two-parameter creation tool with no output schema, the description covers what it does and what it returns, which is the minimum viable. It is missing the surrounding workflow context (e.g., that this must precede send_message) and any failure/edge-case behavior.

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

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

Schema description coverage is 100%: project_id ('from list_projects') and graph_id ('omit for the project's first canvas') are already fully documented, including the default behavior. The description adds nothing beyond that, so the baseline of 3 applies.

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

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

States a specific verb ('Open') and resource ('conversation with the Studio agent') plus the scope ('on a project's canvas'), which is far more than a restatement of the name. It does not, however, distinguish itself from siblings like send_message, get_chat, or list_chats, leaving the agent to infer that this is the chat-creation call.

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 when-to-use guidance, no statement of prerequisites, and no mention of alternatives such as get_chat (retrieve) or list_chats (enumerate). The agent must infer from 'Open a conversation' that this is the creation step that precedes send_message.

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 write (readOnlyHint=false) and non-destructive/global scope, so the safety profile is partly covered. The description adds high-value context beyond them: the operation SPENDS the user's coins, the mismatch-refusal behavior means nothing is spent on failure, and the polling next step. This is material economic and failure semantics that annotations do not 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?

Three tight sentences, front-loaded with purpose and immediately followed by the critical cost warning. No filler; every sentence carries actionable information.

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

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

Covers purpose, prerequisite, cost/refusal behavior, and the polling follow-up, which is strong for a write tool with no output schema. It stops short of saying what start_run itself returns (e.g. a run id to feed get_run), leaving a minor gap an agent would have to infer.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds meaning by binding expected_total and version to estimate_run's output and explaining the consequence of a stale value (run refused, nothing spent), which gives these parameters semantic weight beyond their terse schema 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?

States a specific verb and resource ('Start rendering a canvas') and situates it precisely in the workflow between estimate_run (which supplies version/expected_total) and get_run (which is polled). An agent can distinguish it from the sibling estimate/get tools 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?

Explicitly names the prerequisite sibling (estimate_run) and the follow-up sibling (get_run), and gives the condition that governs use: pass the estimate's values exactly or the run is refused. The routing to alternatives is concrete rather than implied.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds genuinely useful context beyond that: work performed so far is preserved rather than discarded, and a waiting turn's review is what gets cancelled. It still doesn't say whether the operation is reversible or what state the turn ends in.

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

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

One front-loaded sentence with two parallel clauses, no filler, and the outcome-bearing detail (work is kept) placed immediately after the verb.

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 mutation with no output schema, the description covers both invocation states and the preservation semantics. What is missing is post-condition detail such as whether the turn can be resumed or is terminal.

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 100% and the single turn_id parameter is already documented as coming 'from send_message', so the schema carries the parameter burden. The description adds no further parameter meaning, which is the expected baseline for full 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?

States a specific verb plus resource (stop a turn) and distinguishes two distinct states: a running turn versus a waiting turn's review. That is more precise than the title alone, though it never names the related siblings (cancel_generation, undo_turn, interject_turn) it could be confused with.

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

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

The description implicitly defines when it applies by describing the two turn states it handles, but it offers no explicit exclusions or alternatives. An agent facing a stuck run has no guidance on stop_turn versus cancel_generation, retry_turn, or undo_turn.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds genuinely new behavioral semantics beyond that: the undo is conditional and per-item, reverting each change 'only while it is still what the agent wrote', which tells the agent partial/stale reverts are possible. It omits any auth requirement or reporting of partial success.

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, front-loaded with the core action and scope; the artifact enumeration is dense but each item earns its place by defining the scope boundary. No filler or restatement of the title.

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 mutation with no output schema, the description covers scope, conditional behavior, and the relationship to apply_turn. It could still say what a partial revert looks like to the caller, but nothing essential prevents 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 100% and the single parameter's provenance ('from send_message or get_chat') is already documented in the schema. The description adds no syntax, format, or validation detail for turn_id, so this is the baseline case where the schema does the work.

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

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

States a specific verb ('Revert') and a precisely scoped resource ('what a turn changed OUTSIDE the canvas'), then enumerates the affected artifact types. It also distinguishes itself from the sibling apply_turn by explaining that canvas proposals are not landed without apply_turn and therefore need no undo here.

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 when-to-use condition (revert turn changes outside the canvas) and a when-not-to condition (canvas changes, which require apply_turn to land at all). It does not discuss the sibling recovery tools retry_turn/stop_turn or warn about irreversibility, so it stops short of full alternative routing.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), the description discloses the economically critical behaviors: coins are spent, a changed price results in no charge and a new quote, failed/canceled upscales are refunded in full, and retries are deduplicated via idempotency_key. This is exactly the kind of context annotations cannot express.

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

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

Four tight sentences, each carrying distinct operational information (what it does, cost contract, refund policy, result polling, retry safety), with the cost warning front-loaded immediately after the purpose. 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 paid, asynchronous, idempotent mutation tool, the description covers cost preconditions, failure refunds, result retrieval, and retry behavior, and an output schema exists so return formatting need not be explained. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds real meaning: expected_cost must be the exact value estimate_upscale returned and is rejected if stale, and idempotency_key causes a retry to answer the first upscale rather than re-charge. These semantics go beyond the terse schema hints.

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 ("Upscale an image or a video") that matches the title and states the operation unambiguously. However, it never distinguishes itself from near-identical siblings such as app_upscale or app_upscale_quote, so an agent cannot tell from the text alone which upscale entry point applies.

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

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

It gives clear workflow context: obtain expected_cost from estimate_upscale for these very arguments, poll get_generation for the result, and repeat idempotency_key on a retry. That covers the main sequencing decisions, but it offers no exclusion guidance about when to prefer app_upscale or the quote tool instead.

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