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

Annotations only declare readOnly=false, openWorld=true, idempotent=false, destructive=false; the description adds that the conversation is stateful across messages and that the tool returns generation parameters requiring a confirm_generation step before anything is produced. That is real workflow context beyond the annotations, though it says nothing about credit consumption or failure behavior for a non-idempotent, open-world call.

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

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

Front-loads the purpose, then exclusions, then workflow note, then compact examples. No filler sentences and each block carries distinct routing or behavioral 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?

Without an output schema, the description does well to explain that generation parameters come back and must be reviewed before confirm_generation. It is nearly complete for the create flow, but leaves the conversation/workspace parameters and the cost implications unexplained.

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

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

Schema coverage is 0% and the description never explains the three parameters: message is only implied through examples, while workspace_id and conversation_id are completely undocumented. The statefulness sentence hints that conversations persist but never tells the agent to pass conversation_id to continue one, which is a significant gap.

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

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

States a specific verb and resource ("Send a message to Canvora's AI visual creation assistant") and explicitly scopes it as the primary creation entry point, which separates it from get_generation, create_variation, localize_generation and export_visuals.

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

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

Provides explicit when-to-use (describe text/URL/idea to create visuals) plus concrete when-NOT-to-use with each named sibling and the condition that selects it, including the tip to omit generation_id on get_generation for the latest result.

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 a genuine behavioral constraint (no proactive checks) beyond annotations. It does not describe what the response contains (balance units, remaining quota), leaving a small gap.

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

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

Two short sentences, zero filler, with the purpose front-loaded and the invocation constraint immediately following. Nothing could be removed without losing meaning.

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

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

For a zero-parameter read tool with full annotation coverage, the description covers purpose and gating adequately. The only absent detail is what the tool returns (e.g., numeric balance), which matters slightly since no output schema exists.

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

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

The tool takes zero parameters, so there is no parameter semantics for the description to explain; the baseline applies. There is nothing incorrect or missing here.

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

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

States a specific verb and resource ('Check your current Canvora credit balance') with clear scope. None of the siblings (list_formats, get_generation, list_workspaces, etc.) deal with credits, so the tool is unambiguously distinguishable.

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 gates invocation: 'Only call this when the user explicitly asks about their credits or balance.' This is a clear when-to-use rule rather than an implied one, which prevents speculative polling.

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

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

Annotations declare destructive/openWorld/non-idempotent, and the description substantiates all three: it explains that duplicate calls create duplicate generations and double-charge credits, that work runs in the background for 30-120 seconds, and that a generation ID is returned immediately. It adds a concrete polling protocol (wait 15s, then every 10-15s until status "completed") and names the output destination (Canvora workspace plus preview/downloadable URLs) — none of which is inferable 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-loads the trigger condition and the override model, then the critical anti-duplication warning. It is long but nearly every sentence carries operational weight; the only waste is mild repetition of the get_generation polling instruction, which appears three times in slightly different framings.

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 credit-charging, non-idempotent mutation tool with 13 params and no output schema, the description gives a complete operational picture: trigger condition, override scope, re-plan escape hatch, async lifecycle, polling cadence, and where artifacts land. The remaining gap is per-parameter meaning, which is real but secondary to calling the tool 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 0% across 13 parameters, so the description carries the full burden. It does name several in prose (style, brand, language, resolution, slide counts, formats implied via the carousel rule) and explains the default behavior of omitted params, but roughly half — conversation_id, workspace_id, design_style_id, embed_logo, include_cta, embedding_photos, use_exact_content — are never mentioned, including the sole required 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 and resource — confirm and start a visual generation — and pins the precondition to an exact sentinel string returned by the chat tool ("READY TO GENERATE"). It is clearly distinguished from the chat sibling, which is named as the tool for re-planning design/content.

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

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

