This server enables AI agents to deeply interact with Obsidian vaults through the Local REST API, providing comprehensive file management, search, vault analysis, and command execution capabilities.
File Management: Create or update files, append content, patch files (insert content relative to headings, blocks, or frontmatter), delete files/directories, batch read multiple files, and list directory contents.
Search & Discovery: Perform simple text searches or complex JsonLogic queries with glob and regex support for advanced pattern matching across vault content and paths.
Vault Analysis & Context: Generate comprehensive vault structure including directory trees and NetworkX graph visualizations of note connections, access the currently active note for real-time context, track recently modified files, and open files in new Obsidian leaves.
Periodic Notes: Retrieve current or recent daily, weekly, monthly, quarterly, and yearly notes with optional content inclusion.
Command Execution: List all available Obsidian interface commands and execute one or more commands directly within Obsidian for seamless automation.
Supports loading environment variables from .env files for configuration, including settings for API keys, host, port, vault path, and tool selection.
Allows interaction with Obsidian via the Local REST API plugin, enabling advanced operations like vault structure analysis, note content management, search operations, and NetworkX graph analysis of note connections. Features include reading/writing files, executing Obsidian commands, accessing active notes, and manipulating vault structure.
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., "@Advanced Obsidian MCP Server search for all notes mentioning project Alpha and summarize their connections"
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.
Advanced MCP server for interacting with Obsidian via the Local REST API community plugin. It empowers AI agents (like Claude) to deeply understand your vault's structure, links, and content—beyond basic read/write operations.
Key advanced features, powered by the obsidiantools library:
Vault tree structure discovery to map your note hierarchy
NetworkX graph analysis of note connections for LLM-friendly insights
Execution of Obsidian commands directly from AI
Batch file reading with metadata and link details
Access to your currently active note for real-time context
Opening notes/files in new Obsidian leaves for seamless editing
This setup lets AI agents work alongside you, boosting productivity by efficiently navigating and enhancing your knowledge base.
The server implements multiple tools to interact with Obsidian:
obsidian_list_files_in_dir: Lists all files and directories in a specific Obsidian directory
obsidian_batch_get_files: Return the contents and metadata of one or more notes (.md files) in your vault
obsidian_put_file: Create a new file in your vault or update the content of an existing one
obsidian_append_to_file: Append content to a new or existing file in the vault
obsidian_patch_file: Insert content into an existing note relative to a heading, block reference, or frontmatter field
obsidian_delete_file: Delete a file or directory from your vault
obsidian_simple_search: Simple search for documents matching a specified text query across all files in the vault
obsidian_complex_search: Complex search for documents using a JsonLogic query with support for 'glob' and 'regexp' pattern matching
obsidian_get_active_note: Get the content and metadata of the currently active note in Obsidian
obsidian_periodic_notes: Get current periodic note for the specified period (daily, weekly, monthly, quarterly, yearly)
obsidian_recent_periodic_notes: Get most recent periodic notes for the specified period type
obsidian_recent_changes: Get recently modified files in the vault
NOTE: This tool requires the Dataview community plugin to function. Make sure to install the Dataview plugin in your vault.
obsidian_understand_vault: Get a comprehensive understanding of the vault structure including directory tree and NetworkX graph of note connections
obsidian_open_files: Open one or more files in the vault in a new leaf
obsidian_list_commands: List all available commands you can run in obsidian interface
obsidian_execute_commands: Execute one or more commands in obsidian interface
Its good to first instruct Claude (or any other MCP client) to use Obsidian. Then it will always call the tool. For instance,
The use prompts like this:
"Expand on the Marketing section of the report I'm currently working on in obsidian"
Claude will use obsidian_get_active_note, read it, then edit the note.
"Search for all files where Azure CosmosDb is mentioned and quickly explain to me the context in which it is mentioned"
"Summarize the last meeting notes and put them into a new note 'summary meeting.md'. Add an introduction so that I can send it via email."
Related MCP server: Obsidian MCP Server
For this MCP server, there are 2 required environment variables that need to be configured:
OBSIDIAN_API_KEY: Obtain this by installing the Obsidian REST API plugin, and go into settings.
OBSIDIAN_VAULT_PATH: The absolute path to your vault must be set in order for tools (e.g. obsidian_understand_vault) to function properly.
Additionally, there are 3 optional environment variables that could be altered:
OBSIDIAN_HOST: Could be changed in the Obsidian REST API plugin settings. Defaults to 127.0.0.1 as per the plugin's default settings.
OBSIDIAN_PORT: Could be changed in the Obsidian REST API plugin settings. Defaults to 27124 as per the plugin's default settings.
INCLUDE_TOOLS: This variable controls which tools would be available for use.
Write the name of the tool(s) you want to include (name listed above), separated by commas.
For instance, if you only want the obsidian_understand_vault and obsidian_simple_search tool, you would set INCLUDE_TOOLS="obsidian_understand_vault,obsidian_simple_search" in the .env or in the server config.
There are two ways to configure the environment with the Obsidian REST API Key.
Add to server config (PREFERRED):
{
"mcp-obsidian-advanced": {
"command": "uvx",
"args": [
"mcp-obsidian-advanced"
],
"env": {
"OBSIDIAN_API_KEY": "%3Cyour_api_key_here%3E",
"OBSIDIAN_HOST": "<your_obsidian_host>",
"OBSIDIAN_PORT": "<your_obsidian_port>",
"OBSIDIAN_VAULT_PATH": "</path/to/your/vault>",
"INCLUDE_TOOLS": ""
}
}
}Sometimes Claude has issues detecting the location of uv / uvx. You can use
which uvxto find and paste the full path in above config in such cases.
Create a .env file in the working directory with the following variables (only OBSIDIAN_API_KEY and OBSIDIAN_VAULT_PATH are required):
OBSIDIAN_API_KEY=your_api_key_here
OBSIDIAN_HOST=your_obsidian_host
OBSIDIAN_PORT=your_obsidian_port
OBSIDIAN_VAULT_PATH=/path/to/your/vault
INCLUDE_TOOLS=name_of_tool1,name_of_tool2,...Note: You can find the API key, Host and Port in the Obsidian plugin config Default port is 27124 if not specified Default host is 127.0.0.1 if not specified
To install Advanced Obsidian MCP Server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @ToKiDoO/mcp-obsidian-advanced --client claudeYou need the Obsidian REST API community plugin running: https://github.com/coddingtonbear/obsidian-local-rest-api
You can install it by going to "Community Plugins" in Obsidian, search it up.
Install and enable it in the settings and copy the api key.
On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%/Claude/claude_desktop_config.json
Published Servers Configuration:
{
"mcpServers": {
"mcp-obsidian-advanced": {
"command": "uvx",
"args": [
"mcp-obsidian-advanced"
],
"env": {
"OBSIDIAN_API_KEY": "<your_api_key_here>",
"OBSIDIAN_VAULT_PATH": "/path/to/your/vault/"
}
}
}
}Development/Unpublished Servers Configuration
{
"mcpServers": {
"mcp-obsidian": {
"command": "uv",
"args": [
"--directory",
"/dir/to/mcp-obsidian-advanced",
"run",
"mcp-obsidian"
],
"env": {
"OBSIDIAN_API_KEY": "<your_api_key_here>",
"OBSIDIAN_VAULT_PATH": "/path/to/your/vault/"
}
}
}
}Additional documentation for the obsidiantools library and Obsidian REST API can be found in the docs directory.
obsidiantools_in_15_minutes_documentation.md is a ipynb file that demonstrates use cases for obsidiantools.
obsidian_rest_api_documentation.yaml is a yaml file that demonstrates use cases for the Obsidian REST API.
To prepare the package for distribution:
Sync dependencies and update lockfile:
uv syncSince MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we strongly recommend using the MCP Inspector.
You can launch the MCP Inspector via npm with this command:
npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-obsidian-advanced run mcp-obsidian-advancedUpon launching, the Inspector will display a URL that you can access in your browser to begin debugging.
You can also watch the server logs with this command:
tail -n 20 -f ~/Library/Logs/Claude/mcp-server-mcp-obsidian-advanced.logAppend content to a new or existing file in the vault.
| Name | Required | Description | Default |
|---|---|---|---|
| filepath | Yes | Path to the file (relative to vault root) | |
| content | Yes | Content to append to the file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but lacks behavioral details. It states 'Append content' implying mutation, but doesn't disclose permissions needed, whether appending is additive or destructive to existing content, error handling (e.g., if file doesn't exist), or rate limits. This is a significant gap for a mutation tool with zero annotation coverage.
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 zero waste. It front-loads the core action ('Append content') and target, making it easy to parse. Every word earns its place, achieving maximum clarity with minimal 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 the tool's complexity (a mutation operation with 2 parameters), no annotations, and no output schema, the description is incomplete. It lacks details on behavioral traits, error conditions, return values, and differentiation from siblings. For a tool that modifies files, this minimal description leaves critical 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 100%, so the schema fully documents both parameters (filepath and content). The description adds no additional meaning beyond what the schema provides, such as format details or usage examples. Baseline 3 is appropriate when the schema does the heavy lifting, but no extra value is contributed.
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 target ('to a new or existing file in the vault'), specifying the verb and resource. It distinguishes from siblings like obsidian_delete_file (deletion) and obsidian_patch_file (partial update), though not explicitly named. However, it doesn't fully differentiate from obsidian_put_file (which might overwrite vs. append), leaving some ambiguity.
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 like obsidian_put_file (for overwriting) or obsidian_patch_file (for partial updates). It mentions 'new or existing file' but doesn't clarify prerequisites (e.g., file must exist for appending vs. creation) or exclusions, offering only implied usage without explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the contents and metadata of one or more notes (.md files) in your vault.
| Name | Required | Description | Default |
|---|---|---|---|
| filepaths | Yes | List of file paths to read |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the tool reads files and returns content/metadata, but lacks details on permissions needed, error handling for non-existent files, rate limits, or return format. It adds basic behavioral context but leaves gaps for a 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?
The description is a single, efficient sentence that front-loads the core purpose ('Return the contents and metadata') without wasted words. Every part earns its place by specifying scope and resource.
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 annotations and no output schema, the description is minimally complete for a read tool with one parameter. It covers what the tool does but lacks details on output structure, error cases, or vault-specific constraints. Adequate but with clear gaps in behavioral 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 100%, so the schema fully documents the single parameter 'filepaths'. The description adds no additional parameter semantics beyond implying multiple files can be specified, which is already clear from the schema's array type. Baseline 3 is appropriate as the schema does the heavy lifting.
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 ('Return') and target resource ('contents and metadata of one or more notes (.md files) in your vault'), specifying both verb and resource. It distinguishes from siblings like obsidian_get_active_note (single active note) and obsidian_list_files_in_dir (list files without 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 implies usage for reading multiple notes by specifying 'one or more notes', providing clear context. However, it doesn't explicitly state when not to use it (e.g., vs. obsidian_simple_search for filtered content) or name alternatives, missing explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Complex search for documents using a JsonLogic query. Supports standard JsonLogic operators plus 'glob' and 'regexp' for pattern matching. Results must be non-falsy.
Use this tool when you want to do a complex search, e.g. for all documents with certain tags etc.
ALWAYS follow query syntax in examples.
Examples
1. Match all markdown files
{"glob": ["*.md", {"var": "path"}]}
2. Match all markdown files with 1221 substring inside them
{
"and": [
{ "glob": ["*.md", {"var": "path"}] },
{ "regexp": [".*1221.*", {"var": "content"}] }
]
}
3. Match all markdown files in Work folder containing name Keaton
{
"and": [
{ "glob": ["*.md", {"var": "path"}] },
{ "regexp": [".*Work.*", {"var": "path"}] },
{ "regexp": ["Keaton", {"var": "content"}] }
]
}
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | JsonLogic query object. ALWAYS follow query syntax in examples. Example 1: {"glob": ["*.md", {"var": "path"}]} matches all markdown files Example 2: {"and": [{"glob": ["*.md", {"var": "path"}]}, {"regexp": [".*1221.*", {"var": "content"}]}]} matches all markdown files with 1221 substring inside them Example 3: {"and": [{"glob": ["*.md", {"var": "path"}]}, {"regexp": [".*Work.*", {"var": "path"}]}, {"regexp": ["Keaton", {"var": "content"}]}]} matches all markdown files in Work folder containing name Keaton |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It effectively discloses key behavioral traits: it's a read-only search operation (implied by 'search'), supports JsonLogic with extensions ('glob' and 'regexp'), and specifies that 'Results must be non-falsy.' It doesn't mention pagination, rate limits, or authentication needs, but covers core functionality well.
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 clear sections: purpose, usage guidelines, and examples. It's appropriately sized for a complex tool, though the examples are lengthy. Every sentence adds value, but it could be more front-loaded by moving the usage guidance closer to the beginning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (JsonLogic queries, pattern matching), no annotations, and no output schema, the description does a good job. It explains the query language, provides examples, and specifies result requirements. However, it doesn't describe the output format (e.g., what fields are returned), which is a gap since there's no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds significant value beyond the schema by explaining the JsonLogic operators ('standard JsonLogic operators plus 'glob' and 'regexp' for pattern matching'), providing three detailed examples with explanations, and emphasizing 'ALWAYS follow query syntax in examples.' This compensates for the schema's technical nature.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Complex search for documents using a JsonLogic query.' It specifies the resource (documents) and method (JsonLogic query), and distinguishes it from sibling 'obsidian_simple_search' by emphasizing complexity and additional operators like 'glob' and 'regexp'.
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 explicit guidance: 'Use this tool when you want to do a complex search, e.g. for all documents with certain tags etc.' It distinguishes from simpler alternatives by naming the use case, though it doesn't explicitly list when NOT to use it or name all alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a file or directory from the vault.
| Name | Required | Description | Default |
|---|---|---|---|
| filepath | Yes | Path to the file or directory to delete (relative to vault root) | |
| confirm | Yes | Confirmation to delete the file (must be true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('Delete') but lacks critical details: whether deletion is permanent or reversible, what happens to nested directories, error conditions (e.g., non-existent paths), or permissions required. For a destructive operation with zero annotation coverage, this is a significant gap.
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 that front-loads the core action ('Delete a file or directory'). There is no wasted verbiage or redundancy, making it highly concise and well-structured for quick comprehension.
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 destructive nature, lack of annotations, and no output schema, the description is incomplete. It doesn't address safety considerations (e.g., irreversible deletion), error handling, or return values. For a delete operation, this leaves critical gaps in understanding behavioral outcomes.
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 clear descriptions for both parameters ('filepath' and 'confirm'). The description adds no additional parameter semantics beyond what the schema provides (e.g., it doesn't explain path formatting or why 'confirm' is required). Baseline 3 is appropriate when the schema does the heavy lifting.
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 file or directory from the vault'), making the purpose immediately understandable. It doesn't explicitly distinguish from sibling tools like 'obsidian_patch_content' or 'obsidian_put_content' (which modify rather than delete), but the verb 'Delete' is specific enough for basic differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., file must exist), exclusions (e.g., cannot delete locked files), or sibling tools for related operations like 'obsidian_list_files_in_vault' to check existence first. Usage is implied only by the action itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute one or more commands in obsidian interface, in order. For commands used on specific notes, make sure to open a note first.
| Name | Required | Description | Default |
|---|---|---|---|
| commands | Yes | List of commands to execute |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions execution order ('in order') and a prerequisite for note-specific commands, but fails to cover critical aspects like whether this tool is read-only or destructive, what permissions are needed, error handling, or rate limits. This leaves significant gaps in understanding the tool's 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 appropriately sized with two sentences that are front-loaded: the first states the core purpose, and the second adds a specific usage note. There's no wasted text, though it could be slightly more structured for 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?
Given the complexity of executing commands in an interface, the lack of annotations, and no output schema, the description is incomplete. It misses details on return values, error cases, side effects, and how it interacts with sibling tools, making it inadequate for safe and effective use by 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?
The input schema has 100% description coverage, clearly documenting the 'commands' parameter as a list of strings. The description adds minimal value beyond this by emphasizing execution order and note-related context, but doesn't provide additional semantic details like command examples, format, or constraints. This meets the baseline for high 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 the action ('Execute one or more commands in obsidian interface') and specifies the resource ('obsidian interface'), making the purpose understandable. However, it doesn't explicitly differentiate this tool from sibling tools like 'obsidian_list_commands' or 'obsidian_understand_vault' beyond the execution aspect, which prevents a perfect score.
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 implied usage guidance by mentioning 'For commands used on specific notes, make sure to open a note first,' which suggests a prerequisite context. However, it lacks explicit when-to-use vs. alternatives (e.g., compared to 'obsidian_list_commands' or other sibling tools) and doesn't specify exclusions, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the content and metadata of the currently active note in Obsidian. Always returns the note that is most recently edited (edit with user).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that it returns content and metadata, and clarifies the note selection as 'most recently edited', which adds useful context. However, it doesn't cover other behavioral aspects such as error handling, performance, or whether it requires specific permissions or has side effects, leaving gaps for a tool with no annotation support.
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 front-loaded and concise, consisting of two clear sentences that directly explain the tool's purpose and behavior without any wasted words. Every sentence adds value, making it efficient and well-structured.
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 no parameters, no annotations, and no output schema, the description provides basic purpose and selection criteria. However, for a tool that retrieves note content and metadata, it lacks details on the return format, potential errors, or how 'active' is defined in edge cases, making it adequate but incomplete for full contextual understanding.
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 has 0 parameters with 100% coverage, so no parameter information is needed. The description appropriately adds no parameter details, focusing on the tool's function instead. This meets the baseline for zero parameters, as it doesn't need to compensate for any schema gaps.
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 resource ('content and metadata of the currently active note in Obsidian'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from siblings like 'obsidian_recent_changes' or 'obsidian_open_files', which might also relate to note access or state.
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 specifying 'currently active note' and 'most recently edited', suggesting it should be used when the user needs the latest edited note. However, it lacks explicit guidance on when to use this tool versus alternatives like 'obsidian_recent_changes' or 'obsidian_open_files', and doesn't mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available commands you can run in obsidian interface. For commands used on specific notes, make sure to open a note first.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The description mentions that it 'lists' commands, which implies a read-only operation, but it doesn't specify whether this requires specific permissions, what the output format looks like, or if there are any rate limits or constraints. For a tool with zero annotation coverage, this leaves significant gaps in understanding its 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 two sentences, each serving a distinct purpose: the first states the tool's function, and the second provides a usage tip. There is no wasted language, and the information is front-loaded with the core purpose. This is an excellent example of concise and well-structured description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is adequate but could be more complete. It explains what the tool does and offers a usage tip, but without annotations or output schema, it doesn't fully cover behavioral aspects like response format or constraints. This meets the minimum viable standard for such a 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 has 0 parameters with 100% coverage, so no parameter information is needed. The description appropriately adds no parameter details, focusing instead on usage context. This aligns with the baseline expectation for tools with no parameters, earning a high score for not cluttering the description with unnecessary information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List all available commands you can run in obsidian interface.' This specifies the verb ('list') and resource ('available commands'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from sibling tools like 'obsidian_execute_commands' or 'obsidian_understand_vault', which prevents a perfect score.
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 some usage guidance with the second sentence: 'For commands used on specific notes, make sure to open a note first.' This implies a prerequisite context for certain commands, but it doesn't explicitly state when to use this tool versus alternatives like 'obsidian_execute_commands' or other siblings. The guidance is helpful but incomplete for distinguishing between tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists all files and directories that exist in a specific Obsidian directory.
| Name | Required | Description | Default |
|---|---|---|---|
| dirpath | Yes | Path to list files from (relative to your vault root). Note that empty directories will not be returned. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the core function (listing files/directories) and notes that empty directories are not returned (via schema description), but does not disclose other behavioral traits such as permissions needed, rate limits, output format, pagination, or error handling. It adds some context but leaves significant gaps for a tool with no annotation coverage.
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 that directly states the tool's purpose without unnecessary words. It is front-loaded with the core action and scope, making it easy to parse. Every part of the sentence contributes essential information, earning its place with zero waste.
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 annotations, no output schema, and a simple single-parameter input schema, the description provides basic completeness for a read-only listing tool. However, it lacks details on output structure (e.g., format of returned list), error conditions, or integration with sibling tools. It is minimally viable but has clear gaps in contextual information that could aid 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 100%, with the single parameter 'dirpath' fully documented in the schema (path relative to vault root, empty directories not returned). The description does not add any parameter-specific semantics beyond what the schema provides, such as format examples or edge cases. Baseline 3 is appropriate as the schema handles parameter documentation adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Lists') and resource ('all files and directories') with specific scope ('in a specific Obsidian directory'). It distinguishes from sibling 'obsidian_list_files_in_vault' by specifying directory-level rather than vault-wide listing, though not explicitly named. The purpose is unambiguous but could be more explicit about the 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?
The description implies usage context (directory-level listing) but does not explicitly state when to use this tool versus alternatives like 'obsidian_list_files_in_vault' or file-content tools. It provides no guidance on prerequisites, exclusions, or comparative scenarios. The context is clear but lacks explicit alternative naming or when-not-to-use advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open one or more files in the vault in a new leaf.
| Name | Required | Description | Default |
|---|---|---|---|
| filepaths | Yes | List of file paths to open |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Open') and outcome ('in a new leaf'), implying a read operation that may involve UI changes, but doesn't specify permissions, side effects (e.g., if files must exist), error handling, or what 'new leaf' entails (e.g., tab, window). This is a significant gap for a tool with potential user interface impacts.
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 that front-loads the core action and outcome. Every word earns its place, with no redundancy or unnecessary details. It's appropriately sized for a straightforward tool.
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 moderate complexity (opening files with UI implications), no annotations, and no output schema, the description is minimally adequate. It covers the basic purpose but lacks details on behavior, error cases, or return values. It meets the minimum viable threshold but has clear gaps in contextual 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?
Schema description coverage is 100%, with the parameter 'filepaths' fully documented in the schema as an array of file paths relative to the vault root. The description adds no additional meaning beyond the schema, such as format examples or constraints. Baseline 3 is appropriate since the schema does the heavy lifting.
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 ('Open') and resource ('one or more files in the vault'), specifying the outcome ('in a new leaf'). It distinguishes from siblings like obsidian_get_active_note (retrieves content) or obsidian_list_files_in_dir (lists files), but doesn't explicitly differentiate from all siblings. The purpose is specific but not fully contrasted with every alternative.
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. It doesn't mention prerequisites (e.g., file existence), exclusions, or compare to siblings like obsidian_get_active_note for viewing current content or obsidian_simple_search for finding files first. Usage is implied but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert content into an existing note relative to a heading, block reference, or frontmatter field.
| Name | Required | Description | Default |
|---|---|---|---|
| filepath | Yes | Path to the file (relative to vault root) | |
| operation | Yes | Operation to perform (append, prepend, or replace) | |
| target_type | Yes | Type of target to patch | |
| target | Yes | Target identifier (heading path, block reference, or frontmatter field) | |
| content | Yes | Content to insert |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states what the tool does, not how it behaves. It doesn't disclose whether this modifies files permanently, requires specific permissions, handles errors, or has any side effects. For a file modification tool with zero annotation coverage, this leaves critical behavioral aspects undocumented.
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 that's perfectly front-loaded with all essential information. No wasted words, no unnecessary elaboration - every word earns its place in conveying the tool's core functionality efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a file modification tool with 5 parameters, no annotations, and no output schema, the description is insufficient. It explains what the tool does but not how it behaves, what it returns, or potential consequences. The agent would need to guess about error handling, file locking, or whether changes are reversible.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 5 parameters thoroughly. The description adds minimal value beyond what's in the schema - it mentions 'heading, block reference, or frontmatter field' which aligns with target_type enum values but doesn't provide additional context about parameter interactions or usage patterns.
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 specific action ('Insert content'), target resource ('existing note'), and positioning method ('relative to a heading, block reference, or frontmatter field'). It distinguishes from sibling tools like obsidian_append_to_file by specifying targeted insertion rather than simple appending.
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 obsidian_append_to_file or obsidian_put_file. The description implies usage for targeted content insertion but doesn't specify scenarios, prerequisites, or exclusions that would help an agent choose between similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current periodic note for the specified period. Returns both comprehensive metadata (tags, links, titles, etc.) and note content using the enhanced API approach.
| Name | Required | Description | Default |
|---|---|---|---|
| period | Yes | The period type (daily, weekly, monthly, quarterly, yearly) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'enhanced API approach' but doesn't clarify behavioral traits like error handling, performance, or side effects. It states it returns metadata and content, but lacks details on format, pagination, or limitations.
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 front-loaded with the core purpose and efficiently structured in two sentences. However, the second sentence could be more concise by integrating 'enhanced API approach' into the first sentence to reduce 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 moderate complexity (single parameter, no output schema, no annotations), the description is minimally adequate. It covers what the tool does but lacks details on output format, error conditions, and usage context, leaving gaps for an AI agent to infer behavior.
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 the parameter 'period' fully documented in the schema. The description adds no additional meaning beyond the schema, such as examples or edge cases, so it meets the baseline of 3 without compensating for any gaps.
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 resource ('current periodic note'), specifying it retrieves both metadata and content. It distinguishes from siblings like obsidian_get_active_note by focusing on periodic notes, but doesn't explicitly differentiate from obsidian_recent_periodic_notes, which might have overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when-not scenarios or prerequisites, and with siblings like obsidian_recent_periodic_notes available, there's no indication of which to choose for different use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new file in your vault or update the content of an existing one in your vault.
| Name | Required | Description | Default |
|---|---|---|---|
| filepath | Yes | Path to the relevant file (relative to your vault root) | |
| content | Yes | Content of the file you would like to upload |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions creating or updating files, implying mutation, but fails to detail critical aspects like whether it overwrites existing content entirely, requires specific permissions, or handles errors. This leaves significant gaps in understanding the tool's 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, efficient sentence that directly states the tool's function without unnecessary words. It is front-loaded and wastes no space, making it highly concise and well-structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity as a file mutation operation with no annotations and no output schema, the description is insufficient. It lacks details on behavioral traits, error handling, or return values, making it incomplete for safe and effective use by an AI agent in a vault environment.
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 has 100% description coverage, clearly documenting both parameters ('filepath' and 'content'). The description adds no additional semantic details beyond what the schema provides, such as file format constraints or content handling specifics, so it meets the baseline for adequate but unenhanced parameter information.
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 ('create' or 'update') and resource ('file in your vault'), making the purpose evident. However, it does not explicitly differentiate from sibling tools like 'obsidian_append_to_file' or 'obsidian_patch_file', which also modify files, so it lacks sibling distinction for a perfect score.
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 'obsidian_append_to_file' for appending content or 'obsidian_patch_file' for partial updates. It also omits prerequisites like file permissions or vault accessibility, leaving usage context unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get recently modified files in the vault.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of files to return (default: 10) | |
| days | No | Only include files modified within this many days (default: 90) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool retrieves files but lacks details on permissions, rate limits, error handling, or the return format (e.g., list structure, metadata included). This is a significant gap for a tool with potential operational 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?
The description is a single, efficient sentence that directly states the tool's function without unnecessary words. It is front-loaded and easy to parse, making it highly concise and well-structured for quick understanding.
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 (2 parameters, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose but lacks details on behavioral aspects and usage context, which are needed for a complete understanding, especially without annotations to fill in gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, clearly documenting both parameters ('limit' and 'days') with defaults and constraints. The description does not add any parameter-specific information beyond what the schema provides, so it meets the baseline score of 3 for adequate but no extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Get') and resource ('recently modified files in the vault'), making it immediately understandable. However, it does not explicitly differentiate from sibling tools like 'obsidian_list_files_in_dir' or 'obsidian_simple_search', which might also list files under different criteria, so it falls short of a perfect score.
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. It does not mention scenarios where this tool is preferred over siblings like 'obsidian_list_files_in_dir' for listing all files or 'obsidian_simple_search' for filtered searches, leaving the agent to infer usage based on the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get most recent periodic notes for the specified period type. When include_content=True, return notes' comprehensive metadata (tags, links, titles, etc.) and note content using the enhanced API approach.
| Name | Required | Description | Default |
|---|---|---|---|
| period | Yes | The period type (daily, weekly, monthly, quarterly, yearly) | |
| limit | No | Maximum number of notes to return (default: 5) | |
| include_content | No | Whether to include note content and comprehensive metadata (default: false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the include_content behavior (comprehensive metadata vs. basic) and mentions 'enhanced API approach', adding some context. However, it doesn't cover rate limits, error conditions, or what 'most recent' means temporally (e.g., by creation date, modification date).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose. The second sentence efficiently explains the include_content parameter effect. No wasted words, though it could be slightly more structured (e.g., bullet points for behaviors).
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 annotations and no output schema, the description is moderately complete for a read operation. It covers the core purpose and key parameter effect, but lacks details on return format (e.g., structure of returned notes), error handling, or pagination behavior. Adequate but with 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 100%, so the schema fully documents all parameters. The description adds marginal value by explaining the effect of include_content=True ('comprehensive metadata... and note content'), but doesn't provide additional semantics beyond what's in the schema. Baseline 3 is appropriate.
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 resource ('most recent periodic notes'), specifying the period type parameter. It distinguishes from sibling 'obsidian_periodic_notes' by focusing on 'most recent' notes, though the distinction could be more explicit. The purpose is specific and actionable.
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 context by mentioning 'most recent' and the include_content parameter effect, but doesn't explicitly state when to use this tool versus alternatives like 'obsidian_periodic_notes' or 'obsidian_recent_changes'. No explicit when-not or prerequisite guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Simple search for documents matching a specified text query across all files in the vault. Use this tool when you want to do a simple text search
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Text to a simple search for in the vault. | |
| context_length | No | How much context to return around the matching string (default: 300) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions that the search is 'simple' and 'across all files,' but doesn't describe key behaviors such as whether it's case-sensitive, how results are returned (e.g., format, pagination), performance implications, or error handling. For a search tool with zero annotation coverage, this leaves significant gaps in understanding its operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences that directly state the purpose and usage. It's front-loaded with the core functionality and avoids unnecessary details. However, the second sentence is somewhat redundant with the first, slightly reducing efficiency, but overall it's well-structured and to the point.
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 moderate complexity (search function with 2 parameters), no annotations, and no output schema, the description is minimally adequate. It covers the basic purpose and usage but lacks details on behavior, output format, and differentiation from siblings. It meets the minimum viable threshold but has clear gaps that could hinder effective tool selection and 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 100%, so the input schema already documents both parameters ('query' and 'context_length') with descriptions. The description adds no additional parameter semantics beyond what's in the schema, such as examples of query syntax or how context_length affects output. With high schema coverage, the baseline score of 3 is appropriate as the description doesn't enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Simple search for documents matching a specified text query across all files in the vault.' It specifies the verb ('search'), resource ('documents'), and scope ('across all files in the vault'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from its sibling 'obsidian_complex_search' beyond the 'simple' qualifier, which is somewhat vague.
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 some guidance with 'Use this tool when you want to do a simple text search,' which implies usage for basic searches. However, it doesn't specify when to use this versus 'obsidian_complex_search' or other search-related tools, nor does it mention any prerequisites or exclusions. The guidance is implied but lacks explicit alternatives or detailed context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a comprehensive understanding of the vault structure. Returns: 1. directory tree representation and 2. NetworkX graph of note connections used to understand how different notes (.md) and other files (e.g. images, PDFs, referenced/attached) are connected. Combines filesystem directory structure with note relationship graph between notes (.md files).
| Name | Required | Description | Default |
|---|---|---|---|
| directory_path | No | Optional path to a subdirectory to analyze, defaults to vault root | |
| include_attachments_in_graph | No | Whether to include attachment files (images, PDFs, etc.) in the *NetworkX connections graph*, excluding attachments in Obsidian. Defaults to True | |
| include_other_files_in_tree | No | Whether to show only .md files in the *directory tree structure*, excluding other file types. Defaults to True |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It describes what the tool returns (directory tree and NetworkX graph) and the scope of analysis, but lacks details about performance characteristics, error conditions, or what 'comprehensive understanding' entails. It doesn't mention whether this is a read-only operation or has side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with the main purpose. All sentences contribute value by explaining outputs and scope, though it could be slightly more concise by combining some concepts about what's included in the analysis.
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 parameters, 100% schema coverage, but no annotations or output schema, the description provides adequate context about what the tool does and returns. However, it lacks details about the format/structure of the returned data and behavioral characteristics that would be helpful 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 100%, so the schema already documents all three parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema, maintaining the baseline score of 3 for high 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 the tool's purpose: 'Get a comprehensive understanding of the vault structure' with specific outputs (directory tree and NetworkX graph) and scope (combines filesystem structure with note relationships). It distinguishes from siblings like obsidian_list_files_in_dir by emphasizing comprehensive analysis rather than simple listing.
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 understanding vault structure and connections, but doesn't explicitly state when to use this tool versus alternatives like obsidian_list_files_in_dir or obsidian_complex_search. No specific exclusions 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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
obsidian_append_to_fileobsidian_batch_get_filesobsidian_complex_searchobsidian_delete_fileobsidian_execute_commandsobsidian_get_active_noteobsidian_list_commandsobsidian_list_files_in_dirobsidian_open_filesobsidian_patch_fileobsidian_periodic_notesobsidian_put_fileobsidian_recent_changesobsidian_recent_periodic_notesobsidian_simple_searchobsidian_understand_vaultScored across 16 tools
Most tools have distinct purposes, but there is some overlap between obsidian_simple_search and obsidian_complex_search that could cause confusion. The descriptions help differentiate them, but both are search tools with similar naming, which might lead to misselection if an agent isn't careful. Other tools like obsidian_append_to_file and obsidian_patch_file are clearly distinct in their file modification roles.
All tool names follow a consistent snake_case pattern with the prefix 'obsidian_' followed by a descriptive verb_noun combination. This uniformity makes the tools predictable and easy to understand, such as obsidian_list_files_in_dir, obsidian_delete_file, and obsidian_get_active_note. There are no deviations in naming conventions across the set.
With 16 tools, the count is slightly high but reasonable for an advanced Obsidian server that aims to provide comprehensive vault management. It covers a wide range of operations from file CRUD to search and vault analysis, though it might feel a bit heavy compared to simpler servers. Each tool appears to have a specific role, justifying its inclusion without excessive redundancy.
The tool set provides complete coverage for managing an Obsidian vault, including CRUD operations (e.g., obsidian_put_file, obsidian_delete_file), search capabilities (simple and complex), file navigation (list, open), vault understanding, and specialized features like periodic notes and command execution. There are no obvious gaps; agents can perform all typical workflows without dead ends.
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.
Search your Obsidian vault to quickly find notes by title or keyword, summarize related content, a…
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
