Manage Nodes

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

The description adds useful behavioral detail beyond annotations: 'remove (delete node and cascade edges)' discloses destructive cascading, 'batch_create/batch_update atomically' discloses atomicity, and 'add_note (log observation node with optional context link)' discloses side effects. However, the disclosed cascade-delete behavior directly conflicts with annotations' destructiveHint=false, creating trust ambiguity about whether remove is safe.

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 word earns its place — no filler. But the entire action taxonomy is crammed into one run-on sentence, making it hard to scan for a specific action. A bulleted or structured enumeration would materially improve parseability without adding length.

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?

This is a complex dispatcher (21 params, 9 actions, nested objects) with no output schema, yet the description leaves critical gaps: no action-to-parameter mapping, no return-value or response-shape disclosure for each action, and no per-action constraints. An agent cannot reliably determine which parameters are relevant for a chosen action or what result to expect, so the definition is incomplete for its complexity.

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 21 parameters carry descriptions in the schema; the tool description itself adds no parameter details beyond the action names. The description does not map actions to their relevant parameters (e.g., that 'algorithm' applies only to 'search'), but per the baseline rule for full schema coverage, the description need not duplicate the schema. The un-enumerated 'action' string benefits slightly from the listed valid values.

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

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

The description states 'Manage graph nodes in the state graph' with a specific resource, and enumerates nine concrete actions (create, update, get, remove, list, search, batch_create, batch_update, add_note). This distinguishes it from siblings like manage_edges and manage_snapshots by resource. However, 'manage' plus a long action list is a dispatcher-style breadth that weakens the single-purpose clarity.

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?

No when-to-use or when-not-to-use guidance is provided. The sibling list includes conceptually overlapping tools (manage_tasks, manage_specs, query_graph, manage_edges), and the description never explains when to call manage_nodes versus those alternatives, nor does it note that 'task'/'spec' node types exist here despite dedicated manage_tasks/manage_specs siblings. An agent has no routing cues.

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