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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the mutation profile is covered. The description adds two genuinely useful behavioral facts beyond that — the operation is a single atomic 'undoable step', and the default origin is the nodes' current top-left. It still omits whether unlisted nodes are affected and whether existing positions are overwritten.

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 tight sentences with no filler. The primary action and its options come first, followed by the one-line behavioral note about undo, which is the right front-loading order.

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 4-parameter mutation tool with a nested origin object and no output schema, the description covers layout modes and the origin default but leaves 'gap' undefined and says nothing about how the result is reported. Adequate but with clear gaps for an agent trying to call it precisely.

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 0% at the top level, so the description carries real weight. It explains the layout enum values, including that 'tree' arranges by links, and gives the origin default, which are meaningful additions. However, 'gap' is never described in either place, and 'ids' only gets partial coverage from the nested item description.

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 ('lay out existing nodes') and enumerates the exact layout modes from the enum, so an agent can match intent to the tool without opening the schema. It does not explicitly differentiate itself from the sibling 'move_nodes', which is the nearest alternative for repositioning.

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

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

Usage is implied rather than stated: the word 'existing' signals this operates on already-created nodes, and 'tree (by their links)' hints at a link-dependent mode. There is no explicit when-to-use guidance, no mention of when to prefer move_nodes, and no prerequisites or exclusions.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false. Description adds useful behavioral context beyond annotations: linking rules apply, refused links explain why, and the operation is a single undoable step. Good extra transparency.

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?

Dense but well-structured single paragraph. Front-loads the core action, then adds rules and undoability. No wasted words.

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

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

For a mutation tool with no output schema, the description covers the key operational details: what it does, constraints (existing nodes, hive rules), error behavior (refused links explain why), and reversibility (one undoable step). Missing explicit output format details, but annotations and the undo hint cover most needs.

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 has 0% description coverage at the top level, but nested items do have descriptions for 'to', 'from', 'kind', and 'shape'. The description mentions 'strong = arrow from → to, weak = dashed' which adds some meaning but doesn't explain 'shape' or parameter structure fully. With nested schema descriptions present, 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+resource: draws lines between existing nodes. Distinguishes from delete_links/update_links/list_links by the 'create' operation, but doesn't explicitly contrast with the sibling update_links.

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

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

Implies usage by saying nodes must exist and beacons follow special rules, but gives no explicit when-to-use-this-vs-alternatives guidance. No mention of update_links for modifying existing links.

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=false): it discloses that the whole batch is a single undoable step, that nodes inherit the Q-menu defaults, that placement never overlaps existing nodes, and that name collisions get a numeric suffix. These are non-obvious behaviors an agent would otherwise have to discover by trial.

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 placement rules, then ref linking, then return values. Every sentence carries information, though the middle is dense and could be broken into clearer clauses.

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 correctly states what is returned (final ids, names, positions) and covers the mutation's reversibility and default behaviors. It omits practical limits (the 200-node cap in the schema) and any permission/auth requirements, which are minor gaps for a creation 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 only 60%, but the description compensates by explaining the placement precedence order, that origin defaults to the centre of the visible area, and how ref enables intra-call linking (with a mind-map example). It adds real meaning beyond the schema for the placement parameters, though it is silent on gap/layout interactions.

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 (Create) and resource (nodes of any kind), plus the batch+link scope in one undoable step. This distinguishes it clearly from update_nodes, delete_nodes and create_links, which an agent can rule out 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?

Usage guidance is strong at the parameter level (placement precedence: explicit x/y → near → origin/layout, and ref-based linking within the call), but it never says when to prefer this tool over siblings such as create_links, import_file, or a create-then-arrange sequence. Context is implied rather than stated.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=false). The description adds valuable undo behavior ('One undoable step'), which is not in the annotations, but omits other traits such as whether the name must be unique, what happens on invalid rects, or whether the zone persists automatically.

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 core verb and object, then the two creation modes, then the undo behavior. Every phrase carries information.

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

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

For a create tool with nested objects, zero schema description coverage, and no output schema, the description should clarify required/optional structure and any effects beyond undo. It leaves parameter semantics, validation behavior, and result shape unexplained.

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 0%, so the description should compensate. It clarifies the semantic mode of rect and around but does not explain units, coordinate meaning, padding semantics, or the optionality/relationship between name, color, and the two geometry inputs. Baseline is lowered for low coverage, but the description adds only partial meaning.

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 zone') with two distinct modes (explicit rect or around nodes with padding). Distinguishes itself from siblings like update_zone and delete_zones by naming both creation paths, though it doesn't explicitly contrast with those siblings.

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

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

