ShadowGraph

Official

Overview Schema Source Related Servers Discussions Admin

shadowgraph_confidence_evidence

Destructive

Update a decision's confidence with keyed supporting or contradicting evidence. Reuse a stable key to prevent double-counting; use a new key for each new observation.

Instructions

Update decision confidence with keyed supporting or contradicting evidence; no outcome is recorded. Use shadowgraph_record_outcome once the decision has played out, shadowgraph_record_fact for an observation that can reopen it. Reusing key cannot double-count, but restamps the decision and commits a revision; a new observation needs a new key.

Input Schema

Name	Required	Description
`key`	Yes	REQUIRED stable dedupe key. Reuse the same key for the same observation so retries cannot double-count; use a NEW key for a genuinely new observation. There is no default, because a generated one would only be stable within a millisecond.
`actor`	No	Who performed this write, such as an agent or person name. Stored for audit; never used to grant trust.
`client`	No	Which client software performed this write, such as the host application name.
`reason`	Yes	Why this evidence matters. Required, non-empty, and kept in the audit history.
`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.
`supports`	No	Defaults to true. false records contradicting evidence, moving confidence down instead of up.
`sessionId`	No	Caller-owned identifier that groups related writes in the audit trail.
`decisionId`	Yes	Identifier of an existing decision, as returned by shadowgraph_record_decision, shadowgraph_search, or shadowgraph_retrieve.
`observedAt`	No	ISO 8601 time the evidence was observed. Defaults to now.
`sourceClass`	No	Claimed origin, never proof: agent_claimed (the default), tool_observed, human_confirmed, or production_verified. It weights confidence only. An unrecognised label downgrades to agent_claimed, kept verbatim in sourceRaw.

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

Changed10 schema fields changedv0.40.1Sep 3, 2026

changedInput schema / properties / actor / description

Previous value: -"Who performed this write, e.g. an agent name."New value: +"Who performed this write, such as an agent or person name. Stored for audit; never used to grant trust."

changedInput schema / properties / client / description

Previous value: -"Which client performed this write."New value: +"Which client software performed this write, such as the host application name."

addedInput schema / properties / decisionId / description

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

changedInput schema / properties / key / description

Previous value: -"REQUIRED stable dedupe key. Reuse the same key for the same observation so retries do not double-count; use a NEW key for a genuinely new observation."New value: +"REQUIRED stable dedupe key. Reuse the same key for the same observation so retries cannot double-count; use a NEW key for a genuinely new observation. There is no default, because a generated one would only be stable within a millisecond."

addedInput schema / properties / observedAt / description

Added value: +"ISO 8601 time the evidence was observed. Defaults to now."

addedInput schema / properties / reason / description

Added value: +"Why this evidence matters. Required, non-empty, and kept in the audit history."

changedInput schema / properties / sessionId / description

Previous value: -"Session identifier for this write."New value: +"Caller-owned identifier that groups related writes in the audit trail."

changedInput schema / properties / sourceClass / description

Previous value: -"Claimed origin class. A claim, not proof: no value here can make a fact verified."New value: +"Claimed origin, never proof: agent_claimed (the default), tool_observed, human_confirmed, or production_verified. It weights confidence only. An unrecognised label downgrades to agent_claimed, kept verbatim in sourceRaw."

changedInput schema / properties / supports / description

Previous value: -"Defaults to true. false records contradicting evidence."New value: +"Defaults to true. false records contradicting evidence, moving confidence down instead of up."

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 beyond the annotations meaningfully: it discloses that key reuse 'cannot double-count, but restamps the decision and commits a revision' — exactly the nuance behind idempotentHint=false, since dedupe does not mean no side effect. It also states no outcome is recorded. It stops short of explaining what makes the call destructive (destructiveHint=true) — e.g. whether prior evidence or confidence values are superseded — so a 4 rather than 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 sentences, no filler, and the core operation plus its 'no outcome' exclusion come first. The final sentence is dense but each clause adds a distinct rule (no double-count / restamp+revision / new key for new observation).

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?

Output schema and annotations are supplied and the description covers routing, dedupe semantics, and the audit-trail consequence. What remains unaddressed is the destructive side of the operation — which prior state a restamp overwrites — the one gap an agent would want before calling a destructiveHint=true tool.

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 description coverage is 100%, including detailed per-parameter text for key, sourceClass, supports, and project/originId preconditions, so the schema carries the parameter burden. The description's key-reuse sentence echoes rather than extends the schema's 'REQUIRED stable dedupe key' text. Baseline 3 applies.

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 and resource — 'Update decision confidence' — with the scope qualifier 'with keyed supporting or contradicting evidence; no outcome is recorded.' The negative clause immediately separates it from outcome recording, so an agent can distinguish it from shadowgraph_record_outcome 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 Guidelines5/5

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

Explicitly routes to alternatives with conditions: use shadowgraph_record_outcome 'once the decision has played out' and shadowgraph_record_fact 'for an observation that can reopen it.' That is both a when-to-use-this and a when-to-use-something-else statement, naming the two sibling tools by exact name.

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