Skip to main content
Glama
putervision

state-memory-mcp

by putervision
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

manage_nodes

Destructive

Create, update, get, remove, list, search, or batch-process state graph nodes for decisions, artifacts, plans, milestones, and blockers. Returns nodes, edges, or matches.

Instructions

Manage graph nodes in the state graph (actions: create, update, get, remove, list, search, batch_create, batch_update, add_note). Use manage_nodes instead of manage_tasks when operating on general node types (decisions, artifacts, plans, milestones, blockers) rather than runnable task workflow states.

Returns node object, edge connections, batch results, or search matches.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
idNoUnique node identifier for get, update, or remove.
idsNoArray of node IDs for batch_update.
tagsNoArray of searchable tags.
textNoText note content for add_note.
typeNoThe type classification of the node.
limitNoMaximum number of items to return (1-1000).
nodesNoArray of node payloads for batch_create.
queryNoSearch term for full-text search.
titleNoTitle or label of the node.
actionYesThe node management action to execute: create, update, get, remove, list, search, batch_create, batch_update, add_note.
offsetNoNumber of items to skip for pagination.
statusNoStatus of the node (e.g. pending, in_progress, done, blocked, active, accepted, current).
compactNoWhether to return a lightweight compact summary.
projectNoTarget project name or slug.
metadataNoArbitrary structured key-value metadata.
algorithmNoSearch algorithm for search action.
attach_toNoNode ID to attach observation note to via references edge.
git_branchNoGit branch filter.
session_idNoActive session identifier for change attribution.
include_edgesNoWhether to include inbound/outbound edges on get.
expected_versionNoOptimistic concurrency version check for update.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv1.3.1
    • changedInput schema / properties / action / description
      Previous value: -"The node management action to execute."New value: +"The node management action to execute: create, update, get, remove, list, search, batch_create, batch_update, add_note."
    • addedInput schema / properties / action / enum
      Added value: +[
+  "create",
+  "update",
+  "get",
+  "remove",
+  "list",
+  "search",
+  "batch_create",
+  "batch_update",
+  "add_note"
+]
  2. Changed5 schema fields changedv1.2.1
    • removedInput schema / $schema
      Removed value: -"http://json-schema.org/draft-07/schema#"
    • removedInput schema / additionalProperties
      Removed value: -true
    • removedInput schema / properties / metadata / additionalProperties
      Removed value: -{}
    • removedInput schema / properties / nodes / items / additionalProperties
      Removed value: -{}
    • addedInput schema / required
      Added value: +[
+  "action"
+]
  3. Addedv1.0.0

TDQS

A3.8/5.0
Behavior3/5

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is partly covered. The description adds the return-shape surface ('Returns node object, edge connections, batch results, or search matches'), which is useful given there is no output schema, but it never warns which actions mutate/destroy data (remove, batch_update) or mention the optimistic concurrency behavior implied by expected_version.

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

Conciseness4/5

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

Two compact sentences plus a short return-shape line, with the action enumeration and the sibling-routing rule front-loaded. No filler, though the parenthetical action list slightly duplicates the action enum in the schema.

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

Completeness3/5

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

For a 21-parameter, 9-action, nested-object tool with no output schema, the description covers the action set and the return surface but omits action/parameter coupling (e.g. add_note requires attach_to/text, batch_update requires ids) and any warning that some actions are destructive. Adequate but with clear gaps for a tool this broad.

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

Parameters3/5

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

Schema description coverage is 100% across all 21 parameters, so the schema already carries the parameter semantics; the description adds no per-parameter meaning beyond the action list. 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.

Purpose5/5

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

The description names a specific verb+resource ('Manage graph nodes in the state graph') and enumerates the nine supported actions, so an agent knows exactly what surface this tool exposes. It also explicitly distinguishes itself from the closest sibling by routing runnable task states to manage_tasks.

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

Usage Guidelines4/5

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

It gives an explicit when-to-use rule with an alternative named: 'Use manage_nodes instead of manage_tasks when operating on general node types (decisions, artifacts, plans, milestones, blockers) rather than runnable task workflow states.' That is clear routing context, but it offers no guidance on when to pick specific actions versus the overlapping query_graph sibling (e.g. search), and no exclusions for the destructive actions.

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

Deploy Server

Other Tools