Implies usage by describing the two input modes, which lets an agent infer when to use rect vs around. But it offers no explicit when-to-use guidance, no prerequisites, and no mention of alternatives (e.g., when to prefer zones vs node grouping).

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, readOnlyHint=false and non-idempotent, so the safety profile is covered. The description adds two traits the annotations do not carry: only links are affected (nodes survive) and the operation is 'one undoable step', which usefully links it to undo_last_change. Return/failure behavior is still undisclosed.

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 clauses, zero filler, and the scope constraint is front-loaded before the undo note. Nothing extraneous to trim.

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

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

For a one-parameter destructive tool whose annotations already flag destructiveness, the description covers the essentials (target, side-effect boundary, reversibility). It omits what happens with unknown ids, partial failures, and the return value, so it is adequate but not 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 0% and the single parameter is an ids array. The description says 'by id' in the singular, which is mildly at odds with the batched array (minItems 1, maxItems 500) and adds no detail on batching limits or how invalid ids are handled, so it fails to compensate for the coverage 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 ('Remove links') and immediately scopes it against the obvious sibling by clarifying '(nodes stay)', so an agent can distinguish it from delete_nodes without reading either schema. The subject is unambiguous.

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

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

'Remove links by id (nodes stay)' implies the use case and rules out node deletion, but it never states when to prefer this over update_links or when-not to call it. Usage is inferable rather than 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 and readOnlyHint=false, so safety is covered. The description adds genuinely useful context beyond annotations: items are restorable via restore_from_trash, links are deleted along with nodes, mode 'archive' switches behavior to archiving instead of trash, and the operation is described as 'one undoable step'. That's real behavioral disclosure.

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

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

Three short clauses, no filler, front-loaded with the core behavior and then layering recovery, the mode alternative, and the undoability. Every phrase adds 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?

Covers the essential agent questions for a destructive node tool: what happens (trash + links), how to reverse it (restore_from_trash, undo), and the archive alternative. No output schema exists, but the description adequately describes the outcomes. It could mention any limits (e.g., the 500 maxIds cap) but that is captured by the schema.

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

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

Schema description coverage is 0% and there is a bare enum with no per-value description in the schema—so the description carries the burden. It explains what 'archive' mode does versus default trash behavior, which is the key semantic the agent needs. It does not elaborate on the 'ids' array format, though the schema itself documents that via item description.

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 (delete) and resource (nodes), and it goes further by analogizing to the Delete key in hive and naming the trash-vs-archive outcome. It also names restore_from_trash as the recovery path, which differentiates it from sibling deletion tools like delete_links or delete_zones.

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?

Clearly signals when to use it (mirror the Delete key behavior) and introduces the 'archive' alternative via the mode parameter, referencing restore_from_trash for recovery. It does not explicitly say when NOT to use it versus delete_links or delete_zones, but the node-scoped framing is clear enough.

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 and non-idempotent, so the safety profile is covered. The description adds genuinely useful context beyond that: the blast radius (nodes remain on the board) and that the deletion is a single undoable step reversible via undo_last_change. It does not mention what happens to links attached to the deleted zones.

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, front-loaded clauses with no filler. The core action and its side effect come first, though the phrasing is clipped to the point of being terse.

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, non-idempotent bulk delete with no output schema, the description covers the key side effect and reversibility, which is the most important part. It omits what the caller passes (IDs), whether links to the zones are affected, and whether the operation can partially fail.

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 0% for the single required 'ids' parameter, and the description never mentions that deletion targets a list of zone IDs or any constraint such as the minimum of one item. With low coverage the description is expected to compensate, and it does not.

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 ('Delete zones') and immediately clarifies scope by noting that contained nodes survive, which differentiates it from the sibling delete_nodes. It stops short of explicitly naming delete_nodes as the contrasting alternative, but the effect on nodes makes the distinction inferable.

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

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

