Exposes an Obsidian vault to AI assistants, enabling operations such as reading, writing, searching, and managing notes, tags, frontmatter, and links.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-obsidian search my notes for 'marketing strategy' and summarize the latest one"
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.
An MCP server that exposes your Obsidian vault to AI assistants via the Model Context Protocol.
Python 3.12+
Related MCP server: Obsidian MCP Tool Server
git clone https://github.com/johnkang/mcp-obsidian
cd mcp-obsidian
uv syncSet the OBSIDIAN_VAULT_PATH environment variable to the absolute path of your vault, then run the server:
OBSIDIAN_VAULT_PATH=/path/to/your/vault uv run mcp-obsidianAdd the following to your claude_desktop_config.json:
{
"mcpServers": {
"obsidian": {
"command": "uv",
"args": ["run", "--directory", "/path/to/mcp-obsidian", "mcp-obsidian"],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
}
}
}
}The config file is located at:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Tool | Description |
| List files and folders in the vault or a subdirectory |
| Read the contents of a note |
| Create or overwrite a note (parent dirs created automatically) |
| Append content to the end of an existing note |
| Delete a note or folder |
| Move or rename a note within the vault |
Tool | Description |
| Case-insensitive full-text search across all |
| Find all notes containing a specific tag |
Tool | Description |
| Read the YAML frontmatter of a note |
| Set or update a frontmatter field (creates it if absent) |
Tool | Description |
| Find all notes that link to a given note via |
| Extract all |
| Find notes with no incoming or outgoing links |
Tool | Description |
| Read the daily note for a date (defaults to today, format: |
| Create a daily note, using a daily template from |
Tool | Description |
| List all tags in the vault with usage counts |
| List the N most recently modified notes |
| Return vault statistics (note count, word count, tags, links) |
| List all templates in the vault's |
All file paths are validated to prevent path traversal attacks — no operation can escape the configured vault directory.
Append content to the end of an existing note.
Args:
path: Relative path to the note.
content: Markdown content to append.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| content | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 states the tool appends content to an existing note, implying a mutation operation, but doesn't disclose behavioral traits such as error handling (e.g., what happens if the note doesn't exist), permissions required, whether changes are reversible, or rate limits. The description is minimal and lacks critical context for safe use.
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 core purpose stated first and parameters listed clearly. It avoids unnecessary details, but the parameter section could be more integrated. Overall, it's efficient with minimal waste, though not perfectly 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 2 parameters, no annotations, and an output schema (which likely handles return values), the description is moderately complete. It covers the basic action and parameters but lacks behavioral context (e.g., error cases, side effects) and usage guidelines. For a mutation tool with no annotations, it should provide more safety and operational details to be fully adequate.
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 schema provides no parameter details. The description adds basic semantics by explaining 'path' as a relative path to the note and 'content' as Markdown content to append, which clarifies purpose beyond the schema's generic titles. However, it doesn't elaborate on format constraints (e.g., path syntax, Markdown support), leaving gaps. With 2 parameters and low schema coverage, this is a baseline adequate explanation.
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 'append' and the resource 'existing note', specifying it adds content to the end. It distinguishes from siblings like 'write_note' (which likely creates/overwrites) and 'read_note' (which only reads), though it doesn't explicitly name alternatives. The purpose is specific but lacks explicit sibling 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., the note must exist), exclusions (e.g., not for creating new notes), or compare to siblings like 'write_note' or 'update_frontmatter'. Usage is implied by the action but not explicitly defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a daily note for a given date, using a daily template if available.
Args:
date_str: Date in YYYY-MM-DD format. Defaults to today.
| Name | Required | Description | Default |
|---|---|---|---|
| date_str | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 mentions using a template if available, which adds some context, but lacks critical behavioral details: whether this overwrites existing notes, what permissions are needed, what the output contains, or error conditions. For a creation tool with zero annotation coverage, this is insufficient.
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: the first sentence states the core purpose, and the second provides essential parameter details in a clear 'Args' section. Every sentence earns its place 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 the tool has an output schema (which handles return values), the description covers the basic purpose and parameter semantics adequately. However, for a creation tool with no annotations, it should ideally include more behavioral context (e.g., idempotency, error handling) to be fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful semantics for the single parameter: it explains that 'date_str' is a date in YYYY-MM-DD format and defaults to today. With 0% schema description coverage (schema only shows type and default), this fully compensates by providing format and default behavior, making the parameter well-understood.
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: 'Create a daily note for a given date, using a daily template if available.' It specifies the verb ('create'), resource ('daily note'), and key behavior ('using a daily template if available'). However, it doesn't explicitly differentiate from sibling tools like 'write_note' or 'get_daily_note', which would require a 5.
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. With multiple note-related siblings like 'write_note', 'get_daily_note', and 'append_to_note', there's no indication of when this specific creation tool is preferred, nor any prerequisites or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a note or folder from the vault.
Args:
path: Relative path to the note or folder to delete.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the action ('Delete') but fails to describe critical traits: whether deletion is permanent or reversible, if it requires specific permissions, what happens to linked content (e.g., backlinks), or error conditions (e.g., invalid paths). This leaves significant gaps for a destructive 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 front-loaded with the core purpose in the first sentence, followed by parameter details. It avoids redundancy and is appropriately sized for a simple tool, though the parameter explanation could be integrated more seamlessly rather than as a separate 'Args' section.
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, no annotations, and an output schema (which handles return values), the description is minimally adequate. It covers the basic action and parameter but lacks safety warnings, error handling, or sibling differentiation, leaving room for improvement in 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?
The description adds meaningful context for the single parameter 'path' by specifying it as a 'Relative path to the note or folder to delete,' which clarifies its purpose beyond the schema's basic string type. With 0% schema description coverage and only one parameter, this adequately compensates, though it could detail path format or examples.
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 resource ('a note or folder from the vault'), making the purpose unambiguous. It distinguishes from siblings like 'move_note' or 'write_note' by specifying deletion. However, it doesn't explicitly differentiate from all potential destructive operations, keeping it at 4 rather than 5.
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 'move_note' for relocation or 'update_frontmatter' for modification. The description lacks context about prerequisites (e.g., existence of the note/folder) or exclusions (e.g., cannot delete non-empty folders if applicable), offering minimal usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find all notes that link to the given note via [[wikilinks]].
Args:
path: Relative path to the note (e.g. 'Notes/My Note.md').
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 the tool's read-only nature (implied by 'Find') and the wikilink mechanism, but lacks details on permissions, rate limits, or output format (though an output schema exists). It adds some behavioral context but is incomplete for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, followed by a concise parameter explanation. Every sentence earns its place, with no wasted words, making it efficient and easy to parse.
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) and the presence of an output schema (which handles return values), the description is mostly complete. It covers purpose, parameter semantics, and usage context, but could improve by addressing behavioral aspects like permissions or limitations, though the output schema mitigates this gap.
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 description coverage is 0%, so the description must compensate. It explains the 'path' parameter with meaning ('Relative path to the note') and an example ('e.g. 'Notes/My Note.md''), adding significant value beyond the schema's basic type definition. With only one parameter, this is sufficient for clarity.
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 ('Find all notes that link to') and resource ('the given note via [[wikilinks]]'), distinguishing it from siblings like get_outlinks (which finds outgoing links) or get_orphans (which finds unlinked notes). It precisely defines the tool's scope and mechanism.
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 specifying 'via [[wikilinks]]' and providing a path example, which helps differentiate it from tools like search_notes (general search) or get_frontmatter (metadata retrieval). However, it does not explicitly state when not to use it or name alternatives, such as get_outlinks for outgoing links.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the daily note for a given date (defaults to today).
Args:
date_str: Date in YYYY-MM-DD format. Defaults to today.
| Name | Required | Description | Default |
|---|---|---|---|
| date_str | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a read operation and mentions the default behavior, but doesn't cover important aspects like error handling, permissions required, rate limits, or what happens if the note doesn't exist. This represents 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 perfectly concise and well-structured. The first sentence states the core purpose, and the second provides parameter details in a clear, bullet-like format. Every sentence earns its place 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 the tool has an output schema (which handles return values) and only one parameter, the description covers the basics adequately. However, for a read operation with no annotations, it should ideally mention what happens when the note doesn't exist or other edge cases. The presence of an output schema raises the baseline, but gaps remain.
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 substantial value beyond the schema, which has 0% description coverage. It explains the parameter's purpose ('Date in YYYY-MM-DD format'), default behavior ('Defaults to today'), and provides format specifics that aren't in the schema. For a single parameter tool with poor schema coverage, this is quite helpful.
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 ('Read') and resource ('daily note'), and specifies the date parameter context. However, it doesn't explicitly differentiate from sibling tools like 'read_note' or 'get_recent_notes', which limits the score to 4 rather than 5.
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 'defaults to today' and the date format, but provides no explicit guidance on when to use this tool versus alternatives like 'read_note' or 'get_recent_notes'. This leaves usage somewhat ambiguous, warranting a score of 3.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parse and return the YAML frontmatter of a note as key-value pairs.
Args:
path: Relative path to the note.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 the basic operation. It doesn't disclose behavioral traits like error handling (e.g., if the note lacks frontmatter or the path is invalid), performance characteristics, or any side effects. This leaves significant gaps for a tool that parses structured data.
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 in the first sentence, followed by a concise parameter explanation. Every sentence adds value without redundancy, making it efficient and easy to parse.
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 (parsing YAML), no annotations, and the presence of an output schema (which handles return values), the description is reasonably complete. It covers purpose and parameter semantics but lacks behavioral details like error cases, which would enhance completeness for a parsing operation.
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 meaningful context for the single parameter 'path' by specifying it's a 'Relative path to the note,' which clarifies its format beyond the schema's generic 'string' type. With 0% schema description coverage, this compensates well, though it could mention path conventions or examples.
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 ('Parse and return') and resource ('YAML frontmatter of a note as key-value pairs'), distinguishing it from sibling tools like read_note (which reads full content) or update_frontmatter (which modifies frontmatter). It precisely defines the tool's scope.
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 specifying it works on notes with YAML frontmatter, but it doesn't explicitly state when to use this versus alternatives like read_note (for full content) or get_note_stats (for metadata). It provides clear prerequisites but lacks explicit comparison to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return statistics about the vault: note count, word count, tag count, link count.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool returns statistics but doesn't describe important behavioral aspects: whether it requires authentication, how it handles large vaults (performance/rate limits), if it's read-only (implied but not explicit), or what format the statistics are returned in. For a tool with zero annotation coverage, this represents significant gaps in 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 perfectly concise at a single sentence that efficiently communicates the core functionality. Every word earns its place by specifying exactly what statistics are returned. There's no redundancy, fluff, or unnecessary elaboration for such 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 simplicity (0 parameters, has output schema) and lack of annotations, the description is minimally adequate. It tells what the tool returns but doesn't provide important context about authentication needs, performance considerations, or how the statistics are calculated. The existence of an output schema means the description doesn't need to explain return values, but other behavioral aspects remain undocumented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage, so the baseline is 4. The description appropriately doesn't discuss parameters since none exist, and it correctly focuses on what the tool does rather than trying to explain non-existent inputs.
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 ('Return') and resource ('statistics about the vault'), listing the exact metrics provided (note count, word count, tag count, link count). It distinguishes from siblings like 'get_recent_notes' or 'list_tags' by focusing on aggregated statistics rather than listing individual items. However, it doesn't explicitly contrast with all siblings, keeping it at 4 instead of 5.
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, timing considerations, or compare it to siblings like 'get_orphans' or 'search_notes' that might provide overlapping or complementary data. This lack of contextual usage information leaves the agent without clear selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find notes with no incoming backlinks and no outgoing wikilinks.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 the behavioral trait of finding notes based on specific linkage criteria, but does not add context on permissions, rate limits, or output format. The description is accurate but lacks depth 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 front-loads the key action and criteria with zero waste. It is appropriately sized for a simple, parameterless tool, making it easy to understand at a glance.
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 (0 parameters, no annotations) and the presence of an output schema, the description is complete enough for its purpose. It clearly defines what the tool does, though it could benefit from slight elaboration on usage context or output expectations to achieve full 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?
The tool has 0 parameters with 100% schema description coverage, so no parameter information is needed. The description does not add param details beyond the schema, but this is acceptable as the baseline is high for zero parameters, and it focuses on the tool's purpose instead.
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 ('Find') and resource ('notes') with precise criteria ('with no incoming backlinks and no outgoing wikilinks'). It effectively distinguishes this tool from siblings like get_backlinks, get_outlinks, and search_notes by focusing on isolation rather than linkage or general search.
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 identifying isolated notes, providing clear context. However, it does not explicitly state when to use this tool versus alternatives like get_backlinks or get_outlinks for related queries, nor does it mention exclusions or prerequisites, leaving some guidance gaps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract all [[wikilinks]] from a note.
Args:
path: Relative path to the note.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 extraction action but does not mention whether this is a read-only operation, what permissions are needed, how errors are handled, or the format of extracted links. For a tool with zero annotation coverage, this leaves significant behavioral gaps.
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 in the first sentence, followed by a brief parameter explanation. Every sentence earns its place with no wasted words, making it highly efficient and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one parameter, no nested objects) and the presence of an output schema (which handles return values), the description is mostly complete. It covers the purpose and parameter semantics adequately, but could improve by addressing behavioral aspects like error handling or permissions, especially with no annotations.
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 meaningful semantics beyond the input schema, which has 0% coverage. It explains that 'path' is a 'Relative path to the note,' clarifying its purpose and format. With only one parameter, this provides adequate compensation for the schema's lack of description, though it could specify path examples 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 specific action ('Extract all [[wikilinks]]') and resource ('from a note'), distinguishing it from siblings like get_backlinks (which likely extracts incoming links) or read_note (which reads content). It precisely defines the tool's scope without being vague or tautological.
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 what it extracts (wikilinks from a note), but does not explicitly state when to use this tool versus alternatives like get_backlinks or search_notes. It provides some context but lacks clear exclusions or named alternatives, leaving room for interpretation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the N most recently modified notes in the vault.
Args:
n: Number of notes to return (default 10).
| Name | Required | Description | Default |
|---|---|---|---|
| n | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 the basic operation. It lacks details on permissions, rate limits, error handling, or what 'recently modified' means (e.g., time frame, sorting order). This is a significant gap 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 front-loaded with the core purpose in the first sentence, followed by a concise parameter explanation. Every sentence earns its place with no wasted words, making it highly 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's low complexity (1 parameter) and the presence of an output schema (which handles return values), the description is minimally adequate. However, with no annotations and incomplete behavioral details, it leaves gaps in understanding operational constraints.
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 meaning beyond the input schema by explaining that 'n' is the 'Number of notes to return' with a default of 10, which clarifies its purpose. Since schema description coverage is 0% and there's only one parameter, this adequately compensates, though it doesn't cover edge cases like negative values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('List'), resource ('notes in the vault'), and scope ('N most recently modified'), distinguishing it from siblings like list_files or search_notes. It precisely defines what the tool does without 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 implies usage for retrieving recent notes but does not explicitly state when to use this tool versus alternatives like get_note_stats or search_notes. No exclusions or prerequisites are mentioned, leaving usage context partially inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List files and folders inside the vault (or a subdirectory of it).
Args:
path: Relative path within the vault to list. Defaults to the vault root.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 describes the basic behavior (listing files and folders) and includes a default value for the path parameter, but lacks details on permissions, rate limits, pagination, or output format. For a tool with no annotations, this is adequate but leaves gaps in behavioral context.
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 in the first sentence, followed by a concise explanation of the parameter. There is no wasted text, and the structure efficiently communicates essential information without 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 optional parameter) and the presence of an output schema (which handles return values), the description is mostly complete. It covers the purpose, usage context, and parameter semantics adequately. However, without annotations, it could benefit from more behavioral details like error handling or output examples.
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 meaningful context beyond the input schema, which has 0% description coverage. It explains that 'path' is a 'Relative path within the vault to list' and defaults to 'the vault root', clarifying usage that the schema alone does not provide. With only one parameter, this compensates well for the low 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 specific action ('List files and folders') and resource ('inside the vault or a subdirectory'), distinguishing it from siblings like 'search_notes' or 'get_recent_notes' which have different purposes. It explicitly mentions the scope of listing contents, 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 clear context by specifying that it lists files and folders in the vault or a subdirectory, which helps differentiate it from tools like 'search_notes' (which searches content) or 'list_tags' (which lists tags). However, it does not explicitly state when not to use it or name alternatives, such as 'get_recent_notes' for recent files only.
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 usage counts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the tool's read-only nature and output format (tags with usage counts), but does not mention behavioral traits like performance, pagination, or error handling. It adds basic context but lacks depth 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 with zero waste. It is front-loaded with the core action and resource, and every word earns its place by specifying scope and output details. No unnecessary elaboration or repetition.
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 (0 parameters, no annotations) and the presence of an output schema, the description is largely complete. It clearly states what the tool does and what it returns, though it could benefit from more behavioral context (e.g., sorting, limits) to fully compensate for the lack of annotations.
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 documentation is needed. The description appropriately adds no parameter details, focusing on the tool's purpose instead. This aligns with the baseline for zero parameters, though it doesn't compensate for any gaps (none exist).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('List all tags') and resource ('used across the vault'), distinguishing it from sibling tools like 'search_by_tag' or 'get_frontmatter'. It provides exact scope ('with their usage counts'), making the purpose unambiguous and 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?
The description implies usage for retrieving tag metadata across the entire vault, but does not explicitly state when to use this tool versus alternatives like 'search_by_tag' or 'get_note_stats'. It offers some context but lacks explicit guidance on 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 templates in the vault's Templates folder.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 clearly indicates this is a read-only operation ('List') and specifies the location scope, but doesn't mention potential limitations like pagination, sorting, or error conditions. The description is accurate but lacks depth about behavioral traits.
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 that efficiently communicates the tool's purpose and scope without any redundant information. Every word earns its place, making it easy to parse and understand immediately.
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, read-only operation) and the presence of an output schema, the description provides adequate context about what the tool does and where it operates. However, it could benefit from mentioning what format the templates are returned in or any special characteristics of the Templates folder.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage, so the schema already fully documents the absence of parameters. The description appropriately doesn't add parameter information beyond what the schema provides, maintaining focus on the tool's purpose and scope.
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 ('List all available templates') and the target resource ('in the vault's Templates folder'), distinguishing it from siblings like list_files or list_tags. It uses precise language that leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly provides context by specifying the scope ('vault's Templates folder'), which helps differentiate it from general file listing tools. However, it doesn't explicitly state when to use this tool versus alternatives like list_files or search_notes, nor does it mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move or rename a note within the vault.
Args:
src: Relative path to the source note or folder.
dest: Relative path to the destination (new name/location).
| Name | Required | Description | Default |
|---|---|---|---|
| src | Yes | ||
| dest | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 moving or renaming, implying mutation, but fails to detail permissions, whether it overwrites existing files, error handling, or effects on linked notes (e.g., backlinks). This is a significant gap for a mutation tool.
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 a clear purpose statement followed by parameter explanations. Every sentence adds value, though the structure could be slightly improved by integrating usage context more seamlessly.
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 (mutation with 2 params), no annotations, and an output schema (which reduces need to explain returns), the description is moderately complete. It covers the basic action and parameters but lacks behavioral details like safety warnings or integration with sibling tools, making it adequate but with 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%, so the description must compensate. It adds meaning by explaining 'src' as 'Relative path to the source note or folder' and 'dest' as 'Relative path to the destination (new name/location)', clarifying beyond the schema's basic titles. However, it doesn't cover format details like path syntax or validation rules.
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 ('Move or rename') and resource ('a note within the vault'), distinguishing it from sibling tools like 'rename_note' (which doesn't exist) or 'copy_note' (not present). It precisely defines the tool's function without being vague or tautological.
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 'rename' (implied but not explicit) or other file operations. It lacks context about prerequisites, exclusions, or comparisons to sibling tools such as 'write_note' or 'update_frontmatter', leaving usage unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the contents of a note in the vault.
Args:
path: Relative path to the note file (e.g. 'folder/My Note.md').
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 tool reads note contents but doesn't mention any behavioral traits like error handling (e.g., what happens if the path doesn't exist), permissions required, rate limits, or whether it's a safe read operation. This leaves significant gaps for an agent to understand how to use it effectively.
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 concise with two sentences: one stating the purpose and another explaining the parameter with an example. It's front-loaded with the core functionality, though the parameter explanation could be slightly more integrated rather than a separate 'Args' section.
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 (single parameter) and the presence of an output schema (which handles return values), the description is somewhat complete but lacks behavioral context. It covers the basic purpose and parameter semantics adequately, but without annotations, it should ideally mention safety aspects or error conditions to be fully helpful for an 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 description adds meaningful context for the single parameter 'path' by explaining it's a 'Relative path to the note file' and providing an example ('folder/My Note.md'). Since schema description coverage is 0% (the schema only has a title 'Path'), this compensates well, though it doesn't cover edge cases like path formatting rules or supported file extensions.
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 ('Read') and resource ('contents of a note in the vault'), making it immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_frontmatter' or 'get_note_stats' that also read note data, 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 no guidance on when to use this tool versus alternatives. With siblings like 'get_frontmatter' (reads metadata), 'get_daily_note' (reads a specific type), and 'search_notes' (reads multiple notes), there's no indication of when 'read_note' is preferred or what distinguishes it from these other read operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find all notes containing a specific tag.
Args:
tag: Tag to search for (with or without leading #).
| Name | Required | Description | Default |
|---|---|---|---|
| tag | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 mentions the search behavior but lacks details on permissions, rate limits, pagination, or return format. The description doesn't disclose whether this is a read-only operation (implied by 'Find') or other behavioral traits, leaving 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 appropriately sized and front-loaded: the first sentence states the purpose clearly, followed by a brief parameter explanation. Every sentence earns its place with no wasted words, making it efficient and easy to parse.
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 (1 parameter, no nested objects) and the presence of an output schema (which handles return values), the description is minimally adequate. However, with no annotations and incomplete behavioral disclosure, it lacks context on usage scenarios and operational constraints, making it just sufficient 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?
The description adds meaningful semantics beyond the input schema. The schema has 0% description coverage (only a title 'Tag'), but the description clarifies that the 'tag' parameter is 'Tag to search for (with or without leading #).' This provides crucial context on format flexibility, compensating well for the low 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: 'Find all notes containing a specific tag.' This is a specific verb ('Find') and resource ('notes'), and it distinguishes from siblings like 'search_notes' by focusing on tag-based filtering. However, it doesn't explicitly contrast with 'list_tags' (which likely lists tags rather than notes with tags), keeping it at 4 instead of 5.
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 siblings like 'search_notes' (which might allow broader searches) or 'list_tags' (for listing tags themselves), nor does it specify prerequisites or exclusions. Usage is implied by the purpose 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.
Full-text search across all markdown notes in the vault.
Args:
query: Search string (case-insensitive).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 mentions 'case-insensitive' search behavior, which is useful, but lacks other critical details like whether it returns partial matches, supports wildcards, handles pagination, or describes the output format. For a search tool with zero annotation coverage, this is insufficient.
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, followed by a brief parameter explanation. Every sentence earns its place, with no redundant or verbose language, making it highly efficient and easy to parse.
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 operation), no annotations, and an output schema (which covers return values), the description is partially complete. It covers the purpose and parameter semantics but lacks behavioral details like search scope limitations or performance hints, leaving 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?
The description adds meaningful semantics: it explains that 'query' is a 'Search string (case-insensitive),' which clarifies the parameter's purpose and behavior beyond the schema's basic type (string). With 0% schema description coverage and 1 parameter, this compensates well, though it could note query syntax or examples.
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: 'Full-text search across all markdown notes in the vault.' It specifies the verb ('search'), resource ('markdown notes'), and scope ('all...in the vault'), distinguishing it from siblings like search_by_tag (tag-based) or list_files (no search).
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 full-text search across notes, but does not explicitly state when to use this versus alternatives like search_by_tag (tag-based) or get_recent_notes (recency-based). It provides clear context (searching markdown notes) but lacks explicit exclusions or named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set or update a frontmatter field in a note. Creates frontmatter if absent.
Args:
path: Relative path to the note.
key: Frontmatter key to set (e.g. 'status', 'tags').
value: Value to set. Use comma-separated values for lists (e.g. 'tag1,tag2').
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| key | Yes | ||
| value | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 modifies notes ('set or update'), implying mutation, but doesn't cover permissions, error handling, or response format. It adds some context about creating frontmatter if absent, but for a mutation tool with zero annotation coverage, this is insufficient.
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: the first sentence states the core purpose, followed by a structured 'Args' section. Each sentence adds value, with no wasted words. It could be slightly more concise by integrating the examples into the main text, but overall it's efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (mutation with 3 parameters), no annotations, and an output schema (which reduces the need to explain return values), the description is moderately complete. It covers the purpose and parameters well but lacks usage guidelines and behavioral details like error cases or side effects, leaving 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?
The description adds significant meaning beyond the input schema, which has 0% description coverage. It explains each parameter: 'path' as 'Relative path to the note', 'key' as 'Frontmatter key to set (e.g. 'status', 'tags')', and 'value' with examples for lists. This compensates well for the schema's lack of documentation, though it doesn't cover all edge cases.
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: 'Set or update a frontmatter field in a note. Creates frontmatter if absent.' It specifies the verb ('set or update'), resource ('frontmatter field in a note'), and scope ('creates frontmatter if absent'). However, it doesn't explicitly differentiate from sibling tools like 'write_note' or 'append_to_note', which might also modify notes, keeping it from 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 doesn't mention sibling tools like 'write_note' (which might handle broader note updates) or 'get_frontmatter' (for reading), nor does it specify prerequisites or exclusions. Usage is implied by the purpose but lacks explicit context.
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 note in the vault.
Args:
path: Relative path to the note (e.g. 'folder/New Note.md').
Parent directories are created automatically.
content: Markdown content to write.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| content | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 describes key behaviors: it can create or overwrite notes, automatically creates parent directories, and handles markdown content. However, it doesn't mention permissions, rate limits, error conditions, or what happens if the note already exists beyond 'overwrite'.
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 efficiently structured with a clear purpose statement followed by parameter explanations. Every sentence adds value: the first defines the tool's action, and the two parameter lines provide crucial usage details. No wasted words or 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 has an output schema (which handles return values), no annotations, and 2 parameters fully explained in the description, the description is mostly complete. It covers the core functionality and parameter usage well, though additional behavioral context (like error handling) would make it more robust for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate. It provides essential semantics for both parameters: 'path' is explained as a relative path with parent directories created automatically, and 'content' is specified as markdown content. This adds significant value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('Create or overwrite') and resource ('a note in the vault'), distinguishing it from siblings like 'append_to_note' (which only appends) and 'create_daily_note' (which creates notes with a specific naming convention). The phrase 'Create or overwrite' precisely defines the tool's behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: to create new notes or overwrite existing ones. It doesn't explicitly state when not to use it or name alternatives, but the distinction from siblings like 'append_to_note' is implied by the 'overwrite' action. No misleading guidance is present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have distinct purposes targeting specific operations like reading, writing, searching, or managing metadata, with clear boundaries. However, some overlap exists between 'read_note' and 'get_daily_note' (which also reads a note), and 'write_note' and 'create_daily_note' (both create notes), though their specialized contexts help differentiate them.
All tool names follow a consistent verb_noun pattern using snake_case, such as 'append_to_note', 'delete_note', and 'search_notes'. This uniformity makes the set predictable and easy to navigate, with no deviations in style or convention.
With 19 tools, the count is slightly high but reasonable for a comprehensive note-taking system like Obsidian, covering operations from basic CRUD to advanced features like backlinks and templates. It might feel heavy but aligns well with the domain's complexity.
The toolset provides complete coverage for managing an Obsidian vault, including full CRUD for notes (create, read, update, delete), metadata handling (frontmatter), search capabilities (full-text, tags), and vault analytics (stats, orphans). No obvious gaps exist for core workflows.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/jkang8/mcp-obsidian'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
