Canva

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds substantive context beyond them: the overwrite 'replaces its content and cannot be undone,' update_in_place is only available to some accounts and fails elsewhere, and exactly one source is required. This meaningfully enriches the safety and availability profile the annotations only gesture at.

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 usage, prerequisites, and return value in three tight paragraphs. Every sentence carries weight, though the dense multi-clause sentences are slightly heavy for the size of the operation.

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

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

For a complex mutation tool with nested objects and no output schema, the description covers prerequisites, source exclusivity, destructive in-place behavior, account limitations, and the return value (design_id). Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents each parameter, giving a baseline of 3. The description adds a genuine cross-parameter constraint ('Requires exactly one source') and data/schema-match requirement that the per-parameter schema text does not express, lifting it above baseline.

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: merge structured text/image/video/chart values into named autofill fields to populate a Canva design. It clearly distinguishes itself from siblings like create-design, create-design-from-brand-template, and copy-design by framing the operation as field-based merge rather than design creation.

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 enumerates when to use (merge a dataset/spreadsheet, place placeholders, populate an existing design, refill stale content), states the prerequisite (identify a Brand Template or design and confirm fillable fields), and gives a when-not-to-use exclusion ('Not for creating a blank Brand Template copy') plus the condition governing the in-place overwrite.

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

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

The description goes beyond the destructiveHint annotation by stating that unsaved changes are permanently lost and the transaction_id can no longer be used. It also mentions the return behavior ('confirmation that the changes were discarded'), which is useful 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?

The description is short, front-loaded with the core action, and every sentence adds relevant information. There is no filler or repetition beyond what is needed for clarity.

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 cancellation tool with a destructive annotation, the description covers what happens, the side effect on transaction_id, and the confirmation return. With no output schema, a bit more detail about the confirmation response could be useful, but the current description is sufficient for an agent to invoke 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 coverage is 100%, so the schema already explains transaction_id and user_intent. The description adds only minor context by calling the transaction 'active' and noting the ID comes from the start operation, but it does not materially improve parameter understanding beyond the schema.

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

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

The description clearly states the action ('Undo or discard all unsaved changes') and the specific resource ('active Canva editing transaction'). It also signals the opposite of saving, which differentiates it from the sibling commit-editing-transaction without needing to open that tool.

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

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

The description explicitly says when to use the tool: 'cancel a set of in-progress edits or finish editing without saving.' It does not name the commit sibling as the alternative for saving, but the context is clear enough for an agent to choose correctly.

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

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

Annotations only state readOnlyHint=false and destructiveHint=false. The description adds that the comment is visible to all design collaborators and that the call returns the created comment and comment_id, which is important side-effect and outcome information. It could mention permission requirements, but this is adequate.

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 with the core action, followed by use cases, visibility, and return value. Every sentence adds 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?

For a simple create tool with no output schema, the description covers main use cases, visibility, and return shape. A small gap is the absence of explicit guidance to use reply-to-comment when the user is responding to an existing comment, and it doesn't resolve the user_intent 'mandatory' wording in the 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 description coverage is 100%, and all three parameters have their own descriptions, so the tool description doesn't need to elaborate on them. It adds no new parameter semantics beyond implying the comment body is message_plaintext; 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 opens with a specific verb and resource: 'Leave a new comment on an existing Canva design.' It also clarifies scope by saying 'new comment' and 'visible to everyone who has access,' which distinguishes this top-level comment action from sibling tools like reply-to-comment.

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

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

It explicitly lists when to use the tool: giving feedback, asking a question, flagging an issue, or adding context for collaborators. It doesn't mention exclusions or direct the agent to reply-to-comment for responses to existing comments, so it falls 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?

Annotations already flag destructiveHint: true, so the description adds value by disclosing the concrete consequences: 'apply all draft changes to the design, closes the editing transaction, and makes its transaction_id invalid.' It also mentions return behavior ('Returns confirmation'). This goes beyond the annotation without contradicting it.

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 sentences, each earning its place: purpose, use case, approval requirement, and operational effect. Front-loaded with the main action. No redundancy or 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 destructive mutation with two well-documented parameters and no output schema, this description covers purpose, usage gating, behavioral consequences, and return confirmation. It could mention error scenarios (e.g., already-closed transaction) but that is a minor omission given the clarity provided.

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 clear descriptions for both parameters: transaction_id is 'Exact ID of the active editing transaction' and user_intent is described. The description adds no new parameter-specific details beyond restating that the transaction is active and that the id becomes invalid—context already implied by the schema's phrasing. Baseline 3 is appropriate.

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

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

States a specific verb ('make permanent'), resource ('all draft changes in an active Canva editing transaction'), and scope ('text, layout, or media updates'). Clearly distinguishes from sibling cancel-editing-transaction by describing the permanent save action and from start-editing-transaction by implying an existing transaction.

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 instructs when to use it ('to save a completed set of edits') and provides a mandatory precondition: 'Show the user a preview of the design and obtain their explicit approval before calling this tool.' This gives the agent clear decision and action guidance, including a human-in-the-loop step.

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

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

Annotations are all false with no hints about effects, so the description carries the burden. It clearly states that the tool creates a new design, leaves the source unchanged, and returns the new design_id. This meaningfully explains the behavioral outcome beyond 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?

The description is concise and well-structured: the core action is in the first line, usage scenarios follow, and the key side-effect/result is stated last. Every sentence earns its place 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?

For a low-complexity tool with a fully documented schema and no output schema, the description covers what the tool does, when to use it, what it creates, the source immutability, and the returned design_id. Nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents design_id and page_numbers thoroughly. The description adds a small hint by mentioning 'copy selected pages', but does not go beyond the schema's explicit parameter documentation.

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 ('Duplicate') and resource ('existing Canva design'), and explains the page-selection variation. It distinguishes itself from siblings by explicitly stating it is not for combining pages from more than one design, setting it apart from merge-designs.

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

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

The description explicitly lists when to use the tool: making a separate working copy, cloning, forking, backing up, or preserving the original. It also gives clear exclusion criteria: single source design only and not for combining pages from multiple designs.

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, openWorldHint=false, so the mutation profile is covered. The description adds genuinely useful non-obvious behavior: idempotency (an existing draft is returned rather than a new one created) and the draft's editability/publiability. No auth or rate-limit context, but the key behavioral trait is disclosed.

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

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

The core purpose and idempotency constraint are front-loaded in the first two sentences, and the numbered workflow is scannable. The workflow list is somewhat long but each step carries distinct routing value, so little 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?

With no output schema, the description compensates by telling the agent that a design ID is returned and consumed by start-editing-transaction. Annotations cover the safety profile, so the combination is nearly complete; only the relationship to create-design-from-brand-template is 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 description coverage is 100% and both parameters are documented in the schema (brand_template_id even points to search-brand-templates). The description adds no additional semantics for brand_template_id or user_intent, 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 (creates an editable draft design from a brand template) and adds the key behavioral distinction that the draft can be edited and published back. It does not explicitly contrast itself with the similarly-named sibling create-design-from-brand-template, so sibling 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?

Explicitly states when to use it ('to get a design that can be edited and later published back') and provides a full ordered workflow naming the alternative tools (start-editing-transaction, perform-editing-operations, commit-editing-transaction, publish-brand-template) for the Autofill/tagging case. Nothing is left to guesswork.

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, destructive=false, openWorld=true; the description adds substantial context beyond them — that it creates rather than edits, that it returns job_id and continuation_token, and the exact polling protocol including who polls (widget vs. caller) and the wait_seconds cadence.

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?

Long but front-loaded: the core purpose and the image-vs-design disambiguation come first, followed by routing and polling detail. A few clauses restate the same routing rule (image wording priority is illustrated with two near-identical examples), which trims it below a 5.

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

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

Complete for a high-complexity generation tool with nested parameters and an output schema: it covers scope, exclusions, sibling routing, and the async job lifecycle an agent must drive, despite the output schema already existing.

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 brief, format, outline, and user_intent are already fully documented in the schema, including the format-orientation caveat. The description only gestures at this with 'with any supplied content folded in', so it adds no meaning beyond the structured fields — 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?

Opens with a specific verb+resource ('Generate a new Canva design from a written brief') and immediately enumerates the output types it produces, then differentiates itself from generate-image, the brand-template tools, and legacy generation tools by name.

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

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