There is no statement of when to use this tool versus alternatives such as delete_nodes or delete_zone-like siblings, nor any prerequisite or exclusion. 'One undoable step' describes a behavior, not a usage condition, so the agent gets no routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds a real operational prerequisite — "Needs hive running" — which is behavioral context the annotations do not carry. It does not describe response size or caching, so not a 5.

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

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

Front-loaded with the core subject ("Every node kind hive supports") followed by a dense but purposeful enumeration of contents, then the usage note and prerequisite. It is a single long sentence, which is heavy, but nearly every clause carries distinct information.

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

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

With no output schema, the description must convey what is returned, and it does so thoroughly — kinds, their metadata, kind-specific data fields, and the enumerated allowed values. An agent knows what it will get and when it needs to call this.

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

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

The tool takes zero parameters and the schema is empty, so the baseline is 4. There is nothing to disambiguate, and the description correctly spends no words on parameter semantics.

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

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

The description names a specific resource (every node kind hive supports) and enumerates exactly what each entry contains — description, default width, Markdown body flag, kind-specific data fields — plus the allowed-value vocabularies and Markdown syntax. This clearly distinguishes it from siblings like list_nodes or get_nodes, which return node instances rather than kind definitions.

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?

"Call before creating anything other than plain notes" gives an explicit trigger condition and implicitly excludes plain-note creation, which is genuinely useful routing guidance. It does not name the alternative tool (create_nodes) by name, so it falls short of a 5.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description adds meaningful context beyond them: this only moves the camera and is not recorded as an undo step. It does not describe viewport persistence or whether zoom is retained, but the undo-history clarification is genuinely useful for an agent sequencing edits.

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

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

A single sentence with the action, the target, the trigger condition, and the exclusion clause, all front-loaded. Nothing is padded or repeated from 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?

