Skip to main content
Glama
Sign In
ShadowGraph

ShadowGraph

Official
by LiLara-AI
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

shadowgraph_search

Search decision and attempt records by literal query terms, requiring every term to match, with filters for kind, status, confidence, source class, project, or origin plus paginated completeness data.

Instructions

Find direct content matches for every literal query term. shadowgraph_retrieve adds ordered neighbours; shadowgraph_recall ranks matches; shadowgraph_context prepares a working set. Own-scope read saves nothing; an access key commits a revision and bounded audit. Paginated matches and completeness. "redis timeout" requires both terms, not an exact phrase; empty query applies filters only.

Input Schema

NameRequiredDescriptionDefault
kindNoRestrict results to decisions or to attempts. A structured filter, never a content match.
limitNoMaximum items to return, 1-1000; the default is 50 and completeness.limitSource reports which applied. Out of range is rejected, never silently clamped.
queryNoWhitespace-separated terms, matched case-insensitively as substrings against the declared content fields (title, goal, chosen, assumption, evidence, alternative, attempt solution, attempt result, attempt reason, environment). Every term must match something, so more terms narrow the result. Omit to filter without searching.
offsetNoItems to skip before this window. Ordering is total and deterministic, so paging cannot drop or duplicate an item.
statusNoReturn only decisions in this lifecycle state. A structured filter, so matching it is never counted as a content match.
grantIdNoAlias for accessId; conflicting identifiers are refused.
projectNoProject or confirmed workspace binding; otherwise origin-only. No identity returns an empty scoped view.
accessIdNoGrant 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.
originIdNoCapture-origin id; with no project the record belongs to it alone.
sourceClassNoReturn only records carrying this claimed origin class. A structured filter, never a content match.
minConfidenceNoReturn only decisions whose current confidence is at least this value, 0-1. A structured filter, never a content match.

Output Schema

NameRequiredDescriptionDefault
pageYesThe window actually applied to the matching items.
itemsYesThe items in this window, in deterministic order.
completenessYesDeclares exactly what this response left out, so a truncated result can never look complete.
readProvenanceNoOriginal read bounds; reuse intersects these with currently valid authority.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.42.4
    • changedOutput 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"
