Skip to main content
Glama
Shepherd-Creative

Obsidian MCP Server

by Shepherd-Creative
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

Custom Obsidian MCP Server

A comprehensive Model Context Protocol (MCP) server for Obsidian vault operations, optimized for Zettelkasten note creation workflows. Works with any LLM that supports MCP (Claude, Perplexity, etc.).

Overview

This MCP server connects to the Obsidian Local REST API plugin and provides 12 powerful tools for:

  • File Operations: List, read, and manage files in your vault

  • Content Operations: Create, append, and precisely edit notes

  • Search: Find related notes across your vault

  • Metadata Management: Tags, frontmatter, and note properties

Designed specifically for Zettelkasten practitioners who want AI assistance in creating atomic notes, finding connections, and maintaining a knowledge graph.

Related MCP server: Advanced Obsidian MCP Server

Features

✅ Zettelkasten-Optimized: Tools designed for atomic note creation and linking
✅ LLM-Agnostic: Works with any MCP-compatible LLM
✅ Safe by Default: CREATE mode won't overwrite existing notes
✅ Powerful Search: Find existing notes before creating duplicates
✅ Precise Editing: Insert content at specific headings or blocks
✅ Metadata Rich: Full frontmatter and tag management

Prerequisites

  1. Obsidian with Local REST API plugin installed and configured

  2. Python 3.10+

  3. uv (optional but recommended for managing Python environments)

Installation

1. Install the MCP Server

Using uv (recommended):

cd custom-obsidian-mcp
uv sync

Or using pip:

cd custom-obsidian-mcp
pip install -e .

2. Set Up Obsidian Local REST API

  1. Install the "Local REST API" plugin in Obsidian

  2. Enable the plugin in Settings → Community plugins

  3. Go to plugin settings and copy your API key

  4. Note the port (default: 27124)

3. Configure Environment Variables

Create a .env file or set these variables:

export OBSIDIAN_API_KEY="your-api-key-here"
export OBSIDIAN_HOST="127.0.0.1"  # Usually localhost
export OBSIDIAN_PORT="27124"      # Default port

Configuration for LLM Clients

Claude Desktop (Desktop App)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "/path/to/uvx",
      "args": ["custom-obsidian-mcp"],
      "env": {
        "OBSIDIAN_API_KEY": "your-api-key-here",
        "OBSIDIAN_HOST": "127.0.0.1",
        "OBSIDIAN_PORT": "27124"
      }
    }
  }
}

Or if using pip installation:

{
  "mcpServers": {
    "obsidian": {
      "command": "python",
      "args": ["-m", "custom_obsidian_mcp.server"],
      "env": {
        "OBSIDIAN_API_KEY": "your-api-key-here",
        "OBSIDIAN_HOST": "127.0.0.1",
        "OBSIDIAN_PORT": "27124"
      }
    }
  }
}

Perplexity or Other MCP Clients

Use similar configuration structure adapted to your client's format.

Available Tools

File Operations

obsidian_list_files_in_vault

List all files and directories in vault root.

# No parameters needed

obsidian_list_files_in_dir

List contents of a specific directory.

{
  "dirpath": "Zettelkasten"  # Empty string for root
}

obsidian_get_file_contents

Read a single file's complete contents.

{
  "filepath": "Zettelkasten/202411061234.md"
}

obsidian_batch_get_file_contents

Read multiple files at once (max 20).

{
  "filepaths": [
    "Zettelkasten/note1.md",
    "Zettelkasten/note2.md"
  ]
}

Search Operations

obsidian_simple_search

Text search across all vault files with context.

{
  "query": "systems thinking",
  "context_length": 100  # Optional, default 100
}

obsidian_complex_search

Advanced JsonLogic-based search.

{
  "query": {"glob": ["*.md", {"var": "path"}]}
}

Content Operations

obsidian_write_note

Create or modify notes with optional frontmatter.

{
  "filepath": "Zettelkasten/202411061234 Systems Thinking.md",
  "content": "# Systems Thinking\n\nContent here...",
  "mode": "create",  # create|overwrite|append|prepend
  "frontmatter": {
    "tags": ["zettelkasten", "systems"],
    "created": "2024-11-06"
  }
}