Explicit when-to-call (only after user reviewed and approved), explicit when-not (never re-call when slow), and an explicit alternative for a distinct case: format or content changes go back to chat, not to overrides here. It even states a hard constraint on the override path (carousel format requires carousel_counts).

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 non-read-only, open-world, non-idempotent, non-destructive, so the safety profile is covered. The description usefully adds that the result is returned as a downloadable URL rather than inline bytes, but says nothing about whether the converted file is persisted, whether repeated calls create duplicates, or any cost/latency implications.

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 action and output front-loaded and no padding. It is arguably too short rather than verbose, but nothing 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?

No output schema exists, and the description does cover the return (downloadable URL), which is the most important gap filled. However, with three undocumented parameters, no input constraints, and no mention of persistence or cost, an agent lacks enough to invoke it confidently beyond the happy path.

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

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

Schema description coverage is 0%, so the description carries full burden, yet it never mentions the 'quality' parameter (default 90) or its valid range, nor what form image_url must take. Only the format enum is discoverable from the schema itself; the description adds nothing about any of the three parameters.

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 ('Convert an image') with the target formats enumerated, which cleanly separates it from siblings like edit_image, upload_photo, and download_visual. It omits 'jpeg' though the schema enum accepts it, a small inconsistency an agent could trip on.

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 indication of when to prefer this over edit_image, export_visuals, or download_visual, and no preconditions (e.g., whether the source image must be hosted/accessible, or whether conversion consumes credits per the check_credits sibling). The agent must infer usage entirely.

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

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

