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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that both endpoints must be pre-existing items and that IDs must be obtained first, but says nothing about permissions, reversibility, error behavior, or the return value of a create/mutation operation.

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

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

Four sentences, each earning its place, front-loaded with purpose then usage, prerequisite, and the sibling exclusion. 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 create tool with no output schema and no annotations, it covers purpose, usage, prerequisite, and alternatives well. The remaining gap is behavioral disclosure (permissions, error/idempotency behavior), which is not addressed.

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 seven parameters (color, label, style, board_id, end_marker, start_item_id, end_item_id) are already documented with descriptions and defaults. The description adds no parameter-level detail such as valid ID formats or color syntax, 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 a connector (line/arrow) between two existing items') with the consumed inputs named. It explicitly distinguishes itself from the sibling create_mindmap_node, so an agent can route without opening either schema.

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

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

Gives the use case (drawing relationships in diagrams), a prerequisite ('You need the item IDs of both endpoints — call list_board_items first'), and an explicit exclusion routing mind map hierarchies to create_mindmap_node. When-to-use, prerequisite, and alternative are all present.

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 usefully discloses that the call 'Returns the frame ID which you can then use to place items inside it,' which substitutes for the missing output schema. However, it says nothing about permissions, side effects, or board-state requirements for a write operation.

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

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

Three sentences, front-loaded with the core action and followed by grouping rationale and return value. Every sentence contributes, though the framing could be marginally 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?

For a creation tool with full schema coverage and no output schema, the description covers purpose, ordering guidance, and the returned ID. The absence of any mention of permissions or board-access prerequisites is the only notable gap.

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

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

Schema description coverage is 100%, so all seven parameters are already documented in the schema. The description adds no positional, sizing, or color detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Creates a named frame') and immediately clarifies what that resource is ('a rectangular container'), preventing confusion with sibling tools like create_shape or create_sticky_note. An agent can distinguish this tool 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 clear when-to-use guidance: 'Use this before populating a new area with items so they can be logically grouped.' It establishes the ordering context relative to item-creation tools, though it names no explicit alternative or exclusion condition.

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 and does well: it discloses the experimental API status, that the server auto-computes x/y, that missing coordinates default to (0,0) and stack nodes, the allowed request fields, and rate-limit behavior. It omits auth/permission requirements and what happens on an invalid parent_node_id.

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 essential layout rule (LTR, children to the right, vertical sibling spacing) before the supporting rationale. It is dense but the excursion into why the desktop + button lacks coordinates and the dual doc links make it longer than strictly necessary.

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 create tool with no annotations and no output schema, the description covers the layout model, coordinate fallback, sibling indexing, and rate limits well. Remaining gaps are auth requirements and error/return behavior, which are not covered anywhere given the missing output schema and 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 the per-parameter descriptions already carry most meaning (baseline 3). The description goes beyond by explaining how x/y auto-computation interacts with parent_node_id and layout_sibling_index, plus a worked example showing root/child/leaf combinations, which clarifies parameter interaction rather than just restating fields.

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 a native Miro mind map node') and scopes it to the experimental REST API. It is immediately distinguishable from siblings like create_sticky_note, create_shape, and update_mindmap_node/delete_mindmap_node.

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 concrete when-to guidance: omit parent_node_id for a root, pass layout_sibling_index when creating several children quickly because list_mindmap_nodes lags, and insert delays for rate limits. It does not, however, explicitly state when to prefer a mind map node over sibling primitives like create_sticky_note or create_shape.

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 behavioral burden. It implies additive, non-destructive creation, but says nothing about whether an item ID is returned for subsequent edits (no output schema exists), permission/auth requirements, or how x/y coordinates are interpreted. For a creation tool with zero annotation coverage this is a real 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?

Three tight sentences, front-loaded with the action and resource, then usage context, then the sibling routing note. 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?

Purpose and routing are complete enough for an agent to pick this tool, but with 11 params, no annotations, and no output schema, the description leaves positioning, frame scoping, sizing defaults, and post-creation behavior unexplained. Adequate as a selector, thin as a usage guide.

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 only 45% across 11 parameters, and the description adds no parameter meaning beyond what the schema already documents. Content, shape, and colors get partial schema descriptions while x, y, width, height, border_width, and frame_id are undocumented in both places, and the description does not compensate for that gap.

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

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

States a specific verb and resource (creates a geometric shape on the board), enumerates supported shape types, and notes the optional text content. It explicitly distinguishes itself from the mind map tooling by pointing to list_mindmap_nodes and create_mindmap_node, so an agent can route without opening either schema.

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

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

Gives positive use contexts (labels, containers, visual nodes in diagrams and flows) and an explicit alternative route with the condition that selects it: native mind map widgets with hierarchy/auto connectors belong to create_mindmap_node. Nothing about when-not-to-use is left to inference.

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

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

