ShadowGraph

Official

Overview Schema Source Related Servers Discussions Admin

shadowgraph_record_outcome

Destructive

Record an existing decision's outcome to update its evidence-weighted confidence and timestamp; re-recording replaces the prior outcome without changing lifecycle status.

Instructions

Record what happened to an existing decision and update its evidence-weighted confidence. shadowgraph_confidence_evidence records evidence short of an outcome, shadowgraph_update_status changes the lifecycle state. One outcome contribution per decision: re-recording replaces it, updates the decision timestamp and commits a revision; it does not change lifecycle status.

Input Schema

Name	Required	Description
`outcome`	Yes	The outcome to record.
`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.

Changed3 schema fields changedv0.42.1Oct 25, 2026

addedInput schema / properties / originId

Added value: +{
+  "description": "Capture-origin id; with no project the record belongs to it alone.",
+  "type": "string"
+}

addedInput schema / properties / project

Added value: +{
+  "description": "Owning project; required unless originId is set, else the write is refused.",
+  "type": "string"
+}

changedOutput schema / properties / project / description

Previous value: -"Project namespace; records imported from a schema that predates projects may carry null."New value: +"Project namespace; null for an unattributed record or one imported from before projects."

Changed7 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 / outcome / description
```
Added value: +"The outcome to record."
```
addedInput schema / properties / outcome / properties / lessons / description
```
Added value: +"What was learned, stored with the outcome."
```
addedInput schema / properties / outcome / properties / observedAt / description
```
Added value: +"ISO 8601 time the outcome was observed. Defaults to now."
```

addedInput schema / properties / outcome / properties / sourceClass / description

Added value: +"Claimed origin of this outcome observation. It weights how far confidence moves; it never verifies anything."

addedInput schema / properties / outcome / properties / status / description

Added value: +"successful raises confidence, failed lowers it and makes the decision due for review, mixed lowers it by half, and unknown moves nothing because \"we do not know\" is not evidence."

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.4/5.0

Behavior4/5

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

Goes well beyond the annotations: re-recording replaces the prior outcome, updates the decision timestamp, commits a revision, and explicitly does not change lifecycle status. The overwrite behavior matters given destructiveHint=true and is genuinely useful. It stops short of saying whether the replaced outcome is recoverable or what auth is needed, which keeps it off 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?

Three tight sentences, front-loaded with purpose then sibling routing then side effects. No repetition of schema content and no filler.

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?

For a destructive mutation with a rich nested schema and an output schema, the description covers the key deltas: replacement semantics, timestamp and revision side effects, and no lifecycle change. It leaves the required project-or-originId precondition entirely to the schema, which is the only notable gap.

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 nested outcome object documents status semantics, lessons, observedAt, and sourceClass richly, so the schema carries the parameter burden. The description adds only the per-decision uniqueness constraint, which is useful but marginal. Baseline 3 is appropriate.

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?

States a specific verb+resource (record an outcome) plus the effect (update evidence-weighted confidence on an existing decision). It then names the two nearest siblings, shadowgraph_confidence_evidence and shadowgraph_update_status, so an agent can separate it from them without reading 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 Guidelines5/5

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

Explicitly draws the boundary: evidence short of an outcome goes to shadowgraph_confidence_evidence, lifecycle changes go to shadowgraph_update_status, and this tool is for a realized outcome. The alternatives and the condition that selects each are both stated, plus the one-contribution-per-decision constraint that governs repeat use.

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