Modes:

  • create: Only create new files (won't overwrite)

  • overwrite: Replace entire file

  • append: Add to end

  • prepend: Add to beginning

obsidian_append_content

Quick append to file (creates if doesn't exist).

{
  "filepath": "Zettelkasten/note.md",
  "content": "\n## New Section\n\nNew content..."
}

obsidian_patch_content

Insert content at specific locations within notes.

{
  "filepath": "Zettelkasten/note.md",
  "target_type": "heading",  # heading|block|frontmatter
  "target": "Related Concepts/Subsection",
  "operation": "append",  # append|prepend|replace
  "content": "New related concept..."
}

Target Types:

  • heading: Navigate to heading path (e.g., "Section/Subsection")

  • block: Use block reference (e.g., "^block-id")

  • frontmatter: Update specific frontmatter field

obsidian_delete_file

Delete file or directory (requires confirmation).

{
  "filepath": "Zettelkasten/old-note.md",
  "confirm": true  # Must be true to proceed
}

Metadata Operations

obsidian_get_frontmatter

Extract YAML frontmatter from a note.

{
  "filepath": "Zettelkasten/note.md"
}

obsidian_update_frontmatter

Update frontmatter without modifying content.

{
  "filepath": "Zettelkasten/note.md",
  "updates": {
    "tags": ["zettelkasten", "new-tag"],
    "status": "published"
  }
}

obsidian_manage_tags

Add, remove, or list tags.

{
  "filepath": "Zettelkasten/note.md",
  "action": "add",  # add|remove|list
  "tags": ["systems-thinking", "mental-models"]
}

obsidian_get_notes_info

Get metadata for multiple notes (max 50).

{
  "filepaths": [
    "Zettelkasten/note1.md",
    "Zettelkasten/note2.md"
  ]
}

Returns: tags, creation date, size, and other metadata.

Zettelkasten Workflow Examples

Creating a New Atomic Note

  1. Search for existing related notes:

    Use obsidian_simple_search with query "systems thinking"

  2. Read related notes:

    Use obsidian_batch_get_file_contents with discovered notes

  3. Create new atomic note:

    Use obsidian_write_note:
- filepath: "Zettelkasten/202411061234 Systems Thinking Core Concept.md"
- content: Your atomic note content
- mode: "create" (safe - won't overwrite)
- frontmatter: {tags: ["zettelkasten", "systems"], created: "2024-11-06"}

Linking Related Notes

  1. Find notes in topic cluster:

    Use obsidian_simple_search or obsidian_get_notes_info

  2. Add connection to existing note:

    Use obsidian_patch_content:
- target_type: "heading"
- target: "Related Concepts"
- operation: "append"
- content: "- [[202411061234 Systems Thinking Core Concept]]"

Organizing with Tags

  1. Check current tags:

    Use obsidian_manage_tags with action: "list"

  2. Add topic tags:

    Use obsidian_manage_tags with action: "add"

Best Practices

For Zettelkasten

  • Always search first: Use obsidian_simple_search before creating new notes to avoid duplicates

  • Atomic notes: One idea per note, clearly titled

  • Link liberally: Use obsidian_patch_content to add connections

  • Tag consistently: Use obsidian_manage_tags for topic organization

  • Use CREATE mode: Default to mode="create" to prevent accidental overwrites

For Safety

  • CREATE mode is default: Won't overwrite existing notes

  • Confirmation required: Destructive operations need explicit confirmation

  • Test in dev vault: Try tools in a test vault before using on your main Zettelkasten

Troubleshooting

Connection Errors

Error: "Connection error for GET /vault/"

Solutions:

  1. Verify Obsidian is running

  2. Check Local REST API plugin is enabled

  3. Verify API key is correct

  4. Check port matches plugin settings (default: 27124)

Authentication Errors

Error: "Authentication failed"

Solutions:

  1. Check OBSIDIAN_API_KEY environment variable

  2. Regenerate API key in plugin settings

  3. Ensure no extra spaces in API key

File Not Found

Error: "Resource not found"

Solutions:

  1. Verify file path is relative to vault root

  2. Check file exists: use obsidian_list_files_in_dir

  3. Ensure proper file extension (e.g., .md)

Architecture

custom-obsidian-mcp/
├── src/
│   └── custom_obsidian_mcp/
│       ├── __init__.py
│       ├── server.py          # FastMCP server with all tools
│       └── obsidian_client.py # REST API client
├── pyproject.toml             # Project configuration
└── README.md

Key Components

  • FastMCP: Modern Python MCP framework with Pydantic validation

  • ObsidianClient: Async HTTP client for REST API communication

  • Pydantic Models: Type-safe input validation for all tools

  • Error Handling: Actionable error messages guide correct usage

Development

Running Tests

# Verify Python syntax
python -m py_compile src/custom_obsidian_mcp/server.py

# Test basic import
python -c "from custom_obsidian_mcp.server import mcp; print('OK')"

Adding New Tools

  1. Define Pydantic input model

  2. Add tool function with @mcp.tool decorator

  3. Include proper annotations (readOnlyHint, etc.)

  4. Add comprehensive docstring

  5. Implement error handling

Contributing

Contributions welcome! Please:

  1. Follow existing code style

  2. Add Pydantic models for validation

  3. Include docstrings with examples

  4. Test with Obsidian Local REST API

License

MIT License - See LICENSE file for details

Acknowledgments

Support

For issues or questions:

  1. Check Troubleshooting section

  2. Verify Obsidian Local REST API is working

  3. Test with simple tools first (list_files_in_vault)

  4. Open an issue with error messages and configuration

Happy note-taking! 📝✨

Available Tools

13 tools
obsidian_append_contentA

Append content to the end of an existing file or create new file.

Quick way to add content to notes. Useful for adding new thoughts, references,
or connections to existing Zettelkasten notes.

Args:
    params (AppendContentInput): Contains:
        - filepath (str): Path to file
        - content (str): Content to append

Returns:
    str: Success message with updated file info
    
Example:
    Add a new related concept to an existing note.
ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate this is not read-only, not open-world, not idempotent, and not destructive. The description adds useful behavioral context by specifying that it appends to the end of files and can create new files if needed, which goes beyond the annotations. However, it doesn't mention potential side effects like file creation behavior details or error conditions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and appropriately sized: it starts with a clear purpose statement, provides usage context, details parameters with a structured Args section, specifies return values, and includes a practical example. Every sentence adds value without redundancy, and information is front-loaded effectively.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (file operations with creation fallback), the description covers purpose, usage, parameters, and returns adequately. The presence of an output schema means return values don't need explanation. However, for a tool that modifies files, more behavioral details (e.g., what happens if the file doesn't exist, encoding considerations) would enhance completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the schema provides no parameter descriptions. The description compensates by listing both parameters (filepath and content) and their basic purpose in the Args section, adding meaningful semantics. However, it doesn't provide format details (e.g., filepath structure, content encoding) or constraints beyond what's implied, leaving some gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

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 ('append content', 'create new file') and resource ('existing file'), distinguishing it from siblings like obsidian_patch_content (which patches rather than appends) and obsidian_write_note (which writes rather than appends). The opening sentence provides a precise, actionable summary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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 ('Quick way to add content to notes', 'Useful for adding new thoughts, references, or connections to existing Zettelkasten notes'), which helps differentiate it from tools like obsidian_patch_content or obsidian_write_note. However, it doesn't explicitly state when NOT to use it or name specific alternatives, preventing a perfect score.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

obsidian_batch_get_file_contentsA
Read-onlyIdempotent

Read multiple files at once, concatenated with headers.

Efficient way to read several related Zettelkasten notes together to understand
connections and context before creating new atomic notes.

Args:
    params (BatchGetFilesInput): Contains:
        - filepaths (List[str]): List of file paths to read (max 20)

Returns:
    str: All file contents concatenated with clear separators
    
Example:
    Reads multiple related notes to understand a concept network.
ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false. The description adds valuable behavioral context beyond annotations: it specifies that contents are concatenated with clear separators, mentions the maximum of 20 files, and explains the efficiency rationale for batch reading related notes. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (purpose, Args, Returns, Example) and front-loaded key information. It's appropriately sized, though the example could be more concrete. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity, rich annotations (read-only, idempotent), and the presence of an output schema (returns str), the description is complete. It covers purpose, usage context, parameter semantics, and behavioral details like concatenation and limits, leaving output specifics to the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description compensates by explaining the 'filepaths' parameter in the Args section, including the max 20 constraint. However, it doesn't provide format details (e.g., path syntax, relative/absolute) or error handling. With one parameter documented, this meets the baseline for adequate coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Read multiple files at once, concatenated with headers') and distinguishes it from sibling tools like 'obsidian_get_file_contents' (single file) and 'obsidian_search' (search-based). It explicitly mentions the Zettelkasten context and purpose of understanding connections between notes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool: 'Efficient way to read several related Zettelkasten notes together to understand connections and context before creating new atomic notes.' It distinguishes this batch operation from single-file reading and suggests it's for preparatory analysis of related notes.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

obsidian_delete_fileA
DestructiveIdempotent

Delete a file or directory from the vault.

DESTRUCTIVE OPERATION. Requires explicit confirmation. Use carefully when
removing outdated or duplicate notes from your Zettelkasten.

Args:
    params (DeleteFileInput): Contains:
        - filepath (str): Path to file/directory to delete
        - confirm (bool): Must be True to proceed with deletion

Returns:
    str: Success or error message
    
Example:
    Delete a duplicate note after merging content into another note.
ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds valuable behavioral context beyond annotations: it explicitly warns 'DESTRUCTIVE OPERATION' and notes 'Requires explicit confirmation,' which aligns with the destructiveHint=true annotation. However, it doesn't mention idempotentHint=true (deleting a non-existent file might succeed or fail), leaving some behavioral traits uncovered. No contradiction with annotations exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (purpose, warning, usage, Args, Returns, Example) and front-loads key information. It's appropriately sized for a destructive tool, though the example sentence could be slightly more concise. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (destructive operation with confirmation) and the presence of an output schema (Returns: str), the description is largely complete. It covers purpose, guidelines, parameters, and behavioral warnings, but could benefit from mentioning idempotency or error cases for a fully comprehensive view.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates by explaining both parameters in the Args section: 'filepath (str): Path to file/directory to delete' and 'confirm (bool): Must be True to proceed with deletion.' This adds clear meaning beyond the bare schema, though it doesn't detail constraints like maxLength for filepath.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Delete a file or directory') and resource ('from the vault'), distinguishing it from sibling tools like obsidian_append_content or obsidian_update_frontmatter which modify content rather than remove files. The verb 'Delete' is precise and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool ('removing outdated or duplicate notes from your Zettelkasten') and includes a cautionary note ('Use carefully'). It also offers an example scenario ('Delete a duplicate note after merging content into another note'), which helps differentiate it from alternatives like obsidian_patch_content for modifications.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

obsidian_get_file_contentsA
Read-onlyIdempotent

Read the complete contents of a single file from the vault.

Use this to read existing Zettelkasten notes, understand their structure,
and find connections for creating new atomic notes.

Args:
    params (GetFileInput): Contains:
        - filepath (str): Path to file relative to vault root

Returns:
    str: File contents including frontmatter and body
    
Example:
    For filepath="Zettelkasten/202411061234.md", returns the full note content.
ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering safety and idempotency. The description adds valuable context beyond this by specifying it reads 'complete contents... including frontmatter and body' and provides an example, though it doesn't mention error handling or file existence checks.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear purpose statement, usage guidelines, parameter details, return value, and an example—all in four concise sentences. Each section adds value without redundancy, and information is front-loaded appropriately.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

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), rich annotations covering safety and behavior, and the presence of an output schema (specifying return type as str), the description is complete. It adequately explains the tool's purpose, usage, parameters, and output without needing to duplicate structured data.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description compensates by explaining the single parameter 'filepath' in the Args section and providing an example. However, it doesn't add significant meaning beyond what the schema's properties already define (e.g., path format, length constraints).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Read the complete contents of a single file') and resource ('from the vault'), distinguishing it from siblings like obsidian_get_frontmatter (partial content) or obsidian_batch_get_file_contents (multiple files). The mention of 'Zettelkasten notes' provides domain-specific context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use this tool ('to read existing Zettelkasten notes, understand their structure, and find connections for creating new atomic notes'), but does not explicitly state when not to use it or name alternatives like obsidian_get_frontmatter for partial content or obsidian_batch_get_file_contents for multiple files.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

obsidian_get_frontmatterA
Read-onlyIdempotent

Extract YAML frontmatter metadata from a note.

Read metadata like tags, creation date, and other properties from Zettelkasten
notes without loading the full content.

Args:
    params (GetFrontmatterInput): Contains:
        - filepath (str): Path to file

Returns:
    str: JSON object containing frontmatter fields
    
Example:
    Get tags and metadata from a note to understand its classification.
ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering safety and idempotency. The description adds valuable context by specifying it extracts 'YAML frontmatter' (format), mentions 'Zettelkasten notes' (context), and clarifies it doesn't load full content (performance/scope). No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (purpose, Args, Returns, Example) and front-loaded key information. It's concise but includes a slightly verbose example sentence that could be tighter.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

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), rich annotations (covering safety and idempotency), and the presence of an output schema (implied by Returns section), the description is complete. It explains purpose, usage context, parameter role, and output format adequately without needing to detail return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description compensates by explaining the single parameter 'filepath' in the Args section and providing an example use case. However, it doesn't add significant meaning beyond what's implied by the parameter name and basic schema constraints (e.g., path format or vault context).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Extract YAML frontmatter metadata'), the resource ('from a note'), and distinguishes it from siblings by mentioning it reads metadata 'without loading the full content' (unlike obsidian_get_file_contents). It provides concrete examples of metadata types like tags and creation date.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use it: to 'Read metadata... without loading the full content,' which differentiates it from content-reading tools like obsidian_get_file_contents. However, it doesn't explicitly mention when NOT to use it or name specific alternatives beyond the implied contrast.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

