Annotations

annotate

Unified annotation tool for attaching notes, web findings, and quality gaps to graph nodes, plus entity history timeline.

Absorbs: annotate_node, web_annotate, upsert_gap, get_gaps, get_entity_history.

Parameters

Parameter	Type	Required	Description
`action`	string	No	`add` (default), `add_web`, `add_gap`, `list_gaps`, `history`.
`node_id`	string	action=add/add_web/add_gap	Node ID to annotate.
`note`	string	action=add	Annotation text. Optional for add_web.
`agent_id`	string	No	Agent identifier for attribution.
`hits`	string	action=add_web	JSON array of `{title, url, snippet}` web hits.
`gap_id`	string	action=add_gap	Short stable slug for gap deduplication.
`description`	string	action=add_gap	Gap description.
`severity`	string	No	`low`, `medium`, `high`, `critical`. action=add_gap/list_gaps.
`status`	string	No	`open`, `fixed`, `wontfix`. action=add_gap. For list_gaps: also accepts `all`.
`fix_notes`	string	No	How the gap was fixed. action=add_gap with status=fixed.
`file`	string	No	Filter gaps by file path (list_gaps). Disambiguate entity (history).
`entity`	string	action=history	Entity name for timeline.
`limit`	number	No	Max timeline events. action=history. Default 50.

Action: add (default)

Attach a note to a graph node.

{
  "tool": "annotate",
  "arguments": {
    "node_id": "node-abc",
    "note": "This function has a known race condition under high load",
    "agent_id": "claude-1"
  }
}

Action: add_web

Persist web research findings as an annotation on a node.

{
  "tool": "annotate",
  "arguments": {
    "action": "add_web",
    "node_id": "node-abc",
    "hits": "[{\"title\": \"Go concurrency patterns\", \"url\": \"https://example.com\", \"snippet\": \"Use channels instead of mutexes\"}]"
  }
}

Action: add_gap

Record a quality gap on a node.

{
  "tool": "annotate",
  "arguments": {
    "action": "add_gap",
    "node_id": "node-abc",
    "gap_id": "missing-error-handling",
    "description": "No error handling for database timeout",
    "severity": "high"
  }
}

Action: list_gaps

Query quality gaps, optionally filtered by severity, status, or file.

{
  "tool": "annotate",
  "arguments": {
    "action": "list_gaps",
    "severity": "high",
    "status": "open"
  }
}

Action: history

Get the timeline of changes for an entity.

{
  "tool": "annotate",
  "arguments": {
    "action": "history",
    "entity": "handleSessionInit",
    "limit": 20
  }
}