ShadowGraph

Official

Overview Schema Source Related Servers Discussions Admin

shadowgraph_ack_review

Destructive

Acknowledges a saved review signal by updating its status and acknowledged timestamp without changing the underlying decision or creating a journal entry.

Instructions

Acknowledge a saved review signal; changes its status, not the decision. Use reviewSignalId from shadowgraph_review or shadowgraph_review_context as id; shadowgraph_review_signals lists signals. Change decisions with shadowgraph_update_status or shadowgraph_supersede. Overwrites signal status and acknowledgedAt without a journal entry; rebuild cannot recover it. Each call commits a revision; repeats restamp it.

Input Schema

Name	Required	Description
`id`	Yes	Persisted signal id: reviewSignalId from shadowgraph_review or shadowgraph_review_context, or id from shadowgraph_review_signals. A fresh context evaluation can be unpersisted and have no ID. This is not the decisionId.
`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.

Output Schema

Name	Required	Description
`id`	Yes	Signal identifier, used by shadowgraph_ack_review.
`kind`	Yes	Always "review".
`title`	No	Decision title, when the stored decision has one.
`reason`	Yes	Why it was raised. Identity is this plus decisionId and coverage.
`status`	Yes	open until acknowledged.
`coverage`	No	Exact conditions covered, and part of this identity.
`createdAt`	Yes	ISO 8601 time the signal was raised.
`decisionId`	Yes	The decision this signal is about.
`acknowledgedAt`	Yes	ISO 8601 time of the most recent acknowledgement.
`alternativesToReconsider`	Yes	Alternative labels to look at again.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.42.3Oct 26, 2026

changedInput schema / properties / id / description

Previous value: -"Review signal id, as returned in reviewSignalId by shadowgraph_context, in the id field by shadowgraph_review_signals (full mode only), or in reviewSignals by shadowgraph_maintain. This is the signal id, not the decisionId it refers to."New value: +"Persisted signal id: reviewSignalId from shadowgraph_review or shadowgraph_review_context, or id from shadowgraph_review_signals. A fresh context evaluation can be unpersisted and have no ID. This is not the decisionId."

Changed1 schema field changedv0.42.2Oct 25, 2026

changedInput schema / properties / id / description

Previous value: -"Review signal id, as returned in reviewSignalId by shadowgraph_context, in the id field by shadowgraph_review_signals, or in reviewSignals by shadowgraph_maintain. This is the signal id, not the decisionId it refers to."New value: +"Review signal id, as returned in reviewSignalId by shadowgraph_context, in the id field by shadowgraph_review_signals (full mode only), or in reviewSignals by shadowgraph_maintain. This is the signal id, not the decisionId it refers to."

Changed5 schema fields changedv0.42.1Oct 25, 2026

changedInput schema / properties / id / description

Previous value: -"Review signal id, as returned in the id field by shadowgraph_review_signals or in reviewSignals by shadowgraph_maintain. This is the signal id, not the decisionId it refers to."New value: +"Review signal id, as returned in reviewSignalId by shadowgraph_context, in the id field by shadowgraph_review_signals, or in reviewSignals by shadowgraph_maintain. This is the signal id, not the decisionId it refers to."

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"
+}

addedOutput schema / properties / coverage

Added value: +{
+  "description": "Exact conditions covered, and part of this identity.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedOutput schema / properties / reason / description

Previous value: -"Why the signal was raised. Together with decisionId this is the dedupe identity, so the same cause never raises a second signal."New value: +"Why it was raised. Identity is this plus decisionId and coverage."

Changed2 schema fields changedv0.40.1Sep 3, 2026

addedInput schema / properties / id / description

Added value: +"Review signal id, as returned in the id field by shadowgraph_review_signals or in reviewSignals by shadowgraph_maintain. This is the signal id, not the decisionId it refers to."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "description": "The acknowledged review signal, retained rather than deleted.",
+  "properties": {
+    "acknowledgedAt": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "ISO 8601 time of the most recent acknowledgement."
+    },
+    "alternativesToReconsider": {
+      "description": "Alternative labels to look at again.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "createdAt": {
+      "description": "ISO 8601 time the signal was raised.",
+      "type": "string"
+    },
+    "decisionId": {
+      "description": "The decision this signal is about.",
+      "type": "string"
+    },
+    "id": {
+      "description": "Signal identifier, used by shadowgraph_ack_review.",
+      "type": "string"
+    },
+    "kind": {
+      "const": "review",
+      "description": "Always \"review\".",
+      "type": "string"
+    },
+    "reason": {
+      "description": "Why the signal was raised. Together with decisionId this is the dedupe identity, so the same cause never raises a second signal.",
+      "type": "string"
+    },
+    "status": {
+      "description": "open until acknowledged.",
+      "enum": [
+        "open",
+        "acknowledged"
+      ],
+      "type": "string"
+    },
+    "title": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Decision title, when the stored decision has one."
+    }
+  },
+  "required": [
+    "id",
+    "kind",
+    "decisionId",
+    "reason",
+    "alternativesToReconsider",
+    "status",
+    "createdAt",
+    "acknowledgedAt"
+  ],
+  "type": "object"
+}

First observedv0.40.0Sep 2, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Goes well beyond the destructiveHint=true and idempotentHint=false annotations by explaining exactly what is lost: signal status and acknowledgedAt are overwritten with no journal entry and rebuild cannot recover it. It also confirms the repeat-call behavior ("repeats restamp it") consistent with the non-idempotent hint, so the agent can reason about retries and irreversibility.

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?

Leads with the action, then provenance, then alternatives, then the destructive caveat — ordered by decision value. Every sentence carries new information despite the high density; there is no filler.

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?

For a destructive mutation with three params and full schema coverage, the description supplies the missing pieces: irreversibility, lack of journaling, revision commits and retry semantics. Since an output schema exists, return values need not be described.

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 id, project and originId are already fully documented, including the unpersisted-signal case and the not-a-decisionId warning. The description restates the id provenance already in the schema and says nothing about the project/originId interaction, so it adds little beyond the 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?

States a specific verb and resource ("Acknowledge a saved review signal") and immediately delimits scope with "changes its status, not the decision," which separates it from decision-mutating siblings. An agent can distinguish it from shadowgraph_update_status and shadowgraph_supersede 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?

Names the exact sources for the id (shadowgraph_review, shadowgraph_review_context) and points to shadowgraph_review_signals for discovery. It also explicitly routes the other intent elsewhere: "Change decisions with shadowgraph_update_status or shadowgraph_supersede." Both when-to-use and when-not-to-use are covered.

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

shadowgraph_ack_review

Instructions

Input Schema

Output Schema

Schema Changelog

TDQS

Other Tools