This server provides an evidence-based personal memory system for AI agents: it captures user words verbatim, derives structured knowledge, and enforces a hard validation gate before answering.
Preflight every user turn to detect personal content and persist a turn receipt.
Capture the full user message verbatim with timestamps/session metadata, and refuse non-personal or unprepared turns.
Read memory via survey → probe/deep retrieval, gated on the current turn's capture.
Add derived records (events, entities, decisions, preferences, states, etc.) with source/verbatim refs, salience, confidence, sensitivity, and date precision.
Close each capture with a derivation-loop finalization: require linked records or an explicit "nothing new" reason.
Check derivation status for pending captures, orphans, and link drift.
Register scheduled follow-ups with context and due rules for proactive check-ins.
Record candidate causal hypotheses (with supports/contradicts/alternatives/scope) as candidates, not facts.
Validate archive structure and distinguish clean/warnings/failed; strict mode requires all captures finalized.
Log feedback (helpful/missed/corrected) tied to memory IDs for future improvement.
Run session_check as a mandatory pre-answer gate ensuring turn receipt, capture closure, structure, and v2 integrity.
Allows backing up the memory archive to any rclone remote, enabling mirror-to-second-location backups with integrity verification.
Verbatim-first · Evidence-chain · Associative recall · Anti-fabrication · Local-first · One folder, zero dependencies
中文文档 · How recall works · Quick start · Design principles
agent-memory mcp claude codex skills local-first associative-recall personal-knowledge
Typical agent memory has a dirty secret: the model summarizes first and stores the summary. Your words get paraphrased, compressed, and blended with the model's own interpretations on day one. Six months later, "you" are a stack of lossy summaries — and when the model gets you wrong, you can't even audit why, because the original evidence is gone.
And the retrieval underneath is similarity. Here's the part most memory products don't say out loud:
Recall is not similarity. When you complain "this game feels like trash, the hits have no weight," a human who knows you thinks: he once said his benchmark for game feel was Red Dead Redemption 2, and The Witcher 3 lost to it. Zero words overlap between the complaint and that memory — a similarity score gives it zero, and the memory you need most is invisible. Human recall is directional and associative: you think of a thing's opposite, its reason, the same mental core one abstraction up. That is not what a vector database computes.
Personal Understanding fixes both halves:
Save the exact words first. Recall by evidence chains and graph spread, not similarity. Prove every path.
Every personal message is captured verbatim and immutably (SHA-256 hashed, timestamped, session-tagged) before anything else happens. Structured understanding is built on top of the evidence, every derived fact linking back to the quote it came from. And recall runs through a measured three-layer stack that can surface records with zero lexical overlap — with the association path shown, so the model can judge it instead of trusting a bare score. When the agent misremembers you, you audit it. When it doesn't know, it says so.
Related MCP server: midas-memory-mcp
Typical memory tools | Personal Understanding | |
What gets stored first | the model's summary | your exact words — immutable, hashed |
Recall model | similarity over summaries | three-channel lexical + associative graph spread, evidence path visible |
Derived facts traceable to source | rarely | ✓ every record links back to its verbatim |
Model guesses marked as guesses | no | ✓ hypothesis layer, |
Old lossy summaries | silently reused | ✓ flagged as summary debt — retrieval discloses "this part comes from an old summary" |
Says "saved" when the save failed | happens | ✗ impossible — a hard gate ( |
Invented dates, merged people, fake causal edges | possible | ✗ forbidden by written policy and enforced by validators |
Runtime | server + vector DB + embeddings | one folder, Python stdlib only |
Where your data lives | often their cloud | your machine. Full stop. |
Newer agents ship with "memory" now — if that's enough for you, use it. This project exists for the people who hit its walls:
Built-in agent memory | Personal Understanding | |
Data ownership | locked in the vendor's account, rarely exportable, gone when you switch tools | a plain-text folder on your machine — read it, grep it, back it up, move it |
Portability | memory only works inside that product | one archive, any MCP client — Claude, Codex, ZCode, VS Code, whatever comes next |
Auditability | black box — you can't see what got stored, or why it answered that way | every derived fact links back to the exact quote; the retrieval trace shows why each record surfaced, and what was deliberately held back |
Retrieval | fuzzy summary recall | three-channel + associative recall that bottoms out in your original words |
Privacy | your personal history on their servers | local only — no telemetry, no cloud calls |
Vendor memory optimizes for a smoother conversation inside their product. This project optimizes for a memory you own, that moves with you across tools, and that can prove where every fact came from. Different products — vendor memory getting better doesn't make this one redundant.
Most memory READMEs stop at "we use embeddings." Here is the whole stack, because the mechanics are the product.
Layer 0 — self-trained lexicon (query hygiene). Every query is tokenized against a vendored dictionary (jieba, MIT) plus a lexicon the archive trains on itself: any 2–4 char string occurring in ≥2 archive texts becomes a word, so proper nouns no general dictionary knows (弦一郎, 艾迪芬奇, 晕3D) are recognized automatically. Out-of-vocabulary slices keep their recall but are weight-capped so cross-word accidents (郎我) can no longer out-anchor real terms. Measured root cause this fixed: the query 巫师3 splits into 巫师 + 3, and a stray 3 matches dates inside record IDs — it once handed a driver's-license record the top slot for a Witcher query.
Layer 1 — three-channel lexical recall. Timeline events, fact/model cards, and entity cards are scored separately (IDF-weighted, length-normalized, anchor-demoted) instead of one blended soup — a complaint about game feel reaches the fact card even when no event matches. Every probe records a decision trace: what was selected, what was held back and why.
Layer 2 — associative spread (the recall humans do). Entities and concept cards (game-feel, money-and-guilt, body-limits, reading-taste …) form a graph. A personalized PageRank spread — local, hub-capped so popular nodes can't dress popularity up as association — surfaces records the query shares zero words with, each with its via path visible:
"this game's hits feel like paper" → concept: gameplay-feel → the Witcher-3-vs-RDR2 feel-anchoring record (no shared word — exactly the recall a friend would do)
"book drought, recommend something" → concept: reading-taste → your reading history and taste anchor
"recommend me a game" → concept: narrative-games → the hard rule that 3D-sickness is a body-level exclusion — the opposite side of the desire, one edge away
The stack is scored on a 16-round simulated-usage matrix (real user-tone queries across 8 life domains, model-graded); every release re-runs it. Zero expected-recall regressions through 2.6.0, while the two "all-channels-missed" cases above went from nothing to surfaced.
Why not embeddings? They're the right tool at archive scale, and the design leaves a slot for them. But at personal-archive scale the measured failures are lexical and structural, not semantic — and a similarity score is unauditable by nature: it returns a number, never a path. Here, when a memory surfaces, why it surfaced is always shown.
Without Personal Understanding — a typical memory implementation:
You: I finally played my first full song on guitar today. Three weeks until I perform it at my cousin's wedding — honestly less nervous than before. AI: That's awesome, congrats! 🎸 Keep it up!
What got stored:
"user played guitar, feeling positive."A lossy summary. No source, no date, no people, no way to check it. Next month it's gone — or worse, silently paraphrased into something you never said.
With Personal Understanding — the same message:
You: I finally played my first full song on guitar today. Three weeks until I perform it at my cousin's wedding — honestly less nervous than before. AI: (first: captures your complete message verbatim — SHA-256-hashed, timestamped, session-tagged — before anything else) (then: derives and links —
event"first full song on guitar" · saliencesupporting· linked toSaraand the wedding goal · updates your current state: performance anxiety ↓) AI: First full song is a real milestone. Last time, performing at the wedding made you nervous — how does it feel now that it's three weeks out?Every claim traces back to your exact words. Ask "where does that come from?" and the agent shows you the original quote — not a paraphrase of a paraphrase. And when it's the wedding week, the archive checks in by itself.
🗣️ Verbatim-first capture — the complete message, word for word, before any summarizing, splitting, or interpreting. Corrections add new captures; nothing is ever silently overwritten.
🔁 Derivation closure — a successful capture is not a finished update. Every capture must be split into records, linked, and closed — or explicitly closed as "nothing new" with a stated reason. Orphans can't slip through.
🧠 Human-like progressive recall — survey (compact routing map) → probe (fan out along entities, concept cards, and time neighbors) → deep (verify the exact quote). No vector dumps, no keyword-only search.
🕸️ Associative recall with visible paths — zero-overlap memories surface through a concept-card graph with the association path attached; the model judges the link, nothing arrives as an unexplained score.
📻 Cold recall ladder — for "I forget, we talked about something like this…" moments: probe from any hint, walk time neighbors, then browse a time window like flipping through an old photo album.
🔬 Causal hypothesis layer — "why am I like this?" gets a structured answer: claim, mechanism, supports, counterexamples, competing explanations, scope, confidence — always candidate, never presented as fact.
⏰ Proactive follow-ups — "let's see in a few days" becomes a tracked loop. When it's due, the agent checks back with the original context, not a context-free nag.
🚦 Hard gates, not vibes — three-state validation (clean / warnings / failed), atomic writes everywhere, session_check as a non-zero-exit gate before any "the archive is updated" claim. Reads that cannot corrupt the archive have an audited degraded path; writes never do.
📉 Summary debt accounting — legacy material that lost its source is labeled, counted, and disclosed in retrieval. It can never impersonate verbatim.
📊 Pipeline timeline & audit dashboard — replay one turn's whole life (gating decision → capture → closure → every retrieval query, association, and held-back candidate) as a single read-only page, or browse the full dashboard.
🔌 Drop-in for your client — an idempotent installer auto-detects and registers a local MCP server across Claude clients, Codex, VS Code / Cursor / Windsurf / Cline / Trae, ZCode, and generic .agents configs.
💾 Backups with integrity — SHA-256-manifested snapshots, mirror-to-second-location support (any rclone remote), and a quarterly salience review that gracefully demotes stale imported weights instead of letting them fossilize.
flowchart LR
A["user message"] --> B{"turn preflight<br/>(router)"}
B -->|"personal content"| C["immutable verbatim capture<br/>+ SHA-256 · session · source"]
C --> D["derivation ledger<br/>(pending)"]
D --> E["derive: events · entities · concept cards<br/>context cards · hypotheses · follow-ups"]
E --> F["finalize:<br/>derived / nothing-new"]
B --> G["probe: lexicon-hygiened query"]
G --> H["three-channel lexical recall<br/>timeline · cards · entities"]
G --> I["associative spread (PPR)<br/>zero-overlap candidates + via path"]
H --> J["deep = verbatim only<br/>(summary debt disclosed)"]
F --> K["session_check<br/>hard gate · must exit 0"]
I --> K
J --> K
K --> L["answer"]
L --> M["feedback loop<br/>helpful / missed / corrected"]
M -.->|quarterly| N["salience review<br/>+ deep semantic review"]On disk it's plain files you can read, grep, and back up: sources/conversation/ (immutable verbatim + hashes) and memory/v2/ (fragments, timeline, entities, concept cards, contexts, follow-ups, hypotheses, decision traces) — with legacy records kept as a compatibility layer and honestly marked summary_only.
# 1. clone into your client's skills directory
git clone https://github.com/caix84476-netizen/personal-understanding.git \
~/.claude/skills/personal-understanding # or ~/.codex/skills/ , or your client's equivalent
# 2. bootstrap the archive skeleton (directories + generic domain branches; idempotent)
python scripts/init_archive.py
# 3. register the local MCP server (auto-detects clients; idempotent)
python scripts/install_mcp.py --auto # Windows: just double-click register-mcp.cmd
# 4. restart your client session — the personal_* tools go live
# 5. open the audit dashboard / replay any turn's pipeline any time
python scripts/open_dashboard.py # Windows: double-click open-dashboard.cmd
python scripts/pipeline_view.py --latest 5Requirements: Python 3.10+ · stdlib only, zero pip installs · Windows / macOS / Linux.
Prefer pip? The MCP server + installer are also on PyPI: pip install personal-understanding, then personal-understanding-install to register the local MCP server. The pip package ships the Python side only — for the full skill brain (SKILL.md + dashboard), use the clone steps above. As of 2.2.1 the wheel is no longer a stale snapshot — every packaged file is byte-identical to the source tree, re-verified on every release. One caveat remains: personal-understanding-install registers the server but does not bootstrap an archive root, so start from scratch with python -m personal_understanding.init_archive. The clone steps above remain the recommended path for the full skill.
Then just talk normally: "I've been feeling…", "remember that…", "why do I keep…" — the skill's description triggers on personal content, captures your words, and takes over from there. Ask "what do you remember about…", or "where does that come from?" and follow the evidence chain.
Everything is processed locally, in the skill folder. No telemetry, no cloud calls, no embeddings shipped to third parties.
The shipped .gitignore blocks memory/, sources/, and backups/ — so you can version-control your skill folder and never commit your private archive by accident.
Sensitivity labels (private / highly-private) control relevance, not secrecy-from-you: unrelated questions never leak unrelated private material.
These are written policy, enforced by validators — not aspirations:
Verbatim fidelity first — no summary ever poses as the user's words; summary_only is marked as such forever.
Recall must be auditable — similarity alone never decides; associative candidates carry their graph path, and every probe logs what was selected and what was deliberately held back.
No fabricated certainty — uncertain dates stay uncertain; vague pronouns don't become people; single events never become causes; association edges are declared semantics, never invented for a prettier graph.
Newer words outrank older archives — corrections build supersedes / contradicts chains; nothing is silently erased.
One salience axis — pivotal / key / supporting / passing on a single 0–3 scale; imported weights admit they're heuristics.
Silence is not feedback — only explicit corrections and confirmations, with quotable evidence, feed the feedback loop.
Structure clean ≠ semantically correct — deep review exists precisely because validators can't catch meaning.
Not a framework thought up in one afternoon — a working archive refined through daily use and a dozen hardening rounds (see the CHANGELOG): a salience-decay bug that once shredded frontmatter is why all writes are now atomic and reviewed; survey used to load ~818 KB of legacy catalog per turn — it's a ~90 KB routing map now (~230 ms); the associative layer exists because its author kept hitting the wall that "recall is not similarity" — the 2.6.0 changelog documents the measured root causes, the designs tried and rejected, and the regression that proved deletion was wrong before demotion was chosen.
Current release: v2.6.1 — generalization-audit release: associative-channel projection fixes, lexical recency (half-life 180d, undated-neutral), knowledge-update demotion for superseded facts, classifier first-person-affect fix; two-tier invocation with footprint discipline; schema stable (memory/v2/ v2.0.0); actively maintained. Also on PyPI.
Works with any MCP-capable client. The skill brain (SKILL.md) is written in Chinese and works with archives in any language; retrieval is tuned for mixed Chinese/Latin text and degrades gracefully elsewhere.
Roadmap: editable dashboard pages, richer cold-recall ranking, optional vector side-channel for very large archives (pluggable by design), optional encrypted archive-at-rest.
Issues and PRs welcome — especially: new client installers for install_mcp.py, dashboard improvements, and evaluation matrices for languages beyond Chinese.
MIT © 2026 caix84476-netizen
If Personal Understanding saves you from re-explaining yourself to your AI for the nth time, a star ⭐ helps others find it.
记录一次依赖个人记忆的回答的效果：用了哪些记忆、用户反应说明 helpful/missed/corrected。不需要用户正式打分。
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| outcome | Yes | ||
| capture_id | No | ||
| memory_ids | No | ||
| feedback_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that feedback is informal and inferred from user reaction rather than formal scoring, and it names the outcome categories. However, it does not state whether this creates or updates a record, how identifiers should be supplied, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact sentence that front-loads the purpose and ends with a clarifying exclusion. Every part earns its place; no redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, 0% schema coverage, no annotations, and no output schema, the description is not sufficient for correct invocation. It lacks details on feedback_id and capture_id provenance and on how the record is stored or returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning for outcome and memory_ids ('用了哪些记忆'), but it leaves the required feedback_id unexplained and does not clarify note or capture_id. An agent cannot reliably know what values to provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool records the effect of an answer that relied on personal memory, listing what is recorded (used memories and user reaction) and the outcome categories. This is specific and distinguishes it from sibling tools like personal_add_record or personal_add_followup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: use after a memory-dependent answer when the user's reaction indicates helpful, missed, or corrected. It also explicitly excludes formal rating/scoring. It doesn't name alternative siblings, but the intended scenario is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
登记有上下文的待回访问题；到期后由个人理解 Skill 主动检查。
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| due_at | No | ||
| prompt | Yes | ||
| context | Yes | ||
| due_rule | No | ||
| priority | No | normal | |
| source_refs | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It does reveal that the tool registers follow-ups with context and that due items are later checked by a Personal Understanding Skill, which is useful. It does not describe mutation effects, duplicate handling, idempotency, or what happens when due_at is null, but the core persistence-and-check behavior is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. It states the action first and then the relevant follow-up behavior, making it easy for an agent to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a seven-parameter write operation with no annotations, no output schema, and no parameter descriptions, this is under-specified. The agent would still need to infer the meaning of several parameters and operational details such as return behavior and due handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for seven undocumented parameters. It only alludes to context and due behavior; id, due_rule, priority, and source_refs remain semantically unexplained. One sentence is insufficient to replace absent parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly centers on registering a pending follow-up/revisit and adds the lifecycle behavior that it will be actively checked when due. This is specific enough to differentiate its core purpose, though it does not explicitly distinguish it from personal_add_record or other personal_* write tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase '登记有上下文的待回访问题' implies the tool is for storing context-carrying follow-ups rather than immediate actions, and the due-check behavior gives a signal about when it applies. However, it provides no explicit when-to-use versus alternatives such as personal_add_record or personal_add_feedback.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
登记候选因果解释；默认 candidate，不得冒充事实。
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| claim | Yes | ||
| scope | No | ||
| supports | No | ||
| mechanism | Yes | ||
| confidence | No | low | |
| contradicts | No | ||
| source_refs | No | ||
| alternatives | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It usefully discloses that items are stored as 'candidate' by default and must not be presented as facts. However, it does not mention persistence behavior, side effects, idempotency, validation, or what happens after creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short, front-loaded, and contains no filler. Both clauses earn their place, though for a 9-parameter tool with no parameter documentation, the terseness leaves out important detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the absence of annotations and output schema, and the presence of similar sibling tools, the description is not complete enough. It omits return behavior, required parameter guidance, relationship to other add tools, and any operational constraints beyond the candidate/fact distinction.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the 9 parameters, such as id, claim, mechanism, confidence, or source_refs. It only conveys the overall object type ('candidate causal explanation'), so an agent gets little help with parameter-level semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: '登记候选因果解释' (register candidate causal explanation). It also explicitly contrasts hypotheses with facts via '不得冒充事实', which differentiates this tool from fact-recording siblings like personal_add_record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates this tool is for candidate causal explanations and should not be used for established facts. It provides a clear when-to-use context, though it does not explicitly name alternative sibling tools or spell out when to choose them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
创建派生记录。若来源是当前用户补充，必须先有 verbatim capture，并把 verbatim_refs 写入记录。活动足迹类微型记录传 tier=light（salience 0-1），完整档记录不传或传 full；记录层 tier 仅表示记录形态，不再表示调用档位。
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| kind | Yes | ||
| tier | No | 记录形态：light=活动足迹微型记录（salience 0-1）；缺省/full=完整档记录。仅表示形态，不再表示调用档位 | |
| phase | No | ||
| domain | No | ||
| aliases | No | ||
| summary | Yes | ||
| date_end | No | ||
| salience | No | ||
| capture_id | No | ||
| confidence | No | high | |
| date_basis | No | ||
| valid_from | No | ||
| entity_refs | No | ||
| record_role | No | ||
| related_ids | No | ||
| sensitivity | No | ordinary | |
| source_refs | No | ||
| verbatim_refs | No | ||
| date_precision | No | ||
| last_confirmed | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses important behavioral traits: the dependency on prior verbatim capture, the requirement to write verbatim_refs, and the semantic shift for tier (now only represents record form, not API tier). This is substantial behavioral context for a create operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, with key information front-loaded about the derived-record purpose. The tier explanation is dense but necessary. It earns its place, though it could be slightly more structured for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 21-parameter create tool with no output schema and no annotations, the description covers the most critical preconditions (verbatim capture) and the ambiguous tier parameter. It doesn't explain all parameters, but the sibling tools and schema already provide structural context. The core call-critical constraints are well covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 5%, so description must compensate. The description explains the critical tier parameter semantics ('记录层 tier 仅表示记录形态，不再表示调用档位') and the verbatim_refs requirement, which are not self-evident from the schema. It also clarifies the salience range for light tier. This meaningfully adds value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('创建派生记录' - create derived record) and resource, and differentiates it from capture tools by stating it creates derived records. However, it doesn't explicitly distinguish itself from sibling tools like personal_add_followup or personal_add_hypothesis, so it's clear but lacks sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it must be used after a verbatim capture when the source is user-supplied, and specifies when to use tier=light vs full. However, it doesn't explicitly state when NOT to use this tool or name alternatives, leaving some room for inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
绑定已判定为个人材料的 turn receipt，原样保存完整用户消息。没有 preflight 或 preflight 判为非个人时拒绝写入；捕获后仍必须派生并 finalize。
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | ||
| turn_id | Yes | ||
| capture_id | Yes | ||
| captured_at | No | ||
| message_kind | No | ||
| conversation_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the behavioral disclosure burden. It discloses that writes are conditional on a passing preflight and that the tool rejects writes otherwise, plus the post-capture requirement to derive and finalize. It does not cover return values or idempotency, but for a narrow capture tool the key behaviors are stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The core purpose is front-loaded, and every clause adds either a precondition, a behavior, or a follow-up requirement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given six parameters, no output schema, and no annotations, the description provides the essential workflow guards but leaves parameter semantics and return/error behavior to inference. It is sufficient for an agent familiar with the domain, but not fully self-contained for a generic caller.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it only loosely alludes to 'complete user message' (text) and 'turn receipt' (turn_id/capture_id). The optional parameters captured_at, message_kind, and conversation_id are entirely unexplained, leaving the agent to infer their meaning from names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: bind a pre-assessed personal turn receipt and save the full user message verbatim. It also clearly distinguishes the tool's role by referencing the preflight prerequisite and the required derive/finalize follow-up, placing it in an unambiguous pipeline.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-not-to-use conditions: if there is no preflight or preflight marks the turn non-personal, writes are refused. It also states that after capture, derivation and finalization are mandatory, effectively instructing the agent on the required next steps within the sibling toolset.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
读取 v2 全局勘察。常规交互读取必须先完成当前轮次 turn preflight capture 并提供 capture_id；足迹/攻略类消息被 capture 闸门拦下时，可用 maintenance=true 做只读降级读取（有 trace 审计，不写档案），随后按足迹纪律用 tier=full 重声明补 capture。
| Name | Required | Description | Default |
|---|---|---|---|
| view | No | survey | |
| query | No | ||
| capture_id | No | ||
| maintenance | No | 显式声明非交互只读（等价 CLI --maintenance）；不能代替 capture 完成写入闭环 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses meaningful behavioral traits: it respects a capture gate, requires capture_id for normal reads, and maintenance=true performs an audited read-only fallback that does not write archives. However, it doesn't describe the response format, data freshness, or side effects of the tier=full re-declaration, so it is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but compact, delivering key behavioral rules in two sentences. It front-loads the main purpose and then explains the exception path. Some may find it dense, but each clause carries operational meaning; missing a short hint about the view param's role.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and no output schema, the description covers operational preconditions, the fallback path, audit implications, and the post-read discipline, which is strong for a read tool. It doesn't explain the difference between view enum options or return format, but for a survey read operation the critical workflow context is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (25%), and the description adds significant parameter semantics: it explains the capture_id precondition, the maintenance=true fallback's purpose, side effects (trace audit, no archive writing), and the requirement to later re-declare with tier=full. It does not explicitly explain the view enum values, but it contextualizes the key parameters well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the verb (读取/read) and the central resource (v2 全局勘察/global survey), distinguishing it as the read tool for the v2 global survey. It doesn't explicitly distinguish from siblings like personal_retrieve or personal_derivation_status, so it is clear about what it reads but not fully differentiated from all siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage conditions: regular reads must first complete turn preflight capture and provide capture_id, and when footprint/strategy messages are blocked by the capture gate, maintenance=true can be used for read-only fallback. It implies when not to use it (when writing is needed, use capture/add_record), but doesn't name specific alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
读取 capture→records 闭环状态，检查 pending、孤立捕获和链接漂移。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It conveys read-only intent via '读取' and names the checks it performs, which is useful. But it does not explicitly state that the call is side-effect-free or describe what kind of result the agent should expect beyond the named status categories.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise, front-loaded sentence with no filler. The action, object, and specific checks all fit in a compact line.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only status tool with no output schema, the description covers what the tool does and what it checks, which is sufficient to call it correctly. It could be slightly more explicit about return shape or prerequisites, but the low complexity makes that gap minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no parameter documentation burden. The description adds value by naming the dimensions ('pending, orphaned captures, link drift') that the no-arg call will report on, going beyond the empty input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action ('读取', read) and a clear resource ('capture→records 闭环状态'), then lists the exact conditions checked: pending, orphaned captures, and link drift. This distinguishes it from sibling write/capture tools, which perform mutations rather than status inspection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended usage is implied: call this tool to inspect the capture-to-records closure status and detect pending/orphaned/link-drift issues. However, the description does not explicitly say when to prefer it over alternatives like personal_validate or personal_session_check, nor does it provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
关闭当前原话捕获的派生闭环。derived 必须已有至少一条双向链接记录；无需派生时必须写具体原因（零新增收场须写明定向查重命中的既有记录）。回答前必须调用。
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | ||
| capture_id | Yes | ||
| disposition | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does disclose important behavioral constraints: the precondition on linked records and the requirement to write a concrete reason, including citing the deduplication hit for zero additions. It does not disclose side effects, reversibility, or return/error behavior, so it remains incomplete for a finalizing mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences carry the action, prerequisites, conditional requirements, and the call-time rule with no filler. The most actionable instruction ('must call before answering') is placed at the end but all content earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter finalization tool with no output schema and no annotations, the description covers the required inputs, the enum branches, the conditional reason, and the sequencing rule. It is missing post-condition/effect details and a definition of 'bidirectional link record', but the provided instructions are sufficient for correct invocation in most cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the meaning of disposition by tying derived to the bidirectional-link precondition and no-derivation-needed to a specific written reason, and it spells out what the reason must contain in the zero-add case. capture_id is only implied as 'current', which is the main gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('close'/'finalize') on a specific resource ('current raw-quote capture derivation loop'), which is enough to distinguish it from sibling tools like add_record or validate. It loses a point because 'current' and 'derived loop' rely on context and no explicit contrast with sibling tools is given.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states explicitly that the tool must be called before answering, and gives the precondition for derived (at least one bidirectional link) and the mandatory content for no-derivation-needed. It does not name alternative tools or when not to call, but the operational trigger is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
当前用户消息的强制内容预检。它持久化 turn receipt；个人经历、感受、关系、偏好、决定即使请求形式是润色/总结/看图，也会要求 capture。两档调用（2.4.0 起）：内容含个人材料或活动足迹类轮次（如'正在玩某游戏'）走完整档（tier=full/auto），足迹轮次受足迹纪律（写入前定向查重、恰好一条微型记录、零新增可 no-derivation 收场）；纯技术/吃喝/购物等明显无关或零增值轮次不调用本工具（跳过档）。tier=light 已废弃，传入按 full 处理。
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | ||
| tier | No | 模型显式声明档位；auto=纯内容分类，skip=强制跳过，full=完整档兜底（含活动足迹轮次）；light 已废弃按 full 处理 | |
| turn_id | No | ||
| conversation_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden, and it does substantial work: it discloses a persistent side effect (turn receipt), capture expectations, footprint discipline (pre-write dedup, exactly one micro record, zero-new no-derivation), and deprecated-tier handling. It stops short of describing return values, errors, or downstream effects of invoking skip/full, so it is strong but not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but purposeful, front-loading the core purpose before tier rules. Some long clause chains make parsing harder, but every sentence contributes policy or behavioral detail, and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no annotations and no output schema, and the domain is policy-heavy, so the description must do more. It thoroughly covers tier selection and capture discipline, but it omits the role of turn_id/conversation_id, what the tool returns, and what the agent should do after a full/skip result. An agent could select the tier but not confidently construct a complete invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 25%; only tier is documented there. The description richly explains tier semantics and implies text is the current user message, but it never clarifies turn_id or conversation_id. Since those two parameters are undocumented in both schema and description, the low coverage gap is only partially compensated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a mandatory content preflight for the current user message and states that it persists a turn receipt while requiring capture of personal materials. This is a specific verb+resource pairing that distinguishes it from sibling capture/retrieve tools, though it never explicitly names or compares itself to siblings like personal_capture_user_turn or personal_finalize_capture.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-call and when-not-to-call rules: full/auto for personal or activity-footprint turns, skip for technical/eating/shopping/zero-value turns, and light treated as deprecated. It does not name alternative tools, but for a gate/preflight tool the call/skip decision itself is the main usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
关闭一条回访（answered 回访完成 / declined 用户不再跟进 / resolved 回路以其他方式关闭，含方案被取代或过时）；note 必填且须具体。可选 capture_id 把本轮用户回答的原话 capture 绑到回访上（须已存在于 ledger）。
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| note | Yes | ||
| capture_id | No | ||
| resolution | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It discloses the closure action, requires a specific note, and states the ledger-existence precondition for capture_id, but it does not mention side effects, reversibility, permissions, or what happens after closure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence packs the operation, enum meanings, field requirements, and an optional binding rule without filler. It is efficient and front-loaded, though slightly dense due to multiple clauses packed together.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Input semantics are well covered, including required fields and preconditions. However, with no output schema and no annotations, the description omits return behavior and broader operational consequences, which is a noticeable gap for a state-changing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it largely does: it defines the resolution enum semantics, clarifies that note must be specific, and explains capture_id binds an existing ledger capture. Only the id parameter is left unexplained, which is acceptable given its obvious role.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb and resource: '关闭一条回访' (close a follow-up), and explains the distinct meanings of the three resolution values: answered, declined, and resolved. This clearly separates the tool from siblings like personal_add_followup and personal_finalize_capture.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit conditions for each resolution choice ('answered 回访完成 / declined 用户不再跟进 / resolved ...'), so an agent knows which resolution to select in which scenario. It does not explicitly name sibling alternatives or say when not to use the tool, so it falls just 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.
按 v2 事件、实体和情境卡读取 probe/deep。必须先完成当前轮次 turn preflight capture，并提供 capture_id；否则拒绝读取。
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | ||
| level | No | probe | |
| query | No | ||
| capture_id | No | ||
| maintenance | No | 显式声明非交互只读（等价 CLI --maintenance）；足迹/攻略类消息 capture 被拦时的只读降级通道，有 trace 审计 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses a critical non-obvious behavior: the tool refuses to read unless the current turn preflight capture is completed and capture_id is provided. It does not describe return values or other failure modes, but the key enforcement behavior is clearly surfaced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two compact sentences with no filler. The main purpose is front-loaded, and the prerequisite/refusal behavior follows immediately, making the critical information easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter tool with no output schema and no annotations, this description is incomplete. It captures the main precondition but leaves most parameter semantics, result shape, and relationship to the many sibling tools unaddressed, so an agent would still struggle to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20%, so the description must compensate for underdocumented parameters. It only gives meaningful context for capture_id; ids, query, and level remain effectively unexplained beyond their schema types/enums/defaults, leaving the agent unable to construct well-formed calls.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('读取' / read) and the resource ('probe/deep'), and scopes the access by v2 events, entities, and scenario cards. It does not explicitly differentiate from sibling tools, but the phrasing makes its role as a retrieval step after preflight distinct enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: retrieval requires the current turn's preflight capture and a valid capture_id, otherwise the tool refuses. It lacks explicit when-not-to-use guidance or named alternatives, so it is one step below full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
回答或声称档案已更新前的硬闸门：turn receipt + capture 闭环 + 结构 + v2 完整性。个人 turn 必须传 turn_id，缺 capture 或 finalize 会失败。
| Name | Required | Description | Default |
|---|---|---|---|
| turn_id | No | ||
| allow_warnings | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does reveal meaningful behavior: it is a blocking gate, and missing capture or finalize causes failure. It also enumerates what is checked. However, it does not disclose whether the tool is read-only, what warnings mean, whether allow_warnings can bypass failures, or what the response shape looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loads the purpose before listing the main failure condition. The dense jargon ('closed loop', 'v2 completeness') slightly hurts comprehensibility, but the structure is efficient and every clause adds information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter check with no annotations and no output schema, the description is too thin. It omits allow_warnings semantics, response/error behavior, and any routing guidance against sibling validation tools. An agent would need to infer several important details before calling it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains that turn_id is required for personal turns, but it says nothing about allow_warnings, its default, its effect, or the format/expected values of turn_id. Half the parameter surface is effectively undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a hard pre-answer gate and lists the dimensions it checks: turn receipt, capture closed loop, structure, and v2 completeness. This goes beyond the bare name and distinguishes it from capture/finalize operations. However, 'v2 completeness' is left unexplained and no explicit verb such as 'validate' or 'check' appears.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit use window: run this before answering or claiming the profile has been updated. It also states a hard requirement for personal turns: turn_id must be supplied. It does not mention when not to use it or how it compares with siblings like personal_preflight_turn or personal_validate, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
校验 v2 结构，并明确区分失败、警告和干净。默认强制要求所有 capture 已完成派生闭环。只读。
| Name | Required | Description | Default |
|---|---|---|---|
| strict | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well: it discloses that the operation is read-only, that it distinguishes failure/warning/clean, and that by default all captures must have completed derivation closure. This goes beyond a generic 'validate' statement and gives an agent useful behavioral expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with purpose, and every sentence adds distinct value: validation scope, result categories, default behavior, and read-only safety. There is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately covers the tool's purpose, output categories, default behavior, and read-only nature. However, given that the only parameter 'strict' is entirely undocumented in both schema and description, the definition is not fully complete for an agent to invoke it with full confidence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one boolean parameter, 'strict', with no description and 0% schema description coverage. The description does not explain what 'strict' does or how it interacts with the default derivation-closure requirement, leaving the agent to guess whether setting strict to true relaxes or tightens validation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('校验' / validate) and a clear resource ('v2 结构' / v2 structure), and it clarifies the output categories of failure, warning, and clean. It does not explicitly differentiate from siblings by name, but the validate action is distinct enough among the listed siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys that this tool is for validating the v2 structure and implies it should be used when such validation is needed. However, it does not explicitly state when to use this over siblings, nor does it provide exclusions or alternative tool guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.6.0personal_add_record1 field changedInput schema / properties / tierAdded value: +{
+ "description": "记录形态：light=活动足迹微型记录（salience 0-1）；缺省/full=完整档记录。仅表示形态，不再表示调用档位",
+ "enum": [
+ "full",
+ "light"
+ ],
+ "type": "string"
+}personal_catalog2 fields changedInput schema / properties / maintenanceAdded value: +{
+ "default": false,
+ "description": "显式声明非交互只读（等价 CLI --maintenance）；不能代替 capture 完成写入闭环",
+ "type": "boolean"
+}Input schema / requiredPrevious value: -[
- "capture_id"
-]New value: +[]personal_preflight_turn1 field changedInput schema / properties / tierAdded value: +{
+ "description": "模型显式声明档位；auto=纯内容分类，skip=强制跳过，full=完整档兜底（含活动足迹轮次）；light 已废弃按 full 处理",
+ "enum": [
+ "auto",
+ "full",
+ "light",
+ "skip"
+ ],
+ "type": "string"
+}personal_resolve_followuppersonal_retrieve2 fields changedInput schema / properties / maintenanceAdded value: +{
+ "default": false,
+ "description": "显式声明非交互只读（等价 CLI --maintenance）；足迹/攻略类消息 capture 被拦时的只读降级通道，有 trace 审计",
+ "type": "boolean"
+}Input schema / requiredPrevious value: -[
- "capture_id"
-]New value: +[]v0.1.0personal_add_feedbackpersonal_add_followuppersonal_add_hypothesispersonal_add_recordpersonal_capture_user_turnpersonal_catalogpersonal_derivation_statuspersonal_finalize_capturepersonal_preflight_turnpersonal_retrievepersonal_session_checkpersonal_validateScored across 13 tools
The tools form a clear pipeline (preflight → capture → derive → finalize → retrieve), but the check-like family (preflight_turn, derivation_status, validate, session_check) has fuzzy boundaries that require careful reading of each dense description. Catalog vs retrieve is also a subtle distinction (global survey vs targeted retrieval). The descriptions contain enough context to disambiguate if read fully, but an agent could easily misselect among the gate/validation tools.
All tools share the personal_ prefix and 8 of 13 follow the verb_noun pattern (add_record, resolve_followup, capture_user_turn, finalize_capture). The bare verbs (retrieve, validate), noun commands (catalog), and noun-noun compounds (derivation_status, session_check) are minor deviations that remain readable and predictable within the overall imperative style.
13 tools is on the higher end of well-scoped but each maps to a distinct stage of the capture-derive-finalize-retrieve workflow, plus follow-ups, hypotheses, and feedback. The pipeline ceremony (6 capture/check tools) could potentially be consolidated, making the count feel slightly padded rather than bloated.
The capture→derive→finalize→retrieve pipeline is fully covered, and follow-ups have both add and resolve operations. However, there is no tool to update or delete a personal record (correcting a wrong memory is essential for personal memory), and hypotheses can be added but never confirmed or retired, leaving notable lifecycle gaps in the core domain.
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Person-owned AI memory that learns, not just stores — portable context for any MCP client.
Persistent, verbatim, searchable memory for AI assistants — one memory across every MCP client.