obsidian_get_notes_infoA
Read-onlyIdempotent

Get metadata for multiple notes including tags, dates, and sizes.

Efficient way to get overview information about several Zettelkasten notes
without reading full content. Useful for analyzing note collections.

Args:
    params (GetNotesInfoInput): Contains:
        - filepaths (List[str]): Paths to files (max 50)

Returns:
    str: JSON array with metadata for each file
    
Example:
    Get info about all notes in a topic cluster to understand their relationships.
ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false. The description adds valuable context beyond this: it clarifies the tool's efficiency ('Efficient way'), scope ('without reading full content'), and practical use case ('analyzing note collections'), which helps the agent understand behavioral traits not covered by annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded with the core purpose, followed by usage context, parameter details, return value, and an example. 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.

Completeness5/5

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, read-only operation), the description is complete. It covers purpose, usage, parameters, returns (noting JSON format), and includes an example. With annotations providing safety hints and an output schema existing, no additional behavioral or output details are needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description includes an 'Args' section that documents the single parameter 'params' with its structure, including 'filepaths (List[str]): Paths to files (max 50)'. This adds meaning beyond the schema, but since there's only one parameter, the baseline is 4. However, the description could provide more semantic context (e.g., path format, note types).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

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 metadata for multiple notes including tags, dates, and sizes.' It specifies the verb ('Get'), resource ('metadata for multiple notes'), and scope ('without reading full content'), distinguishing it from siblings like obsidian_get_file_contents (full content) and obsidian_get_frontmatter (specific metadata).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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: 'Efficient way to get overview information about several Zettelkasten notes without reading full content. Useful for analyzing note collections.' It implicitly distinguishes it from content-reading tools but does not explicitly name alternatives or state when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

