This server provides filesystem-based read/write access to an Obsidian vault — no Obsidian app or plugins required. Capabilities include:
File Operations
List vault files, optionally filtered by directory or sorted by recent modification
Read full file content or a specific heading's section
Create/overwrite files (with auto-creation of parent directories)
Append content to files, delete files
Rename/move files and automatically update all [[wikilinks]] referencing them
Content Manipulation
Patch files by heading — append, prepend, or replace content relative to a markdown heading
Rename a heading while preserving its level
Find and replace text vault-wide or in a single file, with optional regex support
Directory Management
Create directories (including nested parents)
Delete directories (non-recursive by default; recursive option available)
Search
Case-insensitive substring search across all vault markdown files
Structure & Metadata
Get the heading outline of a file
Get or set YAML frontmatter properties (creates the frontmatter block if none exists)
Tags
List all #tags used across the vault with occurrence counts
Find all files containing a specific tag
Links & Graph
List outgoing [[wikilinks]] from a file
Find all files that link to a given file (backlinks)
Security: All operations are restricted to the vault root directory.
Provides tools for interacting with Obsidian vaults, including listing files, reading/writing content, searching, and patching notes relative to headings.
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-vault-mcp list files in my daily notes folder"
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 filesystem-based MCP server for Obsidian vaults. Works when Obsidian is closed.
Every existing Obsidian MCP connector requires Obsidian to be running and the Local REST API plugin active. When Obsidian goes to the background or is closed, the connector drops — silently, mid-session.
Related MCP server: pablo-obsidian-mcp
This server reads and writes your vault directly from disk via Node's
fs module. No Obsidian process required. No plugin dependencies.
No background disconnects.
list_vault_files — list vault files, optionally filtered by directory
get_vault_file — read a file's content
append_to_vault_file — append content (creates file and dirs if needed)
create_vault_file — create or overwrite a file
patch_vault_file — insert/replace content relative to a heading
search_vault_simple — plain-text substring search across all notes
patch_vault_file supports three operations relative to any heading:
append — add content after the heading's section
prepend — add content immediately after the heading line
replace — replace the entire heading section with new content
Download obsidian-vault-mcp.mcpb from the latest release and
double-click it. Claude Desktop handles the rest.
Requires Node.js 18+.
git clone https://github.com/WhiteWolf-Cyber/obsidian-vault-mcp cd obsidian-vault-mcp npm install npm run build
Add to mcpServers in
~/Library/Application Support/Claude/claude_desktop_config.json:
{ "Obsidian Vault": { "command": "node", "args": ["/absolute/path/to/obsidian-vault-mcp/dist/index.js"], "env": { "OBSIDIAN_VAULT_PATH": "/Users/yourname/ObsidianVault" } } }
{ "Obsidian Vault": { "command": "node", "args": ["C:\Users\yourname\dev\obsidian-vault-mcp\dist\index.js"], "env": { "OBSIDIAN_VAULT_PATH": "C:\Users\yourname\Documents\ObsidianVault" } } }
Restart Claude Desktop after saving.
The vault path resolves in this order:
OBSIDIAN_VAULT_PATH environment variable
~/ObsidianVault (fallback)
Paths are validated at runtime — requests that resolve outside
VAULT_PATH are rejected. The server never traverses above the
vault root.
The same 21 vault tools are also served over HTTP/SSE so Claude on iOS/iPad can reach your vault as a custom connector. This is purely additive — the stdio transport above continues to work unchanged for Claude Desktop.
Install cloudflared:
brew install cloudflare/cloudflare/cloudflared
Authenticate with Cloudflare:
cloudflared tunnel login
Create the tunnel:
cloudflared tunnel create obsidian-vault-mcp
Copy the tunnel UUID printed by the previous command into
cloudflare-tunnel.yml (replace <tunnel-id> in the
credentials-file path).
Set VAULT_MCP_SECRET in your environment (or skip this and let
the server generate one — it will print it to stderr on first run,
copy it from there).
Start the HTTP server:
npm run start:http
Run the tunnel:
cloudflared tunnel run obsidian-vault-mcp
(or install cloudflared as a launchd service for persistent
background operation on macOS — see Cloudflare's
launchd service docs
for the plist template.)
In the Claude iOS/iPad app, add a custom connector:
URL: https://vault.envoyagent.app/sse
Authorization: Bearer <your VAULT_MCP_SECRET>
If the connector seems stuck, the 10-second I/O timeout guard (see
withTimeout in src/tools.ts) will surface a clear error instead of
hanging silently. To restart the HTTP transport itself:
pkill -f http-server.js
npm run start:httpNo Claude Desktop restart is needed — this only affects the HTTP/SSE transport, not the stdio connection Claude Desktop uses.
VAULT_MCP_SECRET=<generate with: openssl rand -hex 32 — do not commit>
PORT=3456
OBSIDIAN_VAULT_PATH=/Users/darrellmahrle/dev/vaultEnvoyAgent — AI-powered outbound voice appointment setting.
Append content to a vault file, creating the file and any missing parent directories if needed.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| content | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It discloses that the tool can create files and directories, which is good. However, it lacks details on whether appending is to the end of the file, if content is treated as a line, or any constraints like encoding or file size limits. Adequate but not thorough.
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 sentence of 18 words, front-loaded with the core action and essential details (creating file/dirs). Every word earns its place, with no redundancy.
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 simplicity and lack of output schema, the description covers the main behavior: appending, creating file, creating parent directories. It is mostly complete, though it could clarify whether appending always adds to the end of the file.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only implicitly references 'path' and 'content' through the action, but does not explain their formats, constraints, or allowed values. This adds little meaning 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 action ('Append content') and the resource ('vault file'), and it distinguishes itself from siblings like 'create_vault_file' by implying the file may already exist. The additional detail about creating missing directories adds precision.
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?
No explicit guidance on when to use this tool versus alternatives. There is no mention of when not to use it, nor any reference to sibling tools like 'create_vault_file' or 'patch_vault_file' for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a directory (and any missing parents) inside the vault.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only discloses basic mutation (create) and recursive behavior (missing parents). It does not mention outcomes when the directory already exists, permission requirements, or return values, which are important for a write 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?
Extremely concise: one 10-word sentence that front-loads the verb and resource. Every word earns its place with no redundancy.
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 low complexity (one parameter, no output schema), the description covers the essential purpose. However, it lacks details on behavior for existing directories, error conditions, and vault-specific constraints, leaving some gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains that 'path' is used for the directory path and can include missing parents, adding meaning beyond the schema type. However, it omits details like path format (absolute/relative) and trailing slash conventions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create) and resource (directory inside the vault) and specifies the capability to create missing parent directories, distinguishing it from sibling tools like create_vault_file or delete_vault_directory.
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?
No guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. The description lacks context about idempotency, error handling, or scenarios where this tool should be avoided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create (or overwrite) a vault file with the given content, creating any missing parent directories.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| content | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description conveys important behavioral traits: it can overwrite existing files and it creates missing parent directories. However, it does not disclose other relevant aspects like permissions, size limits, or return 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 a single concise sentence that conveys the core functionality and key behavioral note about parent directories. It is well-structured and 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?
Given the tool's simplicity (2 required parameters, no output schema, no annotations), the description covers creation, overwrite, and directory creation. It could be improved by mentioning return value or error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds minimal parameter context beyond the schema. It mentions 'with the given content' but does not explain the format or constraints of path or content parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create or overwrite), resource (vault file), and key behavior (creating missing parent directories). It distinguishes from sibling tools like append_to_vault_file which appends rather than overwrites.
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 creating or overwriting files but does not explicitly provide when-to-use or when-not-to-use guidance. It lacks comparison to alternatives such as append_to_vault_file or patch_vault_file.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a directory inside the vault. Non-recursive fails if the directory is not empty.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| recursive | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the non-recursive failure condition but does not mention irreversibility, permission requirements, or what happens to contents on recursive deletion.
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, 15 words. Front-loaded with the core action, followed by the key condition. No redundancy or 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?
Given low complexity (2 params, no output schema, no annotations), the description covers the essential behavior. Missing details like error handling or return value, but acceptable for this scope.
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 0%, so description compensates. It explains the recursive parameter's purpose via the condition. The path parameter is minimally described, but the tool context clarifies it is the vault directory path.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Delete) and resource (a directory inside the vault). It also specifies the non-recursive behavior, distinguishing it from file-level sibling tools like delete_vault_file.
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 this tool (to delete directories) and hints at when not to use non-recursive (if directory not empty). However, it does not explicitly compare to alternatives or provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a single vault file.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does not state that deletion is permanent, whether confirmation is needed, or what errors may occur. The single sentence only repeats the action.
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 (5 words) and front-loaded with the verb and resource. However, it sacrifices necessary information for brevity, making it slightly under-specified.
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 tool with one parameter and no output schema, the description should at least note the irreversible nature of deletion and potential error conditions. It fails to provide a complete picture, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate for missing parameter details. It does not explain the 'path' parameter beyond implying it is a file path. No format, constraints, or example is given.
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 'Delete' and the resource 'a single vault file', distinguishing it from sibling tools like delete_vault_directory. It is unambiguous and specific.
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?
No guidance is provided on when to use this tool versus alternatives. It does not mention that it should be used only for files and not directories, nor does it give any context on prerequisites or outcomes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find all vault files that link to the given file via [[wikilinks]].
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states basic behavior without disclosing traits like recursion depth, inclusion of indirect links, or performance implications.
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?
Single sentence, no wasted words. However, it is so brief that it sacrifices completeness for conciseness.
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 should explain return format. It also omits details like whether symbolic links or embedded links are included. The tool's simplicity is not an excuse for missing context given 20 sibling tools.
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 0%, and the description adds no meaning to the 'path' parameter beyond 'the given file'. It does not explain the format, scope, or constraints of the path.
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 'Find', the resource 'vault files', and the specific constraint 'that link to the given file via [[wikilinks]]'. This distinguishes it from sibling tools like 'get_outgoing_links' which serves the opposite direction.
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?
No guidance on when to use this tool versus alternatives (e.g., get_outgoing_links). The description does not mention when not to use it or provide any comparative context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List vault files that contain a given #tag, with per-file occurrence counts.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | Yes | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that results include per-file occurrence counts, adding value beyond the purpose. However, it does not mention read-only nature, permissions, or other behavioral traits like rate limits or data freshness.
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 concise sentence that is front-loaded with the core action and result. Every word contributes meaning, with no 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?
Given no output schema, no annotations, and 0% schema description coverage, the description is insufficient. It fails to explain the 'limit' parameter or provide context about the result set, pagination, or limitations.
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%. The description implicitly covers the 'tag' parameter but provides no explanation for the 'limit' parameter. It adds only marginal meaning beyond the schema's property 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 lists vault files containing a given #tag with per-file occurrence counts. It uses a specific verb ('List') and resource ('vault files'), distinguishing it from siblings like 'list_tags' or 'search_vault_simple'.
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 tag-based file listing but does not explicitly state when to use this tool versus alternatives. No exclusions or guidance on when not to use it is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the heading outline of a vault file.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It only states the basic action, without disclosing whether it is read-only, required permissions, rate limits, or what happens if the file has no headings. The description is insufficient for 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 a single, efficient sentence with no unnecessary words. However, it lacks structural elements like separate sections for usage or parameters, which would improve readability without increasing length.
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, no annotations, and only one parameter with no description, the tool description is severely incomplete. It does not explain the format of the returned outline, error handling, or edge cases. The agent lacks critical information to correctly invoke and interpret results.
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%, meaning the parameter 'path' lacks any schema documentation. The description does not add meaning beyond the parameter name, failing to explain what format the path should be (relative/absolute) or whether it refers to a file or directory. The description adds minimal value over the structured schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Get the heading outline of a vault file'), clearly indicating the tool's function. However, it does not differentiate it from sibling tools like get_vault_file or get_outgoing_links, which could also involve file content. The purpose is clear but lacks sibling distinction.
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?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, suitable contexts, or when not to use it. The agent receives no help in selecting this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a YAML frontmatter property's value from a vault file.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | ||
| path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses only the basic operation. No annotations are provided, so the description should cover side effects, required permissions, or error handling, but it omits all such details.
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 sentence with no wasted words. It is front-loaded and efficiently conveys the core purpose.
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 should explain what the tool returns (e.g., value type, null for missing property), but it does not. It also lacks details on error cases or behavior for non-existent properties.
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%, yet the description adds no information beyond the parameter names. It does not clarify that 'path' is a file path or 'key' is a YAML key, nor does it specify expected formats or constraints.
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 ('Get') and the resource ('YAML frontmatter property's value from a vault file'). It is specific and distinct from sibling tools like 'set_note_property' and other retrieval tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It does not mention prerequisites, when not to use it, or any context-specific conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List [[wikilinks]] a vault file links out to.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry behavioral disclosure. It only states the action but does not mention any traits like required file existence, permission needs, error cases, or whether empty results are possible. Score 2 for insufficient disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one sentence), which is concise, but it front-loads the key action. However, it would benefit from additional context about the parameter or return value. Score 3 for acceptable conciseness but minimal structure.
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 has only one parameter with no output schema and many sibling tools, the description is incomplete. It does not cover return format, error handling, or usage tips. Score 2 for insufficient 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 0%, meaning the parameter 'path' has no description in the schema. The tool description does not explain what 'path' means (e.g., relative vs absolute, required format). The description adds no value beyond the schema. Score 2 for lack of parameter context.
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 it lists wikilinks from a vault file, using a specific verb and resource. It distinguishes from the sibling get_backlinks (which lists links pointing to the file) but not from other similar tools like get_note_outline. Score 4 for clear purpose but minor differentiation gaps.
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?
No guidance is provided on when to use this tool versus alternatives such as get_backlinks or list_vault_files. There is no mention of prerequisites or context. Score 2 due to lack of usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List vault markdown files sorted by most recently modified first.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the sorting order (most recently modified first), which is a key behavior. However, does not explicitly state read-only nature or other constraints.
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?
Single sentence, no extraneous words. However, slight over-brevity as it omits parameter explanation. Efficient but not maximally informative.
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 simple tool with one optional parameter and no output schema, description adequately conveys core functionality and sorting order. Lacks details on parameter use and possible return format, leaving minor 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?
Parameter 'limit' has 0% schema coverage and is not mentioned in the description. The description adds no meaning beyond the schema's type field. Agent has no guidance on what 'limit' does or its expected 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?
Description clearly states action (list), resource (vault markdown files), and distinguishing feature (sorted by most recently modified first). Differentiates from siblings like list_vault_files and get_files_by_tag.
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?
Implies usage for retrieving recently modified files, but lacks explicit guidance on when to use this tool versus alternatives such as list_vault_files. No exclusions or direct comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the contents of a vault file by its vault-relative path.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It only states that the tool retrieves 'contents', but does not specify whether the output is plain text, markdown, binary, or structured data. It also omits any mention of auth requirements, rate limits, file size limits, or error handling, which are critical for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the core functionality. While slightly more detail might be beneficial, it remains appropriately concise without sacrificing clarity.
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 tool with one parameter and no output schema, the description is minimally adequate. It explains what the tool does and the input needed. However, it lacks details about the return format (e.g., 'contents' is ambiguous), error conditions, or any limitations, leaving the agent with partial information.
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 0% description coverage for the single 'path' parameter, so the description must compensate. The phrase 'vault-relative path' explains that the path is relative to the vault, not an absolute filesystem path, which adds crucial context beyond the schema's bare string type. However, it does not specify format details (e.g., leading slash, allowed characters), which could lead to errors.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and the resource ('contents of a vault file') with the specific qualifier 'by its vault-relative path', which distinguishes it from sibling tools like 'get_vault_file_partial' that retrieve partial content. It uses a specific verb and resource, 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 provides no guidance on when to use this tool versus alternatives such as 'get_vault_file_partial' or 'list_vault_files'. There are no conditions, prerequisites, or exclusions mentioned, leaving the agent to infer appropriate usage without explicit instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the content of a single heading's section from a vault file (heading line through the next same-or-higher-level heading, exclusive).
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| target | Yes | ||
| targetType | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Describes what is returned (heading section exclusive of next same-or-higher). Does not address error behavior (e.g., heading not found, file missing) or edge cases like duplicate headings. Adequate for a simple read 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?
Single sentence with parenthetical clarification. No wasted words, front-loaded with verb and object. Efficiently communicates the core behavior and boundary condition.
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 0% schema coverage and no output schema, the description should provide more context. It captures the essential functional behavior but lacks details on parameter values, error scenarios, and usage nuances. Adequate for a simple tool but incomplete for fully informed invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must add meaning. Only clarifies that targetType is 'heading', but does not explain what 'target' represents (e.g., heading text) or what 'path' is. Leaves two parameters partially or fully undocumented in terms of semantics beyond 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?
Description clearly states the verb 'Get' with specific resource 'content of a single heading's section from a vault file'. It precisely defines boundaries: includes heading line through next same-or-higher-level heading exclusive. This distinguishes it from siblings like get_vault_file (full file) and get_note_outline (structure only).
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?
Implies usage when a specific section under a heading is needed. Does not explicitly exclude alternatives or mention when not to use, but the focused description makes it clear this is for partial content. Lacks explicit when-not and alternative references.
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 across the vault with their occurrence counts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description mentions occurrence counts but lacks details on sorting, pagination, or output format. Annotations are absent, so description carries full burden; more info on return structure would improve 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?
Single concise sentence that front-loads the action and resource, 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?
Adequate for a simple listing tool, but without output schema, the agent might not fully understand the response format (e.g., array of objects).
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?
No parameters, so description adds no value beyond schema. Baseline 4 for 0 parameters.
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 tags with occurrence counts, using a specific verb ('List') and resource ('#tags'), and distinguishes from siblings like get_files_by_tag which filters files.
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?
No explicit guidance on when to use this tool versus alternatives like get_files_by_tag, but the purpose is clear enough for straightforward listing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List markdown (.md) files in the vault, optionally under a subdirectory.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| directory | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description must fully disclose behavior. It states it lists markdown files but omits details such as whether directories are recursed, whether hidden files are included, pagination behavior, or the format of the returned file identifiers. This lack of context reduces 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 a single, concise sentence that is front-loaded with the core action. However, it sacrifices necessary detail for brevity, making it less useful than a slightly longer but more informative 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?
Given the lack of annotations, output schema, and parameter descriptions, the description is insufficient. It does not explain return values, pagination, recursion behavior, or how it compares to the many sibling tools (e.g., get_files_by_tag, search_vault_simple). The tool is moderately complex, requiring more 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?
Schema description coverage is 0%, so the description must clarify parameters. It only mentions 'optionally under a subdirectory' for the directory parameter, with no details on format or default. The limit parameter is not addressed at all, leaving its purpose and constraints ambiguous.
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 'List' and the resource 'markdown (.md) files in the vault', with an optional subdirectory qualifier. This distinguishes it from sibling tools like get_vault_file (retrieves a single file) and get_recent_files (lists recently modified files).
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?
No explicit guidance on when to use this tool versus alternatives. While the description mentions optional subdirectory filtering, it does not compare to related tools like search_vault_simple or get_files_by_tag, nor does it specify when listing files is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Patch a vault file relative to a markdown heading: append/prepend content within the heading's section, or replace the section's content entirely.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| target | Yes | ||
| content | Yes | ||
| operation | Yes | ||
| targetType | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It does not disclose behavioral traits such as whether the operation is destructive, permission requirements, side effects (e.g., what happens if the heading does not exist), or idempotency. The agent has no insight into risks or guarantees.
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, well-structured sentence. It fronts the purpose and lists operations concisely without extraneous information. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 required parameters, no output schema, and no annotations, the description is insufficient. It does not mention return values, error handling, behavior when headings are missing or duplicated, or the effect on file structure. The tool's complexity exceeds the description's coverage.
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 must compensate, but it only mentions parameters superficially (path, target heading, operation, content). It does not explain format constraints (e.g., case sensitivity of target, expected content format), default behaviors, or edge cases. The agent has to infer semantics from parameter names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'patch', the resource 'vault file', and the specific context 'relative to a markdown heading'. It also lists the three operations (append, prepend, replace), which distinguishes it from sibling tools like append_to_vault_file that likely operate on the entire file.
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 when modifying content under a specific heading but provides no explicit guidance on when to use this tool versus alternatives, nor does it state prerequisites or conditions. It lacks exclusion criteria or caveats.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename a heading's text in a vault file, preserving its level.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| newHeading | Yes | ||
| oldHeading | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description alone must disclose behavioral traits. It states the action (rename heading text) and preservation of level, but fails to mention key behaviors: whether it renames only the first occurrence or all, error handling for missing headings, or if the modification is destructive (permanent change).
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 overly concise—one sentence that omits necessary detail. While brevity is valued, it fails to earn its place by not covering parameter usage or behavioral context, making it underspecified.
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 lack of output schema, three undocumented parameters, and no behavioral context, the description is woefully incomplete. The agent cannot safely invoke this tool without guessing behavior for edge cases like missing headings or multiple matches.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not elaborate on any of the three parameters (path, oldHeading, newHeading). The description adds no meaning beyond what the schema's property names imply, leaving the agent to guess format or constraints.
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 ('rename') and resource ('heading's text in a vault file'), and adds the crucial constraint 'preserving its level.' This clearly distinguishes it from sibling tools like 'rename_vault_file' (renames the whole file) or 'search_and_replace' (generic text replacement).
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 such as 'search_and_replace' or 'append_to_vault_file'. Given the diverse sibling list, explicit context on usage scenarios is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename/move a vault file and update [[wikilinks]] referencing its old filename across the vault.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| newPath | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the important side effect of updating wiki links, which is good. However, it does not mention behavior when newPath exists, permission requirements, or other edge cases, and annotations are absent.
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 sentence that front-loads the action (rename/move) and key side effect, with 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?
Given no output schema and minimal parameter info, the description covers the primary function but lacks details on overwrite behavior and path format, which are relevant for correct 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?
Schema description coverage is 0%, and the description does not explain what 'path' and 'newPath' represent (e.g., absolute vs relative paths). While context makes it somewhat inferable, the lack of explicit parameter semantics is a gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool renames or moves a vault file and updates wiki links, which is specific and distinguishes it from sibling tools like rename_heading or delete_vault_file.
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 renaming files with link updates but provides no explicit when-to-use or when-not-to-use guidance, nor does it reference alternatives like rename_heading.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find and replace text across the vault (or a single file). Supports literal or regex patterns.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | ||
| isRegex | No | ||
| pattern | Yes | ||
| replacement | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description only reveals that literal and regex patterns are supported. It fails to disclose that the tool modifies files, potential side effects (e.g., irreversible changes), performance implications, or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) and front-loads the core purpose. However, it is too concise, missing important details without becoming verbose.
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 mutation tool that can affect the entire vault, the description lacks crucial context: no mention of destructive nature, no output schema, no prerequisites. It is not complete enough for safe usage.
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 adds minimal value beyond the schema: it mentions literal/regex support (tying to pattern and isRegex), but does not explain the path parameter (how to scope to a file) or the replacement behavior. With 0% schema coverage, more detail is needed.
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 performs find and replace on text, with scope across the vault or a single file. It stands out from sibling tools which focus on file creation, deletion, or simple edits, making its purpose distinct.
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?
No guidance is provided on when to use this tool versus alternatives like manual editing or other search tools. There is no mention of prerequisites, limitations, or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Case-insensitive substring search across all vault markdown files.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses core behavior (case-insensitive substring search across all markdown files), but does not explain return format (e.g., file paths, snippets) or pagination. Adequate but incomplete.
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 sentence that immediately conveys the tool's purpose. No wasted words; front-loaded with the key functionality.
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 two parameters, no output schema, and no annotations, the description is insufficient for correct agent usage. It omits return value specification and details about the 'limit' parameter, making the tool's complete behavior unclear.
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%. The description explains 'query' as a substring search term, but does not mention 'limit' at all. This leaves the agent to guess its purpose or constraints.
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 'Case-insensitive substring search across all vault markdown files', which specifies the verb (search), resource (vault markdown files), and scope (all). This distinguishes it from sibling tools like list_vault_files or search_and_replace.
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 provide any guidance on when to use this tool versus alternatives (e.g., search_and_replace, get_vault_file). No when-to-use, when-not-to-use, or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set (or add) a YAML frontmatter property on a vault file, creating a frontmatter block if none exists.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | ||
| path | Yes | ||
| value | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that the tool creates a frontmatter block if none exists, which is a key behavioral trait. However, it does not mention overwrite behavior or file existence handling.
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 sentence with no wasted words. It concisely conveys the essential action and boundary condition.
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 tool with 3 required parameters and no output schema, the description covers the core action but lacks parameter documentation and usage context. It is minimally adequate but has clear 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 0%, yet the description provides no explanation of the parameters (key, path, value) beyond their names. It fails to add meaning about types, constraints, or roles, making it insufficient for selecting and invoking the tool correctly.
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 specifies the action ('set or add') and the resource ('YAML frontmatter property on a vault file'), and distinguishes from sibling tools like get_note_property. It also clarifies the behavior of creating a frontmatter block if none exists.
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 (when setting a frontmatter property) but does not explicitly state when not to use it or mention alternatives. It lacks guidance on distinguishing from similar tools like patch_vault_file.
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.
v1.0.0append_to_vault_filecreate_vault_directorycreate_vault_filedelete_vault_directorydelete_vault_fileget_backlinksget_files_by_tagget_note_outlineget_note_propertyget_outgoing_linksget_recent_filesget_vault_fileget_vault_file_partiallist_tagslist_vault_filespatch_vault_filerename_headingrename_vault_filesearch_and_replacesearch_vault_simpleset_note_propertyScored across 21 tools
Each tool has a clearly distinct purpose, from file/directory CRUD to specialized operations like heading manipulation, tag listing, and link tracking. Overlaps are minimal and well-differentiated.
All tools follow a consistent verb_noun pattern in snake_case, e.g., create_vault_file, get_backlinks, search_and_replace. This pattern is predictable and aids agent understanding.
With 21 tools, the set is well-scoped for managing an Obsidian vault. It covers essential operations without being overwhelming.
The tool surface covers file/directory CRUD, search, tag management, link tracking, frontmatter properties, and heading operations. No obvious gaps for typical vault management tasks.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
An MCP server that used to create notes
