Allows AI agents to read, search, edit, and reorganize an Obsidian vault, including tools for managing notes, frontmatter, backlinks, and link-safe moves.
Click on "Install 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., "@obsidian-mcp How many notes are in my vault, and where are the newest ones?"
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.
Let Claude (or any MCP client) read, search, edit, and reorganize your Obsidian vault — safely.
A Model Context Protocol server that treats your vault as what it really is: a folder of markdown files. No plugins, no cloud, no database. Obsidian can be closed while Claude works on your notes.
The implementation follows the SDK's current recommended API (McpServer + zod-validated tool contracts) — and pins its protocol behavior with integration tests that speak raw JSON-RPC to the real process, so SDK upgrades can't silently change the wire. If you want to understand what an MCP server actually does beyond npx some-server, start with test/server.test.ts next to the specification.
"How many notes are in my vault, and where are the newest ones?" "Find every note that mentions 'spaced repetition' and summarize the key ideas." "Create
research/glossary.mdwith these ten terms and tag it#glossary." "Renamedaily/2026-09-06.mdtojournal/2026-09-06.md— don't break any links." "Which notes link to my reading list? Show the exact lines." "Research solid-state batteries on the web, then createresearch/solid-state-batteries.md— summary, key players, open questions, and frontmatter with the sources."
Related MCP server: Obsidian MCP Server
Tool | What it does |
| Vault path + note count — the "is it alive?" call |
| Browse folders, with sizes and modification dates |
| Full markdown content of one note |
| Full-text search (case-insensitive substring or regex), with |
| A note's YAML properties as JSON — cheaper than reading the whole note |
| New note, parent folders auto-created, optional YAML frontmatter generated |
| Append, prepend (after frontmatter), find & replace, or replace a heading section |
| To |
| Rename/move and repair every link across the vault |
| What references this note? (wikilinks, embeds, relative markdown links) |
All read-only tools are annotated readOnlyHint: true, so MCP clients can skip approval prompts for them and only ask about writes.
Your vault is irreplaceable; the design starts there.
No path escapes. Every user-supplied path goes through one guard (safeResolve); ../../../etc/passwd comes back as a contained error, never a read
Deletes are reversible. Notes move to the vault's .trash/ (Obsidian's own convention) — never rm
No silent clobbers. create_note fails if the note exists, unless you explicitly say overwrite
Kernel-atomic where possible. Creates use the wx flag (no check-then-write race); deletes and moves are rename() calls
Link-safe moves. Moving a note rewrites inbound links in other notes and rebases the moved note's own relative links — aliases and #anchors preserved
Empty-folder cleanup after deletes/moves uses non-recursive rmdir up the tree: the kernel refuses anything non-empty, so cleanup is data-loss-proof by construction
The one rule that makes this work: the vault folder is the only thing this server can touch.
Requires Node 20+.
git clone https://github.com/laurentiudanielgi-coder/obsidian-mcp.git
cd obsidian-mcp
npm install && npm run buildEdit claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS):
{
"mcpServers": {
"obsidian": {
"command": "/absolute/path/to/node",
"args": ["/absolute/path/to/obsidian-mcp/dist/index.js"],
"env": { "OBSIDIAN_VAULT_PATH": "/absolute/path/to/your/vault" }
}
}
}Notes: use which node for the absolute path — GUI apps don't inherit your shell's PATH. Fully quit and reopen Claude Desktop. In Obsidian, set Files & Links → Deleted files → .trash folder so trash semantics match. And back your vault up (git works beautifully) — safety features are seatbelts, not brakes.
The server is configured with one environment variable: OBSIDIAN_VAULT_PATH, pointing at the vault root. It speaks JSON-RPC over stdio — the default transport for locally-spawned MCP servers.
src/
├── index.ts — entrypoint: transport wiring; why stdout is the protocol channel
├── server.ts — protocol layer: handshake, capabilities, tools/list, tools/call
├── config.ts — env-var config; why clients spawn servers and pass settings via env
└── vault.ts — the only code that touches files: path guard, trash, links, editsArchitecture in one sentence: JSON-RPC messages arrive over a transport (stdio), get dispatched by the protocol layer to tool handlers, which delegate every filesystem operation to the vault layer — the single choke point where safety lives.
The codebase doubles as a guided tour:
Concept | Where to look |
The |
|
Tool contracts: descriptions are written for the model; zod schemas |
|
Tool errors vs protocol errors (two failure channels) |
|
Server config via env vars (clients spawn servers) |
|
Stdio framing and the stdout-is-protocol rule |
|
The traversal guard when an LLM builds the paths |
|
Obsidian link resolution & unique-basename rule |
|
Raw wire format |
|
npm test # unit tests against real temp filesystems + wire-level tests speaking raw JSON-RPC
npm run dev # tsc --watchTwo probe scripts exist for debugging clients against the server:
node scripts/big-create-test.mjs 9000 # create a 9,000-char note, time it
node scripts/create-from-json.mjs note.json # replay an exact client payloadCRUD, search, frontmatter, backlinks, link-repairing moves
RAG: heading-aware chunking → local embeddings → sqlite-vec → semantic_search
Streamable HTTP transport (same server, new transport — proving the decoupling)
Full decision log and reasoning in PLAN.md.
Create a new note. Fails if it already exists unless overwrite=true. Parent folders are created automatically. Pass frontmatter to have YAML properties generated; content is the markdown body.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Vault-relative note path (.md optional) | |
| content | Yes | Markdown body of the note | |
| overwrite | No | Replace an existing note | |
| frontmatter | No | Optional YAML properties, e.g. {"tags": ["research"]} |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses duplicate-handling (fails unless overwrite), automatic parent-folder creation, and frontmatter generation. It could add more about return values or the destructive nature of overwrite, but key side effects are 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?
Three short, front-loaded sentences. The core action comes first, followed by edge-case behavior and parameter semantics. Every sentence adds useful information with 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 covers the essential facts for a create operation: existence check, overwrite behavior, parent-folder creation, and parameter roles. With no output schema and no annotations, a brief note on return value or error behavior would be a small enhancement, but the current coverage is strong.
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 100%, so the baseline is 3. The description adds extra meaning beyond the schema by explaining that parent folders are created automatically for path, that frontmatter gets turned into generated YAML, and that content is the markdown body. These details help the agent pass the correct values.
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 a specific verb and resource: 'Create a new note.' It also discloses an overriding behavior (fails if exists unless overwrite=true) that distinguishes it from edit_note and other siblings, so there is no ambiguity about what the tool does.
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 implies usage: it is for creating new notes, and the overwrite/fails behavior gives some context. However, it does not explicitly say when to prefer this over edit_note or when not to use it, leaving the routing decision to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a note to the vault's .trash folder. NEVER a permanent delete — the note can be restored from .trash. Folders are refused, but folders left empty by the delete are removed automatically.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Vault-relative note path |
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 so well. It discloses that the operation is a move to .trash, not a permanent delete, that restoration is possible, that folders are refused, and that empty folders are auto-removed. This goes far beyond a simple 'delete' statement and gives the agent important 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?
Three concise sentences, each adding essential information: the core action, the non-destructive nature, and the folder-handling behavior. No redundant phrasing, and the most important information is front-loaded. This is an efficient, well-structured description.
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 single-parameter tool with no output schema, the description covers the key operational details: the .trash destination, restorability, folder refusal, and auto-cleanup of empty folders. It does not specify error behavior or the return value, but the critical success and failure conditions for calling this tool are adequately covered. A small gap remains around what happens if the path doesn't exist or isn't a note.
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 already describes 'path' as a 'Vault-relative note path' with 100% coverage, so the baseline is 3. The description adds value by explicitly stating 'Folders are refused', clarifying that the path must reference a note and not a folder. This semantic constraint is not present in the schema, raising the score to 4.
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 action: 'Move a note to the vault's .trash folder', clearly identifying the resource and the operation. It also explicitly distinguishes itself from a permanent delete with 'NEVER a permanent delete', removing ambiguity. This is a clear, non-tautological definition that differentiates from sibling tools like move_note and create_note.
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 implies when to use the tool (to soft-delete a note) and explicitly excludes folders with 'Folders are refused'. However, it does not name any sibling alternatives or provide when-not-to-use guidance relative to tools like move_note. The usage context is clear but the distinction from alternatives is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit an existing note in place. Modes: 'append'/'prepend' content (prepend lands after frontmatter); 'find_replace' all occurrences of find→replace (fails if find is absent); 'replace_section' swaps everything under heading (subsections included) for content.
| Name | Required | Description | Default |
|---|---|---|---|
| find | No | Text to find (find_replace) | |
| mode | Yes | ||
| path | Yes | Vault-relative note path | |
| content | No | Text for append/prepend/replace_section | |
| heading | No | Exact heading text (replace_section) | |
| replace | No | Replacement text (find_replace) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden, and it delivers meaningful traits: "Edit an existing note in place" reveals mutation, "prepend lands after frontmatter" flags a placement nuance, find_replace's "fails if find is absent" discloses a concrete failure condition, and "subsections included" reveals destructive scope. It stops short of stating irreversibility or behavior when the path doesn't exist, but the disclosed traits go well beyond what the schema conveys.
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 core purpose is front-loaded in one sentence, followed by a compact semicolon-separated mode breakdown where every parenthetical earns its place. Three sentences fully specify a four-mode editing tool without redundancy or 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?
For a 6-parameter, 4-mode tool with no annotations and no output schema, the description covers mode semantics, parameter-mode relationships, a failure condition, and scoping nuances. Minor gaps remain — no explicit statement of what happens if the note doesn't exist, no success/return behavior, and no reversibility note — but the essentials for invoking the tool correctly are 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 coverage is 83%, so the baseline is 3, but the description adds real semantic value by mapping parameters to modes: find→replace pairs, content used by append/prepend/replace_section, and heading scoping replace_section. It also clarifies behavioral nuances the terse schema labels miss, such as "all occurrences" for find_replace and frontmatter placement for prepend.
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 specific verb and resource: "Edit an existing note in place," which immediately distinguishes it from sibling tools like create_note, delete_note, move_note, and read_note. The four named modes (append, prepend, find_replace, replace_section) further specify exactly what operations are available, leaving no ambiguity about the tool's job.
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 clear within-tool mode guidance, such as find_replace "fails if find is absent" and replace_section swapping "subsections included," which helps an agent choose a mode. However, it never explicitly says when to prefer edit_note over siblings or when not to use it — that must be inferred from the tool name and the sibling list rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List notes that link TO a given note (wikilinks, embeds and relative markdown links). Use before editing or deleting to understand what references it, or to follow the knowledge graph backwards.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Vault-relative note path |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true, and the description adds useful behavioral detail about the link types included and the direction of links (incoming, not outgoing). This adds value beyond the structured data, though return format and pagination are not described.
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?
Two sentences, front-loaded with the core action and scope, followed by practical usage contexts. No filler or redundant restatement of the name.
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 simple one-parameter read tool with readOnlyHint, the description explains the result (list of backlink notes), the link types included, and when to use it. No critical information is missing for an agent to select and 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 covers the single required 'path' parameter with description 'Vault-relative note path', so schema coverage is 100%. The tool description adds no further parameter semantics beyond referring to a given note, so the baseline 3 applies.
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 'List notes that link TO a given note' with explicit link types (wikilinks, embeds, relative markdown links). This clearly distinguishes the tool from siblings like list_notes and read_note by focusing on incoming references.
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?
Explicitly prescribes when to use it: 'before editing or deleting to understand what references it, or to follow the knowledge graph backwards.' It lacks when-not guidance or named alternatives, which would be needed for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a note's YAML frontmatter (its properties: tags, dates, custom fields) as JSON. Cheaper than read_note when you only need metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Vault-relative note path |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description confirms the read-only nature. It adds useful behavioral context by noting the tool is cheaper than read_note and returns JSON, going beyond the annotation's basic safety signal.
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?
Two tight sentences with zero filler. The main action is front-loaded, followed by a brief efficiency comparison with read_note. Every word 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?
With no output schema, the description adequately conveys the return format (JSON) and lists common frontmatter fields (tags, dates, custom fields). It handles the essentials for a simple read-only tool, though it could mention edge cases like missing frontmatter.
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 100% and the path parameter is already well-documented as 'Vault-relative note path'. The description adds no extra parameter semantics, so it rests at the baseline for full schema coverage.
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?
Description states the specific verb ('Read'), the resource ('a note's YAML frontmatter'), and the output format ('as JSON'). It also clearly distinguishes itself from read_note by emphasizing it's cheaper and focused only on metadata, making its purpose unambiguous.
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 'Cheaper than read_note when you only need metadata' explicitly gives the condition for using this tool and names the alternative. An agent can immediately decide between reading full note content versus just metadata.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List markdown notes in the vault (or a subfolder), newest info included. Returns vault-relative paths — use those in read_note.
| Name | Required | Description | Default |
|---|---|---|---|
| folder | No | Optional subfolder to list, vault-relative (e.g. 'projects') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint already declaring safety, the description adds behavioral context by specifying the return contract: vault-relative paths to be used with read_note. It also mentions 'newest info included', though this phrase is somewhat ambiguous; overall it goes beyond the annotation.
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 and front-loads the main action and scope, then provides a useful return-value pointer. The phrase 'newest info included' is slightly unclear and could be tightened, but there is no wasted verbiage.
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 simple read-only list tool with one optional parameter and no output schema, the description covers the key facts: what is listed, where it can be scoped, what is returned, and how to use the result. It could be more precise about ordering/recursion, but it is complete enough for correct 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?
The single parameter 'folder' is already fully documented in the schema as optional and vault-relative, and the description only echoes this with 'or a subfolder'. It adds no new semantic detail about folder formatting or default behavior.
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 action ('List markdown notes') and a clear scope ('vault or a subfolder'), and it names what the caller receives ('vault-relative paths'). It does not explicitly contrast itself with search_notes, but the verb and resource are concrete enough to identify the tool's role.
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 context for listing by optional subfolder and tells the caller to feed returned paths into read_note. However, it does not say when to prefer list_notes over search_notes or whether listing is recursive, so the when-to-use guidance is incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move or rename a note (folders created automatically) and automatically update all links across the vault that pointed at its old location: wikilinks, embeds and relative markdown links. Emptied source folders are pruned. Prefer this over create+delete for renaming.
| Name | Required | Description | Default |
|---|---|---|---|
| to_path | Yes | New vault-relative path | |
| from_path | Yes | Current vault-relative path |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure burden. It discloses important side effects: folders are created automatically, all link types are updated (wikilinks, embeds, relative markdown links), and emptied source folders are pruned. It does not mention what happens if the destination path already exists, which is a notable gap for a mutating move 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?
Three dense sentences with no filler. The core action and primary side effects are front-loaded, and the usage preference is a concise final sentence that earns its place by aiding tool selection.
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 purpose, key side effects, and an explicit usage alternative. For a tool with no annotations and no output schema, it provides enough for an agent to call it correctly in the common case. It could be more complete by stating behavior when the destination already exists, but overall it is nearly sufficient.
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 100%, so the schema already documents both parameters as vault-relative paths. The description adds minor context (folders created automatically) but does not elaborate on path format, edge cases, or conflict behavior. Baseline 3 is appropriate because the schema handles parameter meaning.
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 ('Move or rename') with a clear resource ('a note') and explains the full scope: automatic folder creation, link updates across the vault, and pruning of emptied folders. This distinguishes it from siblings like create_note, edit_note, and delete_note without needing to inspect their schemas.
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 explicitly says 'Prefer this over create+delete for renaming,' giving the agent a direct decision rule for when to choose this tool over an alternative. This is clear usage guidance for the main scenario (move/rename) and names the relevant alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the full markdown content of one note. path is vault-relative (from list_notes), e.g. 'projects/alpha.md'. The .md suffix is optional.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Vault-relative note path |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint already tells the agent this is non-destructive, and the description reinforces it by saying 'Read'. It adds that the full markdown content is returned, but doesn't describe error behavior or what happens for missing or invalid paths. No contradiction.
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?
Two dense sentences with no fluff. The core action is front-loaded, and the path-format details are packed efficiently.
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 one-parameter read tool with readOnlyHint set and complete schema coverage, the description covers everything needed to call it correctly. The absence of an output schema is compensated by 'full markdown content', which makes the return value obvious.
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 already documents path with 100% coverage, so the baseline is 3. The description adds useful meaning: a concrete example, the source of the path (from list_notes), and the fact that .md is optional.
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 verb ('Read'), the resource ('one note'), and the scope ('full markdown content'). This distinguishes it from siblings like get_frontmatter (metadata only) and search_notes (search behavior).
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 clear practical guidance: path comes from list_notes and the .md suffix is optional. It does not explicitly name alternatives or when-not-to-use, but for a simple read tool this context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full-text search across all notes. Default is case-insensitive substring matching; set regex=true to treat query as a regular expression. Returns path, line number and the matching line, capped at 50 hits.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Text to search for | |
| regex | No | Treat query as a regular expression | |
| folder | No | Optional subfolder to restrict the search |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds substantial behavioral detail beyond that: default case-insensitive substring matching, regex opt-in, the return format (path, line number, matching line), and the 50-hit cap. This gives the agent an accurate expectation of what the tool does and returns.
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?
Two sentences, no wasted words. The core purpose is front-loaded, and the behavioral details follow naturally. Every sentence 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?
Given no output schema, the description responsibly explains the return shape and limit. It covers search scope, matching semantics, regex behavior, folder restriction, and result contents. An agent has enough to invoke this tool correctly without ambiguity.
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 100%, so the baseline is 3. The description goes further by explaining the default matching behavior ('case-insensitive substring matching') and the implication that regex is opt-in, which adds meaning beyond the schema's brief parameter descriptions. Folder restriction is not expanded, but the overall parameter semantics are well supported.
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 'Full-text search across all notes', which names a specific verb and resource and clearly distinguishes it from sibling tools like list_notes or read_note. The mention of substring matching and regex further clarifies the exact operation.
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 establishes when to use this tool: when you need to find matching content across notes, with optional folder restriction. It does not explicitly name alternatives or exclusion criteria, but the context is clear enough that an agent can infer this is the content-search tool rather than a metadata or note-management tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report the vault root path and how many markdown notes it contains. Use this first to confirm the vault is mounted and readable.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes this as a read-safe operation, and the description reinforces this by framing the tool as a confirmation/read rather than a mutation. It adds useful context about what the tool reports (root path and note count) and how to interpret it as a readiness check, going beyond the raw annotation.
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?
Two sentences with no filler or repetition. The first sentence states the core function, and the second provides a clear usage directive, making the description maximally efficient.
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 vault status tool, the description covers what it returns and when to call it. The sibling list confirms all other tools operate on notes, so there is no missing context or potential confusion.
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 the schema is empty and there is nothing for the description to compensate for. The baseline of 4 applies here; the description appropriately says nothing about parameters because none exist.
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 'Report' as a specific verb with 'vault root path' and 'number of markdown notes' as the resource, making the tool's function immediately clear. It naturally distinguishes itself from sibling tools that operate on individual notes rather than the vault itself.
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 explicitly instructs to 'Use this first to confirm the vault is mounted and readable,' giving a clear when-to-use directive. It does not mention exclusions or alternatives, but since no sibling tool serves the same vault-level purpose, this is sufficient and not misleading.
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.5.0create_notedelete_noteedit_noteget_backlinksget_frontmatterlist_notesmove_noteread_notesearch_notesvault_infoScored across 10 tools
Each tool maps cleanly to a distinct resource/action: note content, frontmatter, backlinks, vault info, and file operations. Even close pairs like get_frontmatter vs read_note are explicitly differentiated by cost and scope.
Most tools follow a consistent verb_noun snake_case pattern (read_note, create_note, delete_note, move_note). vault_info is a minor outlier since it lacks a get_ or other verb prefix, but the overall pattern remains predictable and readable.
Ten tools is well-scoped for an Obsidian vault server. Each tool covers a distinct core operation with no redundancy or unnecessary bloat.
The toolset provides complete note lifecycle coverage: create, read, update, delete, move, search, plus Obsidian-specific needs like frontmatter and backlinks. Folder handling is implicit in move/create, so there are no obvious dead ends for the implied domain.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Notes, files, GitHub, and Drive through one MCP connection.
Notes, files, GitHub, and Drive through one MCP connection.
Notes, files, GitHub, and Drive through one MCP connection.
Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.