Goes well beyond the annotations by disclosing credit cost (10/image, 15/carousel slide), the multiplicative count semantics, where artifacts land (user's Canvora workspace) and that URLs are returned. This makes the non-idempotent, cost-incurring, destructiveHint=true profile actionable rather than just flagged.

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 trigger words, then behavior, then semantics and cost, with labeled sections. Slightly long and the IMPORTANT/confirm_generation warning partially repeats the opening distinction, but nothing is padding.

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, yet the description covers return values (preview/downloadable URLs), persistence to the workspace, cost, and the visual multiplication rule. For a 2-parameter mutation tool this is sufficient to call correctly and set user expectations.

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

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

Schema coverage is 0%, so the description must carry the load and largely does: 'count applies PER VISUAL' with a concrete worked example (count=2 on 2 visuals yields 4 images) removes the main ambiguity, and the tool's purpose makes generation_id self-evident. Minor gap: no note on valid generation_id sources or bounds on count.

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

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

States a specific verb+resource (create variations of an existing generation) and immediately separates itself from the two most confusable siblings: 'creating a new generation' and confirm_generation. An agent can route correctly from the first two sentences alone.

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

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

Gives explicit triggering language ('variations', 'alternatives', 'different versions', 'more options') plus a hard exclusion ('Do NOT use confirm_generation for variations') and points to the dashboard per-visual option for the narrower case. When-to-use, when-not-to-use, and the alternative are all 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 readOnly, idempotent and non-destructive behavior. The description adds real value by clarifying that only a URL is returned (not the binary) and that the visual remains stored in the workspace — i.e., nothing is moved or deleted. It stops short of covering URL lifetime or auth requirements.

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

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

Three short sentences, front-loaded with the core action, then the return value, then storage semantics. Little waste, though the third sentence is slightly tangential.

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 tells the agent the return is a direct image URL, which is the key missing piece. However, for a two-parameter tool with 0% parameter documentation, the meaning of output_index and any URL expiry behavior are left unexplained.

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

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

Schema description coverage is 0% and the description does not compensate: 'a specific output' hints at output_index but never states that it is a zero-based index defaulting to 0, and nothing explains the expected generation_id format.

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: get the download URL for a specific output of a completed generation. This is distinguishable from get_generation (metadata) and export_visuals (bulk export), though the differentiation is implied rather than stated explicitly.

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

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

The phrase 'from a completed generation' implies a prerequisite, but the description never names alternatives such as get_generation or export_visuals, nor says when to prefer one over the other. Usage is inferable rather than 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 flag this as destructive, open-world and non-idempotent; the description adds genuine context beyond them by disclosing the refine-then-confirm flow, that out-of-scope edits are declined with a link to the editor, and that the artifact is persisted to the user's workspace and returned as a URL. It stops short of mentioning credit consumption or that a sibling (revert_edit) exists to undo a destructive edit, which would have completed the risk picture.

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 action, then cleanly organized into an operation bullet list, an exclusion note, the two-step flow, and an output note — each block earns its place. Slightly verbose in the closing sentence about accounts and brand kits, but 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?

For a nine-parameter destructive mutation with no output schema, the description covers the workflow, the safety gate, the scope limits and the return destination well. The one material hole is how to point the tool at an existing visual (source_image_url vs generation_id vs output_id), which no structured field explains and the description never addresses.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does well for the two required parameters — operation's four enum values are each defined with examples, and instruction is explained by analogy. But six of nine parameters (source_image_url, generation_id, output_id, output_index, format, and the instruction/confirmed_instruction relationship) are never explained, including the critical question of how the agent identifies which visual to 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?

States a specific verb ('Edit') and resource ('a visual in the user's Canvora workspace') and then enumerates the exact operation categories with examples, so an agent can tell this apart from convert_image, create_variation or localize_generation. It also explicitly bounds scope by naming what the tool will NOT do (subject/scene changes are declined), which is rare and useful.

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 per-operation selection guidance with concrete example instructions for each of the four enum values, states the mandatory two-step call sequence, and adds a hard procedural rule ('Always show the user the edit plan before confirming'). An agent has essentially no inference left to do about when and how to call it.

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

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

Useful additions beyond the annotations: the return value is a downloadable file URL, and the source visuals stay in the workspace, which supports the non-destructive read of annotations. But for an openWorldHint, non-idempotent export against an external account, nothing is said about credit consumption (despite a check_credits sibling), URL expiry, or repeated-export cost. The description adds context without covering the operational traits an agent would want.

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 purpose sentence followed by tightly scoped bullets; nothing is padded. Minor redundancy in listing the three formats in the header and then again as bullet labels, but each bullet adds decision-relevant guidance.

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 only two required params, no output schema, and no nested objects, the description covers the essentials: what comes back (a file URL) and what happens to source assets. It falls short on obtaining the generation_id, credit/cost implications, and the boundary with download_visual.

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

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

Schema coverage is 0%, so the description must carry the parameter meaning: it explains all three format enum values with use cases, which is exactly the missing information. generation_id is only implicitly defined as a 'completed generation' reference, with no hint on where to obtain it (get_generation/confirm_generation siblings), leaving half the parameter set partially specified.

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

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

A specific verb (export) plus resource (a completed generation) and explicit output formats, so the agent knows precisely what the tool produces. However, it never distinguishes itself from the sibling download_visual, which appears to overlap on retrieving generated assets.

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 'completed generation' precondition and the per-format guidance ('Ideal for LinkedIn carousel uploads', 'PowerPoint/Google Slides presentations', 'Bulk download all images as PNG') tell the agent which format to pick in which situation. No exclusions are stated and no alternative tool is named for cases where the generation isn't complete or the user just wants a single image.

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 useful behavioral context by explaining what the result contains: original version, applied edits, and current version.

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 no wasted wording. The core purpose and the key usage rule are front-loaded.

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

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

The description adequately explains the conceptual return value despite there being no output schema. However, for a tool with three undocumented parameters, it leaves the agent without enough information to choose or supply identifiers correctly.

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

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

The schema has 3 parameters with 0% description coverage and no required fields, yet the description does not explain what output_id, output_index, or generation_id mean or how they should be used. It therefore fails to compensate for the missing schema semantics.

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: get the edit history of a generated image. It also clarifies the return scope — original version plus every applied edit and the current version — and distinguishes it from the sibling revert_edit by tying its use to reverting.

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 a clear usage condition: 'Use before reverting an edit.' This explicitly links the tool to the sibling revert_edit, but it does not spell out when not to use this tool or name other alternatives.

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 (readOnly, idempotent, non-destructive), the description explains polling cadence, that outputs may arrive incrementally while processing, and that visuals persist in the Canvora workspace. These are meaningful behavioral details an agent needs.

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

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

The description is front-loaded with the core action and then layers on only actionable detail: ID behavior, polling guidance, incremental outputs, and storage context. Every sentence contributes useful information 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?

No output schema exists, but the description covers return values adequately: output image URLs when ready, incremental arrival during processing, and where visuals are stored. Combined with annotations, an agent has everything needed to call and interpret the 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 0%, so the description carries the full burden. It fully explains the only parameter: generation_id fetches that generation, while omitting it fetches the user's most recent generation, including the exact user phrasing this supports.

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

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

The description uses a specific verb and resource: 'Get the status and outputs of a generation.' It also differentiates the two modes (by ID vs. most recent), making the tool's purpose immediately clear relative to siblings.

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

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

It gives explicit when-to-use guidance: pass generation_id to fetch a specific generation, omit it to fetch the user's most recent generation, and poll after confirm_generation every 10-15 seconds until completed. This is unusually complete routing information.

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

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

Annotations already establish this as a safe, idempotent read operation. The description adds useful content detail by listing the returned brand attributes: names, colors, fonts, logos, and tone. It omits pagination or ordering behavior, but the tool has no parameters and the annotation set carries the safety profile.

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

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

The description is two compact sentences with no filler. The core action is front-loaded, followed immediately by return contents and a downstream usage hint.

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

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

For a zero-parameter list tool with no output schema, the description supplies exactly what an agent needs: what is listed, what fields are returned, and how the result is used with confirm_generation.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain. The description correctly does not invent parameter guidance and instead focuses on the returned data and downstream usage.

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 all brand kits in your Canvora account.' It further distinguishes the tool by naming the sibling confirm_generation as the downstream consumer of brand IDs.

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 explains the practical use case: retrieve brand IDs to pass to confirm_generation for branded styling. It gives clear context but does not explicitly state when not to use this tool or name a competing alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds the scale fact (100+ formats), which is genuinely useful context, but says nothing about pagination or response size despite implying a large catalog.

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, front-loaded with the action and the return fields before the usage routing. 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 correctly implies the return payload (format IDs, dimensions, categories), which is what an agent needs to chain into confirm_generation. The one gap is pagination or completeness behavior for a catalog advertised as 100+ entries.

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

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

Schema description coverage is 0%, so the description should carry the weight, but it never mentions the category parameter or that results can be filtered by it. The enum values are self-explanatory and the default is 'all', which limits the damage, but the filtering behavior itself is left entirely to inference.

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 available visual formats") and names exactly what comes back (dimensions and categories). It also distinguishes itself from sibling tools by routing the agent to confirm_generation for the follow-up action.

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

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

It gives an explicit reason to call it — finding the right format ID before calling confirm_generation — which is a clear use context, not implied. It does not state when not to use it (e.g. when an ID is already known), so it falls short of a full 5.

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

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

Annotations already declare this as a read-only, idempotent, non-destructive, closed-world operation. The description adds useful behavioral context beyond that: it returns workspace IDs, names, role, and credit balances, and using workspace_id switches credit usage from personal to workspace credits.

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

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

The description is three purposeful sentences: purpose and return values first, downstream usage second, default behavior last. There is no filler, and the most important routing information is front-loaded.

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

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

With no output schema, the description correctly explains what is returned. Together with annotations covering safety and the zero-parameter schema, it gives the agent everything needed to decide when to call this tool and how to use its output.

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

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

The tool has zero input parameters, so the baseline is 4. The description appropriately avoids discussing input parameters and instead explains how the returned workspace_id is used downstream.

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 your workspaces and personal account.' It clearly distinguishes the workspaces resource from sibling list tools such as list_brands and list_formats.

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 trigger ('when the user wants to generate visuals for a specific team or workspace') and a clear default path when no workspace is mentioned. It also names the downstream tools that consume workspace_id, so the agent knows how this tool fits into a 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?

Goes well beyond the destructiveHint/openWorldHint annotations: quantifies cost (10 credits per image per language, with a worked 6-slide example), caps languages at 10, explains that every visual in the generation is translated, and describes where output lands (Canvora workspace plus preview/downloadable URLs). It also discloses the async pattern: one generation ID returned per language, poll each with get_generation.

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, then cost, then the critical SEMANTICS/IMPORTANT blocks, so a skimming agent sees the routing rule. It is longer than average and repeats the translation scope (ALL visuals, single call) more than once, but every section carries operational value.

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

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

With no output schema, the description still explains the return shape (a generation ID per language, pollable via get_generation until 'completed') and the resulting artifacts. Cost, caps, side effects, and the sibling escape hatch are all present, so an agent can invoke it correctly without further inference.

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

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

Schema coverage is 0%, so the description must carry the load: it explains that languages is an array of one or more targets (150+ supported, RTL/CJK, max 10 per call) and that generation_id refers to a completed generation inside a chat, with guidance to disambiguate when several exist. It does not specify exact language code format (e.g. BCP-47 vs. names), which is the one gap.

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

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

States a specific verb+resource (translate the visuals of a completed generation into target languages) and immediately constrains it to in-place image-to-image translation of an existing generation. This clearly differentiates it from siblings like edit_image and create_variation.

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 exclusion path: for a single visual, do NOT use this tool, use edit_image with a translation instruction. It also says to ask which generation when multiple exist and to confirm target languages with the user before calling, covering the main ambiguity cases.

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?

Adds value beyond the annotations: the "Free — does not consume credits" cost signal is not in annotations, and the statement that the result stays in the Canvora workspace and is returned as a preview/downloadable URL discloses the output side-effect. Annotations already carry idempotent/non-destructive hints, and the description does not contradict them. It does not say what happens to the edit versions after a revert (still recoverable or discarded).

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: purpose first, then the cost signal, then the prerequisite, then the return shape. No filler or redundancy.

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

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

Return behavior is described in place of an output schema, which is good. However, with 0 required params and 0% schema coverage, an agent still cannot tell how to select between edit_id and generation_id, what output_index refers to, or what the default behavior is when no edit_id is supplied.

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

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

Schema description coverage is 0% and the description only implicitly covers edit_id ("find edit IDs"). It says nothing about generation_id or output_index, nor what passing a null/absent edit_id does relative to "revert to the original", which is central to correct invocation given all 3 params are optional.

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 resource (a generated image's edit) plus the two possible targets: a previous edit version or the original. This clearly separates it from edit_image (which creates a new edit) and get_edit_history (which reads history).

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?

"Use get_edit_history first to find edit IDs" gives an explicit prerequisite and names the sibling to call before this one. Missing is any statement of when NOT to revert (e.g. instead of re-editing), but the operational context is clear.

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

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

Annotations already disclose that this is a non-read-only, non-idempotent, non-destructive, open-world operation. The description adds useful behavior by explaining that it accepts base64 data and returns a CDN URL for embedding_photos, but it omits constraints such as file size, accepted formats, auth needs, and error 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?

The description is compact and front-loaded, immediately stating the upload action and then the return value and downstream usage. There is no redundant or filler content.

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

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

With no output schema, the description helpfully explains that the return value is a CDN URL to pass as embedding_photos. However, it remains incomplete regarding filename semantics and upload constraints, which is significant given the 0% schema description coverage.

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

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

Schema description coverage is 0% for two parameters. The description explains that data is a base64 photo, but it gives no meaning for filename or its expected format/role, so it only partially compensates for the schema gap.

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

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

The description states a specific verb and resource — uploading a photo — and explains its purpose: embedding photos into generated visuals. It also names the downstream use with confirm_generation, making the tool easy to distinguish from sibling tools like list_formats or get_generation.

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 usage context: photos are intended to be embedded in generated visuals and the returned CDN URL is passed as embedding_photos to confirm_generation. It also notes primary use by the setup widget, though it does not explicitly state when not to use it or name alternatives.

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