Engram

Overview Schema Source Related Servers Discussions Admin

get_knowledge_history

Read-onlyIdempotent

Retrieve the revision history of a stored knowledge item to audit version chains, verify prior behavior after an edit, or recover content that was replaced.

Instructions

查看一个知识条目（lesson/decision/playbook）的修订历史。 / Return the revision history (superseded snapshots) of one knowledge item.

**Lifecycle: retrieval** — 需要追溯某条知识改过什么、何时改的、改前长什么样时调用。
Lifecycle: retrieval — call when you need what changed on an item, when, and what the prior body looked like.

用途：修订后核对旧行为、审计版本链、或找回被改掉的内容。
Purpose: verify prior behavior after a revision, audit a version chain, or recover replaced content.

Args:
    item_id: 条目 ID（稳定 HEAD id，不是快照 id）。 / Item id (the stable HEAD id, not a snapshot id).
    include_bodies: 是否在结果里带快照正文（默认 false 只给元数据）。 / Include snapshot bodies in the result (default false returns metadata only).
    version: 精确按版本号取一个快照（可选）；不存在时返回 version_not_found 而不是近似值。 / Exact by-version snapshot lookup (optional); a miss returns version_not_found, never a nearest match.

Input Schema

Name	Required	Description	Default
`item_id`	Yes
`version`	No
`include_bodies`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv4.19.1Aug 30, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already cover read-only, idempotent, non-destructive, closed-world. Beyond that, the description discloses the error contract (version miss returns version_not_found, never approximate) and the payload-size tradeoff of include_bodies=false returning metadata only. It does not describe ordering of snapshots or pagination, so it is not a 5.

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?

Content is front-loaded with purpose, then lifecycle, then purpose-in-practice, then args — a clean structure. The cost is that every sentence is duplicated in Chinese and English, roughly doubling length without adding information, which is the only thing keeping it from a 5.

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 need not be explained. All three parameters are given meaning, the version-miss error path is named, and the HEAD-id-vs-snapshot-id trap is called out — everything an agent needs to invoke this correctly is present.

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

Parameters5/5

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

Schema coverage is 0%, so the description carries the full burden and does: item_id is explicitly 'the stable HEAD id, not a snapshot id' — a distinction the schema cannot convey and an easy mistake to make. It also documents include_bodies' default effect (metadata only) and version's exact-match semantics with the version_not_found failure mode instead of a nearest match.

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: 'Return the revision history (superseded snapshots) of one knowledge item', and enumerates the item types it applies to (lesson/decision/playbook). This clearly distinguishes it from siblings like search_knowledge or get_relevant_knowledge, which retrieve current content rather than version chains.

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?

The 'Lifecycle: retrieval' line plus three concrete triggers (verify prior behavior after a revision, audit a version chain, recover replaced content) tell the agent exactly when to call it. It does not name an alternative tool or state when NOT to use it, which is why it stops 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.