No annotations, so the description carries the full burden. It discloses useful behavior (optional frame nesting, color semantics), but says nothing about permissions/authorization, what happens on invalid frame_id, or the returned result for this mutation. Adequate but incomplete for a write operation with zero annotation coverage.

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

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

Three tight sentences, front-loaded with the core operation, then usage, then optional behavior and color guidance. No filler; each 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?

With no output schema and no annotations, the description covers purpose, usage, frame placement, and color semantics well. It is slightly thin on authorization/prerequisites and return behavior for a create tool, but nothing critical 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, and the description goes beyond the schema by explaining the semantic intent of the color parameter (yellow=ideas, red=blockers, green=done) and the frame_id nesting behavior, adding meaning the enum 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?

Specific verb (creates) plus resource (sticky note) plus scope (Miro board, specified position), and it implicitly distinguishes itself from siblings like create_shape and create_connector by naming the concrete artifact. An agent can route to 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?

The description gives concrete intended uses ('add ideas, tasks, labels, or annotations') and mentions optional frame placement, but never states when NOT to use it or names the alternative tools (e.g. create_shape for non-sticky content). Usage is implied rather than contrasted with siblings.

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 does disclose the key trait — deletion is permanent — which is valuable since destructiveHint is absent. But 'Use with caution' is vague, and it says nothing about required permissions, whether attached connectors or child elements are also removed, or error behavior.

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

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

Short, front-loaded, and the permanence warning lands early. 'Use with caution' is the one sentence that adds little beyond hedging, but overall the text is efficient.

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

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

For a destructive two-parameter tool with no annotations and no output schema, the description covers the essentials (what it does, permanence, when to use it). It still omits permission requirements and any cascade/side-effect details an agent should know before invoking an irreversible delete.

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% (both item_id and board_id documented in the schema), so the baseline of 3 applies. 'Requires item ID' merely restates the required field and adds no format, sourcing, or ID-acquisition guidance 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 and resource ('Deletes an item from the board') and adds the important qualifier 'permanently'. It does not name the sibling it most closely resembles, delete_mindmap_node, so the agent must infer scope from the word 'item' alone.

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

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

'Use this to clean up placeholder content or remove outdated items' gives concrete usage contexts, which is better than none. However, it offers no exclusions or alternatives (e.g., delete_mindmap_node for mindmap nodes) and no prerequisites beyond the required item ID.

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 and does disclose the critical behavior: the deletion cascades to all descendant nodes, which is exactly what a destructiveHint would otherwise convey. It omits permissions, reversibility, and error/partial-failure behavior, so it is not complete.

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 its destructive scope, followed by the prerequisite tool and reference link. 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 2-required-param deletion tool with no annotations and no output schema, the description covers what is destroyed, how to find the id, and where to read more. Only the absence of permission/error semantics keeps it from being fully complete.

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

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

Schema description coverage is 100%, so both board_id and node_id are already documented in the schema. The description adds no format or constraint detail beyond noting that the node's children go with it, 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 (deletes), a specific resource (native mind map node), and a precise scope (all descendant nodes), which separates it from the generic delete_item sibling. The parenthetical about the experimental REST API adds useful identity context.

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

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

Explicitly routes the agent to list_mindmap_nodes to obtain valid node ids, plus a docs link. It gives clear context for use but never states when to prefer this over the sibling delete_item or update_mindmap_node.

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 disclosure burden. 'Returns metadata' implies a read-only, non-destructive operation, and listing the returned fields gives real substance; however, it says nothing about error behavior for an invalid board_id, permission requirements, or rate limits.

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

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

Two sentences, no filler. The resource and its returned fields come first, and the usage guidance follows, which is the correct front-loading for a lookup 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?

There is no output schema, so listing the returned metadata fields in the description is genuinely load-bearing. That covers the main gap; only failure-mode and permission context are absent, which is minor for a single-parameter read.

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

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

Only one parameter, and the schema already documents it at 100% coverage, including the URL-extraction format. The description adds no meaning 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 ('Returns') and resource ('metadata about a Miro board') and enumerates exactly what metadata: name, description, creation date, owner, dimensions. This clearly separates it from every sibling tool, all of which operate on board items rather than on the board itself.

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 call it 'at the start of a session to confirm you are working on the correct board before reading or modifying content,' which gives a concrete trigger point and a rationale. It stops short of naming alternatives or stating when not to use it, so it falls just under the top band.

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 burden. It usefully discloses the return shape (item IDs, types, positions, text content) and the read-only nature is implied by 'Lists', but it says nothing about pagination or result-size limits, which matter for a board-wide listing.

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 operation and its filter, then the usage cue, then the return shape. No filler or redundancy.

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

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

With no output schema, the description compensates by describing the returned fields, which is appropriate. The only real gap is absence of pagination or large-board guidance; otherwise it is sufficient to call the 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 coverage is 100% and the type enum is fully documented in the schema, so the description repeats rather than extends it. It adds no format detail beyond what the schema already gives for board_id and type.

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 ('Lists all items on a Miro board') plus the optional type filter, which pins down the operation precisely. It does not explicitly name a sibling such as get_board_info or list_mindmap_nodes, 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?

