Mapache

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

Annotation coverage is broad (readOnly=false, destructive=false, idempotent=false, openWorld=false), yet the description still adds real behavioral context beyond it: comments never appear in exports, are signed with the agent name, appear live for everyone, and the call returns the comment id plus mentions. It stops short of noting that repeat calls create separate comments or any permission requirements, so it is strong but 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?

The purpose is front-loaded in the first clause, and each subsequent sentence contributes a distinct fact (placement, mentions, export invisibility, attribution, return value, alternative tool). No filler or restatement of the name/title.

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

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

With no output schema, the description compensates by stating what comes back (comment id and who was mentioned). Combined with the placement, mention, and visibility semantics, an agent has everything needed to invoke this correctly and interpret the result.

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 already 100%, so the baseline is 3, but the description adds meaning the schema does not: the "@Name" mention syntax, the fact that "on" accepts an id or its text, and that omitting x/y/on falls back to free space. That is genuine semantic value on top of the structured 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?

The description states a specific verb and resource ("Leave a comment on a board") and immediately scopes the targeting modes (pinned to a node/item or at a point). It explicitly distinguishes itself from the sibling reply_comment, so an agent can route 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?

It gives explicit when-to-use ("ask or suggest instead of changing the person's work") and when-to-use-something-else ("to answer an existing thread use reply_comment"). It also carves out a domain boundary — comments are for talking about the board, not content — which prevents misuse.

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

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

