Skip to main content
Glama
Sign In
ShadowGraph

ShadowGraph

Official
by LiLara-AI
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

shadowgraph_supersede

Destructive

Mark a decision as superseded by a replacement in the same project, keeping history searchable while excluding the replaced decision from current context.

Instructions

Mark one decision superseded by a replacement in the same project. shadowgraph_record_decision creates the replacement; shadowgraph_update_status changes state without replacement. Returns previous, replacement and relation. Both IDs must be owned in the same project/origin. History stays searchable; even repeats commit a revision.

Input Schema

NameRequiredDescriptionDefault
projectNoOwning project; required unless originId is set, else the write is refused.
originIdNoCapture-origin id; with no project the record belongs to it alone.
decisionIdYesThe decision being replaced. It becomes superseded and is excluded from current context.
replacementIdYesThe decision replacing it. Must be in the same project and must not be superseded, archived, abandoned, or stale.

Output Schema

NameRequiredDescriptionDefault
previousYesA stored decision, including its alternatives and auditable confidence basis.
relationYesThe supersedes relationship, or null when a repeated supersession found none to report.
replacementYesA stored decision, including its alternatives and auditable confidence basis.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.42.3
  2. Removedv0.42.1
  3. Changed3 schema fields changedv0.40.1
    • addedInput schema / properties / decisionId / description
      Added value: +"The decision being replaced. It becomes superseded and is excluded from current context."
    • addedInput schema / properties / replacementId / description
      Added value: +"The decision replacing it. Must be in the same project and must not be superseded, archived, abandoned, or stale."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "description": "Both sides of the supersession and the relationship that records it.",
+  "properties": {
+    "previous": {
+      "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"
+    },
+    "relation": {
+      "anyOf": [
+        {
+          "description": "A stored relationship between two entities.",
+          "properties": {
+            "actor": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Who performed the write."
+            },
+            "client": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Which client performed the write."
+            },
+            "createdAt": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "ISO 8601 creation time."
+            },
+            "from": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Source entity identifier."
+            },
+            "id": {
+              "description": "Stable entity identifier.",
+              "type": "string"
+            },
+            "kind": {
+              "description": "Entity kind: decision, attempt, memory, fact, relation, review, or alternative.",
+              "type": "string"
+            },
+            "project": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Project namespace; records imported from a schema that predates projects may carry null."
+            },
+            "relation": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Relationship name, such as depends_on or supersedes."
+            },
+            "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."
+            },
+            "temporal": {
+              "description": "Bi-temporal window for the relationship.",
+              "type": "object"
+            },
+            "to": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Target entity identifier."
+            },
+            "updatedAt": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "ISO 8601 time of the last change."
+            }
+          },
+          "required": [
+            "id",
+            "from",
+            "to",
+            "relation"
+          ],
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The supersedes relationship, or null when a repeated supersession found none to report."
+    },
+    "replacement": {
+      "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"
+    }
+  },
+  "required": [
+    "previous",
+    "replacement",
+    "relation"
+  ],
+  "type": "object"
+}
  4. First observedv0.40.0

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare the write as destructive, non-idempotent, and non-readonly, so the description need not repeat safety flags. It adds useful behavior beyond those annotations: it returns previous, replacement, and relation; history remains searchable; and even repeat calls commit a revision. It does not explicitly describe reversibility or authorization requirements, which keeps it from a 5.

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?

The description is front-loaded with the core action and then adds only high-value clauses: sibling differentiation, return shape, ownership constraint, and history/revision behavior. Every sentence earns its place and there is no redundant restatement of the schema or annotations.

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

Completeness5/5

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

Given the destructive write annotation, full schema coverage, and an output schema, the description supplies the remaining context an agent needs: when to use this versus sibling tools, the same-project/origin ownership rule, and the fact that history remains searchable and repeats create revisions. It is complete for correct selection and invocation.

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%, so the schema already documents each parameter thoroughly, including that decisionId becomes superseded and replacementId must not be superseded, archived, abandoned, or stale. The description adds a cross-parameter ownership constraint (same project/origin) beyond individual field definitions, but otherwise relies on the schema for parameter meaning. A 3 reflects the baseline when schema does the heavy lifting plus modest added constraint context.

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 states a specific verb and resource: marking one decision as superseded by a replacement in the same project. It explicitly distinguishes this from shadowgraph_record_decision (creates the replacement) and shadowgraph_update_status (changes state without replacement), so an agent can route correctly without opening sibling schemas.

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

Usage Guidelines5/5

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

It names the two relevant alternative tools and explains the conditions that select them: record_decision creates the replacement, while update_status changes state without one. It also states the ownership constraint that both IDs must belong to the same project/origin, giving clear preconditions for use.

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