obsidian_list_files_in_dirA
Read-onlyIdempotent

List files and directories in a specific vault directory.

Use this tool to explore the contents of a specific folder, such as your
Zettelkasten directory or any other organized section of your vault.

Args:
    params (ListFilesInput): Contains:
        - dirpath (str): Relative path to directory (empty for root)

Returns:
    str: Formatted list of directories and files in the specified path
    
Example:
    For dirpath="Zettelkasten", lists all notes in your Zettelkasten folder.
ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering safety aspects. The description adds useful context about the scope ('specific vault directory') and example use case, though it doesn't mention rate limits or authentication needs beyond what annotations imply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with purpose statement, usage guidance, parameter explanation, return value, and example - all in concise sentences that earn their place. No wasted words, and key information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (1 parameter), comprehensive annotations, and existence of an output schema, the description provides complete context. It covers purpose, usage, parameters, returns, and examples without needing to duplicate what structured fields already provide.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description compensates by explaining the single parameter dirpath as 'Relative path to directory (empty for root)' and providing an example. However, it doesn't add significant meaning beyond what's already implied by the parameter name and example.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

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 verb ('List') and resource ('files and directories in a specific vault directory'), and distinguishes it from sibling tools like obsidian_list_files_in_vault by specifying directory-level listing rather than vault-wide listing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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 explore the contents of a specific folder') with concrete examples ('Zettelkasten directory or any other organized section'), but doesn't explicitly mention when not to use it or name specific alternatives from the sibling list.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

obsidian_list_files_in_vaultA
Read-onlyIdempotent

List all files and directories in the vault root.

This tool shows the top-level structure of your Obsidian vault, helping you
understand the organization and locate folders for Zettelkasten notes.

Returns:
    str: Formatted list of directories and files in the vault root
    
Example:
    Returns a markdown-formatted list showing all top-level folders and files.
ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only, non-destructive, and idempotent behavior, which the description does not contradict. The description adds valuable context beyond annotations by specifying that it returns a 'markdown-formatted list' and helps 'understand the organization and locate folders for Zettelkasten notes,' enhancing behavioral understanding without redundancy.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and concise, with three sentences that each serve a distinct purpose: stating the tool's function, explaining its utility, and detailing the return format with an example. There is no wasted text, and information is front-loaded effectively.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

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, annotations covering safety, and an output schema implied by the description), the description is complete. It explains what the tool does, why to use it, and the return format, which is sufficient since the output schema handles return values. No gaps are present for this context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0 parameters and 100% schema description coverage, the baseline is 4. The description appropriately does not discuss parameters, as none exist, and instead focuses on the tool's output and purpose, adding meaningful context without unnecessary detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

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 files and directories'), target resource ('in the vault root'), and scope ('top-level structure'), distinguishing it from sibling tools like 'obsidian_list_files_in_dir' which would handle subdirectories. It explicitly mentions the purpose of understanding vault organization and locating folders for Zettelkasten notes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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 ('List all files and directories in the vault root'), but does not explicitly state when not to use it or name alternatives. It implies usage for top-level exploration, which differentiates it from directory-specific listing tools, but lacks explicit exclusions or comparisons.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

obsidian_manage_tagsA

Add, remove, or list tags in note frontmatter.

Manage tags for organizing Zettelkasten notes. Essential for maintaining
topic clusters and enabling efficient retrieval of related atomic notes.

