Provides tools to manage Obsidian vaults, including reading, writing, searching, and deleting notes, as well as managing tags and navigating links.
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., "@obsidian-mcp-server search my notes for meeting notes"
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 Model Context Protocol (MCP) server for Obsidian vault operations. Works with any MCP-compatible client including Claude Desktop, Cursor, Windsurf, and VS Code.
Full Vault Access: Read, write, search, and delete notes
Link Navigation: Get outgoing links and backlinks for any note
Tag Management: List all tags, find notes by tag
Flexible Search: Search by content, title, tags, or folder
Two Transports: Stdio (local) or Streamable HTTP (remote)
Modern MCP: Built with MCP SDK 1.6.1, Zod validation, tool annotations
Related MCP server: Obsidian MCP Server
# Install dependencies
npm install
# Build
npm run build
# Run (stdio mode)
OBSIDIAN_VAULT_PATH=/path/to/vault npm start
# Run (HTTP mode)
OBSIDIAN_VAULT_PATH=/path/to/vault npm run start:httpVariable | Required | Default | Description |
| Yes | - | Absolute path to your Obsidian vault |
| No |
| Transport mode: |
| No |
| HTTP server port |
| No |
| HTTP server host |
| No |
| Enable debug logging |
{
"mcpServers": {
"obsidian": {
"command": "node",
"args": ["/path/to/obsidian-mcp-server/dist/index.js"],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
}
}
}
}Start the server:
OBSIDIAN_VAULT_PATH=/path/to/vault TRANSPORT=http npm startConnect via http://localhost:3000/mcp
Tool | Description |
| List notes with pagination and folder filtering |
| Read a note's full content and metadata |
| Create or update a note |
| Permanently delete a note |
| Search notes by content, tags, or folder |
Tool | Description |
| Get vault statistics (note count, size, etc.) |
| List all tags with usage counts |
| Get all notes with a specific tag |
Tool | Description |
| Get outgoing links from a note |
| Get backlinks to a note |
All tools support a response_format parameter:
json (default): Structured JSON data
markdown: Human-readable markdown
# Development mode (with auto-reload)
npm run dev
# Build
npm run build
# Test (builds and runs --help)
npm testsrc/
index.ts # Entry point, transport handling
server.ts # MCP server with tool registrations
vault.ts # Vault operations (CRUD, search, links)
schemas.ts # Zod input validation schemas
types.ts # TypeScript type definitionsMIT
Permanently delete a note from the vault.
WARNING: This action cannot be undone. The note file will be removed from the filesystem.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path to the note to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations already indicate destructiveHint=true, the description adds critical context by explicitly warning 'This action cannot be undone' and stating 'The note file will be removed from the filesystem.' This goes beyond the annotation to clarify permanence and the filesystem impact, which is valuable for an AI agent. There is no contradiction with the idempotentHint or readOnlyHint.
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 extremely concise, with three short sentences that immediately state the action and the critical warning. It is front-loaded with the purpose and every sentence provides necessary information 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 simple deletion tool with one parameter, no output schema, and strong annotations, the description covers the essential context: permanence and filesystem removal. It could add details about behavior when the path doesn't exist, but that is a minor edge case. Overall, it is sufficiently complete for an agent to safely invoke this 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?
The input schema fully describes the only parameter 'path' as 'Relative path to the note to delete' (100% coverage). The description adds no further parameter semantics, so it does not exceed the schema baseline. However, the schema itself is sufficient.
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 action: 'Permanently delete a note from the vault.' It uses a specific verb (delete) and identifies the resource (note), distinguishing it from sibling tools like read, write, or search. This leaves no ambiguity about the tool's purpose.
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 no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites (e.g., that the path must exist) or exclusion conditions. It only states what the tool does, leaving usage context entirely to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get backlinks to a specific note (notes that link TO this note).
Useful for understanding how notes are connected and finding related content.
Returns: { "note": string, "backlinks": [{ "path": string }] }
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path to the note | |
| response_format | No | Output format: 'json' for structured data or 'markdown' for human-readable | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint=false. The description adds the return structure (note and backlinks array) which is useful because there is no output schema. It also clarifies the link direction ('link TO this note'), going beyond the 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 concise: three sentences and a minimal return example. It front-loads the primary purpose and then adds the return format without unnecessary 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?
For a simple read-only tool with complete schema documentation and safety annotations, the description sufficiently explains the operation and return values. The explicit 'link TO this note' disambiguation from sibling tools adds contextual completeness.
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%, with both path and response_format clearly described. The description does not add extra parameter-level detail beyond what the schema provides, so a baseline of 3 is warranted.
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 'Get backlinks to a specific note (notes that link TO this note).' This uses a specific verb and resource, and explicitly distinguishes the direction of links from the sibling tool obsidian_get_links.
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 context for use ('Useful for understanding how notes are connected and finding related content') but does not explicitly mention when not to use it or compare it to alternatives. This is clear context without exclusions, so a 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get outgoing links from a specific note.
Extracts both wiki-style [[links]] and markdown links. Shows whether each linked note exists in the vault.
Returns: { "note": string, "links": [{ "path": string, "displayText"?: string, "exists": boolean }] }
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path to the note | |
| response_format | No | Output format: 'json' for structured data or 'markdown' for human-readable | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, idempotent, non-destructive. The description adds meaningful behavioral details: it extracts both wiki-style and markdown links, and reports whether each linked note exists in the vault. It also explicitly shows the returned object structure, which helps set expectations for the agent. This goes beyond 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 compact and front-loaded. The first sentence states the purpose, then a concise sentence covers link types and existence checking, and the return format is shown as a small code block. No fluff.
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 tool with two parameters and no output schema, the description is largely complete. It covers behavior, link types, existence flag, and return structure. However, it does not specify behavior for nonexistent notes or edge cases (e.g., missing file, empty links). Given the context and annotations, this is acceptable but not perfect.
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 100% of parameters with descriptions: path as 'Relative path to the note' and response_format as enum with default. The description does not add new parameter semantics but does show a return example that implies the path usage. Since schema coverage is high, baseline of 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?
The description opens with a specific verb-resource pair: 'Get outgoing links from a specific note.' This clearly identifies the tool's function and distinguishes it from sibling tools like obsidian_get_backlinks (incoming links) and obsidian_read_note (note content).
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 does not explicitly compare with alternatives or state when not to use. It implies usage context via 'outgoing links' and 'specific note,' but lacks explicit references to sibling tools or exclusion criteria. The sibling list is separate, not in description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all notes that have a specific tag.
The tag can be provided with or without the # prefix.
Returns: { "tag": string, "total": number, "notes": [{ "path": string, "name": string, "tags": string[] }] }
| Name | Required | Description | Default |
|---|---|---|---|
| tag | Yes | Tag to search for (with or without # prefix) | |
| limit | No | Maximum number of results | |
| response_format | No | Output format: 'json' for structured data or 'markdown' for human-readable | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds useful behavioral context by specifying that the tag can be provided with or without the '#' prefix and by showing the exact return JSON structure (tag, total, notes array with path/name/tags). This goes beyond annotations and adds operational clarity.
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 concise and well-structured, with a clear first sentence stating the action, a brief note about prefix flexibility, and a compact return-type block. Every sentence earns its place, and the length is appropriate for the tool's simplicity.
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 filtered query, the description is largely complete: it covers the purpose, tag prefix behavior, returns, and all parameters are documented in the schema. However, it does not specify edge-case behavior (e.g., no matching notes, case sensitivity, or exact match semantics), so it falls just short of fully comprehensive.
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 does not add significant semantic value beyond the schema: it repeats the '#' prefix flexibility already in the parameter description and does not explain limit or response_format in more depth. It meets the baseline but does not elevate it.
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: 'Get all notes that have a specific tag.' This uses a specific verb (Get) and resource (notes) with an explicit filter (by tag). It also distinguishes from sibling tools like obsidian_search_notes (full-text search) and obsidian_list_notes (all notes), making the 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 description implies the use case: when you need notes with a particular tag. However, it does not explicitly mention alternatives or when not to use this tool. No exclusions or comparisons to sibling tools are provided, so guidance remains implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List notes in the Obsidian vault with pagination support.
Returns a list of note paths, names, tags, and modification dates. Use 'folder' to filter to a specific directory. Use 'offset' and 'limit' for pagination on large vaults.
Returns JSON by default with schema: { "total": number, "count": number, "offset": number, "notes": [{ "path": string, "name": string, "tags": string[], "modified": string }], "hasMore": boolean, "nextOffset"?: number }
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of notes to return | |
| folder | No | Filter to notes within a specific folder path | |
| offset | No | Number of notes to skip | |
| response_format | No | Output format: 'json' for structured data or 'markdown' for human-readable | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHInt, idempotentHint, and destructiveHint. The description goes further by detailing the exact response schema, pagination semantics, and the default JSON format, adding substantial behavioral context beyond the 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 concise and well-structured, starting with the main purpose, then listing parameters, and including an inline output schema. Every sentence adds value with no unnecessary fluff.
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 list tool, the description is complete: it explains what is returned, how to filter and paginate, and the output format. The inline schema fills the gap of a formal output schema field, making the tool's behavior fully understandable.
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% of parameters, so baseline is 3. The description adds relational context (pagination with offset/limit, folder filtering, response_format default), which goes beyond raw schema fields and helps the agent reason about their combined usage.
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 lists notes in the vault, specifies the fields returned (path, name, tags, modified), and notes pagination/filtering. This distinguishes it from siblings like obsidian_search_notes, which focuses on searching.
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 parameter guidance (folder for filtering, offset/limit for pagination) but does not explicitly explain when to use this tool over alternatives like obsidian_search_notes. Usage context is implied rather than explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all tags used in the vault with their usage counts.
Tags are extracted from both YAML frontmatter and inline #tags. Results are sorted by frequency (most used first).
Returns: { "total": number, "tags": [{ "tag": string, "count": number }] }
| Name | Required | Description | Default |
|---|---|---|---|
| response_format | No | Output format: 'json' for structured data or 'markdown' for human-readable | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds value by specifying that tags come from both YAML frontmatter and inline #tags and that results are sorted by frequency. It also details the return structure, providing useful behavioral context beyond safety hints.
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-loaded with the core purpose, followed by two useful details and a concrete return format example. No wasted words.
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 low-complexity read-only tool, the description fully covers what it does, how it extracts tags, sorting order, and the exact return shape. Annotations cover safety, and the optional parameter is self-explanatory, leaving no significant 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?
Schema description coverage is 100%, fully documenting the optional response_format parameter with enum and default. The description adds nothing about parameters, so 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?
Description states 'List all tags used in the vault with their usage counts,' specifying verb (list), resource (tags), and scope (vault). It also adds extraction sources and sorting, clearly differentiating from sibling tools like list_notes or get_tagged_notes.
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?
Description clearly conveys its purpose but does not provide explicit guidance on when to use it versus alternatives such as obsidian_get_tagged_notes or obsidian_list_notes. Usage context is implied rather than stated with exclusions or recommended alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the full content of a specific note by path.
The path can be with or without .md extension. Set include_frontmatter=false to get only the markdown content.
Returns: { "path": string, "name": string, "content": string, "frontmatter"?: object, "tags": string[], "modified": string }
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path to the note (e.g., "folder/note.md" or "note") | |
| include_frontmatter | No | Whether to include YAML frontmatter in response |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable context: path can omit .md extension, include_frontmatter controls response content, and the return object shape is shown. This goes beyond the safety profile and helps the agent anticipate behavior.
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 concise, front-loaded with the core purpose, and includes only relevant details. The return block is structured and immediately useful, with no extraneous content.
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 operation with two parameters and no output schema, the description covers path behavior, frontmatter control, and the exact return fields. It is complete enough for an agent to invoke the tool correctly without guessing.
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 both parameters already have detailed descriptions. The description's note about 'with or without .md extension' and 'include_frontmatter=false' largely repeats the schema's examples and semantics, adding minimal new 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 ('Read') and resource ('the full content of a specific note by path'), clearly distinguishing it from siblings like search, list, or delete. It also adds the path flexibility detail, reinforcing its purpose.
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 states clear context: it is for reading a specific note by path. It does not explicitly mention when not to use it or name alternative tools, but the placement among siblings and the wording imply this is the go-to for full note content.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search notes by content, title, tags, or folder.
'query': Full-text search in content and titles
'tags': Filter to notes with any of these tags
'folder': Filter to notes in a specific folder
'include_content': Include full content in results (default: false)
Returns ranked results with match information: { "total": number, "results": [{ "path": string, "name": string, "score": number, "matches": string[], "tags": string[], "excerpt"?: string }] }
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Filter by tags (notes must have at least one of these tags) | |
| limit | No | Maximum number of results | |
| query | No | Text to search for in note content and titles | |
| folder | No | Filter to notes within a specific folder path | |
| include_content | No | Whether to include full note content in results | |
| response_format | No | Output format: 'json' for structured data or 'markdown' for human-readable | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by revealing that results are 'ranked' and by providing the exact result shape with fields like 'score' and 'matches', which is not present in annotations or an output schema.
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 lead sentence, a compact bullet list, and an example result object. Every sentence earns its place; no redundant filler. The front-loaded purpose makes scanning immediate.
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 6 parameters and no output schema, the description compensates by providing a clear output example and covering the main search parameters. It omits the 'limit' and 'response_format' parameters, but those are fully documented in the schema, so the description remains complete enough for a read-only search 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 coverage is 100% and each parameter already has a description. The tool description still adds meaning by clarifying that 'query' is 'Full-text search in content and titles' and that 'tags' filters to notes with 'any of these tags', which goes slightly beyond the schema's phrasing. This enhances the agent's understanding of the search 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 opens with 'Search notes by content, title, tags, or folder' — a specific verb and resource with a clear scope. It explicitly distinguishes from siblings like obsidian_list_notes (lists all) and obsidian_get_tagged_notes (tag-only search) by covering content, title, tag, and folder filters.
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 by listing the search dimensions (content, title, tags, folder) but never explicitly states when to prefer this over alternatives like obsidian_list_notes or obsidian_get_tagged_notes. No 'use this when' or exclusion criteria are given, but the general-purpose nature is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get statistics about the Obsidian vault.
Returns: { "totalNotes": number, "totalSize": number (bytes), "totalTags": number, "lastModified": string (ISO date) }
| Name | Required | Description | Default |
|---|---|---|---|
| response_format | No | Output format: 'json' for structured data or 'markdown' for human-readable | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds value by specifying the return shape (totalNotes, totalSize, totalTags, lastModified) and their types, which is useful given there is no output schema. However, it doesn't add context about performance or formatting nuances beyond the parameter schema.
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 direct sentence followed by a clear return-type block. No wasted words; the core purpose and output structure are front-loaded.
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 stats tool with one optional parameter and no output schema, the description provides sufficient context through the return object. It does not mention error scenarios or edge cases, but for the tool's simplicity, this is adequate. The sibling set confirms this is a distinct aggregate query 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?
The schema fully documents the only parameter 'response_format' with its enum, default, and description. The tool description does not add any parameter-specific nuance beyond what the schema already provides. Baseline of 3 applies due to 100% 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?
The description clearly states 'Get statistics about the Obsidian vault' with a specific verb and resource. It distinguishes itself from sibling tools like obsidian_list_notes, obsidian_read_note, and obsidian_get_links by focusing on aggregate vault-level statistics.
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 for retrieving vault-level aggregates but does not explicitly differentiate when to use this tool vs alternatives. Sibling tool names suggest distinct purposes, and the tool's objective is clear from the name, but no when-to-use or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or update a note in the vault.
Provide markdown content and optionally YAML frontmatter. Directories are created automatically if they don't exist. Set overwrite=false to prevent overwriting existing notes.
Returns the created/updated note metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path for the note (e.g., "folder/note.md") | |
| content | Yes | Markdown content of the note | |
| overwrite | No | If false, fails when note already exists | |
| frontmatter | No | YAML frontmatter metadata as key-value pairs |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behaviors beyond annotations, such as automatic directory creation and the note metadata return. It reinforces the overwrite flag's effect. No contradiction with annotations, though it could elaborate on edge cases like permission failures.
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 concise and well-structured. The first sentence states the core purpose, followed by three short, informative sentences that add critical usage details without fluff. 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?
For a write tool with 4 well-documented parameters and annotations, the description covers the essential aspects: purpose, overwrite safety, directory creation, and return value. It lacks an explicit note on when not to use it, but overall it is sufficiently complete for effective tool 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?
Since the input schema already describes all 4 parameters (100% coverage), the baseline is 3. The description adds value by explaining the 'overwrite' flag's practical impact and mentioning 'frontmatter' as optional, slightly enriching semantic understanding 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 opens with 'Create or update a note in the vault,' using a specific verb and resource. This clearly distinguishes it from sibling tools like read, delete, or search, making the purpose unmistakable.
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 clearly indicates when to use the tool (for creating or updating notes) and provides a condition for preventing overwrites with 'Set overwrite=false.' However, it does not explicitly name alternative tools for other operations, so it stops short of full 5.
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.0.0obsidian_delete_noteobsidian_get_backlinksobsidian_get_linksobsidian_get_tagged_notesobsidian_list_notesobsidian_list_tagsobsidian_read_noteobsidian_search_notesobsidian_vault_statsobsidian_write_noteScored across 10 tools
Each tool targets a distinct operation: CRUD, search, stats, links, backlinks, and tag management. Even similar tools like list_tags and get_tagged_notes serve clearly different purposes (listing all tags vs. retrieving notes with one tag).
All tools follow a consistent pattern: obsidian_ + verb_noun in lowercase snake_case. The verbs (delete, list, read, write, search, get) are predictable and match the action.
With 10 tools, the server is well-scoped for its purpose. Each tool covers a necessary aspect of Obsidian vault management without unnecessary bloat.
The tool surface provides full coverage for note CRUD, search, link graph, and tag operations. It supports creating, reading, updating (via write), deleting, listing, searching, and exploring connections. Minor missing operations like rename/move are not critical gaps.
Search your Obsidian vault to quickly find notes by title or keyword, summarize related content, a…
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
