Enables Claude to read, write, and manage notes in an Obsidian vault, supporting capture of thoughts, promotion to structured notes with wikilinks, knowledge graph analysis, topic management, and reflection on knowledge landscape and interest drift.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@vault-mcp reflect on how my views on climate changed"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A personal knowledge vault MCP server for Claude Desktop — capture thoughts, connect ideas, and reflect on how your thinking is changing, all through natural conversation.
A vault is more than a folder of notes — it's a mirror of how you think. vault_reflect turns that mirror into something you can look at.
Snapshot · what your mind looks like today | Drift · how it changed over the year |
|
|
Tag bubbles + monthly capture volume | Stacked tag-velocity stream over time |
https://github.com/user-attachments/assets/0ef205a4-0ffc-4a24-a92a-b4acf66377fe
Related MCP server: Claude RAG MCP Pipeline
Most note-taking tools stop at storage. vault-mcp is built around a three-layer vision:
L1 · Capture — frictionless save from any conversation, with auto-tagging and slug generation.
L2 · Connect — promote raw captures into structured notes with auto-wikilinks, build a knowledge graph, find orphans and bridges.
L3 · Reflect — visualize your knowledge landscape, surface interest drift, and discover blind spots over time.
The goal isn't to replace Obsidian. It's to give Claude the hands and eyes to work inside your vault.
flowchart LR
Chat(["💬 Chat with Claude"]) -->|vault_capture| Cap[("📥 captures/")]
Cap -->|vault_promote| Notes[("📝 notes/")]
Notes -->|vault_analyze| Graph["🕸️ knowledge graph"]
Notes -->|vault_topic| Topics[("🗺️ topics/ · MOC")]
Cap -.->|vault_reflect| Mirror["🪞 snapshot · drift · blindspots"]
Notes -.->|vault_reflect| Mirror
Graph -.->|vault_reflect| Mirror
classDef store fill:#eef2ff,stroke:#4c8bf5,color:#1e3a8a
classDef view fill:#f0fdf4,stroke:#16a34a,color:#14532d
classDef chat fill:#fef3c7,stroke:#d97706,color:#7c2d12
class Cap,Notes,Topics store
class Graph,Mirror view
class Chat chatEach tool plays a distinct role: vault_capture lands raw thoughts, vault_promote refines them into notes, vault_analyze & vault_topic weave them together, and vault_reflect lets you step back and see the whole picture.
The lightest way to run vault-mcp. No Docker, no manual venv — just uv and one config change.
Step 1. Install uv (if you don't have it):
curl -LsSf https://astral.sh/uv/install.sh | shStep 2. Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"vault": {
"command": "uvx",
"args": ["obsidian-in-a-vat-mcp"],
"env": {
"VAULT_LOCAL_PATH": "/Users/yourname/my-vault"
}
}
}
}Replace /Users/yourname/my-vault with the absolute path to your local vault directory.
Step 3. Fully quit and reopen Claude Desktop. The vault tools will appear automatically.
Don't have a vault yet? Just point
VAULT_LOCAL_PATHto an empty directory. On first use, ask Claude to "initialize my vault" — it will set up the full directory structure automatically.Already have an Obsidian vault? Point
VAULT_LOCAL_PATHto your existing vault and ask Claude to "initialize my vault". It will scan your notes, classify them (captures vs. notes), and migrate everything into the vault-mcp format. Originals are safely archived under_archive/.
{
"mcpServers": {
"vault": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-v", "/Users/yourname/my-vault:/vault",
"ghcr.io/oliverxuzy-ai/obsidian-in-a-vat:latest"
]
}
}
}Requires Docker Desktop running in the background.
Update to latest: docker pull ghcr.io/oliverxuzy-ai/obsidian-in-a-vat:latest
To run from a local checkout (changes take effect after restarting Claude Desktop):
{
"mcpServers": {
"vault": {
"command": "uv",
"args": [
"run",
"--directory",
"/absolute/path/to/obsidian-in-a-vat",
"vault-mcp"
],
"env": {
"VAULT_LOCAL_PATH": "/Users/yourname/my-vault"
}
}
}
}Switch back to the published version by changing command to "uvx" and args to ["obsidian-in-a-vat-mcp"].
Tools are grouped by the three layers of the vision.
Tool | Actions | Description |
|
| One-click vault initialization: seed empty vaults from template, or migrate existing Obsidian notes with server-side classification, todo conversion, and auto-archiving |
|
| Search vault, read files, list captures by status |
|
| Capture refined insights with auto-tagging, or delete captures |
Tool | Actions | Description |
|
| Promote captures into structured notes with auto-wikilinks |
|
| Knowledge graph: build graph, Louvain clustering, N-degree connections, orphan detection |
|
| Topic lifecycle: gather materials (progressive disclosure), create/update MOC-style topics |
Tool | Actions | Description |
|
| Cognitive visualization: knowledge landscape snapshot, interest drift over time, blind spot and bridge detection |
Tags are extracted from capture text using three sources, in priority order:
tags.yaml— Custom tags and synonym mappings at the vault rootExisting notes — Tags collected from existing vault files' frontmatter
Default domains — Fallback:
ai,llm,productivity,writing,coding,design,business,learning,health,finance,philosophy,psychology
Example tags.yaml in your vault root:
tags:
ai: [artificial intelligence, machine learning, ML, deep learning]
coding: [programming, software, development, code]
design: [UX, UI, user experience]# Run all tests
uv run pytest tests/ -v
# Build image locally
docker build -t vault-mcp .
# Test the container starts (Ctrl+C to stop)
echo '{}' | docker run -i --rm -v $(pwd)/example_vault:/vault vault-mcp
# Syntax check
python -m py_compile src/vault_mcp/server.py
# Interactive MCP Inspector
mcp dev src/vault_mcp/server.py个人知识库 MCP 服务器，适配 Claude Desktop —— 捕获想法、连接笔记、反思自己思维的变化，全部通过自然对话完成。
vault 不只是一个文件夹，而是你思维的一面镜子。vault_reflect 把这面镜子变成了你可以"看"的东西。
Snapshot · 当下你的思维长什么样 | Drift · 这一年它如何变化 |
|
|
标签气泡 + 月度 capture 柱状图 | 堆叠式 tag velocity 流图 |
大多数笔记工具止步于"存储"。vault-mcp 围绕三层愿景设计：
L1 · Capture — 任何对话中无摩擦地保存想法，自动打标签、生成 slug。
L2 · Connect — 把原始 capture 提升为结构化笔记，自动插入 wikilinks，构建知识图谱，发现孤岛和桥接。
L3 · Reflect — 可视化你的知识全景，呈现兴趣漂移，长期暴露盲区。
目标不是替代 Obsidian，而是让 Claude 拥有在你 vault 里"动手"和"看见"的能力。
flowchart LR
Chat(["💬 与 Claude 对话"]) -->|vault_capture| Cap[("📥 captures/")]
Cap -->|vault_promote| Notes[("📝 notes/")]
Notes -->|vault_analyze| Graph["🕸️ 知识图谱"]
Notes -->|vault_topic| Topics[("🗺️ topics/ · MOC")]
Cap -.->|vault_reflect| Mirror["🪞 snapshot · drift · blindspots"]
Notes -.->|vault_reflect| Mirror
Graph -.->|vault_reflect| Mirror
classDef store fill:#eef2ff,stroke:#4c8bf5,color:#1e3a8a
classDef view fill:#f0fdf4,stroke:#16a34a,color:#14532d
classDef chat fill:#fef3c7,stroke:#d97706,color:#7c2d12
class Cap,Notes,Topics store
class Graph,Mirror view
class Chat chat每个工具有清晰的分工：vault_capture 接住原始想法，vault_promote 把它们提炼成笔记，vault_analyze 和 vault_topic 把笔记编织起来，vault_reflect 让你后退一步看到全貌。
最轻量的运行方式。不需要 Docker，不需要手动创建虚拟环境 — 只需安装 uv 即可。
第一步. 安装 uv（如果还没有）：
curl -LsSf https://astral.sh/uv/install.sh | sh第二步. 添加到 Claude Desktop 配置文件（~/Library/Application Support/Claude/claude_desktop_config.json）：
{
"mcpServers": {
"vault": {
"command": "uvx",
"args": ["obsidian-in-a-vat-mcp"],
"env": {
"VAULT_LOCAL_PATH": "/Users/yourname/my-vault"
}
}
}
}将 /Users/yourname/my-vault 替换为你本地 vault 目录的绝对路径。
第三步. 完全退出并重新打开 Claude Desktop，vault 工具会自动出现。
还没有 vault？ 将
VAULT_LOCAL_PATH指向一个空目录即可。首次使用时让 Claude "初始化我的 vault" — 它会自动创建完整的目录结构。已有 Obsidian vault？ 将
VAULT_LOCAL_PATH指向你现有的 vault 目录，让 Claude "初始化我的 vault"。它会扫描你的笔记，自动分类（capture vs. note），并批量迁移为 vault-mcp 格式。原始文件安全归档到_archive/。
{
"mcpServers": {
"vault": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-v", "/Users/yourname/my-vault:/vault",
"ghcr.io/oliverxuzy-ai/obsidian-in-a-vat:latest"
]
}
}
}需要 Docker Desktop 在后台运行。
更新到最新版：docker pull ghcr.io/oliverxuzy-ai/obsidian-in-a-vat:latest
从本地代码运行（修改代码后重启 Claude Desktop 即可生效）：
{
"mcpServers": {
"vault": {
"command": "uv",
"args": [
"run",
"--directory",
"/绝对路径/obsidian-in-a-vat",
"vault-mcp"
],
"env": {
"VAULT_LOCAL_PATH": "/Users/yourname/my-vault"
}
}
}
}切回已发布版本：将 command 改为 "uvx"，args 改为 ["obsidian-in-a-vat-mcp"]。
按三层愿景分组。
工具 | Actions | 说明 |
|
| 一键初始化：空 vault 自动创建模板结构；已有 Obsidian vault 自动扫描分类、todo 转换、批量迁移，原始文件归档到 |
|
| 搜索 vault、读取文件、按状态列出 captures |
|
| 捕获精炼洞察并自动打标签，或删除 capture |
工具 | Actions | 说明 |
|
| 将 captures 提升为结构化笔记，自动插入 wikilinks |
|
| 知识图谱：构建图谱、Louvain 聚类、N 度关联查询、孤岛检测 |
|
| Topic 生命周期：收集原材料（渐进式披露）、创建/更新 MOC 结构笔记 |
工具 | Actions | 说明 |
|
| 认知可视化：知识全景快照、兴趣漂移分析、盲区与桥接发现 |
标签从 capture 文本中提取，使用三个来源（按优先级排序）：
tags.yaml— vault 根目录的自定义标签和同义词映射已有笔记 — 收集已有 vault 文件 frontmatter 中的标签进行匹配
默认领域 — 兜底列表：
ai,llm,productivity,writing,coding,design,business,learning,health,finance,philosophy,psychology
tags.yaml 示例（放在 vault 根目录）：
tags:
ai: [artificial intelligence, machine learning, ML, deep learning]
coding: [programming, software, development, code]
design: [UX, UI, user experience]# 运行所有测试
uv run pytest tests/ -v
# 本地构建镜像
docker build -t vault-mcp .
# 测试容器启动（Ctrl+C 停止）
echo '{}' | docker run -i --rm -v $(pwd)/example_vault:/vault vault-mcp
# 语法检查
python -m py_compile src/vault_mcp/server.py
# 使用 MCP Inspector 交互测试
mcp dev src/vault_mcp/server.pyAnalyze vault knowledge graph.
Actions: rebuild_graph: Build or incrementally update the knowledge graph from notes/ and topics/. Returns node/edge counts. clusters: Run Louvain community detection. Cached if graph unchanged. params: limit, offset connections: Subgraph around a note + common-neighbor recommendations. params: path (required), depth (default 1), limit (default 50) orphans: Notes with no inbound or outbound links. params: limit (default 50), offset (default 0)
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | ||
| depth | No | ||
| limit | No | ||
| action | Yes | ||
| offset | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true is present, and the description adds useful behavioral context beyond that: it mentions caching behavior for clusters ('Cached if graph unchanged') and notes that rebuild_graph returns node/edge counts. This is transparent without contradicting the read-only hint.
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 well-structured and concise, with a clear opening line and a bulleted list of actions. Each line provides actionable information without redundancy, making efficient use of space.
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 covers all actions and their parameters, which is helpful given the multiple sub-operations. However, it lacks explicit return value descriptions for clusters, connections, and orphans (though action names and phrasing imply outputs). This is a minor gap, especially since no output schema exists.
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%, but the description compensates by explaining the role of each parameter within each action (e.g., path is required for connections, depth defaults to 1, limit defaults to 50, offset for pagination). This adds semantic meaning beyond the bare schema names.
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 analyzes the vault knowledge graph and enumerates four specific analysis operations (rebuild_graph, clusters, connections, orphans). This specific verb+resource focus distinguishes it from sibling tools like vault_capture or vault_read, which serve different purposes.
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?
Usage context is implied by the action list and the tool's name, but the description does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions. The sibling names hint at other workflows, but no direct guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture a refined insight into the vault, or delete an existing capture.
Actions: save: Save a new capture. params: title (str, ≤50 chars), insight (str, 1–3 sentences), source_type (str, default "conversation" — also "article" or "flash"), original (str | None), tags (list[str] | None) delete: Permanently delete a capture file. params: path (str, required — must be in captures/)
WORKFLOW — Claude MUST follow these steps before calling this tool: For save:
REFINE: Distill the user's thought into a core insight (1–3 plain-text sentences). Generate a clean, descriptive plain-text title (≤50 chars).
CONFIRM: Present the refinement to the user and wait for approval. Refinement is lossy — only the user knows which version captures what they truly want to remember. Do NOT call this tool until the user explicitly confirms.
STORE: Call this tool with action="save" and the confirmed title, insight, and metadata.
For delete:
IDENTIFY: User specifies which capture to delete.
CONFIRM: Show the capture's title, preview, and path to the user. Deletion is PERMANENT — ask "确认删除？" and wait for explicit approval. Do NOT call this tool until the user confirms.
DELETE: Call this tool with action="delete" and path.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | ||
| tags | No | ||
| title | No | ||
| action | Yes | ||
| insight | No | ||
| original | No | ||
| source_type | No | conversation |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint=true, idempotentHint=false), the description adds critical behavioral details: deletion is permanent, refinement is lossy, and confirmation is mandatory. It also specifies that for delete, the user must be shown the title, preview, and path, and asks '确认删除？'. These are not mentioned in annotations and greatly enhance transparency.
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 lengthy but extremely well-structured with clear headings, action breakdowns, and a numbered workflow. Every sentence serves a purpose, and the structure aids comprehension. It could potentially be tightened slightly, but the detail is justified given the tool's complexity.
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 two actions, 7 parameters, confirmation requirements, and lack of output schema, the description is exceptionally complete. It covers all parameter details, explains the workflow, and provides safety warnings. Nothing essential is missing for an agent 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?
Despite the schema having 0% description coverage, the description fully compensates by documenting every parameter with constraints: title (≤50 chars), insight (1–3 sentences), source_type (default 'conversation' with alternatives), original (nullable), tags (list), and path (required, must be in captures/). This adds significant semantic meaning beyond the raw 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 clearly states the tool's dual function: 'Capture a refined insight into the vault, or delete an existing capture.' This is specific and distinguishes it from sibling tools like vault_read or vault_promote, which have different purposes.
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 an explicit workflow for both save and delete actions, including when to call the tool ('Do NOT call this tool until the user explicitly confirms'), and detailed steps for refinement and confirmation. It also clarifies the difference between save and delete usage, making it clear when each action is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Initialize a new vault or migrate existing Obsidian notes to vault-mcp format.
Actions: setup: Detect vault state and act accordingly. - Empty vault: seeds the vault with template structure (directory layout, .obsidian config, tags.yaml, templates/). - Non-empty vault with unmanaged files: scans all unmanaged .md files, classifies them into auto_captures / auto_notes / ambiguous using server-side heuristics, persists a plan to .brain/import-plan.json, and returns ONLY the ambiguous files for review. Claude should NOT call migrate until the user confirms. - Already-initialized vault: returns status "already_initialized".
migrate: Execute the migration from the persisted import plan. params: manual_overrides (list[dict], optional — each dict must have "path" key to identify the file; supported override fields: target ("captures"|"notes"), title, tags (list[str]), source_type (captures), domain/confidence (notes)), keep_original (bool, default False — if True, source files are preserved after migration)
WORKFLOW: For setup: CALL vault_init(action="setup"). Empty vault → vault seeded from template. Done. Non-empty vault → review summary + ambiguous_files. 1. Present summary counts to user. 2. For ambiguous files, decide target with user if needed. 3. CONFIRM full plan, then call migrate.
For migrate: CONFIRM: Show user the counts and ambiguous decisions before calling. auto-classified files will be migrated automatically. CALL vault_init(action="migrate", manual_overrides=[...], keep_original=False).
Todo conversion (applied automatically during migration):
pending task → - pending task (plain bullet)
done task → - done task (strikethrough, history preserved)
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| keep_original | No | ||
| manual_overrides | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fully discloses the tool's side effects beyond the annotations (destructiveHint=true, idempotentHint=false). It explains that setup may 'scans all unmanaged .md files, classifies them... persists a plan to .brain/import-plan.json', that migrate executes the plan, and that keep_original controls whether source files are preserved. The automatic todo conversion is also disclosed. No contradiction with annotations.
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 long but highly structured with clear 'Actions', 'WORKFLOW', and 'Todo conversion' sections. Every sentence adds necessary information for safe and correct usage of a complex tool. No fluff or redundant repetition of schema/annotations.
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 two-action complexity, absence of output schema, and the need to guide an agent through a multi-step migration process, the description is remarkably complete. It covers all states (empty, non-empty, already-initialized), the decision workflow, parameter details, and side effects, leaving no critical operational gaps.
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?
With 0% schema description coverage, the description carries the full burden of parameter meaning. It defines the allowed values for 'action' (setup/migrate), explains the 'manual_overrides' structure including required 'path' key and supported override fields (target, title, tags, etc.), and clarifies 'keep_original' with a default and consequence. This completely compensates for the empty 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 clearly states the tool's core purpose: 'Initialize a new vault or migrate existing Obsidian notes to vault-mcp format.' It goes further to enumerate two distinct actions (setup and migrate) with specific behaviors for each vault state, making it easily distinguishable from sibling tools like vault_capture, vault_read, or vault_analyze.
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 WORKFLOW section provides explicit step-by-step instructions on when to call setup vs migrate, including when NOT to call migrate ('Claude should NOT call migrate until the user confirms'). It also specifies sequencing (e.g., 'review summary + ambiguous_files' before deciding), making usage clear and unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Promote one or more captures into a structured note.
Actions: promote: Promote captures into a note. params: capture_paths (list[str]), title (str), summary (str), domain (str), content (str), tags (list[str] | None), aliases (list[str] | None), confidence (float, default 0.7), auto_link (bool, default True)
WORKFLOW — Claude MUST follow these steps:
LIST: Call vault_read(action="list_captures", include_content=True) to get all unpromoted captures with full content in a single call.
SELECT & SYNTHESIZE: Choose related captures to promote together. Generate title, summary, domain, content, confidence, tags.
CONFIRM: Present the full synthesis to the user and wait for approval. Promotion is semi-destructive — source captures are marked as promoted and cannot be re-promoted.
PROMOTE: Call this tool with action="promote" and the confirmed output.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| title | No | ||
| action | Yes | ||
| domain | No | ||
| aliases | No | ||
| content | No | ||
| summary | No | ||
| auto_link | No | ||
| confidence | No | ||
| capture_paths | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that promotion is 'semi-destructive' and that source captures 'cannot be re-promoted,' which is important behavioral context. However, this directly contradicts the annotation destructiveHint: false, which implies the tool is not destructive. This contradiction forces a score of 1.
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 structured with a clear purpose statement, an actions block, and a workflow. However, the actions block redundantly restates the schema's parameters and types, which is unnecessary. The workflow section is valuable but the duplication makes it slightly less concise.
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 covers the essential workflow and the semi-destructive nature of the operation, which is good. However, with no output schema, it does not describe return values or success/failure behavior. It also doesn't mention any error handling or prerequisites beyond calling vault_read, leaving some gaps.
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 description repeats the parameter list from the schema with types and defaults, but adds little semantic meaning beyond what the names suggest. The workflow mentions generating title, summary, domain, content, confidence, and tags, providing some context, but parameters like auto_link and aliases are not explained. With 0% schema description coverage, the description fails to compensate adequately.
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's function: 'Promote one or more captures into a structured note.' It distinguishes itself from sibling tools by focusing on promotion of existing captures into notes, while siblings like vault_capture and vault_read handle capture and reading. The 'Actions' section further clarifies the single available action.
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 a detailed WORKFLOW section that explicitly instructs Claude to call vault_read first, then synthesize and confirm with the user before promoting. This gives clear context for when to use the tool. However, it does not explicitly state when not to use it or mention alternative tools beyond the workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read and search vault content.
Actions: search: Search vault notes. params: query, directory, tags get: Read a single file's full content. params: path list_captures: List captures filtered by status, sorted newest first. params: status ("capture" | "promoted" | "all"), limit (default 50), include_content (default False)
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | ||
| tags | No | ||
| limit | No | ||
| query | No | ||
| action | Yes | ||
| status | No | capture | |
| directory | No | ||
| include_content | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation declares readOnlyHint=true, covering the safety profile. The description adds behavioral context by separating actions, noting that list_captures sorts newest first, and providing defaults for limit and include_content. It does not discuss errors or permissions, but the read-only nature is well established.
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 well-structured, presenting a brief overview followed by a clear action list with parameters. Every sentence adds value, and there is no redundant or vague 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?
All 8 parameters are accounted for across the three actions, and the output schema supplements return-value expectations. Minor gaps exist, such as not explicitly noting that 'action' is required or detailing edge-case behavior, but for a read-only composite tool this is largely complete.
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?
With schema description coverage at 0%, the description fully compensates by mapping each parameter to its relevant action: query/directory/tags for search, path for get, and status (with enum values), limit (default 50), and include_content (default False) for list_captures. This provides complete semantic understanding 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 opens with 'Read and search vault content,' clearly identifying the tool's function. It then lists three distinct actions (search, get, list_captures) with specific verbs and resources, distinguishing it from write-oriented sibling tools like vault_capture and vault_promote.
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?
Action descriptions such as 'Search vault notes' and 'Read a single file's full content' provide clear context on when to use each mode. However, it does not explicitly compare with sibling tools or state when not to use this tool (e.g., for writing), 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.
Reflect on your knowledge vault — what you've been thinking about, how your interests are evolving, and what connections you might be missing.
Actions: snapshot: What does my knowledge look like right now? Topics, connections, and what's been on my mind. Auto-saved to .brain/snapshots/. drift: How has my focus shifted? What's growing, what's cooling down, and where my curiosity is heading. params: since_days (default 30) blindspots: What am I missing? Isolated ideas that could be connected, and surprising bridges between clusters. params: limit (default 50)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| action | Yes | ||
| since_days | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden for behavior. It discloses that snapshots are auto-saved to .brain/snapshots/, and describes what each action yields (topics, connections, shifting focus, missing bridges). It doesn't explicitly state whether drift/blindspots have side effects, but the side effect for snapshot is a notable positive.
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 well-structured with an intro and concise action bullets; every sentence adds value without redundancy. The front-loaded purpose statement and clear action breakdown make it easy 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?
The description covers the three actions and their parameters, and explains the output concept for each (snapshot shows topics/connections, drift shows focus changes, blindspots shows missing connections). It lacks explicit return-value formatting details, but no output schema exists, and the description gives enough for an agent to understand what to expect.
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 zero description coverage, but the description compensates by explaining the action values (snapshot, drift, blindspots) and linking since_days to drift and limit to blindspots, including defaults. This gives each parameter meaningful context beyond the 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 clearly states the tool's purpose—reflecting on the knowledge vault—and distinguishes three specific actions (snapshot, drift, blindspots) that set it apart from sibling tools. The verb 'reflect' and resource 'knowledge vault' are specific, and the action list gives concrete functionality.
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 for when to use each action via probing questions (e.g., 'What does my knowledge look like right now?') and parameter details for drift and blindspots, but it does not explicitly compare with sibling tools or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage topic lifecycle: prepare materials, create, or update.
Actions: prepare: Gather structured materials for topic creation/update. Uses progressive disclosure — returns summaries, not full content. params: cluster_id OR note_paths (pick one). topic_path (optional, for staleness detection on update). create: Write a new topic to topics/. params: title, content (Claude-generated body), domain, tags, member_notes, aliases update: Update an existing topic. params: topic_path (required), content (optional, new body), member_notes (optional, updated list), tags (optional)
WORKFLOW — Claude MUST follow these steps:
PREPARE: Call with action="prepare" to get summaries + graph metrics.
DEEP READ (optional): Use vault_read(action="get") for important notes.
SYNTHESIZE: Write topic body (synthesis, not concatenation).
CONFIRM: Present to user. Wait for approval.
WRITE: Call with action="create" or action="update".
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| title | No | ||
| action | Yes | ||
| domain | No | ||
| aliases | No | ||
| content | No | ||
| cluster_id | No | ||
| note_paths | No | ||
| topic_path | No | ||
| member_notes | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the minimal readOnlyHint annotation, the description discloses key behavioral traits: progressive disclosure (returns summaries, not full content), the requirement to synthesize rather than concatenate, and the need to wait for user approval before writing. It also notes staleness detection on update.
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 well-structured with a brief summary, action-specific bullets, and a numbered workflow. It is moderately long but every section earns its place; there is no redundant repetition of schema details.
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 (3 actions, 10 parameters, no output schema), the description covers the full lifecycle, parameter usage, workflow, and even return behavior for prepare ('returns summaries, not full content'). It is sufficiently complete for an agent to invoke the tool correctly without additional context.
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?
Despite 0% schema description coverage, the description compensates fully by grouping parameters per action and specifying constraints such as 'cluster_id OR note_paths (pick one)' and 'topic_path (required) for update.' It maps all 10 schema parameters to their relevant actions, adding meaning far beyond raw schema names.
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 the tool's purpose precisely: 'Manage topic lifecycle: prepare materials, create, or update.' It enumerates the three distinct actions (prepare, create, update) with clear verbs and resources, and the workflow distinguishes it from sibling tools like vault_read.
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 an explicit, numbered workflow that Claude MUST follow, including when to call prepare, when deep-reading via vault_read is appropriate, and when to invoke create vs update. This goes beyond vague guidance and includes a mandatory confirmation step before writing.
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.
v0.3.12vault_analyzevault_capturevault_initvault_promotevault_readvault_reflectvault_topicScored across 7 tools
Each tool has a clear primary purpose (capture, promote, read, analyze, topic, reflect, init). Minor overlap exists between vault_analyze's orphans and vault_reflect's blindspots, both surfacing isolated or under-connected content, but their intended use cases differ (graph analysis vs. reflective synthesis).
Most tools follow a consistent 'vault_verb' pattern (vault_capture, vault_promote, vault_read, vault_analyze, vault_reflect, vault_init). vault_topic breaks the pattern by using a noun as the tool name, though its actions (prepare, create, update) are verb-based. This is a minor deviation rather than chaotic inconsistency.
Seven tools is well-scoped for a knowledge vault management server. Each tool exposes multiple related actions (e.g., vault_read has search/get/list_captures), covering a broad domain without ballooning the surface. The number feels intentional and justified.
The tool set covers the capture→promote→topic lifecycle well, but there is no direct way to update or delete a promoted note (as opposed to captures and topics). Notes are the core artifact, so the inability to edit or remove them is a notable gap that agents would have to work around.
Persistent context for Claude. Your AI always knows your projects and next actions across sessions.
Connect your team's living knowledge base — docs, data, issues, CRM — to Claude and ChatGPT.
A self-improving memory layer. Your memory, notes, tasks and goals, remembered everywhere.
Brain dump, routines, task planning, focus, and instant thought retrieval
