delete_nodes

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

Annotations already flag destructiveHint=true and readOnlyHint=false, so the mutation risk is declared structurally. The description does add real value beyond that: the all-or-nothing guarantee that nothing is deleted if any name is missing. However, it omits whether the deletion is undoable, what errors surface, and how the mode/script context changes behavior.

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

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

Two short sentences, front-loaded with the action and immediately followed by the key transactional constraint. No filler, no restatement of the tool 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?

An output schema exists, so return values need not be described, and the atomicity note is the single most important behavioral fact. Still, with three undocumented parameters including an auto/live/headless mode enum and an optional script, plus no note on undo, the definition is thinner than a destructive tool warrants.

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 parameter meaning. It explains that the nodes parameter is a set of names and that the operation fails atomically if any name is absent, which is meaningful semantics for the required array. The mode enum and script parameters get no explanation at all, leaving a gap, but the most critical required parameter is clarified.

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?

"Delete nodes by name" gives a specific verb and resource, and the second sentence narrows the semantics to name-based lookup. It is clearly distinct from list_nodes/get_node/create_node siblings, though it does not say which context (script vs. live session) the names refer to.

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 definition implies usage through "by name" and states the all-or-nothing condition, but never says when to prefer it, what prerequisites exist, or whether undo/redo siblings can reverse it. With no other delete tool among the siblings, missing alternatives are less damaging, but the mode/script context choices go unaddressed.

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