Canvs

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

The description adds significant behavioral context beyond annotations. Annotations indicate it's not read-only, not destructive, and open-world. The description adds: prerequisite (call get_guide first), dual-mode behavior (create vs. add), critical response requirement (include room_url), element type constraints, text-in-shapes technique, arrow positioning rules, auto-binding behavior, and color format details. No contradiction with annotations.

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

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

The description is front-loaded with the main purpose and critical warnings, but becomes dense with implementation details (element types, text binding, arrow rules, colors). Some sentences could be more concise, and the structure mixes high-level guidance with specific technical constraints in a single paragraph.

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

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

Given the tool's complexity (dual create/add behavior, many element types, binding rules) and the presence of both comprehensive annotations and an output schema, the description provides complete contextual guidance. It covers prerequisites, behavioral modes, critical response requirements, element constraints, and implementation techniques - addressing what structured fields don't capture.

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

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

With 100% schema description coverage, the schema already documents all parameters thoroughly. The description adds some semantic context: it explains the conditional logic of room_url (creates new canvas if not provided), mentions timeout is 'only used when creating new canvas,' and provides element type examples. However, most parameter details remain in 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 tool's purpose: 'Main method for creating canvas and adding elements.' It specifies the dual behavior based on room_url presence (create new canvas vs. add to existing). However, it doesn't explicitly differentiate from sibling tools like 'add_elements_from_mermaid' or 'update_elements' beyond being the 'main method.'

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 usage guidance: '⚠️ IMPORTANT: Call get_guide first and follow its instructions!' It specifies when to use (creating new canvas when room_url not provided, adding elements when provided) and includes critical behavioral instructions like 'ALWAYS include room_url in your response to the user when creating new canvas.'

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

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

The description adds valuable behavioral context beyond annotations: it explains the conditional behavior based on room_url (creates new canvas vs adds to existing), emphasizes the importance of returning room_url to users, and provides specific examples of supported diagram syntax. While annotations cover basic safety (destructiveHint: false), the description adds practical implementation details.

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

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

The description is well-structured with important warnings upfront and clear sections. While slightly lengthy due to including multiple diagram examples, every sentence serves a purpose: establishing prerequisites, explaining conditional behavior, emphasizing user communication requirements, and providing syntax guidance. The information density is high with minimal 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?

Given the tool's complexity (conditional behavior, multiple diagram types, interaction with other tools) and the presence of both comprehensive annotations and an output schema, the description provides excellent contextual completeness. It covers prerequisites, behavioral conditions, supported formats with examples, and user communication requirements - addressing everything an agent needs to use this tool effectively.

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

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

With 100% schema description coverage, the input schema already documents all parameters thoroughly. The description adds minimal parameter semantics beyond the schema - it clarifies the conditional behavior of room_url and mentions timeout is 'only used when creating new canvas,' but doesn't significantly enhance understanding of individual parameters beyond what the schema provides.

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

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

The description clearly states the tool's purpose: 'Add elements from Mermaid diagram' with specific details about creating new canvases or adding to existing ones. It distinguishes itself from siblings by focusing on Mermaid diagram parsing rather than general element manipulation like 'add_elements' or 'update_elements'.

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 usage instructions: 'Call get_guide first and follow its instructions!' and clarifies when to use based on room_url presence. It also specifies supported diagram types (Flowchart, Sequence, Class) with concrete examples, giving clear context for when this tool is appropriate versus other element manipulation tools.

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

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

Annotations already indicate destructiveHint=true, readOnlyHint=false, and openWorldHint=false, covering safety and mutability. The description adds valuable context by specifying that it deletes elements (reinforcing destructiveness) and mentions the requirement for room_url from add_elements, which clarifies dependencies beyond 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 ('Delete elements from a canvas') and uses only two concise sentences that each add necessary information (prerequisites and parameter guidance). There is no wasted text, making it highly efficient.

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

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

Given the tool's complexity (destructive operation with two parameters), annotations cover safety and mutability, and an output schema exists (so return values need not be explained). The description complements this by stating the action, prerequisites, and parameter usage, making it complete for agent understanding.

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 clear descriptions for both parameters (ids and room_url). The description adds minimal value by restating 'ids array of element IDs to delete' and mentioning room_url's source, but does not provide additional semantics 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 clearly states the action ('Delete elements') and the resource ('from a canvas'), making the purpose immediately understandable. It distinguishes itself from siblings like 'add_elements' or 'update_elements' by specifying deletion, avoiding ambiguity.

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

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

The description provides explicit context for when to use this tool by mentioning 'Requires room_url from add_elements', which helps the agent understand prerequisites. However, it does not specify when not to use it or name alternatives (e.g., 'update_elements' for modifications instead of deletion), leaving some guidance gaps.

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

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

