Skip to main content
Glama
persistent-memory-mcp

persistent-memory-mcp

Explain an artifact

memory_explain
Read-onlyIdempotent

Explains why an artifact is or isn’t served by returning metadata on its state, versions, derivations, and dependents; use it when a search omits an expected item or before a correction.

Instructions

Explain why an artifact is or is not served: its state, its versions, what it was derived from and what depends on it. Metadata only, never text. Use it when a search leaves out something the user expects, or before a correction. Read-only; unknown_artifact if it does not exist. Give artifact_id or ref.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "memory_explain"
  }
}

Input Schema

NameRequiredDescriptionDefault
refNoAn exact version: the ref object returned by memory_search, memory_remember or memory_derive, copied unchanged.
artifact_idNoThe artifact_id returned when it was stored or found by memory_search.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so the safety profile is covered. The description still adds value the annotations cannot: the output is metadata only and never document text, and a missing artifact yields an explicit `unknown_artifact` error rather than an empty result. What it does not cover is pagination or result size for large dependency graphs.

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-loaded with the purpose and its answer fields, then the usage trigger, then the invocation constraint. Every clause carries distinct information; nothing is redundant with the title or annotations.

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?

There is no output schema, and the description compensates by naming the fields the explanation reports (state, versions, derivation, dependents) plus the error case. For a read-only, two-parameter lookup tool with full annotation coverage, nothing an agent needs in order to call it correctly is missing.

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?

The schema documents both parameters and the nested ref object at 100% coverage, and the description adds a fact the schema does not enforce: with zero required properties, the agent is told it must supply one of artifact_id or ref. That is genuine routing information beyond the structured fields, though it does not explain precedence if both are given.

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?

"Explain why an artifact is or is not served" pairs a specific verb with a specific resource, then enumerates the exact answer payload: state, versions, derivation chain, dependents. "Metadata only, never text" implicitly separates it from memory_read, so an agent can tell which one it needs 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 Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Two concrete triggering situations are given: "when a search leaves out something the user expects" and "before a correction," which routes the agent between memory_search and memory_correct. There is no explicit when-not-to-use statement or named alternative, so it falls short of a 5.

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