ShadowGraph

Official

Overview Schema Source Related Servers Discussions Admin

shadowgraph_expand

Fetches the full current record behind a context line using its expansion handle, returning revision status and flagging stale digests or unavailable records.

Instructions

Fetch the full current record behind a context line, with its expansion handle as input. shadowgraph_context supplies the handle; flatten its scope into top-level inputs. Own-scope read saves nothing; an access key commits a revision and bounded audit. Returns record, revision status and bounded counterparts. A stale digest yields revision_changed; inaccessible records yield unavailable.

Input Schema

Name	Required	Description
`asOf`	No	The line's expansion.asOf, when it has one.
`digest`	Yes	The line's expansion.digest: the revision the line was derived from.
`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.
`recordId`	Yes	The line's expansion.recordId.
`derivedAt`	No	The line's expansion.derivedAt. A logical purge of the read's own project recorded after it answers purged.
`maxExpansions`	No	How many structural counterparts to fetch in full, 0-50. Defaults to 5; the rest are marked uninvestigated, with their lines.
`derivationVersion`	No	The line's expansion.derivationVersion.

Output Schema

Name	Required	Description
`record`	Yes	The current full record, or null. Never a summary and never the old revision.
`status`	Yes	current: the line came from this revision. revision_changed: the record changed since, and this is the current record. purged: the first purge of the read's own project after the line was logical. unavailable: no record with this id is served in the scope.
`recordId`	Yes	The record the line named.
`completeness`	Yes	Request coverage and any withheld detail.
`boundRevision`	Yes	The revision the line was derived from.
`investigation`	Yes	Counterparts investigated within the budget; null when no record is served.
`readProvenance`	No	Original read bounds; reuse intersects these with currently valid authority.
`currentRevision`	Yes	The live revision; null when no record is served.
`revisionChanged`	Yes	Whether the record changed after the line was derived; null when no record is served.

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.2Oct 25, 2026

addedInput schema / description

Added value: +"Input recipe: copy the line.expansion fields, omit null optional values, and put its scope.project, scope.originId and scope.grantId at top level. Do not pass the operation name or nest a scope object. Keep the digest and original read bounds; no handle field grants wider authority."

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?

Annotations declare readOnlyHint=false and idempotentHint=false without explaining why; the description fills that gap by disclosing that presenting an access key commits a revision and a bounded audit while an own-scope read has no side effects. It also enumerates failure modes (stale digest → revision_changed, inaccessible → unavailable), which is behavior an agent cannot infer from the schema.

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?

Front-loaded with purpose, then prerequisite, side effect, return shape and error outcomes — each sentence carries distinct information with no filler. The density of domain jargon makes some clauses ('Own-scope read saves nothing') require a second read, costing a point.

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?

An output schema exists so return values needn't be spelled out, yet the description still flags the three things an agent must anticipate: record/revision status/counterparts, revision_changed on a stale digest, and unavailable on access failure. With 10 parameters at full schema coverage, nothing material is left undocumented.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema itself is unusually descriptive, so the baseline is 3. The description still adds construction guidance ('with its expansion handle as input', 'flatten its scope into top-level inputs') that tells the agent how to derive the arguments rather than just what they are, pushing it to a 4.

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?

States a specific verb and resource ('Fetch the full current record behind a context line') and names the sibling that produces its input (shadowgraph_context), which lets an agent place it in the workflow. The jargon ('context line', 'expansion handle') is domain-specific and not self-explanatory, keeping it just short of a 5.

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?

Gives an explicit prerequisite chain — shadowgraph_context supplies the handle, then flatten its scope into top-level inputs — and distinguishes the own-scope read from the access-key read by consequence ('saves nothing' vs 'commits a revision and bounded audit'). It stops short of naming a concrete when-not-to-use alternative among the many record_* siblings.

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