Add or update Knowledge Graph nodes for files, functions, symbols, structures, textures, audio, or crashes to keep project relationship data current.
Add or update a node in the project Knowledge Graph (file, function, symbol, structure, texture, audio, crash).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Unique node identifier, e.g. 'func:kart_update' | |
| type | Yes | Node type | |
| label | Yes | Human readable label | |
| props | No | Key-value properties |
Changes observed during successful MCP inspections.
v1.0.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it omits the critical upsert semantics: whether existing `props` are merged or replaced on update, whether a partial node clobbers prior data, and whether the write requires an initialized project graph. 'Add or update' states that mutation occurs but nothing about its consequences or reversibility.
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; the verb, resource, and scope are all stated immediately and nothing is 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?
This is a mutation tool with no annotations and no output schema, so the description must explain merge/replace behavior, side effects on existing nodes, and what the call returns (e.g., the upserted node or its id). It covers none of these, leaving significant gaps for a write operation with a nested free-form `props` object.
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 `id`, `type`, `label`, and `props` are already fully documented, making 3 the baseline. However, the description's parenthetical list of node types is a strict subset of the enum (omitting address, memory_region, build, investigation, note), which adds no meaning and risks misleading an agent about valid types.
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 ('Add or update') and a specific resource ('a node in the project Knowledge Graph'), which cleanly separates it from graph_edge_upsert and graph_query_neighbors by name. It falls short of 5 only because it names the sibling relationship implicitly rather than stating it.
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 explicit when-to-use guidance: nothing says when to prefer this over graph_ingest, when a node already exists, or what prerequisites (project/graph initialization) must be met. The only hint is the phrase 'in the project Knowledge Graph', which implies a persistence context but leaves the agent to infer it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.