ShadowGraph

Official

by LiLara-AI

Overview Schema Source Related Servers Discussions Admin

JavaScript

Local

shadowgraph_update_status

Destructive

Move a decision to another lifecycle state while enforcing allowed transitions and committing a revision.

Instructions

Move one decision to another lifecycle state. shadowgraph_supersede replaces a decision, shadowgraph_maintain alone produces stale, shadowgraph_record_outcome records the result. stale and superseded are system-owned and rejected. Setting the current state writes nothing but still commits a revision.

Input Schema

Name	Required	Description
`status`	Yes	Target state. Legal moves are proposed to planned/in_progress/abandoned/archived; planned to in_progress/abandoned/archived; in_progress to executed/failed/abandoned/archived; executed to validated/failed/reconsidered/archived; validated to reconsidered/archived; failed to reconsidered/abandoned/archived; reconsidered to planned/in_progress/abandoned/archived; stale to reconsidered/archived; abandoned to archived. stale and superseded cannot be set by a caller.
`project`	No	Owning project; required unless originId is set, else the write is refused.
`originId`	No	Capture-origin id; with no project the record belongs to it alone.
`decisionId`	Yes	Identifier of an existing decision, as returned by shadowgraph_record_decision, shadowgraph_search, or shadowgraph_retrieve.

Output Schema

Name	Required	Description
`id`	Yes	Stable entity identifier.
`goal`	No	What the decision was trying to achieve.
`kind`	Yes	Entity kind: decision, attempt, memory, fact, relation, review, or alternative.
`actor`	No	Who performed the write.
`title`	No	Short name of the decision.
`chosen`	No	The option that was chosen.
`client`	No	Which client performed the write.
`status`	No	Lifecycle state. Legacy records may carry a value this build does not recognise; shadowgraph_validate reports those.
`outcome`	No	The recorded outcome, or null until one is recorded.
`project`	No	Project namespace; null for an unattributed record or one imported from before projects.
`evidence`	No	Normalised evidence entries: source, type, sourceClass, confidence, observedAt, detail.
`createdAt`	No	ISO 8601 creation time.
`migration`	No	Present only on migrated records; records the legacy value a field was mapped from.
`sessionId`	No	Session identifier recorded with the write.
`sourceRaw`	No	The original origin label when it differed from sourceClass. Audit only; never evidence.
`updatedAt`	No	ISO 8601 time of the last change.
`confidence`	No	Auditable confidence: initial, current (0-1), policy, a history entry per move, and a basis summarising the contributions it was folded from. Legacy records may lack basis.
`supersedes`	No	Identifiers of decisions this one replaced.
`assumptions`	No	Assumptions the decision rests on. Searchable content.
`reviewAfter`	No	ISO 8601 instant after which shadowgraph_maintain marks this decision stale.
`sourceClass`	No	Claimed origin class recorded with the write. A claim, never proof.
`alternatives`	No	Rejected alternatives, each with id, label, reasonRejected, status, and the reopenWhen rules that make it reconsiderable.
`supersededBy`	No	Identifier of the decision that replaced this one.
`schemaVersion`	No	Storage schema version this entity was written under. A value above the build’s own version is preserved rather than downgraded.
`failedAttempts`	No	Attempt identifiers or notes attached to this decision.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.42.3Oct 26, 2026
Removedv0.42.1Oct 25, 2026

Changed3 schema fields changedv0.40.1Sep 3, 2026

addedInput schema / properties / decisionId / description

Added value: +"Identifier of an existing decision, as returned by shadowgraph_record_decision, shadowgraph_search, or shadowgraph_retrieve."

addedInput schema / properties / status / description