Args:
    params (ManageTagsInput): Contains:
        - filepath (str): Path to note
        - action (TagAction): 'add', 'remove', or 'list'
        - tags (List[str], optional): Tags to add/remove (not needed for 'list')

Returns:
    str: Current tags after operation
    
Example:
    Add tags: action='add', tags=['systems-thinking', 'mental-models']
    Remove tag: action='remove', tags=['draft']
    List tags: action='list'
ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, destructiveHint=false, etc., covering basic safety. The description adds useful context about operating on 'note frontmatter' and the purpose ('organizing Zettelkasten notes'), but does not disclose additional behavioral traits like error handling, permissions needed, or effects on note structure beyond what annotations imply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded with the core purpose, followed by organized sections for Args, Returns, and Example. Every sentence adds value without redundancy, making it efficient for quick comprehension and reference.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (managing tags with three actions), the description is complete: it covers purpose, parameters, return values, and examples. With an output schema present, it appropriately omits detailed return explanations, focusing on practical usage. No gaps remain for effective tool invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates by detailing all parameters in the 'Args' section: it explains 'filepath', 'action' with its enum values, and 'tags' with optionality rules. This adds significant meaning beyond the bare schema, ensuring the agent understands parameter purposes and constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

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 ('Add, remove, or list tags') and resource ('in note frontmatter'), distinguishing it from sibling tools like obsidian_update_frontmatter or obsidian_get_frontmatter. It further explains the organizational context ('for organizing Zettelkasten notes') to reinforce its distinct role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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 ('Manage tags for organizing Zettelkasten notes... enabling efficient retrieval of related atomic notes'), but does not explicitly state when not to use it or name specific alternatives among siblings. The example section implicitly guides usage for different actions but lacks explicit comparisons.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

obsidian_patch_contentA

Insert content at specific locations within notes using headings, blocks, or frontmatter.

CRITICAL: For heading targets, you MUST provide the FULL HIERARCHICAL PATH.

Args:
    params (PatchContentInput): Contains:
        - filepath (str): Path to file
        - target_type (TargetType): 'heading', 'block', or 'frontmatter'
        - target (str): See examples below for correct format
        - operation (PatchOperation): 'append', 'prepend', or 'replace'
        - content (str): Content to insert

Returns:
    str: Success message with patch details