The annotations already indicate read-only, non-destructive, and closed-world behavior. The description adds valuable context beyond annotations: it emphasizes the mandatory nature of calling this tool first and that following instructions 'ensures correct diagrams.' This provides operational guidance that annotations don't cover, though it doesn't detail specific behavioral traits like rate limits or auth needs.

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

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

The description is highly concise and well-structured: it uses a warning symbol and bold text for the mandatory step, then clearly states the return value and benefit in two sentences. Every sentence earns its place by providing critical 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?

Given the tool's complexity (a setup/instruction tool with no parameters), the description is complete. It explains the purpose, mandatory usage, and expected output (instructions for whiteboard creation). With annotations covering safety aspects and no output schema needed for an instruction-returning tool, the description provides all necessary context for an agent to use 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?

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, focusing instead on the tool's purpose and usage. A baseline of 4 is applied since no parameters exist, and the description doesn't attempt to explain non-existent parameters.

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

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

The description explicitly states the tool's purpose: 'Returns comprehensive instructions for creating whiteboards: tool selection strategy, iterative workflow, and examples.' It specifies the verb ('Returns comprehensive instructions'), resource ('creating whiteboards'), and scope ('tool selection strategy, iterative workflow, and examples'), clearly distinguishing it from sibling tools that perform operations on whiteboard elements.

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 usage guidelines: '⚠️ MANDATORY FIRST STEP - Call this tool BEFORE using any other Canvs tools!' It clearly states when to use this tool (as a first step before any other tools) and implies when not to use it (after other tools have been called without it). This directly addresses the context of sibling tools.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, covering safety and scope. The description adds valuable behavioral context beyond this: it specifies that the tool requires a browser to have the canvas open, returns an error otherwise, and mentions that results match optional filters. This provides practical implementation details that annotations don't cover.

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 structured in three sentences: it states the purpose, specifies requirements and returns, and provides error handling guidance. Every sentence adds essential information without redundancy, making it front-loaded and appropriately sized for the tool's complexity.

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

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

Given the tool's moderate complexity, rich annotations, and 100% schema coverage, the description is mostly complete. It covers purpose, prerequisites, error conditions, and basic behavior. However, without an output schema, it doesn't detail return values (e.g., format of matched elements), leaving a minor gap in completeness for a query 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?

With 100% schema description coverage, the input schema already documents all three parameters thoroughly. The description adds minimal parameter semantics beyond the schema—it only mentions that filters are 'optional' and references 'room_url from add_elements'. This meets the baseline for high schema coverage but doesn't significantly enhance understanding of parameter usage.

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

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

The description clearly states the verb 'query' and resource 'elements on a canvas', making the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_image' or 'get_guide' that might also retrieve canvas content, leaving room for ambiguity about when to choose this specific query 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 provides clear context for usage: it specifies that 'room_url from add_elements' is required and warns about the need for an open browser canvas. It also mentions optional filters. However, it doesn't explicitly state when to use this tool versus alternatives like 'get_image' or 'get_guide', nor does it provide exclusion criteria for when not to use it.

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

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

Annotations indicate this is a non-destructive, non-read-only operation, which the description aligns with by implying mutation ('Update'). The description adds minimal behavioral context beyond annotations, such as the requirement for 'room_url from add_elements,' but lacks details on rate limits, authentication needs, or error handling. No contradiction with annotations is present.

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

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

The description is concise with two sentences that efficiently convey key information: the action and a prerequisite. It's front-loaded with the core purpose, though it could be slightly more structured by separating usage notes from parameter hints.

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

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

Given the tool's complexity (mutation with multiple field options), the description is reasonably complete. It covers the basic purpose and a prerequisite, and with annotations providing safety context and an output schema likely detailing return values, the description doesn't need to explain behavior or outputs extensively. Minor gaps remain in sibling differentiation and advanced usage 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?

With 100% schema description coverage, the input schema fully documents both parameters ('room_url' and 'elements'). The description adds marginal value by clarifying that 'elements' must include an 'id' and 'fields to update,' but this is largely redundant with the schema's requirements. Baseline score of 3 is appropriate as 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?

The description clearly states the action ('Update elements') and resource ('on a canvas'), making the purpose immediately understandable. However, it doesn't explicitly differentiate this tool from its siblings like 'align_elements' or 'distribute_elements' which also modify elements, missing an opportunity for clearer distinction.

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

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

The description provides some usage context by mentioning 'Requires room_url from add_elements,' which hints at a prerequisite relationship. However, it doesn't explain when to use this versus alternatives like 'align_elements' or 'lock_elements,' nor does it specify exclusions or edge cases for usage.

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