For a three-parameter tool with a nested bbox object and no output schema, the description covers the core behavior but omits what happens when no ids and no bbox are supplied (zero required parameters) and never addresses zoom. Adequate, but with visible gaps for a tool whose schema is entirely undocumented.

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 0%, so the description must carry the load. It does explain the ids-vs-rectangle either/or relationship that the schema leaves implicit, but it never mentions 'zoom' or the coordinate space/units of the bbox, leaving two of three parameters semantically thin.

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 object ('Move hive's camera') plus the target ('given nodes (or rectangle) are visible'), which is far more precise than the generic title 'Show on screen'. It also pre-emptively differentiates itself from undo_last_change, so 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?

Gives explicit when-to-use guidance: 'use after creating something so the user sees it', and excludes one wrong candidate with 'Not an undo step.' It stops short of naming a full alternative (e.g. that this is viewport-only and not needed after updates or moves), so it lands just below the top tier.

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 cover readOnly, idempotent, non-destructive and closed-world, so safety is handled. The description earns credit by disclosing the batch cap (50) and the exact payload contents (all stored fields, full Markdown, effective size, links with names, zone), which 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?

One dense sentence, front-loaded with the key constraint ('up to 50 nodes by id or exact name') and then the return payload. No filler and nothing redundant.

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

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

With no output schema, the description correctly enumerates what comes back, and annotations carry the safety profile. It omits edge behavior such as missing-id handling, result ordering, or whether ids and names may be combined, which leaves a small 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 coverage is 50%: names carries an 'exact names (case-insensitive fallback)' note while ids is bare. The description restates the id/exact-name lookup and the 50 cap, adding mild clarification but no format or matching details beyond the schema.

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

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

Names a specific verb+resource (get nodes) and pins the lookup keys (id or exact name), which implicitly separates it from search_nodes and list_nodes. It never names a sibling outright, so the differentiation is inferred 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?

The 'by id or exact name' phrasing implies when this tool fits (known identifiers) versus a search, but there is no explicit when-to-use, when-not-to-use, or named alternative. Usage must be inferred from the payload description.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds genuine behavioral context by disclosing that the result carries offline:true when hive is closed and that only read tools function in that state. It adds no auth or rate-limit detail, but for a status probe that is not needed.

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

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

Front-loads the "Start here" cue, then packs the return payload and the offline condition into two tight sentences with no filler. 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?

There is no output schema, so the description carries the burden of describing return values, and it enumerates the returned fields explicitly. Combined with the offline-state caveat, an agent has everything needed to call it 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?

The tool takes zero parameters, so there is no parameter semantics to clarify and the baseline of 4 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 and enumerates exactly what is returned (running state, open project name/folder, object counts, camera, board area, selection). This is clearly distinguishable from every sibling, which are all mutation or list tools.

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

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

"Start here" gives an explicit entry-point directive, and the offline note tells the agent that write tools are unavailable when hive is closed. It stops short of naming alternative tools or explicit exclusions, but the context is clear.

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

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

Annotations declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds real behavioral context beyond them: the file is copied into the project folder, large videos above a user threshold are linked instead of copied, and the node kind is inferred from the file type. It omits collision/overwrite behavior and permission requirements, but the copy-vs-link distinction is genuinely valuable.

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, front-loaded with the primary effect and the node-kind outcome, with the path constraint at the end where it belongs. Slightly dense in the middle clause, but every sentence earns its place.

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

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

For a mutating import tool with no output schema and zero schema description coverage, the description explains the mutation's file-handling behavior well but leaves the spatial placement API undocumented. It is adequate for calling with just the required path, but incomplete for anyone using the optional placement parameters.

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 0% for five parameters, so the description carries the burden and largely fails: only 'path' is explained ('Use an absolute path'). Placement parameters x, y, name, and the nested near object (node/side/gap) get no explanation at all, leaving the agent to guess at positioning semantics.

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 a file from disk to the project') and enumerates the resulting node kinds, so an agent can distinguish it from sibling node-creation tools like create_nodes. The 'exactly like dropping it on the board' framing pins down the resource and effect immediately.

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

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

Implies when to use it (when you have a file on disk rather than raw content to place on the board) and gives one concrete constraint, 'Use an absolute path.' However, it never names an alternative such as create_nodes for non-file sources, so the agent must infer the boundary itself.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety behavior needs no restating. The description adds no context beyond the name itself: no note on scope, ordering, nesting, or how archive differs from trash. It is effectively a tautology against the title 'List archive'.

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

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

It is a single five-word fragment with no waste, but the brevity comes from under-specification rather than disciplined editing. It is front-loaded only in the sense that there is nothing else to front-load.

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 parameters, the description is the only place to explain what this returns and how it relates to list_trash and list_nodes. It leaves the archive-vs-trash distinction entirely unaddressed, which is the single most important ambiguity for this tool.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify; the baseline for a parameterless tool applies. No misleading parameter information is present.

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 phrase identifies the resource (archived nodes of the project) and implies a listing operation, but it is a noun fragment rather than a verb+resource statement. It does not differentiate from close siblings such as list_trash or list_nodes, so an agent cannot tell archive apart from trash from this text 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?

There is no when-to-use guidance, no statement of what state counts as 'archived', and no pointer to alternatives like list_trash or search_nodes. Usage must be entirely inferred from the name.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only the filtering behavior and the fact that results carry both node names; it says nothing about pagination, ordering, or result size, so the added behavioral value is modest.

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 compact sentence with no filler, and the core scope statement leads. The compression costs some clarity ("lines between nodes"), which keeps it just short of a 5.

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

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

With no output schema, the description must characterize the return value and does mention that both node names are included, which is helpful. However, for a listing tool it omits ordering, pagination, and result-size behavior, leaving gaps in what the agent should expect back.

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 0% for the single `nodeId` parameter, so the description carries the full burden and does so reasonably: it states the parameter acts as a filter limiting results to links touching that node, and that omitting it returns all links. It does not specify the expected identifier format, but the optional-filter semantics are clear.

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 conveys the resource (connections/links between nodes) but never uses an explicit verb like "list" and substitutes the ambiguous metaphor "lines" for "links". It does distinguish the filtered and unfiltered modes via `nodeId` and mentions the returned node names, so an agent can infer the intent, but the phrasing is vague rather than a specific verb+resource statement.

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 that omitting `nodeId` returns all links and supplying it narrows to those touching that node, which is the only usage signal present. There is no guidance on when to prefer this over siblings such as `get_nodes`, `list_nodes`, or `search_nodes`, and no exclusions or prerequisites are given.

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 cover read-only, idempotent, non-destructive, closed-world semantics, and the description adds non-obvious traits: truncated 160-char previews, paging behavior, and board coordinate semantics. It does not mention default sort or pagination limits beyond what the schema implies.

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: scope and filters first, return-shape and alternative second, coordinate convention last. No filler and no 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?

No output schema exists, but the description discloses the return shape (short summaries with a 160-char preview) and paging, which is what an agent needs to decide to call it. Minor gaps remain around sort default and maximum paging behavior.

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

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

With 56% schema coverage, the description compensates by mapping filter concepts to parameters (kind→types, zone→zoneId, task state→task, text query→query, rectangle→bbox, linked to→linkedTo) and clarifying that coordinates are board units with x/y as top-left and y growing downward — meaning the sparse bbox fields lack. sort/offset/limit behavior is left to 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 (list) and resource (nodes), enumerates the filter dimensions, and explicitly names get_nodes as the sibling to use for full text. An agent can distinguish it from search_nodes/get_nodes 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 a concrete routing rule: use get_nodes when full text is needed, since this returns 160-character previews. It also implies filter-based retrieval, but does not state when to prefer list_nodes over search_nodes or list_archive.

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, idempotentHint, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds the semantic context that these are deleted nodes restorable via restore_from_trash, which is useful but not rich behavioral disclosure such as pagination or ordering.

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

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

A single, front-loaded sentence with no wasted words. It efficiently conveys the essential concept without redundancy.

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

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

For a parameterless read-only list tool with annotations covering safety, the description supplies enough to call it correctly. However, without an output schema it does not describe the returned entries' shape, leaving a minor 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?

There are zero parameters, so the schema baseline is 4. The description adds nothing about parameters, which is appropriate since none exist.

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 identifies the resource precisely as entries in the project's Trash, clarified as deleted nodes, which distinguishes it from list_nodes for active nodes. It lacks an explicit verb, but the title supplies 'List'. It does not differentiate from the sibling list_archive.

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 mention that restore_from_trash can bring these entries back implies usage (finding restorable items), but there is no explicit when-to-use statement or exclusion. No alternative like list_archive is named or contrasted.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered elsewhere. The description's only behavioral contribution is naming the returned fields (rectangles, member node ids); it says nothing about ordering, pagination, or scope, so it adds modest value over the annotations.

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

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

A single tight sentence with the resource front-loaded and the payload described immediately after. Nothing is wasted and nothing important is buried.

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 burden of explaining return values, and it does so at a high level (rectangles, member node ids). For a zero-parameter list tool this is largely sufficient, though ordering or pagination behavior is left unstated.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The schema is empty and the description correctly implies a no-argument, whole-project listing.

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 name plus description identify the resource (zones) and even define it parenthetically as 'coloured areas that group nodes', which is genuinely clarifying. It does not explicitly contrast with siblings like list_nodes or list_links, but the resource is unambiguous and the return content is 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?

There is no statement of when to call this versus alternatives such as get_nodes, list_nodes, or list_links, and no prerequisites or exclusions. Usage must be inferred entirely from the name.

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

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

Annotations already declare the safety profile (not read-only, not destructive, not idempotent), so the bar is lower. The description adds genuinely new behavioral context beyond that: that the whole batch is 'one undoable step' (atomic undo semantics) and that coordinates are in board units. It does not cover failure behavior when a node id is invalid or what happens beyond the 500-item cap.

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 operation and followed by the undo guarantee. No filler; every clause earns its place.

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

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

For a mutation tool with annotations covering safety and no output schema, the description plus annotations give an agent enough to call it correctly, especially the batch-in-one-undo behavior. It stops short of describing coordinate overwrite semantics or error handling for bad ids.

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 0%, so the description has to carry the semantics. It does explain the coordinate units ('board units') and that x/y are the top-left position, which the schema's bare 'number' types do not say, but it does not explain the 'moves' batch wrapper, the per-item id/x/y contract, or the 1..500 item bounds.

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

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

The description names a specific verb and resource ('Set exact top-left positions ... of nodes') and adds semantic detail (board units, top-left anchor) that makes the operation unambiguous. It does not explicitly contrast itself with the nearby layout sibling arrange_nodes, which is the main differentiation gap.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no reference to alternatives such as arrange_nodes (auto layout) or update_nodes. An agent must infer from the name and siblings which tool applies.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false; the description is consistent with these and adds context annotations cannot express — that restoration puts entries back in their old location with links intact and is a single undoable step. It omits failure behavior for invalid or already-restored ids, keeping it out of the top band.

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

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

A single front-loaded sentence with no filler: action, identifier source, effect, and reversibility are all packed in without repetition of the name or title.

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

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

With one required parameter, no output schema, and annotations covering the safety profile, the description supplies what an agent needs to call it correctly. Missing only edge-case guidance on invalid/already-restored ids and any response confirmation detail, which is minor for a single-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 0%, so the description must carry the load, and it does explain that ids identify Trash entries and where to obtain them (list_trash). It does not clarify batching semantics, duplicate ids, or ordering within the array, so it is not fully compensating.

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 (restore Trash entries) plus the resulting scope: returned to their old place with their links. It also names the sibling that supplies the ids (list_trash), so an agent can distinguish it from delete_nodes, move_nodes, or undo_last_change 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?

It clearly conditions use on ids 'as listed by list_trash' and signals reversibility via 'One undoable step', which implicitly points at undo_last_change as the revert path. It does not spell out when not to use it (e.g., archived items, already-restored ids), so it falls short of a full when/when-not statement.

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 the safety profile (write, idempotent, non-destructive). The description adds meaningful context beyond them: it flushes all *pending* changes, is immediate, and is redundant with automatic saving. It doesn't describe failure modes (e.g., disk errors), but for a zero-argument flush tool this is solid added value.

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

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

A single sentence with zero waste; the action is front-loaded and the caveat about automatic saving is compactly bracketed rather than given its own sentence.

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-parameter, no-output-schema tool, the description covers the essential behavior and the key caveat that saving is already automatic. Minor gap: no indication of what happens on success/failure or whether it blocks, but little is required 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline of 4 applies per the scoring rules.

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: 'Write all pending changes to the project folder immediately.' An agent immediately knows this is a manual save/flush operation, distinct from the node/link/zone CRUD siblings. It does not explicitly name a sibling to contrast against, but none of the siblings overlap in function.

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?

'immediately' plus the parenthetical '(hive also saves automatically)' tells the agent both when to call it (to force an immediate flush) and that it is usually unnecessary because auto-save runs. No explicit alternative or exclusion is named, but the when/when-not context is clear.

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

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

Annotations already establish the safe read-only, idempotent, closed-world profile. The description adds useful behavior beyond annotations: the ranking order (name matches first) and the shape of the result (ids, names, and a snippet around the match). It does not discuss case sensitivity or query syntax, but for a simple search tool this is solid added 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?

Two tight sentences with no filler. The core purpose and ranking behavior are front-loaded, and the return summary follows immediately. Every sentence earns its place.

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

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

With no output schema, the description appropriately explains returned fields, and annotations carry the safety profile. However, for a 3-parameter tool with low schema coverage, it leaves the types parameter unclear and does not position the tool against enumeration alternatives like list_nodes or get_nodes.

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 33%, with just the limit parameter described as 'Default 20.' The description does not explain the required query parameter or the types array. 'Search node names, kinds and text' suggests what is searched but does not clarify that types filters results by node kind, leaving one parameter effectively undocumented.

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 (Search) and resource (node names, kinds, text), and adds a distinctive ranking detail (name matches first). It does not explicitly differentiate itself from siblings like list_nodes or get_nodes, keeping it just short of a 5.

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 implies the tool is for finding nodes by text, name, or kind, but gives no explicit when-to-use or when-not-to-use guidance. It does not name alternatives such as list_nodes for enumeration, leaving the agent to infer usage from the purpose statement.

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 this as destructive and non-idempotent, but the description adds the guard-rail semantics that annotations cannot express: default scope is limited to MCP-labelled entries and the call is aborted if the user changed something since. It does not say whether the undone entry is discarded or recoverable, which would be valuable for a destructive tool.

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

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

Two sentences, no filler. The core action comes first and the scope/refusal caveats follow immediately, which is the right ordering for a destructive operation.

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

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

For a one-optional-parameter tool with no output schema and destructive annotations, this covers action, default behavior, and failure condition. The only meaningful omission is what happens to the reverted change afterward (discarded, trashed, recoverable), which matters given destructiveHint=true.

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% but the schema only says 'Default true' for onlyIfMcp without explaining what the boolean controls. The description supplies that meaning, clarifying that the default restricts undo to MCP-originated changes and implying false widens the scope to any recent change.

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 (undo) and a precisely scoped resource (the most recent change in hive), and immediately narrows the scope to changes made through this MCP server. No sibling tool performs rollback, and the 'MCP:' labelling convention makes the target unambiguous.

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

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

It gives a clear condition for use and, more importantly, an explicit refusal condition ('refuses if the user changed something since'), which tells the agent when the call will not succeed. It does not name an alternative tool for the non-MCP case, so it stops short of a full when/when-not/alternative triad.

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 the mutation profile (readOnly=false, destructive=false, idempotent=false), so the bar is lower. 'One undoable step' adds genuinely useful context that ties this to undo_last_change, but nothing is said about partial failures across the batch or what happens with invalid ids.

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 followed by the one behavioral fact worth knowing. 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?

Annotations cover the safety profile and there is no output schema to explain, but for a batch mutation (up to 500 items) the description says nothing about error handling or whether the update is all-or-nothing. Adequate but with a real 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?

The description names kind and shape, matching two of the nested item fields, but omits the required id and the fact that 'updates' is an array capped at 500. The schema itself carries the enum and shape descriptions, so the description adds only marginal meaning.

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 (Change) and resource (existing links) plus the two mutable attributes (kind, shape), which clearly separates it from create_links, delete_links, and list_links. It does not explicitly name a sibling, so it stops short of a 5.

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

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

There is no statement of when to use this versus create_links (new links) or delete_links (removal), nor any prerequisite such as needing existing link ids. Usage is only inferable from the phrase 'existing links'.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds meaningful context beyond those annotations: changes occur in one undoable step, and only fields that are passed are modified. It does not detail permissions or validation behavior, but it provides clear mutation semantics without contradicting the annotations.

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

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

The opening sentence front-loads the core action and atomic behavior, then compactly enumerates supported update categories. The final sentence 'Only the fields you pass change' adds a critical partial-update rule with no wasted words. Dense but well-structured and appropriately sized.

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

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

For a complex mutation tool with rich nested schema descriptions and annotations, the description covers purpose, atomicity, partial-update semantics, and the breadth of updatable fields. It need not explain return values since there is no output schema. The main omission is explicit array/ID semantics, which the schema provides, so completeness is strong but not perfect.

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

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

The top-level 'updates' parameter has no schema description (0% coverage per context signals), so the description must compensate. It enumerates many updatable aspects and clarifies that only passed fields change, but it omits the array structure, required node id, maxItems limit, and fields such as x/y, accentColor, and headerHidden that are only documented in the nested schema. It partially compensates but leaves clear gaps.

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: 'Change existing nodes'. The enumeration of update categories (rename, text editing, move/resize, colours, glow, task state, etc.) and the atomic scope ('ONE undoable step') make the intended function unambiguous. It also distinguishes itself from create/delete by explicitly scoping to 'existing nodes'.

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 implies when to use the tool: changing existing nodes, especially in a single undoable step, with partial field updates. However, it gives no explicit routing guidance against siblings such as move_nodes or arrange_nodes, nor does it state when not to use it. Usage is implied rather than 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 already declare readOnly=false, destructive=false, idempotent=false and closed-world, so the safety profile is covered. The description adds a genuinely new behavioral fact beyond the annotations: the edit is a single undoable step, which matters for agents chaining mutations with undo_last_change. It still omits whether omitted fields are preserved (patch vs replace semantics).

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, operations listed first and the undo caveat second, with no filler. Every clause adds information.

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

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

For a mutation tool with a nested rect object, 0% schema description coverage and no output schema, the description is adequate but thin: it says what fields exist but not the rect units/origin, the hex color convention, or whether unspecified fields are left untouched. Annotations carry safety, so the remaining shortfall is mostly parameter-level.

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 0%, so the description carries the burden and partially meets it by mapping rename→name, recolour→color, move/resize→rect. However it never mentions the required id parameter, nor the expected format of color (hex) or the x/y/width/height shape of rect, so half the parameter semantics remain undocumented.

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

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

The description names the resource (zone) and the three concrete mutations it supports: rename, recolour, move/resize. That is a specific verb+resource statement that an agent can act on, though it never explicitly distinguishes itself from sibling zone tools such as create_zone or delete_zones beyond the obvious naming.

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

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

Usage is only implied by the tool name and the operations listed; there is no statement of when to choose update_zone over update_nodes or create_zone, no preconditions, and no exclusions. An agent can infer this is the edit path for an existing zone, but nothing in the text confirms that.

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