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

With no annotations, the description carries the full burden. It does add real behavioral value by disclosing a side effect — 'arrows bound to them are detached' — but it omits whether deletion is permanent/undoable, what happens to ids that don't exist, and what the response contains.

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

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

A single sentence that front-loads the primary mode and appends the alternative, with zero wasted words.

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, annotation-free tool with no output schema, the description is only partially adequate: it covers the two modes and one side effect but leaves the safety profile (permanence, recovery, required permissions) 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. The description only restates them ('by id', 'all:true') without adding format, ordering, or edge-case semantics 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 (delete) and resource (canvas elements/board) with both operating modes spelled out ('by id' vs 'all:true'). It is clearly distinguishable from read/draw/search siblings by the verb alone, though it never names a sibling boundary explicitly.

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

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

The two modes are described ('Delete elements by id ... or everything with all:true'), which implies when each parameter applies, but there is no guidance on when to prefer targeted deletion over clearing the board, and no warning about irreversibility or confirmation before 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?

No annotations exist, so the description carries the whole burden. It correctly discloses that updates are partial merges keyed on id and that arrows bind by from/to ids, but says nothing about return values (notably the auto-generated ids an agent needs in order to link arrows), batch limits, or failure behavior when an id is unknown.

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

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

Three short sentences, each carrying a distinct rule, with the primary create-or-update purpose front-loaded. Nothing is padded or 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?

For a single batch parameter with a rich 200-item element spec, the description covers the two most important semantics. The key omission is what the call returns — particularly generated ids — which an agent needs to wire up arrows in a follow-up call, and no mention of whether the whole batch applies atomically.

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% — every nested property, including id, from, to, frame, and points, is documented inline. The description reinforces the two cross-field behaviors (id reuse and arrow binding) but adds little 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?

"Create or update elements" gives a specific verb pair and resource, and the two follow-up sentences clarify the create-vs-update distinction. It does not, however, differentiate from siblings such as canvas_mermaid or canvas_delete, so an agent must infer that this is the low-level shape/arrow authoring 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?

"Re-using an id updates only the given fields" is a genuine usage rule that tells the agent how to choose between create and partial-update paths. But there is no explicit guidance on when to pick this over canvas_mermaid, canvas_save, or canvas_delete, and no stated preconditions for the canvas being open.

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?

With no annotations, the description carries the full burden; it does disclose the format default and that relative paths resolve against the workspace, which is genuinely useful. It says nothing about overwrite behavior, required permissions, or what is returned on success, which matters for a tool that writes to disk.

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

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

Two short sentences, front-loaded with the action and with zero filler. The format default and path resolution are packed into the same compact statement.

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

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

For a simple two-parameter export tool with no output schema, the description covers the essentials of what and where. It leaves the write-side behaviors (overwrite, result path, failure modes) undeclared, which is a moderate gap given the absence of 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 coverage is 100%, so both parameters are already documented, and the format enum is fully specified. The description only adds the workspace-relative resolution rule and the default format, which the schema largely covers.

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 ('Save the board to a file') plus the two supported formats, which is concrete. It does not distinguish itself from the sibling canvas_save, so an agent cannot tell from the description alone which one writes a file versus which one persists state.

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 and no mention of alternatives such as canvas_save or canvas_screenshot, even though the sibling list contains tools that plausibly overlap. Usage is only implied by the word 'Save'.

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?

With no annotations, the description does disclose the key non-obvious behavior: this moves the human's viewport (a shared-state side effect) and that highlight triggers a pulsing animation. It does not say whether the call is blocking, what happens with invalid ids, or whether anything is returned.

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

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

Two compact sentences with the core action and default-up front and the intent hint last. No filler; every clause carries information.

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

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

For a three-optional-parameter viewport tool with no output schema and no annotations, the essential calling information is present. Gaps remain around error behavior with unknown ids and whether the operation completes synchronously, which matter for an agent sequencing calls.

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 earns above baseline by documenting the default when `ids` is omitted (whole scene) and clarifying that `highlight` causes a pulse. It adds no format detail for `zoom` beyond the schema's example, which is acceptable since the schema covers it.

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

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