Annotations declare only write/idempotency flags, but the description adds genuinely new behavioral context: the change is committed immediately as a new board revision, syncs live to open browsers, is reversible by the human via Ctrl+Z, and auto-places items in free space unless x/y are given. Because there is no output schema, it also discloses the return value (each new item with its type and 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?

Four sentences, front-loaded with the core action and item types, then sequencing, then side effects, then the sibling redirect. Every sentence carries a distinct piece of information with no restatement of the schema.

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

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

For a non-idempotent mutation tool with no output schema, the description covers what is created, how it is placed, the table-before-chart dependency, the immediate revision/live-sync/undo behavior, and the return shape. Nothing an agent needs to call or chain this tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema does not: items are grouped and laid out in free space unless x and y are supplied, and a chart's table parameter must reference a previously added table's id. That sequencing and layout rule is real added value beyond the per-field descriptions.

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

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

Opens with a specific verb and resource ("Add sticky notes, text, shapes, sections, stickers, tables, charts or video embeds to a board") and enumerates the item types, so the agent knows exactly what it produces. It also names the sibling it is not ("For mind map branches use add_nodes instead"), making it distinguishable without opening another schema.

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

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

Gives explicit routing guidance: use add_nodes for mind map branches, and for charts add a table first then reference it by id. It also points forward to downstream tools (connect, update_items) for the returned ids, leaving little to inference.

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

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

Annotations only declare readOnly=false, idempotent=false, destructive=false. The description goes well beyond: it saves immediately as a new revision, appears live in open browsers, is undoable via Ctrl+Z, and returns the central idea's id. This is exactly the extra context the annotation bar requires.

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?

Every sentence earns its place: purpose, outline semantics, placement, side effects, return value, and alternative routing. Front-loaded with the core action and 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 6-param mutation tool with no output schema, the description covers placement behavior, persistence/live-sync side effects, the return value, and the alternative tool. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds conceptual meaning beyond the schema by explaining that the first outline line is the central idea and indented lines are branches, and that x/y are optional placement in free space. That is real value over the schema's field descriptions.

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 (add a separate mind map to an existing board), clarifies a board can hold several, and explicitly distinguishes itself from the sibling add_nodes. An agent can tell it apart from the nodes tools without opening a schema.

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

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

Explicitly routes the agent: 'To grow a map that already exists use add_nodes.' It also names the when-not condition (existing map vs. new map), leaving nothing to inference.

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

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

Annotations cover the safety profile (readOnly=false, idempotent=false, destructive=false), and the description adds substantial context beyond them: the change is saved immediately as a new revision, propagates live to open browsers, and is undoable via Ctrl+Z. It also states the return payload (each new node with its id), which is otherwise undisclosed since there is no output schema.

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

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

Three tight sentences: the action and input modes come first, then behavioral guarantees, then sibling routing. Every clause carries information and nothing is padded.

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

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

For a non-idempotent mutation with no output schema, the description supplies exactly the missing pieces: revision semantics, live propagation, undo availability, and the shape of the return value. Nothing an agent needs to call it correctly is absent.

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

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

Schema coverage is 100%, so all five parameters are already documented, including the outline-vs-texts alternatives and the parent path syntax. The description restates the two input modes ('indented outline (nested branches) or a flat list of texts') but adds no format, default, or edge-case detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Add child nodes under an existing node of a mind map') and names the two input modes (indented outline or flat text list). It explicitly differentiates itself from siblings add_mindmap and create_board, so an agent can route correctly without opening schemas.

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

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

Gives explicit when-to-use ('Use it to grow a map') plus named alternatives with their own conditions ('use add_mindmap for a separate new map and create_board for a new board'). The add-vs-create distinction is spelled out rather than implied.

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

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

Adds substantial context beyond the annotations: each call is additive ('does not replace existing ones'), paths auto-route around other objects, the change saves as a new revision and appears live, and it is undoable via Ctrl+Z. This is exactly the mutation/live-sync behavior an agent needs and the annotations don't supply.

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

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

Front-loads what the tool does, then layers additivity, live-sync, return value, and the modify path in tight sentences with zero 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?

With no output schema, the description still states the return ('how many connectors were added') and covers additivity, routing, persistence, and undo. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% with detailed nested descriptions for from/to/label/route/style/endCap, so the schema carries the semantics. The description only adds 'optionally with a label,' which the schema already documents, 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 (Draw) and resource (connectors/arrows between nodes and items) plus the use case (flowcharts and relations). An agent can distinguish this from add_items and update_items 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?

Gives clear context (flowcharts and relations) and explicitly routes the modify case: 'To change a connector later use update_items with its id.' It stops short of stating when to add a connector vs. a node/item from add_items, so no full exclusion set.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false; the description reinforces non-idempotency with a concrete consequence ("calling it twice makes two") and discloses the return payload (board id, central idea id, address). It also explains the outline-to-central-idea resolution rule, which no annotation covers, though it says nothing about permissions or folder-side effects beyond what the schema states.

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 sentences: purpose first, then outline semantics, then non-idempotency, then return values, then the sibling redirect. Each sentence carries distinct information, though the response-payload clause overlaps slightly with what an output schema would normally carry.

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 naming the three return values, and it covers the one genuinely ambiguous input (outline structure) plus the re-invocation hazard. For a four-parameter create tool with full schema coverage, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value beyond the schema: the rule that a single top line becomes the central idea while multiple top lines push the title into that role. That interpretation logic is not in the schema and directly affects how an agent should shape the outline argument.

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

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

The description opens with a specific verb+resource ("Create a new board with a mind map") and immediately differentiates itself from siblings by naming add_nodes, add_mindmap and add_items as tools for existing boards. An agent can distinguish this from create_folder or add_items 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 the explicit when-not condition ("To add to an existing board use add_nodes, add_mindmap or add_items instead") and gives the alternative tool names. The non-idempotency warning ("calling it twice makes two") is exactly the guidance an agent needs before retrying a create call.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so safety is covered. The description adds real behavioral value anyway: it confirms non-idempotency in plain language ('Always creates a new folder, even if one with the same name exists'), states that the returned id is the useful output, and warns that the parent must already exist or you get an error.

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 action, then the non-idempotency caveat, then the routing guidance to siblings. No filler or restatement of the title.

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

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

There is no output schema, but the description closes that gap by saying it returns the folder id. Combined with the error condition on parent and the sibling routing, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so name, icon, color and parent are fully documented in the schema itself, making 3 the baseline. The description only gestures at placement ('optionally inside another folder') without adding syntax or format detail, so it does not exceed the schema's own documentation.

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

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

States a specific verb and resource ('Create a folder in the sidebar') plus the scope it affects (organize boards). It also positions itself against siblings by noting create_board/update_board handle folders implicitly, so an agent can disambiguate without opening schemas.

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

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

Explicitly says 'You rarely need it' and names the alternatives (create_board, update_board) along with the condition under which they cover the need (passing a folder path). This is a rare case of an explicit when-not-to-use plus a named substitute.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so safety is covered. The description adds genuinely useful recovery semantics: the delete is a reversible trash move restorable via `mapache restore <id>`, and it notes the result carries the id. It stops short of stating permission requirements, but goes well beyond the annotations.

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

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

Three short sentences, each earning its place: what happens, how to undo it, when to use it, and what to use instead. The core action is front-loaded and there is 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?

There is no output schema, and the description compensates by telling the agent the result returns the restore id. For a one-parameter destructive tool, the action, reversibility, precondition, and alternatives are all present.

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 `board` parameter (including the "open" sentinel) is fully documented in the schema itself. The description adds no syntax or format detail for the parameter, 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 ("Move a whole board to the trash") and immediately scopes it against siblings by naming delete_nodes and delete_items for partial removal. An agent can distinguish this from the other delete tools 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?

Explicit when-to-act guidance ("Only do this when the person asks") plus an explicit alternative and the condition that selects it ("To remove part of a board use delete_nodes or delete_items instead"). Nothing 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?

Annotations already flag destructiveHint=true and idempotentHint=true, but the description goes further: it discloses the cascade (attached connectors are also removed), the comment behavior (pinned stay, unpinned go), that the action is user-undoable via Ctrl+Z, and that it returns a removal count. That is real behavioral value beyond the structured hints.

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 with zero filler; scope, precondition, side effects, undo, and the sibling routing are all front-loaded in priority order. Every clause carries information an agent needs.

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

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

No output schema exists, and the description covers the return value ('how many items were removed'), the destructive side effects, the undo path, and the sibling alternative. Nothing material is missing for a two-parameter destructive tool.

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

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

Schema coverage is 100%, so both parameters ('board' including the "open" sentinel, and 'items' as ids or exact texts) are already fully documented in the schema. The description adds no format or syntax detail beyond that, so the baseline 3 applies.

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

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

Names a specific verb (delete) plus the full range of resources affected (notes, shapes, tables, charts, connectors, other items) and explicitly routes mind map nodes elsewhere. An agent can distinguish it from delete_nodes and delete_board 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?

States a hard precondition ('Only when the person asks') and names the correct alternative for a sibling case ('For mind map nodes use delete_nodes'). Both when-to-use and when-to-use-something-else are explicit.

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

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

Annotations already declare destructiveHint=true, but the description adds substantive behavior an agent cannot infer: deletion is recursive over descendants and connectors, comments pinned to deleted nodes survive while unpinned ones do not, the main map's central idea is protected, the action is user-undoable via Ctrl+Z, and the result reports a count. That goes well beyond the structured safety hints.

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 destructive scope and dense with information in only four sentences — very little waste. The parenthetical 'comments pinned to them stay, unpinned' is compressed to the point of ambiguity about what happens to unpinned comments, costing a point.

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

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

For a destructive, no-output-schema tool, the description covers the cascade, the protected central idea, the comment side effect, the undo path, and the return value ('Returns how many nodes were removed'). Nothing essential for calling it correctly is missing despite the absence of an output schema.

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

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

Schema description coverage is 100%, so both `board` and `nodes` are already documented with formats and the 'open' sentinel. The description adds no syntax or format detail beyond the schema; the only relevant extra is the central-idea restriction, which is a constraint rather than parameter semantics. Baseline 3 applies.

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

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

States a specific verb+resource (delete nodes) and immediately scopes it with cascade semantics ('every node under them, plus the connectors attached to them'). It also names the sibling to use for the opposite operation ('update_nodes'), so an agent can distinguish it from update_nodes, delete_items, and delete_board 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?

Gives an explicit usage gate ('Only when the person asks'), names the alternative for a non-destructive need ('To change a node instead use update_nodes'), and notes the escape hatch ('they can undo it in the app with Ctrl+Z'). When, when-not, 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?

Beyond the annotations, it discloses meaningful side effects: the app renders the file, may open the browser and switch to that board, the board itself is unchanged, and the file never overwrites an existing one (a number is appended). It also states the return content (save location and file size). This is exactly the behavioral context the annotations cannot convey.

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

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

The description is front-loaded with the core purpose and format guidance, then parenthetical detail on rendering behavior. Slightly long and the browser-switching aside is a touch verbose, but every sentence contributes information an agent would use.

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 stating what is returned (save path and size), along with format options, defaults, and side effects. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the parameter definitions already carry the format enum semantics and the Downloads default. The description's format exposition largely restates the schema, adding only the note that a numbered name is used to avoid overwriting. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb and resource ('Save a board as a file the person can share') and enumerates the supported output formats. It is clearly distinct from siblings like open_board, delete_board, and read_board, so 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?

It gives concrete selection guidance for the format parameter ('html' for a shareable browser page, 'pdf' for printing, 'png' for an image, 'svg' for vector). It lacks explicit when-not-to-use or alternative-tool routing, but no sibling performs the same export function, so there is little to disambiguate.

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

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

Annotations already declare readOnlyHint=true, and the description's "Read-only" restates rather than extends that. It does compensate by disclosing the return shape in detail (one line per board with title, id, folder, node/item/comment counts, last change, and which board is open, plus the folder list), which is valuable given there is no output schema. It skips auth, rate limit, 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?

Three sentences, zero filler, and the front-loading is deliberate: scope first, payload second, routing third. Every sentence earns its place for an agent deciding whether to call it.

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 no-argument, read-only listing tool with no output schema, the description covers what it returns, that it is safe, and where to go next. Nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema coverage is 100% and the single folder parameter is fully documented there, including its name/path/id forms and the leave-out default, so the baseline is 3. The description only implies the filter exists via the returned folder list and does not add format or syntax 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 and resource ("List every Mapache board") and scopes it precisely by naming the two board kinds it covers, mind maps and whiteboards. An agent can immediately distinguish it from read_board, search_boards, and the mutation 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 explicitly positions itself as an entry point ("Start here") and routes to the correct alternatives with conditions: read_board "to see a board's content" and search_boards "to find text across boards." No inference is required to pick the right tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so 'Read-only' largely repeats structured data. The description earns credit by disclosing the return shape (id, author, date, pin target, text, replies) and the sort order ('oldest first'), which is behavior the annotations cannot convey and which matters because no output schema exists.

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

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

Three tight sentences: purpose, return contract, then usage and routing. Front-loaded with what the tool does and free of 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?

With no output schema, the description does the necessary work of enumerating returned fields and ordering, and parameters are fully documented in the schema. Minor gaps remain around result volume or pagination behavior for boards with many threads.

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%, including the non-obvious 'open' sentinel for board and the default-false semantics for include_resolved, so the schema carries the meaning. The description adds only the implicit ordering, not parameter-level detail, making the baseline 3 correct.

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

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

States a specific verb and resource ('List the comment threads on a board') and immediately distinguishes itself from the mutation siblings by naming the reply/resolve tools as follow-ups. An agent knows this is the read side of the comment workflow without opening the schema.

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

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

Explicitly gives the triggering context ('when the person asks you to review a board or answer comments') and routes to the downstream tools reply_comment and resolve_comment. It does not, however, state when NOT to use it (e.g. vs read_board or list_boards), so it stops short of full when/when-not coverage.

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

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

Adds substantial behavior beyond the annotations: the change is saved immediately as a new board revision, appears live in any open browser, and is undoable via Ctrl+Z, and it returns a confirmation. Annotations (readOnly=false, destructive=false, idempotent=true) are consistent with an undoable 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 scoped parenthetically, then constraints, then side effects and return value. Every sentence carries information and nothing is padded.

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

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

With no output schema and full annotation coverage, the description still supplies the persistence model, live-update effect, undo path, and return value. An agent has everything needed to invoke and reason about the call.

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 each parameter already documents its accepted forms (id, text, path; board id/title/'open'; position index semantics). The description reinforces the parent/position reorder relationship but adds no syntax or meaning beyond the schema, 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 (move) plus resource (node/branch) and scope (under another parent in the same board, or reorder among siblings). This clearly separates it from add_nodes, update_nodes, and delete_nodes, so an agent can identify 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?

Explains the two modes of use (reparent vs. reorder via current parent + new position) and states the important constraint that a node cannot go under itself or its own children. It does not explicitly name an alternative tool, but the usage context is unambiguous.

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

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

Annotations only declare readOnlyHint and openWorldHint=false; the description adds meaningful behavioral detail the annotations do not cover: that Mapache may be started if not running, that the board is not modified, and that the return value is the address. This is good added context, though it doesn't detail failure modes or timing.

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 tightly packed sentences, front-loaded with the core action and scope, then the suggested use and the launch nuance. Every clause carries information with no padding.

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

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

For a read-only, zero-required-parameter tool with no output schema, the description covers purpose, effect boundary, side effect (starting the app), and return value. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema, and the enum-like value 'open' for board is defined there. The description restates the launch=false behavior but adds no new syntax or format detail beyond the schema, 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 (open), resource (a board), the surface it opens in (the person's browser, starting Mapache if needed), and the effect boundary ('it does not change the board'). This clearly separates it from read_board and export_board.

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 usage guidance: 'Offer it after a big change; set launch to false to only get the link.' This tells the agent when to invoke it and how to get link-only behavior. It stops short of naming an explicit alternative (e.g., read_board for content vs. open for viewing), leaving minor 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?

Adds real context beyond the annotations: what the payload contains, that each item carries the id the editing tools require, and that open comments are only partial, with list_comments as the escape hatch. "Read-only" merely restates readOnlyHint=true rather than adding new information, which keeps it from a 5.

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

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

Three sentences, each doing distinct work: what it returns, the read-only confirmation plus id contract, then the routing rules. The payoff and the sibling pointers are front-loaded 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?

With no output schema, the description carries the return-value burden and does so by listing the content categories and the id contract needed by editing tools. For a two-parameter read tool with annotations covering safety, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and both parameters are documented there, including the "open" sentinel and the markdown/json tradeoff. The description only implies the default outline format ("indented outlines") and adds no syntax or constraint detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ("Read a whole board") and enumerates exactly what comes back: mind maps as indented outlines, notes, shapes, tables, charts, connectors, images, open comments. This clearly separates it from list_boards (enumeration), view_images (image content) and list_comments (threads).

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 an explicit precondition ("Call it before changing a board you have not read in this conversation") and names two alternatives with the condition that selects them: view_images for what images show, list_comments for full comment threads. An agent needs no inference to choose correctly.

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

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

Annotations establish the write, non-idempotent, non-destructive profile, and the description adds genuinely non-derivable behavior: the reply is signed with the agent name, appears live, and reopens a resolved thread. It stops short of covering failure modes such as an unresolvable comment reference or permission errors.

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

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

Five short sentences, each carrying distinct information (thread requirement, signing, side effect, mention syntax, return shape), with the routing pointer placed last as a natural closer.

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

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

No output schema exists, but the description still discloses what comes back (thread replied to and who was mentioned), and the mutation's side effects are narrated, leaving no material gap for a 3-parameter tool.

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

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

Schema description coverage is 100%, so the baseline is 3; the description goes beyond it by specifying the @Name mention convention, which the schema only calls "plain text" and would otherwise be undiscoverable.

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 ("Reply in an existing comment thread") and explicitly routes the alternative case to add_comment for new threads, so it is distinguishable from its closest sibling without opening either schema.

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

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

Names list_comments as the way to locate the thread, states the condition for the alternative ("To start a new thread use add_comment"), and flags the side effect of replying to a resolved comment. Nothing about when to pick this tool 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?

Annotations already declare non-destructive and idempotent, and the description reinforces this with substantive side-effect detail that annotations cannot express: resolved threads remain on the board, disappear only from the open list, and nothing is deleted. It also discloses the dual resolve/reopen mode and the return value (comment 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?

Three sentences, front-loaded with the action, followed by side-effect clarification and the sibling hand-off. Every sentence carries distinct information with no padding.

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

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

For a three-parameter mutation with no output schema, the description covers the action, the alternate mode, side effects, reversibility of appearance, and the return value, which is everything an agent needs to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by framing 'reopen' as an in-place toggle of the same operation rather than a distinct tool, and by implying the comment selector accepts partial text matches as the schema notes. It does not add syntax or edge-case detail beyond that.

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 (mark as resolved / reopen) on a specific resource (comment thread), and explicitly distinguishes itself from reply_comment. An agent can tell exactly what operation this performs without inspecting 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 an explicit trigger condition ("once you have done what it asked") and names the alternative for the adjacent case ("To answer before resolving use reply_comment"). The when-to-use and which-sibling decision are both spelled out.

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

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

Annotations declare readOnlyHint=true, and the description reinforces read-only plus adds non-obvious behavior: matching ignores case and accents, and results are capped at 30 hits per board. It does not mention pagination or truncation beyond that cap, which is the main remaining 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 ordered scope → matching/return behavior → usage routing. No filler and the distinguishing information is front-loaded.

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

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

There is no output schema, so the description carries the return-shape burden and does so: per-board title and id plus up to 30 hits with ids. Combined with scope and routing, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100% for the single 'query' parameter and the schema already documents substring matching that ignores case and accents. The description's matching note duplicates the schema rather than adding new syntax or format guidance, so the baseline 3 applies.

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

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

States a specific verb+resource (search text across all boards) and enumerates the searched fields (titles, nodes, notes, shapes, tables, sections, connector labels, comments). It explicitly distinguishes itself from read_board, so the agent can route correctly 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 both when-to-use ('find which board talks about something') and the alternative with its condition ('use read_board to see one board in full'). This is explicit routing guidance against a named sibling.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower. The description still adds real context beyond that: it is a partial/patch update where unspecified fields are preserved, board content is untouched, and it returns a confirmation plus the board address. It stops short of detailing failure modes, but that is a minor gap given the 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 short sentences, front-loaded with the operations, then the partial-update rule, then the routing to sibling tools. Every sentence earns its place with no restatement of the name or annotations.

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

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

There is no output schema, and the description fills that gap by stating 'Returns a confirmation and the board address.' Combined with the patch semantics and sibling routing, an agent has everything needed to select and call this tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description maps intent to parameters (rename→title, move→folder, color/icon) but adds no format or syntax details beyond the schema, and does not mention the special 'open' board value that the schema documents. Adequate, but the schema does the heavy lifting.

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

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

States specific verbs and resource: 'Rename a board, move it to a folder, or change its color or icon in the sidebar.' It also explicitly carves out the content-editing scope and routes it to update_nodes/update_items, so an agent can distinguish it from sibling tools without opening a schema.

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

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

The description gives explicit alternatives: '(to edit content use update_nodes or update_items)', which is exactly the boundary an agent needs when choosing between metadata edits and content edits. No exclusions left to inference for the primary fork, and the partial-update rule ('Only the fields you pass change') tells the agent how to invoke 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 only establish readOnly=false, destructive=false and idempotent=true; the description goes well beyond them by describing partial-update semantics (only passed fields change, non-applicable fields are ignored), the validation error on an invalid color, immediate persistence as a new board revision, live propagation to open browsers, undo via Ctrl+Z, and the return value. This is exactly the write-path behavior an agent needs and it is consistent with the annotations.

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

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

Front-loaded with purpose, then behavior, then the sibling pointer. The long parenthetical item list and the many clauses are dense but each sentence carries distinct information; only the enumeration of item types is arguably padded, costing it a perfect score.

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 bulk-mutation tool with no output schema, the description covers the full picture: what can be changed, partial-update behavior, error behavior, persistence and undo, live effects, and what is returned (count of changed items). Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so per-field documentation is already handled and the baseline is 3. The description exceeds that by adding cross-field semantics not present in the schema: only the fields you pass are changed, fields not applicable to an item type are silently ignored, multiple items can be updated per call, and the color error lists valid alternatives.

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 (change/edit) and resource (existing items), enumerating the item types covered: notes, text, shapes, sections, tables, charts, connectors. It also explicitly routes mind map nodes to the sibling update_nodes, so an agent can distinguish it from update_nodes, add_items and delete_items 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 gives clear context for when this applies (modifying existing items, including bulk multi-item edits) and names the alternative for mind map nodes. It stops short of full when-not guidance — it never contrasts itself with add_items for creation or delete_items for removal — but the routing rule to update_nodes is explicit.

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

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

Goes well past the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) by disclosing partial-update semantics ("only the fields you pass change"), the persistence model (saved at once as a new revision of the board), live propagation to open browsers, and user recoverability via Ctrl+Z. It also states the return shape ("Returns how many nodes changed"), which is valuable given there is no output schema. The revision-per-call note is a minor tension with idempotentHint but not a contradiction of the tool's resulting state.

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

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

Front-loaded with the verb and the editable field list, then behavior, then sibling routing. Every sentence carries information (what changes, when it saves, what it returns, what to use instead) with no filler or restatement of the name.

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

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

Despite having no output schema, the description covers the return value, the mutation semantics, persistence and visibility behavior, and the escape hatch to sibling tools. For a two-parameter tool with fully documented nested fields, nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the per-field semantics are already documented in the schema (icon, node, text, color, checked, collapsed). The description adds one genuinely non-obvious rule the schema omits: fields not passed are left unchanged, which matters for a multi-node update array.

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

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

Opens with a specific verb+resource ("Change existing mind map nodes") and enumerates exactly which attributes are editable: text, branch color, icon, folded state, checkbox. It also names the adjacent operations it is not (add_nodes, move_node, delete_nodes), so an agent can separate it from 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?

Explicitly routes the three nearest alternatives: add_nodes for creation, move_node for repositioning, delete_nodes for removal, which covers the realistic confusion set. It also states the batching rule ("Several nodes in one call") and the per-field conditional semantics, giving the agent a clear sense of when this tool is the right pick.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered and the description repeats 'Read-only' only briefly. It adds real behavioral value the annotations don't carry: return format (image content preceded by id, position, size), ordering (top-to-bottom then left-to-right), and the pagination/continuation behavior. It stops short of noting size limits or content-type caveats, so not a full 5.

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

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

A single dense paragraph, but the core purpose is front-loaded and the ordering/limit/continuation facts follow logically. No filler sentences; the density is slightly harder to scan than a bulleted form but 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?

No output schema exists, so the description's job includes explaining returns — which it does (image content plus id, position, size, in reading order) along with truncation behavior. Combined with 100% schema coverage and read-only annotations, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: it clarifies the interaction between items and limit (no ids → first N in reading order) and the origin of item ids (from read_board). This connects the two parameters into a workflow rather than restating field 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?

States a specific verb and resource ('See the images placed on a board'), enumerates the content types it covers, and explicitly contrasts with the sibling read_board ('read_board only lists them'). An agent can distinguish this from read_board and list_boards 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?

Gives concrete routing guidance: use read_board to enumerate, this tool to actually see images; pass item ids from read_board for targeted viewing, or omit them to get the first N in reading order. It also explains the follow-up pattern when the limit is hit (remaining ids are reported so they can be requested next call).

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