+}
  2. Changed1 schema field changedv0.42.2
    • 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."
  3. Changed14 schema fields changedv0.42.1
    • addedInput schema / properties / accessId
      Added value: +{
+  "description": "Grant ID, rechecked at use.",
+  "type": "string"
+}
    • addedInput schema / properties / grantId
      Added value: +{
+  "description": "Alias for accessId; conflicting identifiers are refused.",
+  "type": "string"
+}
    • addedInput schema / properties / originId
      Added value: +{
+  "description": "Capture-origin id; with no project the record belongs to it alone.",
+  "type": "string"
+}
    • changedInput schema / properties / project / description
      Previous value: -"Restrict to one project. Omitted, decisions and facts are searched across projects, while memories stay in the default project and all-null scope."New value: +"Project or confirmed workspace binding; otherwise origin-only. No identity returns an empty scoped view."
    • addedOutput schema / properties / completeness / properties / capture
      Added value: +{
+  "description": "Scoped unprocessed capture, when present.",
+  "properties": {
+    "blocked": {
+      "description": "Items blocked.",
+      "minimum": 0,
+      "type": "integer"
+    },
+    "expired": {
+      "description": "Raw expired before extraction; a gap, not backlog.",
+      "minimum": 0,
+      "type": "integer"
+    },
+    "extractionAvailable": {
+      "description": "Whether extraction runs.",
+      "type": "boolean"
+    },
+    "failed": {
+      "description": "Items failed.",
+      "minimum": 0,
+      "type": "integer"
+    },
+    "gaps": {
+      "description": "Capture refusal/unread gaps; no identities.",
+      "items": {
+        "properties": {
+          "from": {
+            "description": "Gap start time.",
+            "type": "string"
+          },
+          "reason": {
+            "description": "Why capture has a gap.",
+            "enum": [
+              "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"
+            ],
+            "type": "string"
+          },
+          "sessions": {
+            "description": "Sessions covered by this gap.",
+            "minimum": 0,
+            "type": "integer"
+          },
+          "to": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "End time, if known."
+          }
+        },
+        "required": [
+          "reason",
+          "from",
+          "to"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "limited": {
+      "description": "Admission limits; accepted items kept.",
+      "items": {
+        "properties": {
+          "ceiling": {
+            "description": "The limit value.",
+            "minimum": 0,
+            "type": "integer"
+          },
+          "limit": {
+            "description": "The limit reached.",
+            "enum": [
+              "maxQueueDepth",
+              "maxStoreBytes"
+            ],
+            "type": "string"
+          },
+          "since": {
+            "description": "When refusal began.",
+            "type": "string"
+          }
+        },
+        "required": [
+          "limit",
+          "ceiling",
+          "since"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "oldestPendingAt": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Oldest pending capture."
+    },
+    "pending": {
+      "description": "Items waiting.",
+      "minimum": 0,
+      "type": "integer"
+    },
+    "processing": {
+      "description": "Items claimed.",
+      "minimum": 0,
+      "type": "integer"
+    },
+    "workerErrors": {
+      "description": "Scoped worker stops; fixed codes.",
+      "items": {
+        "properties": {
+          "at": {
+            "description": "Stop timestamp.",
+            "type": "string"
+          },
+          "reason": {
+            "description": "Worker stop code.",
+            "type": "string"
+          }
+        },
+        "required": [
+          "reason",
+          "at"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "pending",
+    "processing",
+    "failed",
+    "blocked",
+    "oldestPendingAt",
+    "extractionAvailable",
+    "limited",
+    "gaps"
+  ],
+  "type": "object"
+}
    • changedOutput schema / properties / completeness / properties / complete / description
      Previous value: -"True only when every matching item is present."New value: +"Known-candidate coverage; false for unresolved scope, withheld detail or pending capture; not recall."
    • addedOutput schema / properties / completeness / properties / limitation
      Added value: +{
+  "description": "Limits of this view.",
+  "properties": {
+    "code": {
+      "description": "Stable limitation code.",
+      "type": "string"
+    },
+    "detail": {
+      "description": "What this view cannot establish.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "detail"
+  ],
+  "type": "object"
+}
    • changedOutput schema / properties / completeness / properties / losslessItems / description
      Previous value: -"Always true: each returned item is a full-fidelity record, never a summary or a truncated field."New value: +"False when returned items have withheld or transformed detail."
    • addedOutput schema / properties / completeness / properties / quarantined
      Added value: +{
+  "description": "Items withheld as possibly purged.",
+  "minimum": 0,
+  "type": "integer"
+}
    • changedOutput schema / properties / completeness / properties / scope / description
      Previous value: -"The project, query, and structured filters that produced this result, so it explains its own derivation."New value: +"The resolved read boundary."
    • addedOutput schema / properties / completeness / properties / scope / properties
      Added value: +{
+  "grant": {
+    "anyOf": [
+      {
+        "type": "null"
+      },
+      {
+        "properties": {
+          "accessId": {
+            "description": "The currently rechecked grant identifier.",
+            "type": "string"
+          },
+          "expiresAt": {
+            "description": "Earliest effective expiry of this read authority.",
+            "type": "string"
+          },
+          "surface": {
+            "description": "Actual runtime surface of this read.",
+            "enum": [
+              "cli",
+              "mcp",
+              "http"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "accessId",
+          "expiresAt",
+          "surface"
+        ],
+        "type": "object"
+      }
+    ],
+    "description": "Effective rechecked grant, or null."
+  },
+  "originPresented": {
+    "description": "Usable origin presented; not project selection.",
+    "type": "boolean"
+  },
+  "project": {
+    "anyOf": [
+      {
+        "type": "string"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "description": "Resolved project, or null."
+  },
+  "requestState": {
+    "description": "Whether a project was resolved.",
+    "enum": [
+      "project_selected",
+      "project_unresolved"
+    ],
+    "type": "string"
+  }
+}
    • addedOutput schema / properties / completeness / properties / scope / required
      Added value: +[
+  "project",
+  "requestState",
+  "originPresented",
+  "grant"
+]
    • changedOutput schema / properties / items / items / properties / record / properties / project / description
      Previous value: -"Project namespace; records imported from a schema that predates projects may carry null."New value: +"Project namespace; null for an unattributed record or one imported from before projects."
    • addedOutput schema / properties / readProvenance
      Added value: +{
+  "description": "Original read bounds; reuse intersects these with currently valid authority.",
+  "properties": {
+    "accessId": {
+      "description": "Original grant, revalidated on every reuse.",
+      "type": "string"
+    },
+    "expiresAt": {
+      "description": "Original effective expiry; reuse cannot extend it.",
+      "type": "string"
+    },
+    "request": {
+      "description": "Original request ownership, preserved during expansion.",
+      "properties": {
+        "originId": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Original capture origin, or null when absent."
+        },
+        "project": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Original resolved project, or null when unresolved."
+        }
+      },
+      "required": [
+        "project",
+        "originId"
+      ],
+      "type": "object"
+    },
+    "scope": {
+      "description": "Finite explicit owner bounds; project names, origins and legacy attribution are disjoint.",
+      "properties": {
+        "legacyAttributions": {
+          "description": "Explicit legacy ownership classes; neither is a named project.",
+          "items": {
+            "enum": [
+              "legacy_ambiguous",
+              "legacy_unattributed"
+            ],
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "originIds": {
+          "description": "Exact nonempty origin identifiers for unattributed content.",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "projects": {
+          "description": "Exact named projects, including a real project named default if requested.",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        }
+      },
+      "type": "object"
+    },
+    "surfaces": {
+      "description": "Original permitted surfaces; reuse can only narrow them.",
+      "items": {
+        "enum": [
+          "cli",
+          "mcp",
+          "http"
+        ],
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "version": {
+      "const": 1,
+      "description": "Version of this bounded read provenance.",
+      "type": "integer"
+    }
+  },
+  "required": [
+    "version",
+    "request",
+    "accessId",
+    "scope",
+    "surfaces",
+    "expiresAt"
+  ],
+  "type": "object"
+}
  4. Changed9 schema fields changedv0.40.1
    • addedInput schema / properties / kind / description
      Added value: +"Restrict results to decisions or to attempts. A structured filter, never a content match."
    • changedInput schema / properties / limit / description
      Previous value: -"Page size. Omitted means a declared default, never silent truncation."New value: +"Maximum items to return, 1-1000; the default is 50 and completeness.limitSource reports which applied. Out of range is rejected, never silently clamped."
    • addedInput schema / properties / minConfidence / description
      Added value: +"Return only decisions whose current confidence is at least this value, 0-1. A structured filter, never a content match."
    • changedInput schema / properties / offset / description
      Previous value: -"Page offset."New value: +"Items to skip before this window. Ordering is total and deterministic, so paging cannot drop or duplicate an item."
    • addedInput schema / properties / project / description
      Added value: +"Restrict to one project. Omitted, decisions and facts are searched across projects, while memories stay in the default project and all-null scope."
    • addedInput schema / properties / query / description
      Added value: +"Whitespace-separated terms, matched case-insensitively as substrings against the declared content fields (title, goal, chosen, assumption, evidence, alternative, attempt solution, attempt result, attempt reason, environment). Every term must match something, so more terms narrow the result. Omit to filter without searching."
    • addedInput schema / properties / sourceClass / description
      Added value: +"Return only records carrying this claimed origin class. A structured filter, never a content match."
    • addedInput schema / properties / status / description
      Added value: +"Return only decisions in this lifecycle state. A structured filter, so matching it is never counted as a content match."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "description": "Matching records with their pagination and completeness declaration.",
+  "properties": {
+    "completeness": {
+      "description": "Declares exactly what this response left out, so a truncated result can never look complete.",
+      "properties": {
+        "complete": {
+          "description": "True only when every matching item is present.",
+          "type": "boolean"
+        },
+        "contentFields": {
+          "description": "The declared content fields a query term could match.",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "limitSource": {
+          "description": "Whose choice bounded the result.",
+          "enum": [
+            "caller",
+            "default"
+          ],
+          "type": "string"
+        },
+        "losslessItems": {
+          "description": "Always true: each returned item is a full-fidelity record, never a summary or a truncated field.",
+          "type": "boolean"
+        },
+        "omitted": {
+          "description": "total minus returned.",
+          "minimum": 0,
+          "type": "integer"
+        },
+        "returned": {
+          "description": "Items in this response.",
+          "minimum": 0,
+          "type": "integer"
+        },
+        "scope": {
+          "description": "The project, query, and structured filters that produced this result, so it explains its own derivation.",
+          "type": "object"
+        },
+        "total": {
+          "description": "Items that matched in total.",
+          "minimum": 0,
+          "type": "integer"
+        }
+      },
+      "required": [
+        "scope",
+        "returned",
+        "total",
+        "complete",
+        "omitted",
+        "losslessItems",
+        "limitSource",
+        "contentFields"
+      ],
+      "type": "object"
+    },
+    "items": {
+      "description": "The items in this window, in deterministic order.",
+      "items": {
+        "description": "One hit and the evidence for why it matched.",
+        "properties": {
+          "filters": {
+            "description": "The structured filters that were applied.",
+            "type": "object"
+          },
+          "matched": {
+            "description": "The content fields that actually matched, never schema keys.",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "matchedBy": {
+            "description": "content when query terms matched, filter when only structured filters applied, graph when the item was pulled in as a neighbour.",
+            "enum": [
+              "content",
+              "filter",
+              "graph"
+            ],
+            "type": "string"
+          },
+          "reason": {
+            "description": "Human-readable explanation built from matched, so it can never claim a match it cannot name.",
+            "type": "string"
+          },
+          "record": {
+            "description": "One stored entity: a decision, attempt, memory, fact, or alternative. Fields vary by kind, and an entity imported from an older schema may carry fewer of them.",
+            "properties": {
+              "actor": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Who performed the write."
+              },
+              "client": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Which client performed the write."
+              },
+              "createdAt": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "ISO 8601 creation time."
+              },
+              "id": {
+                "description": "Stable entity identifier.",
+                "type": "string"
+              },
+              "kind": {
+                "description": "Entity kind: decision, attempt, memory, fact, relation, review, or alternative.",
+                "type": "string"
+              },
+              "project": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Project namespace; records imported from a schema that predates projects may carry null."
+              },
+              "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."
+              },
+              "updatedAt": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "ISO 8601 time of the last change."
+              }
+            },
+            "type": "object"
+          },
+          "score": {
+            "description": "Relevance score; 0 when no query terms were supplied.",
+            "type": "number"
+          }
+        },
+        "required": [
+          "record",
+          "score",
+          "matched",
+          "reason",
+          "matchedBy",
+          "filters"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "page": {
+      "description": "The window actually applied to the matching items.",
+      "properties": {
+        "hasMore": {
+          "description": "True when matching items exist beyond this window.",
+          "type": "boolean"
+        },
+        "limit": {
+          "description": "Window size applied, whether the caller set it or the default did.",
+          "minimum": 1,
+          "type": "integer"
+        },
+        "offset": {
+          "description": "Index of the first item returned.",
+          "minimum": 0,
+          "type": "integer"
+        },
+        "total": {
+          "description": "Matching items before the window was applied.",
+          "minimum": 0,
+          "type": "integer"
+        }
+      },
+      "required": [
+        "offset",
+        "limit",
+        "total",
+        "hasMore"
+      ],
+      "type": "object"
+    }
+  },
+  "required": [
+    "items",
+    "page",
+    "completeness"
+  ],
+  "type": "object"
+}
  5. First observedv0.40.0

TDQS

A4.3/5.0
Behavior4/5

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

Annotations declare readOnlyHint=false and idempotentHint=false, and the description earns credit for explaining why: an access key commits a revision and bounded audit (at most one aggregate per grant/surface/outcome/UTC day), while own-scope reads save nothing. It adds pagination and completeness reporting on top. It stops short of describing what the committed revision means for subsequent reads, but the side-effect profile is far better disclosed than the annotations alone provide.

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?

Purpose and sibling routing are front-loaded, and every sentence carries content. Some lines are telegraphic to the point of ambiguity ("Paginated matches and completeness.", "Own-scope read saves nothing"), costing a little clarity even though nothing is padded.

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?

For an 11-parameter, enum-heavy search tool with a full schema and an output schema, the description covers purpose, sibling disambiguation, semantic matching rules, paging guarantees, and the audit side effect. Remaining gaps (return ordering details, interaction between kind/status/sourceClass filters) are adequately handled by the schema and output schema.

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% and the schema is unusually rich (enum semantics, limit bounds, offset determinism, grant aliasing). The description only adds the non-phrase, all-terms-required reading of `query`, which the schema largely already states, so baseline 3 is right.

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?

"Find direct content matches for every literal query term" gives a precise verb (find/match) and resource (content), and the following clause enumerates what each sibling does instead (retrieve adds neighbours, recall ranks, context prepares a working set). An agent can pick this tool over the four lookalike search/read siblings without opening a 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?

The description supplies an explicit routing table across siblings and states the distinguishing behaviour (literal term matching only, no ordering or expansion). It also covers the degenerate case: "empty query applies filters only", plus the "redis timeout" example clarifying that all terms must appear rather than forming a phrase.

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

Deploy Server

Other Tools