Added value: +"Target state. Legal moves are proposed to planned/in_progress/abandoned/archived; planned to in_progress/abandoned/archived; in_progress to executed/failed/abandoned/archived; executed to validated/failed/reconsidered/archived; validated to reconsidered/archived; failed to reconsidered/abandoned/archived; reconsidered to planned/in_progress/abandoned/archived; stale to reconsidered/archived; abandoned to archived. stale and superseded cannot be set by a caller."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "description": "A stored decision, including its alternatives and auditable confidence basis.",
+  "properties": {
+    "actor": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Who performed the write."
+    },
+    "alternatives": {
+      "description": "Rejected alternatives, each with id, label, reasonRejected, status, and the reopenWhen rules that make it reconsiderable.",
+      "type": "array"
+    },
+    "assumptions": {
+      "description": "Assumptions the decision rests on. Searchable content.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "chosen": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The option that was chosen."
+    },
+    "client": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Which client performed the write."
+    },
+    "confidence": {
+      "description": "Auditable confidence: initial, current (0-1), policy, a history entry per move, and a basis summarising the contributions it was folded from. Legacy records may lack basis.",
+      "type": "object"
+    },
+    "createdAt": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "ISO 8601 creation time."
+    },
+    "evidence": {
+      "description": "Normalised evidence entries: source, type, sourceClass, confidence, observedAt, detail.",
+      "type": "array"
+    },
+    "failedAttempts": {
+      "description": "Attempt identifiers or notes attached to this decision.",
+      "type": "array"
+    },
+    "goal": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "What the decision was trying to achieve."
+    },
+    "id": {
+      "description": "Stable entity identifier.",
+      "type": "string"
+    },
+    "kind": {
+      "description": "Entity kind: decision, attempt, memory, fact, relation, review, or alternative.",
+      "type": "string"
+    },
+    "migration": {
+      "description": "Present only on migrated records; records the legacy value a field was mapped from.",
+      "type": "object"
+    },
+    "outcome": {
+      "anyOf": [
+        {
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The recorded outcome, or null until one is recorded."
+    },
+    "project": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Project namespace; records imported from a schema that predates projects may carry null."
+    },
+    "reviewAfter": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "ISO 8601 instant after which shadowgraph_maintain marks this decision stale."
+    },
+    "schemaVersion": {
+      "description": "Storage schema version this entity was written under. A value above the build’s own version is preserved rather than downgraded.",
+      "type": "integer"
+    },
+    "sessionId": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Session identifier recorded with the write."
+    },
+    "sourceClass": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Claimed origin class recorded with the write. A claim, never proof."
+    },
+    "sourceRaw": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The original origin label when it differed from sourceClass. Audit only; never evidence."
+    },
+    "status": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Lifecycle state. Legacy records may carry a value this build does not recognise; shadowgraph_validate reports those."
+    },
+    "supersededBy": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Identifier of the decision that replaced this one."
+    },
+    "supersedes": {
+      "description": "Identifiers of decisions this one replaced.",
+      "type": "array"
+    },
+    "title": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Short name of the decision."
+    },
+    "updatedAt": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "ISO 8601 time of the last change."
+    }
+  },
+  "required": [
+    "id",
+    "kind"
+  ],
+  "type": "object"
+}

First observedv0.40.0Sep 2, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Adds genuinely non-obvious behavior beyond the annotations: stale and superseded are rejected as caller-set targets, and setting the current state is a no-op write that still commits a revision. That no-op/revision detail is exactly the kind of trait an agent cannot infer. The one gap is that destructiveHint=true is never explained — nothing says what a transition destroys or whether it is reversible.

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

Conciseness5/5

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

Four short sentences, front-loaded with the action, then the sibling disambiguation, then the two edge-case rules. No filler and no repetition of the enum contents.

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

Completeness4/5

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

An output schema exists and all four parameters are documented, so the description only needs to carry the tricky behavioral facts — which it does. It leaves the destructive annotation unexplained and does not address the project/originId requirement, though the schema covers the latter.

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 coverage is 100% and the status parameter's own description already enumerates the legal moves and the system-owned exclusions, so the description largely restates it. The 'writes nothing but still commits a revision' note adds a little semantic value, but not much beyond the schema baseline.

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 opens with a specific verb and resource: 'Move one decision to another lifecycle state.' It then explicitly separates the tool from three siblings (supersede replaces, maintain marks stale, record_outcome records results), so an agent can route without opening any schema.

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?

Alternatives and their distinct roles are named, which gives strong implicit routing guidance — use this for transitions, supersede for replacement, record_outcome for results. What's missing is an explicit statement of the triggering condition ('use when a decision advances or is abandoned') and any prerequisite/permission notes.

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