Gives explicit when-to-use ('turn a brief, presentation outline, or draft copy into ...'), explicit when-not (on-brand requests, image/vector wording, editing existing designs, videos/whiteboards), and names the alternative tool for each exclusion, including fallback ordering ('prepare-design-generation where it is listed, otherwise generate-design or generate-design-structured').

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

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

Annotations already indicate this is a mutating operation (readOnlyHint=false, destructiveHint=false), so the description doesn't need to restate that. The description adds useful context about page selection and the direct-call behavior, but it doesn't disclose what happens if the template ID is invalid, whether the design is created in a specific folder, or what the response contains. With annotations covering the basic safety profile, a 3 is appropriate.

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

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

The description is compact and front-loaded: the core action is stated first, followed by the optional behavior, then the routing guidance. Every sentence earns its place, and the guidance is actionable without being verbose.

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 creation tool with no output schema, the description covers the main decision points: when to call directly, when to search, and when to use autofill. It doesn't describe the return value or error cases, but the routing guidance and parameter semantics are strong enough that an agent can invoke the tool correctly in most scenarios.

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 all three parameters. The description adds context for `page_numbers` (optional, 1-based, omit for all pages) and `brand_template_id` (direct-call behavior), but it doesn't add meaning beyond what the schema already provides. Baseline 3 is 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 states a specific verb ('Create') and resource ('a new Canva design from a brand template'), and explicitly distinguishes itself from the sibling `search-brand-templates` and `autofill-design`. It also clarifies the optional page selection behavior, making the tool's purpose unambiguous.

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

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

The description provides explicit when-to-use guidance: call directly when a brand template ID is already known, do NOT call `search-brand-templates` first, and use `autofill-design` instead when custom data needs to be filled. This is strong routing guidance that leaves little to inference.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation profile is covered. The description adds context beyond annotations: the create-then-edit sequential workflow (call this first, then use returned design_id with start-editing-transaction and editing tools), and the requirement to obtain candidate_id from generate-design results. It does not contradict the annotations.

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

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

The description is longer than average but every block earns its place given the complex routing requirements. The 'LEGACY-ONLY' warning and brand exception are front-loaded before the core workflow. Slight redundancy exists (the DO NOT CALL constraint is stated twice), and the routing block could be tightened, but the structure is effective and information-dense rather than 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 tool in a 33-sibling ecosystem with no output schema, the description handles the return value itself ('design summary containing a design ID') and the cross-tool sequencing with generate-design and start-editing-transaction. One minor gap: the routing condition references create-design, which is not actually present in this tool list — the conditional is somewhat hypothetical here, though the description does gracefully state it applies 'when create-design is absent from the tool list.'

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 adds value beyond the schema by explaining the provenance of both job_id and candidate_id ('returned in the generate-design response') and the ordering requirement linking them to the generate-design pipeline. This ties each parameter to its upstream source, which the schema alone does not convey.

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

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

States a specific verb and resource — 'Create a new Canva design from a generation job candidate ID' — and clarifies the mechanism: 'converts an AI-generated design candidate into an editable Canva design.' This distinguishes it from generate-design (which produces candidates) and create-design-from-brand-template (brand-templated variants), so an agent can separate it from siblings 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?

Exceptionally explicit routing: it names the preferred alternative (create-design), forbids calling this tool when that alternative is present, and carves out a precise brand exception ('brand kit, brand colours, fonts or logo, brand template'). It also notes that a failed create-design call does not make this tool available. This is textbook when-to-use vs when-not-to-use guidance.

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

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

Annotations already indicate this is a non-read-only, non-destructive mutation. The description adds useful behavioral context by stating that it returns the new folder including its folder_id. It does not discuss permissions or edge cases, but the annotation coverage lowers the burden.

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 concise and front-loaded with the core action. The use-case sentence adds value, though 'keep designs, images, and folders together' slightly overlaps with 'organise related work'. Overall, every sentence earns its place.

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

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

For a simple create operation, the description covers purpose, use cases, and the return value. Since there is no output schema, mentioning the returned folder_id is helpful. The 'root' special value for parent_folder_id is already covered in the 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 description coverage is 100%, so the parameters are already well documented. The description does not add significant parameter-level meaning beyond what the schema provides, which makes the baseline score of 3 appropriate.

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

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

The description uses a specific verb and resource: 'Create a Canva folder'. It clearly states the purpose ('organise related work') and is distinct from sibling tools like search-folders, list-folder-items, and move-item-to-folder.

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

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

It provides clear context for when to use the tool: setting up a project folder, adding a subfolder, or keeping related items together. It does not explicitly name alternatives or exclusions, but the use cases are specific enough for an agent to select it correctly.

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

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

Discloses non-obvious behavior well beyond annotations: URL is single-use, expires after a short period, must be consumed with a raw octet-stream POST, must not be retried, and returns resource IDs. This is exactly the kind of operational detail an agent needs and annotations do not provide.

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

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

Well-structured and front-loaded, with a clear purpose statement followed by Step 1/Step 2 instructions. The first sentence is somewhat long with enumerations, but every part contributes useful guidance for correct invocation.

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

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

Covers the full workflow: call this tool, POST raw bytes, handle the response, retry policy, and exclusion of public-URL files. The presence of an output schema means return-value details need not be spelled out, and the description still mentions resource IDs returned by the POST.

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 only parameter, user_intent, is fully documented in the schema with 100% coverage, so the description does not need to repeat it. The description adds context about the broader workflow, but not parameter-level meaning beyond the schema.

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

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

States a concrete action: creating a single-use upload URL for files whose bytes the user can access, then uploading those bytes to Canva. It clearly distinguishes itself from URL-import alternatives, which are for files already at a public URL.

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 says when to use this tool ('when the user wants to add, upload, import, or send a file they have') and when not to ('for a file already at a public URL, prefer a URL-import tool'). It also provides retry guidance, which is essential for correct use.

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 the safety profile (not read-only, openWorld, non-destructive), and the description adds substantial behavior beyond that: the AI-limit consumption heads-up, the per-call approval requirement, forbidden topics (remaining limit, estimates, prices, upgrades), and the returned job_id/polling_policy. This is unusually rich behavioral disclosure.

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 usage, then user-facing policy, then return values. It is longer than typical but each block earns its place against the tool's complexity; some wording is duplicated in the confirmation parameter description, a minor redundancy.

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

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

For a high-complexity creation tool with a deep nested schema, existing annotations, and an output schema, the description covers the preconditions (guide selected, assets ready), the approval gate, and the async follow-up, which is everything an agent needs to call it correctly.

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

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

Schema description coverage is 100% and the schema already documents every field exhaustively (production_spec, video_title, video_generation_confirmed). The description adds no syntax or semantic 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 ("Produces a Canva video") and names the input artifact ("a complete production specification"). The precondition "when a production guide has been selected" implicitly separates it from siblings like generate-design and generate-image, but no sibling is named directly, so differentiation is contextual rather than 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?

Gives a concrete when-to-use condition ("a production guide has been selected and its required inputs and assets are available") and a hard when-not gate ("Only call after the user has approved"). It spells out the exact approval and disclosure flow, including the first-call vs later-call distinction, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real behavioral value beyond that: it states the format-support prerequisite and discloses the return value (a download URL), which the 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 sentences, no filler: purpose first, usage triggers second, prerequisite and return value last. The trigger list is longer than one clause but every item is a distinct, useful signal, so 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?

There is no output schema, and the description compensates by stating it returns a download URL. With a fully-documented nested parameter schema and annotations covering safety, an agent has everything needed to decide and invoke 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 the schema fully documents design_id, format, and the nested export settings including size, pages, width/height, and quality. The description mentions 'selected pages' and 'another file type' but adds no syntax or format 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 (export) and resource (an existing Canva design) plus the outcome (a downloadable file to use outside Canva). It is clearly the export/output tool in a sibling set that otherwise covers editing, listing, and format discovery, so an agent can distinguish it 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?

Enumerates concrete when-to-use triggers (printing, email attachments, sharing as a file, format conversion, selected pages) and adds a prerequisite: confirm the design supports the requested format first. It stops short of explicitly naming get-export-formats as the alternative/discovery tool, so the routing hint is implied rather than stated.

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

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