'Use this to understand what is already on the board before creating or modifying anything' gives a clear situational trigger tied to the create/update/delete siblings. It stops short of naming an alternative (e.g. get_board_info for board metadata) or stating 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?

With no annotations, the description carries the full burden. It usefully discloses that the API is experimental, that style/node_view_style fields may be null when Miro omits fill/stroke data, and links to documented limitations. However it omits auth/permission needs, pagination, and rate-limit 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?

Front-loaded with the core purpose and the sibling differentiation before detail. It is somewhat long on return-field minutiae (nodeColor/border, fillOpacity, etc.), but every sentence remains relevant to 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?

With no output schema, the description must describe returns, and it does so adequately (node IDs, parents, text, positions, style fields and their nullability). The main residual gap is guidance on permissions or pagination for large boards.

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 there is only one parameter (board_id) fully documented in the schema, so the baseline of 3 applies. The description adds no syntax or format detail 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?

States a specific verb (Lists) and resource (native Miro mind map widget nodes) and explicitly differentiates itself from the sibling list_board_items by explaining that mind maps are text-based hierarchical nodes with auto-managed connectors. An agent can select it correctly without opening either schema.

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

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

Gives clear context ('Use this to read an existing mind map') and contrasts with the generic board-items tool, effectively routing the agent. It stops short of naming explicit when-not conditions or other sibling alternatives like create_mindmap_node/update_mindmap_node.

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 usefully discloses that coordinates are absolute board coordinates with center at (0,0), but omits whether the move is reversible/undoable, whether other items are affected, and any required permissions for a mutation.

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

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

Front-loaded with the core action and followed by usage and coordinate framing; every sentence earns its place. Tight and efficient with no 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 mutation tool with no annotations and no output schema, the description covers purpose, when to use, and coordinate semantics well. It could go further on side effects, reversibility, and failure behavior to be fully complete.

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

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

Schema coverage is 100%, so the schema already documents all four params and the baseline is 3. The description adds meaning beyond the schema by explaining the coordinate reference frame (absolute, center 0,0), which is essential to supplying correct x/y values.

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 ('Moves an existing item to a new position') that cleanly distinguishes it from creation, content-update, and deletion siblings. The coordinate-system detail further sharpens the intent.

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 use cases ('reorganize layout, avoid overlaps, or align items visually'), which tells the agent when repositioning is appropriate. It stops short of naming an alternative or exclusion (e.g., when to prefer update_item_content vs move_item).

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 burden. It usefully scopes the mutation to text only and states it does not move or delete the item, but it omits key behavioral facts: whether the new content fully replaces the old, whether formatting is preserved, and what happens if the item ID is invalid.

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, zero waste, and the core action is front-loaded before the usage note and prerequisite. Every sentence contributes distinct information.

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

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

With no output schema and no annotations, the description adequately covers purpose, non-destructive scope, and the ID prerequisite. The remaining gap is the replace-vs-merge semantics of the content field and any error behavior, which an agent would need for fully confident 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%, so all three parameters are already documented in the schema; the 3-score baseline applies. The description does add meaning for item_id by explaining how to obtain it, but it adds nothing for board_id or content beyond the schema's own text.

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

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

The description gives a specific verb and resource ('Updates the text content of an existing sticky note, shape, or text item') and explicitly contrasts itself with siblings by clarifying it does so 'without moving or deleting the item.' An agent can distinguish it from move_item, delete_item, and the create_* siblings 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 states when to use it ('to correct or improve existing content') and supplies a concrete prerequisite routing to another tool ('Requires the item ID — call list_board_items first if you don't have it'). It stops short of naming explicit when-not conditions (e.g., use create_sticky_note for new items), so it is strong context rather than full 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?

No annotations, so the description bears full disclosure. It flags the operation as experimental PATCH, states the content REPLACES the previous value, and pinpoints storage location (data.nodeView). It does not cover permissions, error behavior, or whether the board must be open, but the replacement semantics and storage field are meaningful non-obvious 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?

Three short sentences, front-loaded with purpose, followed by the sibling routing rule and then the storage/shape detail. 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 3-param mutation tool with no annotations and no output schema, the description covers purpose, the alternative to avoid, the storage field, and gives a concrete HTML example. Missing only permissions/response-shape detail, which is minor here.

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 schema already documents all three parameters (including that content replaces previous). The description adds the data.nodeView storage shape and one concrete HTML example, but does not add parameter-level meaning beyond the schema, so 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 (updates) and resource (existing native mind map node HTML/text content) and distinguishes itself from the sibling update_item_content by explaining that generic GET /items/{id} does not support mindmap_node. An agent can route correctly without opening any schema.

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

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

Explicitly says 'Use this instead of update_item_content' and supplies the reason (generic item endpoint doesn't support mindmap_node). The alternative and the selecting condition are both named.

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