Specific verb pair (scroll/zoom) applied to a named resource (the human's view of elements), with the default scope stated in parentheses. It is clearly distinguished from read/draw/export siblings by being a viewport-control action, though it doesn't name a sibling to route away from.

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

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

"Use it to point while explaining" gives one positive usage context, which is genuinely helpful for an agent narrating to a human. There is no guidance on when not to use it versus canvas_open or canvas_screenshot, nor on sequencing with other canvas calls.

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?

With no annotations, the description must carry the burden, and it does signal that this is instructional content to be consumed once before drawing, implying a static read with no side effects. It doesn't explicitly state read-only behavior or the nature of the returned text, but the framing as guidance-to-read is transparent enough for a zero-parameter 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?

A single sentence delivers the topic list first and the usage condition second, with no filler. Every clause earns its place.

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

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

For a zero-parameter, no-output-schema documentation tool, the description covers what it contains, when to read it, and its one-time nature. There are no parameters or return values to explain further, so nothing an agent needs is missing.

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

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

The tool takes no parameters, so the baseline of 4 applies. Nothing in the description conflicts with the empty schema and no input semantics are needed.

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

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

The description names the resource (a canvas guide) and enumerates its content — layout, sizes, colours, and the live explain loop — which clearly separates it from the action-oriented siblings like canvas_draw or canvas_export. It lacks a crisp verb, but 'How to explain well on this canvas' leaves no ambiguity about what the tool provides.

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 clause 'Read once before your first drawing' gives an explicit trigger condition for when to invoke it, which is unusually actionable for a documentation tool. It doesn't name alternatives or say when not to call it, but the precedents it establishes are clear enough for an agent.

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

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

No annotations are provided, so the description carries the full disclosure burden. It reveals that existing Mermaid text becomes editable board elements, but says nothing about whether elements are added or replaced, what happens on invalid Mermaid syntax, or whether a board/workspace context is required.

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

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

A single front-loaded sentence with no filler; the verb and resource appear immediately, followed by the output form and diagram examples.

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 three-parameter transformation tool with no output schema and no annotations, the description covers the core action but leaves out return value (element IDs/handles), positioning defaults, and failure behavior — details an agent would want before calling it.

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

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

Schema description coverage is 100%, with x, y, and definition each documented in the schema, so the baseline of 3 applies. The description adds only the loose notion of placement 'on the board' and does not explain coordinate behavior or units beyond the schema's 'Left edge'/'Top edge'.

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 (convert) and resource (Mermaid definition) with example diagram types, and names the output (editable elements on the board). It is clearly distinguishable from siblings like canvas_draw or canvas_export, though it does not explicitly name an alternative.

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 never says when to prefer this over canvas_draw (hand-drawing elements) or what preconditions apply, such as needing an open board. Usage is only inferable from the tool name.

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?

No annotations are provided, so the description carries the burden. It does disclose that the effect is to display the board to a human observer ('beside the chat'), which is genuine behavioral context. It says nothing about whether opening replaces or preserves existing board content, whether a board is created if none exists, or what happens when no human is present (that detail lives only in the schema for 'open').

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

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

Three short sentences, front-loaded with the primary action, with nothing wasted. The telegraphic phrasing ('Name it with title') is efficient but slightly clipped, which keeps it from a 5.

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

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

For a five-parameter, zero-annotation, no-output-schema tool, the description covers the core action but omits the side-effect profile: whether existing drawings are overwritten, whether a missing board is created, and what the caller gets back. The rich schema compensates partially, but the behavioral picture remains incomplete.

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

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

Schema coverage is 100%, so all five parameters including defaults are documented in structured data; baseline is 3. The description reinforces title (naming) and board (reuse another chat's drawing) but adds no syntax, format, or interaction 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?

States a specific verb+resource: showing this chat's own whiteboard to the human beside the chat. It also hints at the reuse case via the board parameter. It does not, however, distinguish itself from siblings like canvas_focus or canvas_read, which plausibly also surface the board to a viewer.

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

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

The phrase 'To reuse another chat's drawing (any folder), pass board' gives a condition for one parameter, and 'Name it with title' gives a light instruction. There is no explicit when-to-use-this-vs-an-alternative guidance despite ten canvas siblings, and no statement of when not to call it.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that the tool returns a scene description or JSON and that the result includes human changes/notes since the previous read, implying incremental stateful behavior, but it omits read-only confirmation, first-read behavior, and error/rate-limit 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 a single front-loaded sentence with no wasted wording. It puts the core operation first and then specifies the return content.

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

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

For a two-optional-parameter read tool with no output schema, the description gives enough information to understand the main return content. It is slightly incomplete about first-read behavior and the exact meaning of "since your last read," but the schema covers parameter details.

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 both optional parameters. The description maps loosely to the format parameter via "or JSON" but does not explain the ids filtering parameter or add details 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/resource pair ("Read the board") and explains the returned content: scene description or JSON plus changes/notes since the last read. It is clear, but it does not explicitly differentiate from siblings such as canvas_screenshot, canvas_search, or canvas_export.

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

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

Usage is implied by "Read the board" and by the mention of changes since the last read, which suggests incremental inspection. However, the description does not explicitly state when to use this instead of canvas_screenshot, canvas_search, or canvas_export, nor does it give exclusions.

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

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

With no annotations, the description carries the burden and does disclose the key mutation trait: reusing the same name overwrites the existing saved copy. 'Frozen copy' also signals the snapshot is immutable with respect to later board edits. Missing are permission requirements, what is returned on success, and whether overwriting is silent.

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

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

Two short sentences, front-loaded with the action and purpose, with the overwrite caveat second. 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 one-optional-parameter, no-output-schema tool this covers what an agent needs to call it correctly. It could still say what the save returns or whether the live board is unaffected, but nothing essential 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% and the single parameter already documents the default (board title). The description adds only the name-as-identity detail via the overwrite sentence — useful but thin 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 specific verb (save a frozen copy) and resource (this board) plus where it lands (the user's library), which cleanly separates it from write-alike siblings such as canvas_export or canvas_delete. It even names the retrieval counterpart, canvas_search.

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?

Implies the usage scenario clearly ('so any later chat can find it with canvas_search'), which tells the agent when this tool is appropriate rather than canvas_export. It does not state explicit when-not conditions or prerequisites (e.g., whether a board must be open first).

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

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

No annotations exist, so the description carries the full burden. It does convey a meaningful behavioral trait — that output is a rendered visual rather than structured data — but never states that the call is non-mutating, has no side effects, or how large/expensive the render is.

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 short sentence with the output format and purpose front-loaded; no filler to remove.

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, zero-required, no-annotation read tool this is minimally adequate — format and intent are covered and the schema covers parameters. Missing is any indication of return size, whether ids filter or crop, and how it relates to the export sibling.

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

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

Schema coverage is 100%, so 'ids' (only these elements) and 'dark' (dark theme) are already documented in the schema. The description adds no further meaning about scoping or theme behavior, which is acceptable at the baseline when the schema is complete.

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

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

States the output format (PNG), the resource (the board) and the perspective ('as the human sees it'), which distinguishes it from a data-level read. It does not explicitly differentiate itself from the nearby canvas_export or canvas_read siblings, so an agent must infer the split.

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?

'To check your layout' implies the workflow (verify visual arrangement after drawing), but there is no explicit when-to-use versus canvas_export/canvas_read, and no statement of exclusions or preconditions.

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?

With no annotations, the description carries the full behavioral burden. It discloses useful scope details such as searching every folder and including other chats' live boards and saved copies, but it does not describe result limits, ordering beyond 'this one first', permissions, or pagination behavior.

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

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

Two sentences with no wasted words. The search scope is front-loaded and the next-step guidance follows immediately.

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

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

For a simple, one-optional-parameter search tool with no output schema, the description covers what it searches, where it searches, and what to do next. It could be more complete by stating the return shape or result limits, but it is largely 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 coverage is 100% and the query parameter is fully documented in the schema ('Words that must all match; omit to list the latest'). The description adds that matching is by name or text, which is minor added context, 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 (Find) and resource (boards) with a clear scope: every folder, this one first. It also distinguishes the follow-up action by naming canvas_open, though it does not explicitly contrast with other read/search 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 explains what to do with results ('Open with canvas_open {board} or {saved}') and implies this is a discovery step before opening. It does not explicitly state when not to use it or name alternative search tools.

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