ShadowGraph

Official

Overview Schema Related Servers Score Discussions

shadowgraph_record_attempt

Record an attempt and its outcome to prevent blindly retrying the same failed approach, building a searchable history for future decisions.

Instructions

Record one attempt and how it turned out, so the same approach is not blindly retried. Use shadowgraph_record_decision for the choice itself, shadowgraph_record_outcome for how one played out. Appends an attempt and a journal entry; without idempotencyKey a retry records a second one.

Input Schema

TableJSON Schema

Name	Required	Description
`actor`	No	Who performed this write, such as an agent or person name. Stored for audit; never used to grant trust.
`client`	No	Which client software performed this write, such as the host application name.
`reason`	No	Why it turned out that way. Searchable content.
`result`	Yes	What happened. Required, non-empty, and searchable content. Wording such as failed, error, or regression is what makes the attempt surface in shadowgraph_context as one to avoid.
`project`	No	Project namespace. Defaults to "default"; an empty string is rejected.
`solution`	Yes	What was tried. Required, non-empty, and searchable content.
`sessionId`	No	Caller-owned identifier that groups related writes in the audit trail.
`environment`	No	Where it was tried, such as a runtime, OS, or version. Searchable content, so a later attempt can be matched to the same environment.
`sourceClass`	No	Claimed origin, never proof: agent_claimed (the default), tool_observed, human_confirmed, or production_verified. It weights confidence only. An unrecognised label downgrades to agent_claimed, kept verbatim in sourceRaw.
`idempotencyKey`	No	Retry key scoped by project and operation: reuse it so a retry returns the first result instead of writing a duplicate. Without it every call creates a new entity.

Output Schema

TableJSON Schema

Name	Required	Description
`id`	Yes	Stable entity identifier.
`kind`	Yes	Entity kind: decision, attempt, memory, fact, relation, review, or alternative.
`actor`	No	Who performed the write.
`client`	No	Which client performed the write.
`reason`	No	Why it turned out that way.
`result`	No	What happened.
`project`	No	Project namespace; records imported from a schema that predates projects may carry null.
`solution`	No	What was tried.
`createdAt`	No	ISO 8601 creation time.
`relatedTo`	No	Identifiers of related entities.
`sessionId`	No	Session identifier recorded with the write.
`sourceRaw`	No	The original origin label when it differed from sourceClass. Audit only; never evidence.
`updatedAt`	No	ISO 8601 time of the last change.
`environment`	No	Where it was tried.
`sourceClass`	No	Claimed origin class recorded with the write. A claim, never proof.
`reusableWhen`	No	Conditions under which the attempt is worth repeating.
`schemaVersion`	No	Storage schema version this entity was written under. A value above the build’s own version is preserved rather than downgraded.

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

Changed11 schema fields changedv0.40.1Sep 3, 2026

changedInput schema / properties / actor / description

Previous value: -"Who performed this write, e.g. an agent name."New value: +"Who performed this write, such as an agent or person name. Stored for audit; never used to grant trust."

changedInput schema / properties / client / description

Previous value: -"Which client performed this write."New value: +"Which client software performed this write, such as the host application name."

addedInput schema / properties / environment / description

Added value: +"Where it was tried, such as a runtime, OS, or version. Searchable content, so a later attempt can be matched to the same environment."

changedInput schema / properties / idempotencyKey / description

Previous value: -"Retry key scoped by project and operation; reuse only for the same logical write."New value: +"Retry key scoped by project and operation: reuse it so a retry returns the first result instead of writing a duplicate. Without it every call creates a new entity."

addedInput schema / properties / project / description

Added value: +"Project namespace. Defaults to \"default\"; an empty string is rejected."

addedInput schema / properties / reason / description

Added value: +"Why it turned out that way. Searchable content."

addedInput schema / properties / result / description

Added value: +"What happened. Required, non-empty, and searchable content. Wording such as failed, error, or regression is what makes the attempt surface in shadowgraph_context as one to avoid."

changedInput schema / properties / sessionId / description

Previous value: -"Session identifier for this write."New value: +"Caller-owned identifier that groups related writes in the audit trail."

addedInput schema / properties / solution / description

Added value: +"What was tried. Required, non-empty, and searchable content."

changedInput schema / properties / sourceClass / description

Previous value: -"Claimed origin class. A claim, not proof: no value here can make a fact verified."New value: +"Claimed origin, never proof: agent_claimed (the default), tool_observed, human_confirmed, or production_verified. It weights confidence only. An unrecognised label downgrades to agent_claimed, kept verbatim in sourceRaw."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "description": "A stored attempt and its result.",
+  "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."
+    },
+    "environment": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Where it was tried."
+    },
+    "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."
+    },
+    "reason": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Why it turned out that way."
+    },
+    "relatedTo": {
+      "description": "Identifiers of related entities.",
+      "type": "array"
+    },
+    "result": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "What happened."
+    },
+    "reusableWhen": {
+      "description": "Conditions under which the attempt is worth repeating.",
+      "type": "array"
+    },
+    "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."
+    },
+    "solution": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "What was tried."
+    },
+    "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."
+    }
+  },
+  "required": [
+    "id",
+    "kind"
+  ],
+  "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?

Discloses side effects beyond the annotations: it appends both an attempt and a journal entry, and warns that without idempotencyKey a retry records a second entity. This complements idempotentHint=false by explaining the concrete consequence.

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?

Two sentences front-load the core purpose, then provide sibling routing and a behavioral caveat. Every clause earns its place with no repetition of schema content.

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 10-parameter write tool with full schema coverage and an output schema, the description supplies essential context: purpose, sibling differentiation, side effects, and idempotency behavior. Nothing necessary for correct invocation is missing.

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 10 parameters. The description does not add parameter details beyond what the schema provides, but it does not need to; the baseline of 3 is appropriate since the schema carries the burden.

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 ('Record one attempt and how it turned out') and explicitly distinguishes itself from shadowgraph_record_decision and shadowgraph_record_outcome. An agent can tell this tool apart from closely related siblings without opening their schemas.

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 sibling tools for adjacent cases ('Use shadowgraph_record_decision for the choice itself, shadowgraph_record_outcome for how one played out') and frames when this tool applies ('so the same approach is not blindly retried'). The guidance is explicit and actionable.

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

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/LiLara-AI/shadowgraph'

If you have feedback or need assistance with the MCP directory API, please join our Discord server