Annotations cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), yet the description adds substantial non-obvious behavior: latency scaling with slide count, that the tool has no memory of prior requests, that output is design candidates not persisted designs, that URL IDs are not design IDs, and that 'Common queries will not be generated' is a detail-seeking signal. This is rich context well beyond the annotations.

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

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

The critical routing constraint (LEGACY-ONLY, brand exception) is correctly front-loaded, but the definition balloons into a full slide-plan authoring template and self-check checklist that dwarfs the actual tool contract. Much of that guidance is prompt engineering rather than tool selection help, diluting the signal.

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

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

For a 7-parameter, no-output-schema generation tool, the description covers inputs, return shape (candidate id, thumbnail, url), the required follow-up sequence (create-design-from-candidate then design_id-based tools), and failure signals. Nothing an agent needs to invoke and chain 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 the baseline is 3, but the description adds meaningful semantics: query must carry prior context and detailed instructions, asset_ids insertion order maps to slide order, extra slides cost latency, and brand_kit_id requires an explicit user confirmation flow via list-brand-kits. These add value beyond the already-complete schema.

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

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

States a specific verb and resource: 'Generate professionally designed content in Canva including visual designs... and text-based documents.' It goes further by naming the exact sibling it competes with (create-design) and the conditions that select each, so an agent can distinguish 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?

Explicit when-to-use ('write, create, generate, or draft ANY document or visual design'), when-not (advice/explanation only, URL import via import-design-from-url, fixed-format designs via prepare-design-generation), and named alternatives (create-design, import-design-from-url, create-design-from-candidate). The brand-kit exception and legacy-override rules are unambiguous.

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=true, idempotent=false), and the description adds substantial context beyond them: it returns only a jobId, the widget polls get-generate-image-job so the agent should not poll itself, upload URLs are single-use, and attachments must be uploaded first. This is a rare case of rich behavioral disclosure.

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 long, but well front-loaded with bolded section headers (When to use / When not to use / Image references / Result) and every section carries non-redundant instructions. It is appropriately sized for a tool with a multi-step upload-and-poll workflow, though some prose could be tightened.

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

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

Given the high complexity and the existence of an output schema, the description still supplies the missing operational context: the async jobId flow, widget-driven polling behavior, and the upload prerequisite. Nothing an agent needs to call and follow up 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 coverage is 100% so the baseline is 3, but the description goes further on imageReferences: one MEDIA entry per successfully uploaded attachment, never combine IDs, never pass an upload URL, omit entirely for text-to-image. This is workflow semantics the schema cannot express, though much still lives in the schema's own aspectRatio documentation.

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

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

The opening sentence states a specific verb and resource ('Generate a standalone image from a text prompt, or edit/restyle images supplied as references') and explicitly distinguishes the tool from the sibling create-design, including the edge case 'Create an image of an infographic' vs 'create an infographic'. An agent can select it 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?

It provides explicit when-to-use and when-not-to-use sections, names the alternative tool (create-design) with the precise condition that selects it, and clarifies that the verb 'create'/'design' alone does not route to create-design. Nearly every selection ambiguity is pre-resolved.

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

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

Annotations already convey readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it guarantees 'Returns the metadata and thumbnail for each item in the same order as the supplied asset_ids,' which informs the caller about output ordering. This is a meaningful behavioral trait not implied by the schema or annotations.

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

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

The description is compact yet comprehensive. It opens with the core purpose, then the usage context, then exclusions, and finally the return behavior. Each sentence earns its place without redundancy, making it easy for an agent to parse quickly.

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 must delineate the return value. It states the tool returns metadata and thumbnails and preserves input order, which covers essentials. While it does not enumerate each metadata field in the response structure (e.g., exact JSON shape), it lists the fields in the opening sentence. Given the tool's read-only nature and the schema's thorough parameter descriptions, it is sufficiently complete 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%, and the schema already provides detailed descriptions for both parameters. 'asset_ids' includes guidance on usage ('When checking which media is the target on a page, include every image and video ID from that page'), and 'user_intent' is clearly mandatory. The description adds little beyond the schema, so a baseline score of 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 explicitly states the resource (images and videos in a Canva design) and the exact fields returned (names, tags, types, creation dates, thumbnails). It also differentiates from siblings by stating it is 'Not for design metadata or editing the media itself,' making it distinct from get-design-content and perform-editing-operations.

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

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

The description provides clear usage context: 'Use when you need to check which image or video is the target on a page, look up its details, or preview it before changing it.' It also gives exclusions: 'Not for design metadata or editing the media itself.' However, it does not explicitly name alternative tool names (e.g., get-design-content or perform-editing-operations), so the guidance is strong but not fully explicit about 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?

