ShadowGraph

Official

Overview Schema Source Related Servers Discussions Admin

shadowgraph_reconsider

Explain review verdicts for a decision or scoped set with evidence and completeness; persists deduplicated signals and commits a revision.

Instructions

Explain review verdicts for one decision or a scoped set, with evidence and completeness. shadowgraph_review lists only due items; shadowgraph_ack_review closes a signal. No choice, confidence or lifecycle changes. Persists deduplicated owned signals and commits a revision. Grants widen audited evaluation, not writes. review_recommended means a trigger; manual_review means unresolved evidence; unchanged requires complete evaluation.

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.
`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.
`decisionId`	No	Limit the resolved project/origin to this decision; the ID does not supply scope. Unknown, out-of-scope, archived, abandoned or superseded decisions are rejected. Omit to explain all eligible decisions in scope.
`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
`scope`	Yes	What was reconsidered.
`verdict`	Yes	Aggregate over every decision in scope: a definite trigger outranks uncertainty, which outranks unchanged.
`decisions`	Yes	One entry per decision in scope, including decisions with nothing to report.
`readProvenance`	No	Original read bounds; reuse intersects these with currently valid authority.
`evaluationCompleteness`	Yes	partial when any decision in scope was partial.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 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 / decisionId / description

Previous value: -"Reconsider only this decision. An unknown id, or one belonging to another project, is an error rather than an empty result, so a mis-addressed request can never read as \"nothing changed\"."New value: +"Limit the resolved project/origin to this decision; the ID does not supply scope. Unknown, out-of-scope, archived, abandoned or superseded decisions are rejected. Omit to explain all eligible decisions in scope."

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

A3.9/5.0

Behavior4/5

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

Annotations already say the tool is not read-only, not destructive, and not idempotent; the description adds important context: it persists deduplicated owned signals and commits a revision, does not change choice/confidence/lifecycle, and grants only widen audited evaluation. It also defines verdict outcomes (review_recommended, manual_review, unchanged), which helps an agent interpret behavior. It leaves somewhat unclear exactly what the committed revision changes if lifecycle/choice/confidence are untouched.

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 description is front-loaded with purpose, then sibling differentiation, then behavioral constraints. Most sentences earn their place, though the final three verdict definitions are terse and somewhat cryptic without more context.

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?

An output schema exists and the parameters are fully described, so the description does not need to explain return values or parameter details. Given the complexity, it covers purpose, sibling alternatives, mutation scope, grant semantics, and verdict meanings; the only gap is a clearer explanation of what 'reconsider' does operationally versus merely explaining.

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 schema already documents all seven parameters in detail. The description adds no parameter-specific guidance beyond the broad mention of decisions, scoped sets, evidence, completeness, and grants; with full schema coverage this meets the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action: explain review verdicts for a decision or scoped set, including evidence and completeness. It also differentiates itself from sibling tools by naming shadowgraph_review (lists due items) and shadowgraph_ack_review (closes a signal). The core verb is 'explain' rather than the tool name's 'reconsider,' which creates minor ambiguity about whether it also re-evaluates.

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?

It gives clear contrast with two siblings: use shadowgraph_review to list only due items and shadowgraph_ack_review to close a signal, implying this tool is for explaining verdicts. It also scopes grants to widening audited evaluation rather than writes, guiding access usage. It stops short of explicit when-not-to-use conditions beyond those sibling contrasts.

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