HEADING PATH EXAMPLES (MUST use full path with '/'):
    ✅ CORRECT:
       - target="Introduction" (for top-level # Introduction)
       - target="Methods/Data Collection" (for ## Data Collection under # Methods)
       - target="Results/Analysis/Statistical Tests" (for ### Statistical Tests under ## Analysis under # Results)

    ❌ WRONG:
       - target="Data Collection" (missing parent "Methods")
       - target="Statistical Tests" (missing parents "Results/Analysis")

BLOCK REFERENCE EXAMPLE:
    - target_type="block", target="^unique-block-id"

FRONTMATTER EXAMPLE:
    - target_type="frontmatter", target="tags"

Note: Always read the file first to see the exact heading structure before patching.
ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide readOnlyHint=false, destructiveHint=false, etc., but the description adds valuable behavioral context: the requirement to read files first to understand structure, the critical heading path format with examples of correct/incorrect usage, and specific examples for block and frontmatter targets. It doesn't contradict annotations and provides operational guidance beyond the basic safety hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with clear sections (purpose, args, returns, examples, notes). Every sentence earns its place by providing essential guidance. Slightly long due to extensive examples, but the examples are necessary for understanding the critical heading path requirement. The information is front-loaded with the core purpose first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of location-based patching with hierarchical paths, the description is complete: it covers purpose, all parameters with semantics, critical usage rules, examples for all target types, prerequisites (read first), and mentions the return value. With an output schema present, it doesn't need to detail return values further. The description compensates fully for the 0% schema coverage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage (the schema has descriptions but coverage calculation shows 0%), the description carries full burden and excels: it explains all 5 parameters in detail, provides critical format requirements for 'target' with hierarchical path examples, clarifies 'target_type' options with usage examples, and explains 'operation' behaviors. The description adds substantial meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Insert content at specific locations') and resource ('within notes'), specifying the three location types (headings, blocks, frontmatter). It distinguishes from siblings like obsidian_append_content (which likely appends to entire files) and obsidian_write_note (which likely writes new files) by emphasizing targeted insertion at specific locations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance is provided: 'Always read the file first to see the exact heading structure before patching' establishes a prerequisite. The description distinguishes when to use this tool (for targeted insertion) versus alternatives like obsidian_append_content (for appending to entire files) by implication of its specific location targeting. The critical note about heading paths provides clear when-to-use criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

obsidian_update_frontmatterA

Update YAML frontmatter metadata without modifying note content.

Add or update metadata fields like tags, status, or custom properties in
Zettelkasten notes while preserving all content.

Args:
    params (UpdateFrontmatterInput): Contains:
        - filepath (str): Path to file
        - updates (Dict): Frontmatter fields to add/update

Returns:
    str: Success message with updated frontmatter
    
Example:
    Add tags to existing note: updates={'tags': ['zettelkasten', 'systems-thinking']}
ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds valuable behavioral context beyond annotations: it specifies that only frontmatter is modified while content is preserved, mentions the tool works with 'Zettelkasten notes,' and provides an example of the update format. Annotations already indicate this is a non-destructive, non-readonly operation, so the description appropriately supplements rather than contradicts them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured with a clear purpose statement, usage context, parameter explanation, return value, and example - all in well-organized paragraphs with zero redundant information. Every sentence adds value and is appropriately front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (1 parameter with nested structure), lack of schema descriptions, and presence of output schema, the description provides good coverage of purpose, behavior, and parameter usage. The example helps clarify the updates format, though more detail on filepath validation or error cases would make it fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates by explaining the 'updates' parameter with examples ('tags', 'status', 'custom properties') and showing dictionary format. However, it doesn't fully document the 'filepath' parameter's requirements or provide comprehensive guidance on the updates dictionary structure beyond basic examples.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Update YAML frontmatter metadata') and resource ('note content'), distinguishing it from siblings like obsidian_manage_tags or obsidian_patch_content by focusing exclusively on frontmatter updates without modifying note body content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context about when to use this tool ('Add or update metadata fields like tags, status, or custom properties') and implicitly distinguishes it from content-modifying siblings by emphasizing 'without modifying note content.' However, it doesn't explicitly mention when NOT to use it or name specific alternative tools for related operations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

obsidian_write_noteA

Create or modify notes with content and optional frontmatter.

Primary tool for Zettelkasten note creation. Supports multiple modes:
- CREATE: Only creates new notes (safe, won't overwrite)
- OVERWRITE: Replaces entire file
- APPEND: Adds content to end
- PREPEND: Adds content to beginning

Args:
    params (WriteNoteInput): Contains:
        - filepath (str): Where to write the note
        - content (str): Note content
        - mode (WriteMode): create/overwrite/append/prepend (default: create)
        - frontmatter (Dict, optional): YAML frontmatter metadata

Returns:
    str: Success message with note location
    
Example:
    Create atomic note: filepath="Zettelkasten/202411061234 Systems Thinking.md",
    content="# Systems Thinking...", frontmatter={'tags': ['zettelkasten', 'concepts']}
ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds significant behavioral context beyond annotations, explaining the four distinct modes with their specific behaviors (e.g., CREATE is safe, OVERWRITE replaces entire file). Annotations provide basic hints (readOnlyHint=false, destructiveHint=false), but the description elaborates on operational details like default modes and safety characteristics, though it doesn't cover rate limits or auth needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and concise, with clear sections (purpose, modes, args, returns, example) and no wasted sentences. Each sentence adds value, such as explaining modes and providing a practical example, making it easy to scan and understand.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (multiple modes, 1 parameter with nested object) and the presence of an output schema (returns str), the description is largely complete. It covers purpose, usage, parameters, and behavior, though it could benefit from more detail on error cases or frontmatter handling. The output schema reduces the need to explain return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds some parameter semantics by listing and briefly describing the four parameters (filepath, content, mode, frontmatter) and providing an example. However, with 0% schema description coverage, the schema lacks descriptions, so the description partially compensates but doesn't fully detail formats or constraints (e.g., filepath structure, content limits).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

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 modify notes') and resources ('notes with content and optional frontmatter'), distinguishing it from siblings like obsidian_append_content by covering multiple modes. It explicitly identifies itself as the 'Primary tool for Zettelkasten note creation,' providing clear differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidelines by detailing four specific modes (CREATE, OVERWRITE, APPEND, PREPEND) with clear behavioral descriptions, including safety notes ('safe, won't overwrite' for CREATE). It distinguishes when to use this tool versus alternatives like obsidian_append_content by offering a comprehensive set of write operations in one tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 13 tool updatesv1.0.0
    • Changedobsidian_append_content2 fields changed
      • addedInput schema / $defs
        Added value: +{
+  "AppendContentInput": {
+    "additionalProperties": false,
+    "description": "Input for appending content to files.",
+    "properties": {
+      "content": {
+        "description": "Content to append to the file",
+        "maxLength": 50000,
+        "minLength": 1,
+        "title": "Content",
+        "type": "string"
+      },
+      "filepath": {
+        "description": "Path to the file to append to",
+        "maxLength": 500,
+        "minLength": 1,
+        "title": "Filepath",
+        "type": "string"
+      }
+    },
+    "required": [
+      "filepath",
+      "content"
+    ],
+    "title": "AppendContentInput",
+    "type": "object"
+  }
+}
      • addedInput schema / title
        Added value: +"append_contentArguments"
    • Changedobsidian_batch_get_file_contents2 fields changed
      • addedInput schema / $defs
        Added value: +{
+  "BatchGetFilesInput": {
+    "additionalProperties": false,
+    "description": "Input for batch reading multiple files.",
+    "properties": {
+      "filepaths": {
+        "description": "List of file paths to read",
+        "items": {
+          "type": "string"
+        },
+        "maxItems": 20,
+        "minItems": 1,
+        "title": "Filepaths",
+        "type": "array"
+      }
+    },
+    "required": [
+      "filepaths"
+    ],
+    "title": "BatchGetFilesInput",
+    "type": "object"
+  }
+}
      • addedInput schema / title
        Added value: +"batch_get_filesArguments"
    • Changedobsidian_delete_file2 fields changed
      • addedInput schema / $defs
        Added value: +{
+  "DeleteFileInput": {
+    "additionalProperties": false,
+    "description": "Input for deleting files.",
+    "properties": {
+      "confirm": {
+        "default": false,
+        "description": "Must be set to true to confirm deletion",
+        "title": "Confirm",
+        "type": "boolean"
+      },
+      "filepath": {
+        "description": "Path to the file or directory to delete",
+        "maxLength": 500,
+        "minLength": 1,
+        "title": "Filepath",
+        "type": "string"
+      }
+    },
+    "required": [
+      "filepath"
+    ],
+    "title": "DeleteFileInput",
+    "type": "object"
+  }
+}
      • addedInput schema / title
        Added value: +"delete_fileArguments"
    • Changedobsidian_get_file_contents2 fields changed
      • addedInput schema / $defs
        Added value: +{
+  "GetFileInput": {
+    "additionalProperties": false,
+    "description": "Input for getting file contents.",
+    "properties": {
+      "filepath": {
+        "description": "Path to the file relative to vault root (e.g., 'Notes/zettelkasten/202411061234.md')",
+        "maxLength": 500,
+        "minLength": 1,
+        "title": "Filepath",
+        "type": "string"
+      }
+    },
+    "required": [
+      "filepath"
+    ],
+    "title": "GetFileInput",
+    "type": "object"
+  }
+}
      • addedInput schema / title
        Added value: +"get_file_contentsArguments"
    • Changedobsidian_get_frontmatter2 fields changed
      • addedInput schema / $defs
        Added value: +{
+  "GetFrontmatterInput": {
+    "additionalProperties": false,
+    "description": "Input for getting frontmatter.",
+    "properties": {
+      "filepath": {
+        "description": "Path to the file",
+        "maxLength": 500,
+        "minLength": 1,
+        "title": "Filepath",
+        "type": "string"
+      }
+    },
+    "required": [
+      "filepath"
+    ],
+    "title": "GetFrontmatterInput",
+    "type": "object"
+  }
+}
      • addedInput schema / title
        Added value: +"get_frontmatterArguments"
    • Changedobsidian_get_notes_info2 fields changed
      • addedInput schema / $defs
        Added value: +{
+  "GetNotesInfoInput": {
+    "additionalProperties": false,
+    "description": "Input for getting metadata about notes.",
+    "properties": {
+      "filepaths": {
+        "description": "List of file paths to get info about",
+        "items": {
+          "type": "string"
+        },
+        "maxItems": 50,
+        "minItems": 1,
+        "title": "Filepaths",
+        "type": "array"
+      }
+    },
+    "required": [
+      "filepaths"
+    ],
+    "title": "GetNotesInfoInput",
+    "type": "object"
+  }
+}
      • addedInput schema / title
        Added value: +"get_notes_infoArguments"
    • Changedobsidian_list_files_in_dir2 fields changed
      • addedInput schema / $defs
        Added value: +{
+  "ListFilesInput": {
+    "additionalProperties": false,
+    "description": "Input for listing files in a directory.",
+    "properties": {
+      "dirpath": {
+        "anyOf": [
+          {
+            "maxLength": 500,
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": "",
+        "description": "Relative directory path to list (empty string for vault root)",
+        "title": "Dirpath"
+      }
+    },
+    "title": "ListFilesInput",
+    "type": "object"
+  }
+}
      • addedInput schema / title
        Added value: +"list_files_in_dirArguments"
    • Changedobsidian_list_files_in_vault1 field changed
      • addedInput schema / title
        Added value: +"list_files_in_vaultArguments"
    • Changedobsidian_manage_tags2 fields changed
      • addedInput schema / $defs
        Added value: +{
+  "ManageTagsInput": {
+    "additionalProperties": false,
+    "description": "Input for managing tags.",
+    "properties": {
+      "action": {
+        "$ref": "#/$defs/TagAction",
+        "description": "Action: 'add' to add tags, 'remove' to delete tags, 'list' to show current tags"
+      },
+      "filepath": {
+        "description": "Path to the note",
+        "maxLength": 500,
+        "minLength": 1,
+        "title": "Filepath",
+        "type": "string"
+      },
+      "tags": {
+        "anyOf": [
+          {
+            "items": {
+              "type": "string"
+            },
+            "maxItems": 50,
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Tags to add or remove (not needed for 'list' action)",
+        "title": "Tags"
+      }
+    },
+    "required": [
+      "filepath",
+      "action"
+    ],
+    "title": "ManageTagsInput",
+    "type": "object"
+  },
+  "TagAction": {
+    "description": "Actions for tag management.",
+    "enum": [
+      "add",
+      "remove",
+      "list"
+    ],
+    "title": "TagAction",
+    "type": "string"
+  }
+}
      • addedInput schema / title
        Added value: +"manage_tagsArguments"
    • Changedobsidian_patch_content2 fields changed
      • addedInput schema / $defs
        Added value: +{
+  "PatchContentInput": {
+    "additionalProperties": false,
+    "description": "Input for patching content relative to headings/blocks/frontmatter.",
+    "properties": {
+      "content": {
+        "description": "Content to insert",
+        "maxLength": 50000,
+        "minLength": 1,
+        "title": "Content",
+        "type": "string"
+      },
+      "filepath": {
+        "description": "Path to the file to patch",
+        "maxLength": 500,
+        "minLength": 1,
+        "title": "Filepath",
+        "type": "string"
+      },
+      "operation": {
+        "$ref": "#/$defs/PatchOperation",
+        "description": "Operation: 'append' to add after target, 'prepend' to add before target, 'replace' to overwrite target"
+      },
+      "target": {
+        "description": "IMPORTANT: For 'heading' type, MUST use FULL HIERARCHICAL PATH with '/' separator. Examples: 'Introduction' (top-level), 'Methods/Data Collection' (nested), 'Results/Analysis/Statistics' (deeply nested). For 'block' type: block reference like '^block-id'. For 'frontmatter' type: field name like 'tags' or 'status'.",
+        "maxLength": 200,
+        "minLength": 1,
+        "title": "Target",
+        "type": "string"
+      },
+      "target_type": {
+        "$ref": "#/$defs/TargetType",
+        "description": "Type of target: 'heading' for markdown headers, 'block' for block references, 'frontmatter' for YAML metadata"
+      }
+    },
+    "required": [
+      "filepath",
+      "target_type",
+      "target",
+      "operation",
+      "content"
+    ],
+    "title": "PatchContentInput",
+    "type": "object"
+  },
+  "PatchOperation": {
+    "description": "Operations for patching content.",
+    "enum": [
+      "append",
+      "prepend",
+      "replace"
+    ],
+    "title": "PatchOperation",
+    "type": "string"
+  },
+  "TargetType": {
+    "description": "Types of targets for patching.",
+    "enum": [
+      "heading",
+      "block",
+      "frontmatter"
+    ],
+    "title": "TargetType",
+    "type": "string"
+  }
+}
      • addedInput schema / title
        Added value: +"patch_contentArguments"
    • Changedobsidian_search2 fields changed
      • addedInput schema / $defs
        Added value: +{
+  "SearchInput": {
+    "additionalProperties": false,
+    "description": "Input for vault searches using JsonLogic queries.",
+    "properties": {
+      "query": {
+        "additionalProperties": true,
+        "description": "JsonLogic query object for searching vault. Examples: {'glob': ['*.md', {'var': 'path'}]} for all markdown files, {'in': ['search term', {'lower': [{'var': 'content'}]}]} for text search",
+        "title": "Query",
+        "type": "object"
+      }
+    },
+    "required": [
+      "query"
+    ],
+    "title": "SearchInput",
+    "type": "object"
+  }
+}
      • addedInput schema / title
        Added value: +"search_vaultArguments"
    • Changedobsidian_update_frontmatter2 fields changed
      • addedInput schema / $defs
        Added value: +{
+  "UpdateFrontmatterInput": {
+    "additionalProperties": false,
+    "description": "Input for updating frontmatter.",
+    "properties": {
+      "filepath": {
+        "description": "Path to the file",
+        "maxLength": 500,
+        "minLength": 1,
+        "title": "Filepath",
+        "type": "string"
+      },
+      "updates": {
+        "additionalProperties": true,
+        "description": "Frontmatter fields to update or add (e.g., {'tags': ['new-tag'], 'status': 'published'})",
+        "title": "Updates",
+        "type": "object"
+      }
+    },
+    "required": [
+      "filepath",
+      "updates"
+    ],
+    "title": "UpdateFrontmatterInput",
+    "type": "object"
+  }
+}
      • addedInput schema / title
        Added value: +"update_frontmatterArguments"
    • Changedobsidian_write_note2 fields changed
      • addedInput schema / $defs
        Added value: +{
+  "WriteMode": {
+    "description": "Mode for writing content to files.",
+    "enum": [
+      "create",
+      "overwrite",
+      "append",
+      "prepend"
+    ],
+    "title": "WriteMode",
+    "type": "string"
+  },
+  "WriteNoteInput": {
+    "additionalProperties": false,
+    "description": "Input for writing/creating notes.",
+    "properties": {
+      "content": {
+        "description": "The content to write to the note",
+        "maxLength": 50000,
+        "minLength": 0,
+        "title": "Content",
+        "type": "string"
+      },
+      "filepath": {
+        "description": "Path where the note should be written (e.g., 'Zettelkasten/202411061234 - Note Title.md')",
+        "maxLength": 500,
+        "minLength": 1,
+        "title": "Filepath",
+        "type": "string"
+      },
+      "frontmatter": {
+        "anyOf": [
+          {
+            "additionalProperties": true,
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Optional frontmatter metadata to add/update (e.g., {'tags': ['zettelkasten'], 'created': '2024-11-06'})",
+        "title": "Frontmatter"
+      },
+      "mode": {
+        "$ref": "#/$defs/WriteMode",
+        "default": "create",
+        "description": "Write mode: 'create' for new files only, 'overwrite' to replace, 'append' to add to end, 'prepend' to add to beginning"
+      }
+    },
+    "required": [
+      "filepath",
+      "content"
+    ],
+    "title": "WriteNoteInput",
+    "type": "object"
+  }
+}
      • addedInput schema / title
        Added value: +"write_noteArguments"
  2. 13 tool updates
    • First observedobsidian_append_content
    • First observedobsidian_batch_get_file_contents
    • First observedobsidian_delete_file
    • First observedobsidian_get_file_contents
    • First observedobsidian_get_frontmatter
    • First observedobsidian_get_notes_info
    • First observedobsidian_list_files_in_dir
    • First observedobsidian_list_files_in_vault
    • First observedobsidian_manage_tags
    • First observedobsidian_patch_content
    • First observedobsidian_search
    • First observedobsidian_update_frontmatter
    • First observedobsidian_write_note
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose with no significant overlap. For example, obsidian_append_content adds to the end of files, obsidian_patch_content inserts at specific locations, and obsidian_write_note offers multiple write modes. The tools cover different aspects of file operations (read, write, update, delete, search, metadata management) without ambiguity.

Naming Consistency5/5

All tools follow a consistent 'obsidian_verb_noun' naming pattern throughout. The verbs are descriptive (e.g., append, batch_get, delete, get, list, manage, patch, search, update, write), and the nouns clearly indicate the target resource (e.g., content, file_contents, frontmatter, tags, note). There are no deviations in style or convention.

Tool Count5/5

With 13 tools, the server is well-scoped for managing an Obsidian vault and Zettelkasten workflow. Each tool serves a specific, necessary function, from basic CRUD operations (read, write, update, delete) to advanced features like search, metadata management, and batch operations. The count is neither too sparse nor bloated for the domain.

Completeness5/5

The tool set provides comprehensive coverage for Obsidian vault management, including full CRUD for files (create, read, update, delete), metadata handling (frontmatter and tags), directory navigation, search, and specialized operations like patching and batch reads. There are no obvious gaps; agents can perform all essential workflows for note-taking and organization.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Advanced Obsidian MCP Server

    ToKiDoO
    A
    license
    A
    quality
    D
    maintenance
    Empowers AI agents to deeply understand and interact with Obsidian vaults through the Local REST API, enabling advanced features like vault structure discovery, graph analysis, command execution, and batch file operations.
    16
    19
    MIT

  • MCP Obsidian Server

    fazer-ai
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables LLMs to interact with Obsidian vaults via the Local REST API plugin for comprehensive note management, file operations, and vault navigation. It supports creating and editing notes, executing Obsidian commands, and performing advanced searches using Dataview queries.
    78
    52
    MIT

  • Obsidian MCP Server

    derrikjb
    F
    license
    A
    quality
    Not graded
    maintenance
    Integrates with the Obsidian Local REST API to enable reading, creating, editing, and searching notes within an Obsidian vault. It supports advanced operations like Dataview queries and partial file updates through both stdio and HTTP transport modes.
    8
    5,784
    -

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Shepherd-Creative/obsidian-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server