Annotations already state readOnlyHint and destructiveHint, so the description correctly avoids repetition. It adds value by disclosing return behavior ('Returns each field's name and data type') and the edge case ('An empty object means...'). It also states the requirement for a brand_template_id, though the param name mismatch with schema is a minor flaw.

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

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

The description is organized into three short paragraphs: purpose, usage, and return details. It is front-loaded with the core action and avoids excessive fluff, though the second paragraph could be merged with the first for tighter structure.

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 read-only tool with one required param, the description covers the return format and the empty-object case. It also clarifies scope ('Not for an individual existing design'). The only notable gap is the param name inconsistency ('brand_template_id' vs 'template_id'), which could confuse an agent.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters. The description adds no additional parameter-level meaning beyond restating that 'brand_template_id' is required, which actually conflicts with the schema's 'template_id' naming. This does not improve on schema coverage.

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

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

The description clearly states the tool's purpose with a specific verb ('Determine... list') and resource ('Brand Template'). It explicitly differentiates from sibling tools by noting 'Not for an individual existing design,' which sets it apart from get-design and similar tools.

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

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

The description provides clear usage scenarios ('Use to check if the template can be populated with data...') and an exclusion ('Not for an individual existing design'). It does not name a specific alternative sibling, but the guidance is sufficient to route the agent appropriately.

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 establish it is a safe read. The description goes well beyond that: it discloses the polling cadence contract, the requirement to relay polling_policy.instructions to the user, and precise conditional rules for exposing print.is_printable/print_url versus staying silent. This is rich, non-obvious behavioral context.

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

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

Front-loads the core polling purpose in the first sentence and keeps sentences purposeful. The print conditional block is dense and long but each clause carries actionable logic, so it earns its space despite the overall 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?

With an output schema present, return values need not be explained, and the description instead supplies the missing operational contract: polling intervals, instruction relaying, and the exact print-eligibility branch. Nothing an agent needs to poll and report 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 the baseline is 3. The description adds meaning by clarifying that continuation_token must be the updated value from the most recent response and that job_id is stable, which is useful sequencing context the schema alone does not convey.

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

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

States a specific verb and resource ('Gets the status and result of a design generation job') and names the originating sibling, create-design. An agent can distinguish this polling tool from create-design or other get-* jobs 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?

Explicitly defines the call sequence: pass job_id and continuation_token from the previous create-design/get-async-job response, wait polling_policy.wait_seconds, then re-poll with the updated token. It also states a negative rule ('Never poll sooner') and routes print behavior conditionally, so the when/when-not is fully specified.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds useful behavioral context: it returns metadata and access links only, does not summarize content, and does not provide per-slide thumbnails. This goes beyond the annotations by clarifying the scope of what the tool can and cannot do, while remaining consistent with the read-only nature.

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

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

The description is well-organized and front-loaded: it starts with what is returned, then gives usage scenarios, then explicit exclusions. It is slightly verbose in repeating the metadata list and final 'Returns metadata' line, but every sentence earns its place and the structure aids comprehension.

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 compensates by enumerating the returned fields (type, title, owner, links, thumbnail, timestamps, page count) and explicitly stating limitations. It lacks details on error conditions or permission requirements, but for a read-only lookup tool with rich annotations and sibling context, this is adequate.

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 the schema already providing detailed semantics for design_id (including URL acceptance and shortlink caveat) and user_intent. The description adds minimal parameter-level meaning beyond 'one existing Canva design,' so the baseline of 3 is appropriate since the schema carries the parameter documentation 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?

The description states a specific action ('Look up the record for one existing Canva design') and explicitly enumerates the metadata returned: design type, title, owner, links, thumbnail, timestamps, page count. It also distinguishes itself from siblings by explicitly stating it is not for folders, image assets, text content, or per-slide thumbnails, which clearly separates it from get-design-content, get-design-pages, and get-design-thumbnail.

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

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

The description gives clear use cases ('open a specific design, find out who created it, check when it was last changed, or see how many pages it has') and explicit exclusions ('Not for folders or image assets. Do not use for reading or summarizing a design's text or for per-slide thumbnails'). It does not name the specific sibling tools to use instead, but the guidance is clear enough for correct selection.

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 read-only, non-destructive, closed-world. The description adds legacy gating, brand exception, and internal-only status, which are valuable behavioral constraints beyond annotations. It does not detail return format or polling behavior, but with annotations covering safety this is strong.

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 critical warning is front-loaded, but the description repeats the create-design availability rule and ends with the actual purpose ('Internal tool for widget UI polling') rather than leading with it. 'All instructions below' is inaccurate since only one sentence follows. Adequate but could be tighter.

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

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

Given the routing complexity, the description covers when to use, when not to use, the brand exception, and the failed-call caveat. It lacks return-value detail, but for a polling tool with no output schema the routing completeness is the priority, and it largely delivers.

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 fully documented in the schema. The description adds no parameter meaning beyond 'Poll that job' and does not mention user_intent. Baseline 3 is correct 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 it is a legacy-only internal polling tool and distinguishes from create-design and get-create-design-async-job. However the core resource is never named: it does not say it retrieves design candidates or what a 'design candidate' is, so the agent must infer from the tool name.

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-not: do not call when create-design is available; call get-create-design-async-job instead. Gives the brand exception and clarifies that a failed create-design call does not make it unavailable. Very strong 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 and destructiveHint=false, and the description reinforces this with "for read-only use" and "without making changes." It adds behavioral exclusions beyond annotations: it does not return presenter notes, sheet cell data, or non-text content, and it returns content per page or specified pages.

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 with the core action, followed by use cases and exclusions. There is minor repetition of the read-only idea ("read-only use" and "without making changes"), but every sentence contributes useful 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?

Given the tool's moderate complexity bugschema richness, the description covers purpose, scope, exceptions, and return scope. There is no output schema, but the description states that rich text for every page or specified pages is returned. No critical call-blocking information 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%, so the schema already documents design_id, pages, content_types, and user_intent in detail. The description adds no new parameter-specific meaning, but none is needed because the schema carries the burden completely.

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 starts with a specific verb and resource: "Extract rich text from an existing Canva design for read-only use." It clearly distinguishes this from editing tools and from related retrieval tools by explicitly excluding presenter notes and non-text content, so an agent can tell it apart from siblings like get-presenter-notes and perform-editing-operations.

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

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

The description gives a clear "Use to" list (read wording, pull copy, summarize, quote) and a clear "Not for" list (rewriting, translating, correcting, updating). It does not explicitly name alternative sibling tools in the description text, but the when/when-not guidance is strong enough to steer an agent away from misuse.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is handled. The description adds genuine behavioral context beyond that: it returns each field's name and data type, and an empty object signals the design cannot be autofilled. That return-shape disclosure is valuable and not in 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?

Front-loaded with the core behavior, then usage, then exclusion, then requirements and return shape. Every sentence carries information, though the three near-synonymous use-case phrases are slightly redundant.

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

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

Despite having no output schema, the description fully specifies the return value (field names and types) and the critical edge case (empty object = not autofillable), which is the main thing an agent needs to interpret the result. Nothing essential is missing for a 2-param read tool.

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

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

Schema coverage is 100%, so both parameters (including user_intent) are already documented in the schema. The description only restates 'Requires a design_id' without adding format or constraint detail 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?

The description states a specific verb (verify/list) and resource (fillable data fields of a selected existing Canva design), and explicitly distinguishes itself from the sibling get-brand-template-dataset with 'Not for a reusable Brand Template.' An agent can tell exactly what this returns.

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 three concrete use cases ('see whether a specific past design can be populated,' 'understand if an existing design can be autofilled,' 'see the fields available') plus an explicit exclusion for Brand Templates. Both when-to-use and when-not-to-use are covered.

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 mark the tool read-only and non-destructive, and the description adds valuable behavioral context beyond that: thumbnails do not reflect uncommitted editing-transaction changes, only the requested pages are returned, and the total page count is not included. This sets accurate expectations without contradicting the annotations.

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

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

The description is front-loaded with the core action, followed by use cases, exclusions, and return limitations. Every sentence earns its place, and there is no redundant restating of the tool name or 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 read-only list operation with no output schema, the description sufficiently explains what the agent will get (page index and thumbnail), what it will not get (total page count), and when it is not appropriate. Combined with fully documented parameters and annotations, the agent has enough context to call it correctly.

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

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

Schema description coverage is 100%, so the parameters are already well documented; the description adds little parameter-specific detail beyond the notion of ranges and requested pages. Per the baseline for full schema coverage, a 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 opens with a specific verb and resource: 'List the pages in an existing Canva design' and specifies the returned content (page index and thumbnail). It clearly distinguishes itself from sibling get-design-thumbnail by focusing on per-page previews, and it narrows applicability with 'Canva Docs do not have pages.'

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

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

It provides explicit use cases ('browse a design's pages or slides, see each page thumbnail in order, show what a specific page looks like, or get a range of page previews') and explicit exclusions ('Do not use to retrieve a thumbnail that reflects uncommitted changes...' and 'Canva Docs do not have pages'). This tells an agent when to choose the tool and when to avoid 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?

Beyond the readOnlyHint and destructiveHint annotations, the description adds valuable behavioral context: one-call-per-page, dependence on an editing transaction, and the non-negotiable instruction to show every thumbnail preview to the user. No contradiction with annotations 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?

The description is front-loaded with the core purpose and keeps the needed operational details in a compact sequence. The all-caps emphasis is redundant in wording but serves a real functional purpose, so the length remains 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?

The description covers the prerequisite workflow, the one-page-per-call constraint, and the required user-facing display behavior. It does not describe the exact response payload, but the absence of an output schema is mitigated by the clear instruction to show the returned thumbnail preview.

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

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

The input schema already provides full descriptions for transaction_id and page_index, including the one-based indexing rule and the exact source of the transaction ID. The description mostly restates these requirements without adding deeper semantic meaning beyond what the schema already provides.

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

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

The description clearly states the resource and action: getting the thumbnail for a specific page of a design within an editing transaction. It distinguishes this from sibling tools like get-design-pages or get-design by focusing specifically on thumbnail retrieval tied to a transaction ID and page index.

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

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

The description explicitly specifies the prerequisite of using start-editing-transaction to get the transaction ID, and clearly states that each call retrieves one page's thumbnail. It does not name alternatives or exclusions, but the context is unambiguous and actionable.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact: thumbnails are 'minted on demand' (i.e. lazily generated), plus the per-page return shape. It says nothing about latency, cost, 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?

Two short fragments with little waste, and the scoping fact ('one thumbnail per page') is present. But the lead clause 'Internal tool for widget UI' consumes the most prominent position without telling the agent anything actionable, and the whole thing is under-specified rather than 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?

No output schema exists, so the description should explain the return shape, and it only partly does ('one thumbnail per page'). For a read tool with three parameters and a near-identical sibling, the absence of any disambiguation or return-format detail leaves the agent guessing about when and how to call it correctly.

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

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

Schema description coverage is 100%, so design_id, limit and user_intent are already documented in the schema, including the limit default and max. The description adds no syntax or format detail beyond that, 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 the resource and its granularity ('one thumbnail per page of a design'), which is more specific than the bare name. However, it never names the singular sibling get-design-thumbnail, so an agent cannot tell which of the two to pick, and the opening 'Internal tool for widget UI' obscures rather than clarifies the purpose.

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?

'Internal tool for widget UI' hints at a restricted audience but gives no when-to-use condition, no prerequisites, and names no alternative. The critical choice against get-design-thumbnail (singular) is left entirely 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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that the tool discloses per-format page availability, but says nothing about auth requirements, rate limits, or how results should be consumed versus export-design. With annotations carrying the behavioral burden, this is adequate 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 well-structured sentences that are front-loaded with the action, then the usage condition, then the return content. The format enumeration is long but functional; no significant waste.

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

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

For a read-only discovery tool with no output schema, the description explains what is returned (supported formats plus available page numbers per type). Parameters are documented in the schema, so the agent has enough to invoke correctly, though the relationship to export-design remains implicit.

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 both parameters (design_id, user_intent) are already fully documented in the schema. The description adds no syntax, format, or constraint detail beyond what the schema provides, so the baseline 3 is appropriate.

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

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

States a specific verb and resource: checking which export file types a design supports and which pages are available per type. The resource is clearly identified (a Canva design's export formats). However, it does not differentiate from the sibling export-design, which performs the actual export, leaving the boundary between the two 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?

Gives clear triggering context: 'Use when a design needs exporting or downloading as a PDF, PNG, JPG...' and when only some pages are needed in a chosen format. It stops short of naming the alternative (export-design) or stating when NOT to use this tool, so the guidance is contextual but not fully routing.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial behavioral context beyond them: the polling cadence, the widget self-invocation caveat, the retry-when-link-not-ready case, and the required user-facing output formatting. This is real operational guidance the schema 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?

Long, but nearly every sentence carries non-redundant behavioral instruction (widget handling, polling, output formatting). Front-loaded with the core purpose. Slightly repetitive around the 'Open generated image' requirement, which is reinforced twice, costing a point.

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 a status-polling tool with an output schema, annotations, and a fully documented schema, the description covers the genuinely ambiguous parts – when to call, how to poll, and how to render results. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description goes further by tying jobId to its origin (returned by generate-image) and requiring the same jobId be reused across polls, which adds sequencing semantics the schema alone does not convey.

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

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

States a specific verb+resource: checking the status of an image generation job started by generate-image. It clearly distinguishes itself from the sibling generate-image (which starts jobs) and from other job-status tools like get-create-design-async-job.

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?

Extremely explicit routing rules: do not call when the UI widget is shown; call only when no widget is shown and pass jobId from generate-image; poll while PENDING; stop on SUCCESS or FAILURE; do not start a replacement job unless the user asks. When/when-not/alternatives are all covered.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds meaningful behavioral context beyond annotations: that only the separate notes are returned, not slide content, and that results cover every page or only requested pages. No contradiction with annotations 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?

Three tightly organized paragraphs: purpose first, use cases and exclusions second, return behavior last. Every sentence earns its place, and the most decision-relevant information (read-only, scope boundary) is front-loaded. No filler or repetition of schema details.

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

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

For a read-only retrieval tool with a single required parameter and no output schema, the description covers what the agent needs: the target resource, the return scope (notes per page), and how to limit to specific pages. Minor omissions like behavior when a slide has no notes or note format are acceptable given the tool's simplicity and supporting annotations.

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 all three parameters (design_id, pages, user_intent) already documented, including one-based page numbering and default all-pages behavior. The description's final sentence reinforces the pages semantics ('from every page, or the specified page numbers') but adds little beyond what the schema already 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?

The description states a specific verb and resource ('Get presenter notes from an existing Canva presentation') and explicitly differentiates from siblings with 'Not for reading the presentation itself; this only returns the separate notes attached to each slide.' This unambiguously separates it from get-design, get-design-content, and get-design-pages without needing to open their schemas.

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

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

The description gives clear when-to-use scenarios ('reviewing speaker notes, pulling talking points for particular slides, or summarizing notes across a presentation') and an explicit exclusion ('Not for reading the presentation itself'). It stops short of naming the specific alternative tool to use for presentation content, so it misses full 5-level routing, but the boundary is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: the polling cadence constraint and the requirement that tokens come from the most recent response. It stops short of describing pagination or error behavior, but this is a solid addition over 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?

Front-loaded with the verb and resource, followed by the call constraints and the return summary. Every sentence carries information; slightly wordy but no filler that could be cut without losing 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?

An output schema exists, so return values need not be spelled out, yet the description still notes the completed design and shareable url. Combined with the polling and token-sourcing constraints, 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 description coverage is 100%, so all three parameters are already documented, and the description adds no per-parameter syntax. It does clarify that both job_id and continuation_token must be sourced from the most recent response, but user_intent is never mentioned. Baseline 3 is appropriate 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 ('Check the status and result') plus resource ('image layer-separation job'), and explicitly ties itself to the separate-image-layers sibling that starts the job. An agent can distinguish it from that sibling 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?

Explicitly says to only call with the job_id and continuation_token from the most recent separate-image-layers or get-separate-image-layers-job response, and never before polling_policy.wait_seconds have elapsed. It also frames the tool as an internal lifecycle action rather than a user-selectable one, leaving nothing to inference.

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

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

Despite annotations already declaring a safe read, the description adds substantial behavioral context: automatic polling stops after 20 minutes, video may appear before preview_url, preview/download links can expire, and a delayed response means generation may still be running. This is far beyond what readOnlyHint/non-destructive 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?

Long but dense and front-loaded, with each sentence carrying an operational rule. The only mild redundancy is restating the no-early-poll rule with its rationale, which is arguably justified for a polling contract.

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 polling tool with rich annotations and an output schema, the description supplies everything the agent needs – polling cadence, timeout, error/delay handling, and what to relay to the user – so nothing required for correct invocation 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 is 3, but the description adds lifecycle meaning beyond the schema: job_id is stable across calls while continuation_token is the *updated* token from the most recent response, clarifying how the two must be passed together.

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 ('Gets the status and result of a video generation job') and explicitly ties it to the create-video producer, which cleanly separates it from sibling job-polling tools like get-generate-image-job and get-create-design-async-job.

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

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

Gives explicit when-to-use and how-to-use rules: pass the job_id/continuation_token from the prior response, wait polling_policy.wait_seconds before re-polling, never poll sooner, follow polling_policy.instructions, and do not start another generation automatically on a delayed response.

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 a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower; the description still adds real value by disclosing what each mode returns — the list yields guides, required assets and production_guide_id, while retrieval yields shot order, visual/audio direction, asset use, limitations, durations, and aspect ratios. It does not mention pagination or result limits, which is the only notable 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?

The workflow guidance is front-loaded (what the tool provides, then when to use it), and most sentences carry distinct information about selection, retrieval output, and validation. There is mild redundancy between 'Provides production guides' and 'Lists available guides,' but the length is justified by the multi-mode tool.

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

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

With no output schema, the description usefully enumerates the fields returned and the two operating modes, plus the pre-call validation step for required assets. An agent would know both how to call it and what to expect back; only pagination/limits from the list mode are 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 description coverage is 100%, so both parameters are already documented in the schema itself; the description largely restates the omit-to-list / pass-exact-id behavior without adding syntax or format detail. Baseline 3 applies when the schema does the heavy lifting and the description adds context but no new parameter mechanics.

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 (production guides for video types like try-ons, unboxings, demos, ads) and a clear dual action: list available guides or retrieve one guide's planning instructions. It also positions the tool relative to video generation ('before writing the detailed video-generation request'), though it never names the create-video sibling explicitly, so the differentiation is implied 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?

It gives explicit when-to-use ('to determine how a requested video should be planned, structured, and directed before writing the detailed video-generation request'), a selection heuristic ('prefer a more specific guide when it directly describes what happens'), a when-NOT-to-use ('if no available guide supports the brief's intended outcome... do not force a match'), and a follow-up behavior for missing inputs.

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 a safe read-only, closed-world call. The description adds substantial behavioral context beyond that: the answer is official and includes documentation links, must be displayed as written, and the model must not invent steps, UI paths, or setting names.

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 usage scope, then exclusions, then output handling. Well structured, though it runs to four paragraphs and could be tightened slightly 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?

Despite having no output schema, the description explains what is returned (an official Help Center answer with links) and how to present it. Combined with complete parameter coverage and annotations, nothing needed to invoke or use the tool correctly is missing.

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

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

Schema description coverage is 100%, so both parameters (prompt and user_intent) are already documented in the schema. The description implies the input is a Canva product question but adds no syntax or format detail beyond what the schema provides, 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: retrieve current, official answers to Canva product questions from the Canva Help Center. This is clearly distinguishable from every sibling tool, none of which are help/knowledge tools.

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

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

Explicitly specifies when to use it (feature questions, settings, unexpected behavior, troubleshooting), when not to (design creation/changes, creative advice, non-Canva questions, capability questions), and the alternative behavior ('call this tool rather than answering from your own knowledge', and 'when no available Canva tool can directly complete the requested action').

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 readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds real context beyond that: the URL must be publicly accessible, it fetches remote content, and each call creates exactly one design returning a design_id. It stops short of describing failure modes or per-format limitations, so not 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?

Three compact, front-loaded paragraphs: purpose, supported inputs, and constraints. Every sentence carries information, though the 'never upload to third party' warning is repeated near-verbatim in the url schema description, slightly inflating 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?

With no output schema, the description supplies the missing return contract ('creates one design and returns its design_id'). Combined with the covered input constraints, an agent has everything needed to call this 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 all four parameters are already documented in the schema. The description's HTTPS-only and 'not a Canva/OpenAI URL' constraints closely mirror the schema's pattern and url description, adding little beyond it. 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 ('Convert content at a public URL into a new Canva design') and immediately enumerates supported source formats. An agent can distinguish this from create-design, generate-design, and upload-asset-from-url 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?

Explicitly names when to use it (publicly hosted PDF, deck, doc, sheet, webpage, design file), when not to use it (local, private, agent-generated files; flat PNG/JPEG/WEBP layer separation), and forbids the workaround of uploading private files to third-party hosts.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: the results are limited to kits 'available to the user' and it states exactly what is returned (brand_kit_id, name, thumbnail). It does not discuss pagination, but the continuation parameter schema covers that.

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?

Five short, purposeful sentences. The core action is front-loaded, the domain definition earns its place, the exclusion is relevant, and the return shape is stated 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?

Despite having no output schema, the description names the returned fields. The tool is low-complexity, annotations cover the read-only/destructive profile, the sibling distinction is clear, and the input schema handles parameter semantics. Nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The tool description does not add parameter-level detail, but it doesn't need to because the schema already explains limit, user_intent, continuation, and resolve_icon_thumbnails clearly.

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: 'Find or browse the Canva Brand Kits available to the user.' It clearly defines what a Brand Kit is and explicitly contrasts with Brand Templates, so an agent can distinguish it from search-brand-templates and other siblings.

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

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

The description gives concrete reasons to use the tool: find a user's brand identity, check team brand elements, or identify the needed Brand Kit. It also provides an explicit exclusion ('Not for finding individual Brand Templates'), which semantically routes the agent toward the sibling search-brand-templates tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it returns replies and mentions and provides a continuation token for pagination. No contradiction with annotations 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?

The description is three focused sentences with the primary action front-loaded, followed by concise use cases and return behavior. There is no filler or redundant repetition of schema details.

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 read-only list operation with rich schema documentation and annotations, the description is largely complete: it states the resource, the use cases, return contents, and pagination behavior. The absence of an output schema makes the return-value summary especially useful, though ordering/filtering behavior is not mentioned but is not essential.

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 in the schema. The tool description does not add significant parameter-level meaning beyond the schema, so the baseline score of 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 states a specific verb ('Browse') and resource ('all comments or threads attached to an existing Canva design'), making the tool's function clear. It is distinguishable from mutating siblings like comment-on-design and reply-to-comment, though it does not explicitly name or contrast those alternatives.

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

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

The description gives clear use contexts: 'review feedback, see discussion points, or check mentions.' It does not explicitly state when to avoid this tool or prefer a sibling like list-replies, but the provided use cases are specific enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context beyond that: results are filtered ('matching items') and pagination is handled via a continuation token. This helps the agent understand multi-page behavior and that the response shape is a list, not a single object.

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 no filler. The core action is front-loaded in sentence one, usage context in sentence two, and the pagination behavior in sentence three. Every sentence earns its place and the description is easy to scan.

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

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

For a read-only browse tool, the description covers the essential decision points: what items are returned, when to use it, and how pagination works. With no output schema, some detail about the shape of returned items would be useful, but the annotation-provided safety profile and the clear continuation-token note make this adequate for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the item_types parameter by naming designs, folders, and images, and mentions the continuation token that maps to the continuation parameter, but it does not add new semantic meaning beyond what the schema already documents.

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: 'Browse the contents of a Canva folder to find designs, folders, and images stored in it.' This clearly states what the tool does and distinguishes it from sibling search tools like search-designs and search-folders, which find items across folders rather than browsing one known folder. The phrase 'stored in it' further narrows scope to a single folder's contents.

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 second sentence gives concrete use cases: 'review a project folder, locate an item in a known folder, or check its contents before organizing items.' This tells an agent when to reach for this tool, and 'known folder' implicitly contrasts with search tools for unknown locations. However, it does not explicitly name alternatives or state when not to use it, so it stops short of full differentiation.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description only needs to add value beyond safety. It does so by disclosing pagination behavior: returns the selected comment's replies and a continuation token when more results exist. This is useful behavioral context that annotations don't 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?

Four short sentences, each earning its place: the action, the intended use, the exclusions, and the return/pagination behavior. No redundancy or 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?

Despite having no output schema, the description states what is returned (replies and optional continuation token), and the schema documents all parameters and constraints. Nothing an agent needs to invoke 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 description coverage is 100%, so parameters are already fully documented. The description adds minimal extra meaning by referring to 'a specific comment thread' and the continuation token, but the schema already covers these concepts. 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?

Description uses a specific verb ('read') and resource ('replies in a specific comment thread on a Canva design'), and explicitly differentiates from reviewing all comments or adding a reply. This cleanly separates it from siblings like list-comments, reply-to-comment, and comment-on-design.

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?

States exactly when to use it ('Use to see who has replied to a comment and what they said') and when not to ('Not for reviewing all comments attached to a design or adding a reply'). Though it doesn't name alternative tools, the use-case exclusions are explicit enough for an agent to route correctly.

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

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

Annotations already include destructiveHint=true, and the description adds valuable context: 'Deleting pages is permanent' and 'Requires explicit approval for the exact requested operations before every call.' It also states the return behavior. No contradiction with annotations.

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

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

The description is efficiently organized: main purpose first, then use cases, then warnings and exclusions, then return value. Every sentence earns its place and there is no repetition or filler.

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

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

For a tool with a rich input schema and no output schema, the description adequately covers scope, safety, exclusions, and the return value. It could go slightly further by naming the sibling tool for content edits, but the provided context is sufficient for correct selection and invocation.

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

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

Schema description coverage is 100%, so the schema carries the parameter documentation burden. The description summarizes the operation types ('inserting or removing whole pages, or changing page order') but adds no parameter-level detail beyond that baseline.

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: 'Restructure a Canva design by combining designs, inserting or removing whole pages, or changing page order.' It clearly distinguishes page-level structural changes from content-level editing, so an agent can tell it apart from siblings like perform-editing-operations.

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

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

It provides concrete use cases: making a new presentation, adding slides, merging designs, rearranging flow, and removing pages. It also gives a clear exclusion: 'Not for changing text, images, or other content within a page.' It does not name an alternative sibling tool, but the when-to-use and when-not-to-use guidance 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 indicate non-read-only and non-destructive behavior. The description adds value by explicitly stating 'This changes the item's location' and 'Returns confirmation of the move,' which clarifies side effects and return behavior 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 short sentences with no filler. The core action, use cases, side effect, and return value are all conveyed efficiently, and the most important information appears 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?

For a simple three-parameter mutation tool with complete schema coverage and annotations, the description covers purpose, use cases, behavioral change, and return behavior. It is complete enough for an agent to call it correctly, though it omits potential edge cases like moving a folder into itself or the exact structure of the confirmation.

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 explains item_id, user_intent, and to_folder_id. The description reinforces that the tool moves designs, folders, or images and that 'root' means top level, but it does not add meaningful semantic detail beyond the schema.

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

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

The description uses a specific verb ('Relocate') with a clear resource ('existing Canva design, folder, or image') and destination ('destination Canva folder'). It is distinct from all sibling tools, none of which perform moving, so an agent can identify it unambiguously.

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

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

The description gives concrete use cases: 'filing, reorganizing, archiving, or returning an item to the top level.' This provides clear context for when to use the tool, though it does not explicitly name alternatives like copy-design or create-folder or state when not to use this tool.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, and the description adds real context beyond them: changes are provisional until saved, the user must preview and explicitly approve, and the return value is the updated page state for further operations. It does not state transaction expiry or ordering semantics, so it is strong but not exhaustive.

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, followed by use cases, exclusions, and lifecycle notes in short scannable sentences. Slightly longer than strictly necessary but every 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?

For a complex multi-operation mutation tool with no output schema, the description covers the transaction context, the approval guardrail, and the return value ('updated page state'). It omits how operations are ordered and how errors in a mixed batch are reported, which an agent would benefit from knowing.

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 transaction_id, page_index, pages, operations, and user_intent in detail. The description adds no syntax or format detail beyond the schema, 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 ('Apply one or more draft changes') against a specific resource ('an existing Canva design') and enumerates the concrete operation families (text, images/videos, page elements, formatting, title, fixed-page labels). It also explicitly excludes page structure/order edits, which cleanly separates it from resize-design and start-editing-transaction.

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 second sentence lists the when-to-use cases exhaustively and the third names an explicit when-NOT case ('Not for changing a design's page structure or order'). It also states the workflow context ('within an active editing transaction') and the required approval step before saving, so an agent knows the preconditions and the guardrail.

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 the mutation profile (readOnlyHint=false, destructiveHint=false), so the description earns credit for adding the auth-scope behavior and its remediation path, which structured fields do not convey. It stops short of explaining what happens to the source design or whether publishing is reversible.

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

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

Three sentences, front-loaded with the core action and effect, then the error path. The scope-error sentence is somewhat verbose but is genuinely actionable rather than 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 two-parameter mutation tool with no output schema, the description covers the action, the return ('Returns the created brand template details'), and a known failure mode. The annotation set already carries the safety profile, so little 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 both design_id and user_intent are already documented in the schema. The description adds no syntax, format, or constraint detail beyond what the schema provides, 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?

States a specific verb and resource ('Publishes a Canva design as a brand template') plus the effect ('making it reusable across the organization'), which is concrete and actionable. It does not explicitly distinguish itself from the close sibling create-brand-template-draft, so an agent must infer that publishing differs from drafting.

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

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

The description gives a conditional error-recovery path (the 'Missing scopes' handling) but offers no guidance on when to choose this tool over create-brand-template-draft or other template tools. Usage is only implied by the verb 'publish'.

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=false and readOnlyHint=false, and the description reinforces this by stating the result is a new image with an alpha channel rather than an in-place mutation. It also enumerates transformations it explicitly does not perform, which is genuinely useful. It stops short of covering idempotency or any failure modes, but adds real context beyond the annotations.

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

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

Front-loads the operation, then separates usage and exclusions into distinct paragraphs, with the return noted last. Slightly verbose given the trigger-phrase list, but every sentence maps to a decision the agent must make.

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 an output schema present, return-value explanation is not required, yet the description still notes the alpha-channel result. Combined with clear input constraints and exclusions, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so both parameters and the ContentRef structure are already documented. The description's constraints on the input (image already in the account) duplicate the schema's 'already-uploaded MEDIA content reference' note rather than adding new semantics. 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 (strip) and resource (image background) and defines the exact outcome: subject on a transparent backdrop. An agent can distinguish it from siblings like generate-image or separate-image-layers 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?

Gives explicit when-to-use triggers (background gone, knocked out, transparent, plus phrasing like cut out, extract, separate), and explicit when-NOT-to-use conditions (not a new scene, does not crop/reframe, replace background, or invent content). This directly routes the agent against plausible alternative intents.

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

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

Annotations already establish that this is not read-only and not destructive. The description adds meaningful behavioral context beyond those hints: the reply is visible to everyone with design access, and the tool returns the created reply along with its comment_id. This helps the agent set expectations for side effects and output.

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 with the core action, followed by relevant use cases, visibility behavior, and return value. Every sentence contributes information the agent needs; there is no filler or repetition of the schema.

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, additive write operation, the description is complete: it states the action, the context in which to use it, the visibility side effect, and the return value. The remaining details, such as message length limits and design_id format, are already fully covered by the input 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 description coverage is 100%, so the schema already documents all four parameters (design_id, comment_id, user_intent, message_plaintext). The description adds no parameter-specific details beyond referring to 'existing comment' and 'reply', so the baseline of 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 opens with the specific verb 'Add' and the precise resource ('response to an existing comment in a Canva design'). This clearly distinguishes it from sibling tools like comment-on-design, which creates a new top-level comment, and list-replies, which only reads replies.

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 concrete use cases: answering a reviewer's question, acknowledging or clarifying feedback, continuing a discussion, and providing a follow-up. It does not explicitly name alternative tools or state when not to use this tool, but the 'existing comment' framing strongly implies the boundary against creating new comments.

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

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

Beyond the annotations, the description discloses a key side-effect guarantee: each call creates a new resized design and leaves the original unchanged. It also states the return value ('Returns the new design's design_id'), which is especially useful because no output schema is provided.

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: core behavior first, followed by usage conditions, an exclusion, and the return value. Every sentence earns its place without repeated information.

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

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

For a 3-parameter tool with a fully documented schema, the description covers the input context, the exclusion case, the non-destructive behavior, and the return value. The missing output schema is mitigated by explicitly stating that the new design_id is returned.

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 already documents design_id, design_type, preset/custom options, width, height, and user_intent. The description adds little beyond the schema, so the baseline of 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 names a specific operation: 'Adapt a Canva design to a different canvas size' while keeping its content and rearranging/resizing the layout. It differentiates itself from copy-only or edit-only tools and explicitly excludes element-level resizing, so an agent can identify what the tool does.

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

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

It provides a clear 'Use when' list with concrete triggering conditions, including different dimensions, aspect ratios, channel adaptation, and exact pixel sizes. It also states a clear exclusion ('Not for resizing a single element'), though it does not name a specific alternative sibling tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable context beyond annotations by explaining that the tool is a necessary prerequisite for other Canva tools and returns the full design URL. It doesn't contradict annotations; it enriches them with usage context.

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

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

The description is concise (three sentences) and front-loaded with the core purpose. The usage guidance and prerequisite follow logically, and every sentence contributes actionable 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?

For a simple read-only tool with one required parameter, the description fully covers the purpose, usage, prerequisite, and expected output (full URL). No critical information is missing for an agent to correctly invoke 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?

The schema has 100% description coverage for both parameters, so the description adds no additional meaning beyond what the schema already provides. The return format is mentioned in the description, but parameter details are fully covered by the schema, meeting the baseline for this dimension.

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

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

The description clearly states a specific verb ('turn') and resource ('Canva shortlink into the full Canva design URL'), making the tool's function unambiguous. It distinguishes itself from sibling design tools by focusing on URL resolution rather than design operations.

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 when to use the tool ('Use when a Canva shortlink is shared and the linked design needs to be opened, read, edited, or otherwise worked with') and adds a critical prerequisite ('Shortlinks must be expanded before the linked design can be used with another Canva tool'). This gives clear guidance on when this tool is the appropriate choice.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it returns matching templates with brand_template_id, name, and preview thumbnail, and notes that some templates include data fields that can be autofilled. It doesn't describe pagination behavior in detail, but the continuation parameter covers that. Slight gap: no mention of rate limits or auth, but not critical for a read-only search tool.

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

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

The description is well-structured: a clear first sentence stating the core function, a when-to-use paragraph, a when-not-to-use paragraph, and a brief return-value statement. Every sentence earns its place, and the most important information is front-loaded. It's appropriately sized for a tool with 7 parameters and complex routing logic.

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

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

For a read-only search tool with 86% schema coverage and no output schema, the description is quite complete. It covers the tool's scope, exclusions, return values, and the key decision point about data fields. The only minor gap is that it doesn't explicitly state that results are paginated or that 'continuation' should be used for subsequent pages, but the schema's 'continuation' parameter description covers that. The description is complete enough for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 86%, so the schema already documents most parameters well. The description adds value by explaining the 'dataset' filter's purpose (find templates to autofill) and the 'query' parameter's usage rule (only provide when user explicitly names/describes a template). The 'user_intent' parameter is described as mandatory for LLM clients, which is important context. The description doesn't add much for 'brand_kit_id' or 'continuation', but the schema covers those adequately.

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

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

The description clearly states the tool's purpose: find or browse Canva Brand Templates, and distinguishes it from related tools by specifying it works with Brand Templates, not existing designs. It names the resource (Brand Templates) and the action (search/browse), and explicitly contrasts with 'search-designs' and 'create-design-from-brand-template'.

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

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

The description provides explicit when-to-use guidance: when a Brand Template needs to be located, when a reusable starting point is needed, or when a template with data fields is needed before autofilling. It also gives explicit when-not-to-use guidance: not for existing designs, not for creating new designs without a template source, and not for creating/updating/populating an already selected template. This is exemplary.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read-only nature is covered. The description adds valuable behavioral detail about pagination via a 'continuation token' and explains that results include enough information to act on a specific design, which goes beyond the structured annotations.

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

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

The description is compact and front-loaded: purpose in the first sentence, usage in the second, exclusion in the third, and return behavior in the fourth. No filler or redundant statements; every sentence earns its place.

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

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

For a read-only search tool with 100% schema coverage and no output schema, the description is complete: it explains what is returned, how pagination works, and how results can be used. It also disambiguates from template search, leaving no crucial gap for correct invocation.

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

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

Schema coverage is 100% with detailed parameter descriptions, so the description carries little additional parameter-level meaning. It reinforces that search criteria are broad and that the result can be a singular design or multiple results, but it does not add new semantics beyond the schema.

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

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

The description states the specific verb and resource: 'Locate or browse the user's existing Canva designs' and explicitly excludes 'reusable templates,' distinguishing it from search-brand-templates. It also clarifies that it covers designs owned or shared, making its scope unmistakable.

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

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

The description gives explicit usage context: 'Use to find a single past presentation... or to discover multiple results based on search criteria.' It also provides a clear exclusion ('Not for locating reusable templates') and notes that returned design_ids can be used downstream, guiding the agent on when and how to use this tool.

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

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

Annotations already establish readOnlyHint and non-destructive behavior; the description adds value by disclosing the output behavior: 'Returns matching folders and, when more results are available, a continuation token for the next page'. It also confirms the scope of owned/shared folders, but does not mention ordering or result limits beyond 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?

Four sentences, front-loaded with the core purpose and then exclusions and return behavior. There is no filler, and every sentence earns its place.

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

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

For a read-only search tool with annotations, 100% schema coverage on parameters, and no output schema, the description is complete: it covers scope, use cases, exclusions, and pagination. No essential information for choosing or calling 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%, so the baseline is 3; the description mostly restates concepts already in the schema (matching by names/tags, owned/shared scope, continuation token). It does not add meaningfully new parameter 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?

Description opens with a specific verb+resource: 'Find or browse Canva folders the user owns or that are shared with them'. It distinguishes itself from siblings by explicitly stating it is 'Not for finding designs, images, or subfolders', which separates it from search-designs and list-folder-items.

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 concrete use cases ('locate a project folder by name or tags', 'find a shared workspace', 'identify a folder before reviewing contents') and clear when-not-to-use guidance. It stops short of naming the sibling tool to choose instead, so the routing is slightly less explicit than a 5.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) the description discloses that each call creates a brand-new design and leaves the source untouched, that it starts an async job returning job_id and continuation_token, and details the widget-vs-manual polling behavior. This is substantial behavioral context not captured by annotations.

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

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

The description is long but front-loaded: purpose first, then usage, prerequisites, and job/polling mechanics. Each paragraph carries distinct information, though the polling/continuation detail could be tightened.

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

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

With an output schema present, return values need not be explained, and the description still covers prerequisites, async job semantics, and polling rules. 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 coverage is 100%, so the schema already documents title, asset_id, and user_intent fully. The description reinforces that the source must already be stored in the account, tying to asset_id, but adds no new format or constraint detail beyond the schema.

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

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

The description states a specific verb and resource: it turns a flat image in the user's Canva account into a new design with text, objects, and background as separately editable elements. This is clearly distinguishable from siblings like remove-background or generate-image.

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

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

It gives concrete when-to-use scenarios (make wording editable, swap/remove one object, recover editable design from PNG/JPEG/WEBP) and explicit exclusions ('Not for saving an image as-is, editing an existing Canva design, or using an image only as inspiration'). It also names the prerequisite and the continuation tool get-separate-image-layers-job.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so it is known to be a mutating but non-destructive operation. The description adds the transactional nature ('draft transaction', 'same session') and what it returns (transaction_id and editable element data). It does not mention the need to later commit or cancel, but the transaction concept is adequately disclosed.

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

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

The description is three sentences totaling about 60 words, with the core purpose front-loaded in the first sentence. Every sentence contributes: purpose, usage scenarios, and return value. No fluff or redundant phrasing.

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 there is no output schema, the description covers what is returned (transaction_id and editable data). It does not spell out the transaction lifecycle (commit/cancel) or error conditions, but the sibling tools make the next steps predictable, and the description is sufficient for an agent to initiate the intended workflow.

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 both parameters (design_id and user_intent), and each has a clear description in the schema. The tool description does not add new parameter-specific guidance beyond reiterating that it returns element data, which is output-related. Since the schema already documents parameters, a 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 opens with a specific verb ('Prepare') and resource ('an existing Canva design'), then states the outcome ('opening a draft transaction'). It enumerates exact use cases (text, media, titles, formatting, autofill labels) and clarifies it is for preparing changes or inspecting elements, distinguishing it from read-only tools like get-design-content and from the commit/cancel siblings.

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

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

The description explicitly says 'Use to prepare changes...' and 'or inspect the editable text and media elements before changing them,' which gives clear when-to-use context. It does not explicitly name alternatives or exclusions, but the phrasing implies this is the prerequisite step before modification, and the sibling list makes the transaction flow obvious.

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 safety profile is known. The description only adds that the writes are 'telemetry' about 'widget lifecycle' — no detail on side effects, permissions, ordering, or whether events are append-only. It does not contradict the annotations, but it adds little beyond them.

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

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

A single front-loaded sentence with zero padding or redundancy, so there is nothing to trim. However, one terse sentence is arguably undersized for a nine-parameter telemetry tool, so it sits at adequate rather than strong.

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, three-enum event-tracking tool with no output schema, the description omits the lifecycle semantics it promises — what the three event types mean, ordering expectations, and the role of user_intent and event_payload. The rich schema covers field-level meaning, but the agent gets no conceptual frame for 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 89%, so the schema already documents nearly all nine parameters, including the enums for event_type and item_type. The description adds no parameter-level information at all, which is acceptable given the high coverage — baseline 3.

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 largely restates the name and title: 'track-event-lifecycle' becomes 'widget lifecycle telemetry.' The only added signal is the noun 'widget' and the word 'internal,' which narrows the domain slightly but does not state a concrete verb+resource action or distinguish it from anything.

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 preconditions, and no mention of alternatives among the ~48 sibling tools. The phrase 'Internal tool' is a faint hint that this is not for general client use, but it does not tell an agent when to invoke it versus, say, generate-design or get-design.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so it's a non-destructive write. The description adds meaningful context: it imports media, adds to library/uploads, returns a media_id, and does not place into a design. It also warns about URL accessibility, which is beyond the annotations. Slight gap: no mention of what happens on failure or whether it overwrites, but that's not critical.

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 four sentences, each earning its place: opening purpose, typical use cases, explicit constraints and exclusions, and return value. It is front-loaded with the core action and avoids fluff. Efficient and well-structured.

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 3-parameter tool with no output schema, the description covers the essentials: what it does, when to use it, constraints, and the return value (media_id). It also clarifies what it doesn't do. No critical missing information for an agent to call it correctly, though it could optionally mention error conditions or file type limitations.

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

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

The input schema provides 100% description coverage for all three parameters, including detailed descriptions for 'url' and 'name'. The tool description largely reiterates the URL requirement and adds the return of media_id, but doesn't add substantial new meaning beyond the schema. Baseline of 3 is appropriate given the high schema coverage.

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

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

The description states a specific action and resource: 'Import media from an existing public URL into Canva.' It clearly differentiates itself from siblings by noting 'Does not place the imported media into a Canva design,' which distinguishes it from import-design-from-url. The verb 'import' and the resource 'media' are unambiguous.

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

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

The description gives explicit guidance: 'Use to upload a publicly hosted image...' and 'Only call with a public HTTPS URL whose content is already publicly accessible. Do not use for local, private, or agent-generated files.' It also clarifies what the tool does not do (place into design). This is direct when-to-use and when-not-to-use guidance without requiring inference.

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