Skip to main content
Glama
total-agent-memory

total-agent-memory

memory_explain_search

Read-onlyIdempotent

Debug why a memory record did or didn't surface for a query by returning per-tier retrieval scores, merged ranking, and rerank status.

Instructions

v11.0: same as memory_search_fast but returns a per-tier breakdown (fts/semantic/graph/fuzzy/hyde with raw scores, the merged RRF list, rerank_applied flag, embedding_space). Use to debug why a record did or didn't surface for a query.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "memory_explain_search"
  }
}

Input Schema

NameRequiredDescriptionDefault
typeNoall
limitNo
queryYes
projectNo
embedding_spaceNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv15.0.0
    • changedInput schema / properties / type / enum
      Previous value: -[
      -  "decision",
      -  "fact",
      -  "solution",
      -  "lesson",
      -  "convention",
      -  "all"
      -]New value: +[
      +  "decision",
      +  "fact",
      +  "solution",
      +  "lesson",
      +  "convention",
      +  "incident",
      +  "all"
      +]
  2. First observedv0.1.0

TDQS

B3.4/5.0
Behavior3/5

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

Annotations already declare readOnlyHint/idempotentHint, so safety is covered. The description adds real value by naming the return payload (per-tier raw scores, merged RRF list, rerank_applied, embedding_space), but it gives no sense of how heavy that payload is, whether results are capped, or how tiers behave when one retrieval path is unavailable.

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?

Two compact sentences, with the differentiator front-loaded before the debug rationale. The 'v11.0:' prefix contributes nothing and the 'same as memory_search_fast' framing forces a cross-reference where a direct verb would read faster.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description rightly spends its words on the returned structure, but it describes that structure only in a comma-separated list without field relationships or ordering. Combined with five undocumented parameters, an agent can invoke it but cannot predict the response shape or control scope precisely.

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

Parameters2/5

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

Schema coverage is 0%, so the description must carry parameter meaning and largely doesn't. Only embedding_space is echoed (and as an output field), while query, type's seven value kinds, limit defaults, and project scoping are left entirely unexplained.

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 concrete operation (search) and its differentiator: it returns a per-tier breakdown instead of the plain fast results. The reference to memory_search_fast anchors it against a sibling, though the tool's own verb is never stated outright and depends on the reader knowing what that sibling does.

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?

'Use to debug why a record did or didn't surface for a query' gives a clear diagnostic context that implicitly distinguishes it from the normal search path. It stops short of saying explicitly not to use it for ordinary retrieval where latency or result volume matters.

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