ShadowGraph

Official

Overview Schema Source Related Servers Discussions Admin

shadowgraph_review_context

Evaluates reopen rules, persists signals, and returns the project working set for review so you can see which items need attention next.

Instructions

Evaluate reopen rules, persist signals and return the project working set. shadowgraph_context does not save signals; shadowgraph_review also persists signals but returns only due items. shadowgraph_ack_review closes a returned signal. Deduplicates owned signals and commits a revision on every call. Grants widen audited evaluation, never writes. No choice or lifecycle changes.

Input Schema

Name	Required	Description
`facts`	No	Temporary key/value overrides for object rules; unlisted keys use stored facts. Example: facts:{ready:true} tests {key:"ready",value:true}. This does not record a fact or fire a string rule; changedFacts supplies those changed-key signals.
`limit`	No	Maximum items per collection, 1-1000, applied to each collection independently. Omit for the default of 50.
`grantId`	No	Alias for accessId; conflicting identifiers are refused.
`project`	No	Project or confirmed workspace binding; otherwise origin-only. No identity returns an empty scoped view.
`accessId`	No	Grant ID, rechecked at use. Widens reads only, never write authority. Presenting an access key commits a revision and bounded operational audit: at most one aggregate per grant, surface, outcome and UTC day. Conflicts with a different grantId are refused.
`originId`	No	Capture-origin id; with no project the record belongs to it alone.
`changedFacts`	No	Ephemeral changed-key signals for string-form reopenWhen rules; not stored facts. Example: changedFacts:["budget"] fires reopenWhen:["budget"]. Object rules instead read values from facts overrides or stored facts.

Output Schema

Name	Required	Description
`project`	Yes	The resolved project, or null when unresolved.
`openReviews`	Yes	Decisions currently due for reconsideration.
`completeness`	Yes	Per-collection completeness. context returns several named collections, so one page object cannot describe it.
`readProvenance`	No	Original read bounds; reuse intersects these with currently valid authority.
`activeDecisions`	Yes	Decisions in a current, actionable state: proposed, planned, in_progress, executed, validated, or reconsidered.
`reusableAttempts`	No	Attempts whose reusableWhen conditions all hold now. Worth reconsidering, not authorised to retry.
`staleAssumptions`	Yes	Facts that are no longer active, such as superseded or expired ones, which earlier decisions may still rest on.
`suggestedQuestions`	Yes	Questions for the low-confidence decisions in this project.
`conditionDiagnostics`	No	Conditions that could not be settled, or that rest on facts which disagree. Neither a breach nor a confirmed-safe decision.
`failedAttemptsToAvoid`	Yes	Attempts that failed: resultClass failed or, with none and not captured, a result mentioning failure, regression, or error.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.42.4Oct 29, 2026

changed

Output schema / properties / completeness / properties / capture / properties / gaps / items / properties / reason / enum

Previous value: -[
-  "maxQueueDepth",
-  "maxStoreBytes",
-  "maxItemsPerSession",
-  "session_in_another_project",
-  "raw_expired",
-  "transcript_unrecognised",
-  "session_left_project",
-  "transcript_rewritten",
-  "transcript_reanchored",
-  "transcript_incomplete_at_end",
-  "transcript_line_oversized",
-  "tool_calls_not_captured"
-]New value: +[
+  "maxQueueDepth",
+  "maxStoreBytes",
+  "maxItemsPerSession",
+  "session_in_another_project",
+  "raw_expired",
+  "prior_setup",
+  "transcript_unrecognised",
+  "session_left_project",
+  "transcript_rewritten",
+  "transcript_reanchored",
+  "transcript_incomplete_at_end",
+  "transcript_line_oversized",
+  "tool_calls_not_captured"
+]

addedOutput schema / properties / completeness / properties / capture / properties / priorSetup

Added value: +{
+  "description": "Unextracted items of no or an earlier setup; never extracted by the current one.",
+  "minimum": 0,
+  "type": "integer"
+}

Changed2 schema fields changedv0.42.3Oct 26, 2026

changedInput schema / properties / changedFacts / description

Previous value: -"Fact keys that just changed. Only string-form reopenWhen rules match this list; it is an ephemeral signal, not durable state."New value: +"Ephemeral changed-key signals for string-form reopenWhen rules; not stored facts. Example: changedFacts:[\"budget\"] fires reopenWhen:[\"budget\"]. Object rules instead read values from facts overrides or stored facts."

changedInput schema / properties / facts / description

Previous value: -"Fact key/value overrides evaluated instead of the stored facts of the same key. Stored facts are used for every key not listed here, so reopen rules still work after a restart."New value: +"Temporary key/value overrides for object rules; unlisted keys use stored facts. Example: facts:{ready:true} tests {key:\"ready\",value:true}. This does not record a fact or fire a string rule; changedFacts supplies those changed-key signals."

Changed1 schema field changedv0.42.2Oct 25, 2026

changedInput schema / properties / accessId / description

Previous value: -"Grant ID, rechecked at use."New value: +"Grant ID, rechecked at use. Widens reads only, never write authority. Presenting an access key commits a revision and bounded operational audit: at most one aggregate per grant, surface, outcome and UTC day. Conflicts with a different grantId are refused."

Addedv0.42.1Oct 25, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Beyond the annotations, the description discloses important side effects: it deduplicates owned signals and commits a revision on every call. It also clarifies the grant boundary ('never writes') and scopes out choice or lifecycle changes, which is valuable behavioral context for a mutating review tool.

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

Conciseness4/5

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

The definition is front-loaded with the core purpose and remains compact despite covering several sibling distinctions. Some phrases such as 'working set' and 'No choice or lifecycle changes' are dense or under-explained, but the overall structure is efficient and purpose-first.

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?

Given 100% schema coverage, existing annotations, and an output schema, the description does not need to explain every parameter or return value. It covers purpose, sibling routing, mutation side effects, and grant behavior, though 'project working set' remains somewhat vague and the scope of persisted signals could be clearer.

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%, so the baseline is 3. The description reinforces grant semantics with 'Grants widen audited evaluation, never writes,' but this largely restates what accessId/grantId already document and does not add meaning for facts, changedFacts, project, originId, or limit.

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 names specific actions and outputs: evaluate reopen rules, persist signals, and return the project working set. It also distinguishes this tool from three siblings by explaining how shadowgraph_context, shadowgraph_review, and shadowgraph_ack_review differ.

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?

The description gives clear sibling-based routing: use shadowgraph_context when signals should not be saved, shadowgraph_review when only due items are needed, and shadowgraph_ack_review to close a returned signal. It does not state an explicit 'use this when...' rule or all when-not conditions, but the alternatives are well identified.

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