Provides tools for interacting with Obsidian vaults, including searching, reading, writing, and managing notes, tags, backlinks, daily notes, and vault settings, with support for multiple vaults and fallback to filesystem access when Obsidian is closed.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@obsidian-mcp Find notes with tag 'meeting' across my vaults"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A FastMCP server for multiple Obsidian vaults. It talks to the Obsidian Local REST API plugin when Obsidian is running, and falls back to direct filesystem access when it isn't — so your notes stay reachable whether or not the app is open.
Every tool takes an optional vault argument, and obsidian_switch_vault sets the default for unqualified calls.
REST (Obsidian running) | Filesystem (always) | |
Search | Obsidian's own index and ranking | substring scan, all terms must match |
Tags | resolved by Obsidian, with counts | parsed from frontmatter + inline |
Backlinks | ✅ from the link graph | ❌ not available |
Active note / open in UI / commands | ✅ | ❌ |
Works with Obsidian closed | ❌ | ✅ |
Works on a headless box or over SSH | ❌ | ✅ |
The router probes REST health once and caches the result for OBSIDIAN_HEALTH_TTL seconds, so a closed Obsidian doesn't cost a failed connection on every call. If REST drops mid-call it retries on the filesystem automatically. Errors that mean "what you asked for doesn't exist" (missing note, bad path) are not retried — falling back would just fail again, slower.
Every response reports which backend served it, so a caller can tell whether it's seeing Obsidian's view or the raw files.
Related MCP server: Obsidian Tools MCP Server
git clone <your-repo> obsidian-mcp && cd obsidian-mcp
uv venv && uv pip install -e ".[dev]" # or: pip install -e ".[dev]"
pytestRequires Python 3.11+. Works with MCP Python SDK 1.x (FastMCP) and 2.x (MCPServer) — _sdk.py papers over the rename.
Define vaults using whichever of these fits; the first one present wins.
A TOML file (best for 3+ vaults) — OBSIDIAN_VAULTS_FILE=~/.config/obsidian-mcp/vaults.toml:
default = "personal"
[vaults.personal]
path = "/Users/you/Vaults/Personal"
description = "Homelab, hobbies"
daily_folder = "Journal"
[vaults.work]
path = "/Users/you/Vaults/Work"
description = "Employer notes"
rest_base_url = "https://127.0.0.1:27125" # note: NOT the default port
api_key = "this-vault's-own-key"Inline JSON — OBSIDIAN_VAULTS='{"default":"work","vaults":{...}}'. Accepts port/protocol/host shorthand instead of rest_base_url, and camelCase keys, so configs from other Obsidian MCP servers mostly paste straight in.
Per-vault env vars — OBSIDIAN_VAULT_WORK_PATH, OBSIDIAN_VAULT_WORK_API_KEY, OBSIDIAN_VAULT_WORK_REST_BASE_URL, etc. The segment between OBSIDIAN_VAULT_ and the field name is the vault name.
Legacy single-vault vars — OBSIDIAN_VAULT_PATH / OBSIDIAN_REST_BASE_URL / OBSIDIAN_API_KEY still work and define one vault named default.
Every vault's Local REST API plugin defaults to port 27124, and only one process can bind a port. If you run two vaults at once, open each vault's Settings → Local REST API → Advanced and give it a unique port (27124, 27125, 27126…), then toggle the plugin off and on.
Each vault also generates its own API key, so a mismatched port usually shows up as a 401 rather than silently reading the wrong vault. To check positively:
obsidian_backend_status(verify=true)That cross-checks each vault's REST root listing against its configured path and warns if they disagree.
path, rest_base_url, api_key, verify_ssl, ca_cert, daily_folder, daily_format, description
Variable | Default | Notes |
| first defined | Overrides |
|
| Set |
|
| Disables every mutating tool, across all vaults. |
|
| Refuse to read anything larger. |
|
| Seconds to cache each vault's REST health probe. |
|
| Per-request timeout in seconds. |
To trust the plugin's cert rather than disabling verification, per vault:
curl -k https://127.0.0.1:27125/obsidian-local-rest-api.crt -o ~/.config/obsidian-mcp/work.crt
# then in vaults.toml: ca_cert = "~/.config/obsidian-mcp/work.crt" and verify_ssl = trueClaude Code:
claude mcp add obsidian -- \
uv --directory /path/to/obsidian-mcp run obsidian-mcpThen set the env vars in .mcp.json or your shell profile.
Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"obsidian": {
"command": "uv",
"args": ["--directory", "/path/to/obsidian-mcp", "run", "obsidian-mcp"],
"env": {
"OBSIDIAN_VAULTS_FILE": "/Users/you/.config/obsidian-mcp/vaults.toml"
}
}
}
}Vaults — obsidian_list_vaults, obsidian_switch_vault
Reads — obsidian_list_notes, obsidian_read_note, obsidian_search_notes, obsidian_list_tags, obsidian_get_active_note*, obsidian_backend_status
Writes — obsidian_write_note, obsidian_append_to_note, obsidian_patch_note, obsidian_append_to_daily_note, obsidian_move_note, obsidian_delete_note
App control — obsidian_open_note, obsidian_list_commands, obsidian_run_command*
* requires Obsidian to be running. These deliberately do not fall back — they return a message telling you to start Obsidian, rather than silently doing something different from what you asked.
All 17 tools accept an optional vault. Targeting works two ways, on purpose:
Per-call — obsidian_search_notes(vault="work", query="..."). Explicit and stateless; the right choice when a task spans vaults.
Session default — obsidian_switch_vault(vault="work") changes where unqualified calls go, so a long stretch of work in one vault doesn't repeat the argument.
A per-call vault always overrides the session default. Switching affects this server session only — it doesn't touch any vault's contents or change which vault Obsidian has open.
obsidian_backend_status is the one to call first when something fails with a connectivity error; with no vault named it probes all of them and reports which backends are live.
Deletes are recoverable by default. obsidian_delete_note moves the note to the vault's .trash, restorable from inside Obsidian. permanent=true is opt-in. Because the plugin's DELETE is unconditional, trashing is routed through the filesystem backend even when REST is live.
Absolute paths and .. traversal are rejected, not silently rewritten. Resolved paths are checked against the vault root.
obsidian_write_note won't clobber an existing note without overwrite=true.
OBSIDIAN_READ_ONLY=true disables every mutating tool in one switch — useful for a research-only session.
Moving a note does not rewrite wikilinks. Only Obsidian does that, and only for moves made inside the app. Search for the old name afterwards if it matters.
Frontmatter patches reformat the YAML block. Values round-trip through PyYAML, so tags: [a, b] comes back as a block list. Content is preserved; formatting isn't.
Filesystem search has no fuzzy matching or ranking beyond a title-match boost. When Obsidian is running you get its real index instead.
The filesystem backend doesn't see unsaved editor buffers. A note being actively edited may be stale on disk by a few seconds.
Cross-vault operations aren't atomic. obsidian_move_note works within one vault only; moving between vaults means read, write, delete as separate calls.
obsidian_get_active_note is per-vault, and only answers for a vault whose Obsidian window is open with the plugin bound to that vault's configured port.
As of v3+, the Local REST API plugin ships its own built-in MCP server at https://127.0.0.1:27124/mcp/ (streamable HTTP, bearer auth). If all you want is Obsidian access while Obsidian is running, point your client at that and skip this project entirely.
This server earns its place when you want the things that one can't do: working with the vault while Obsidian is closed, running on a headless machine, read-only enforcement, trash-by-default deletes, or custom workflow tools shaped around your own vault conventions.
pytest # 40 tests, no Obsidian required
ruff check obsidian_mcp tests
npx @modelcontextprotocol/inspector uv --directory . run obsidian-mcpThe test suite fakes the REST backend, so fallback and multi-vault routing are covered without a running Obsidian.
Append to the daily note for today or a given date, creating it if needed.
The daily note path is built from OBSIDIAN_DAILY_FOLDER and OBSIDIAN_DAILY_FORMAT, so it works whether or not Obsidian is running.
Args: params (DailyNoteInput): - content (str): Markdown to append - day (Optional[str]): ISO date 'YYYY-MM-DD'; defaults to today - heading (Optional[str]): Append under an existing heading instead of at the end of the note
Returns: str: JSON of the shape {"status": "ok", "action": "appended"|"patched", "path": str, "backend": "rest"|"filesystem", "note": str} On failure: "Error: "
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses non-obvious behavior not in annotations: it auto-creates the note, resolves the path from OBSIDIAN_DAILY_FOLDER and OBSIDIAN_DAILY_FORMAT, and can operate through filesystem or REST backends. It also describes the success and failure return shape. Basic safety hints are already in annotations, so this is a meaningful addition without contradiction.
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 action and then uses compact Args/Returns sections. It is scannable with minimal filler, though some of the Args detail is redundant with the schema.
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?
The description covers the key operational details: date defaulting, heading requirement, path construction, backend flexibility, and return/error shape. The only notable gap is the omitted vault parameter, but that is clearly documented in the schema, so the definition as a whole is sufficiently 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 input schema's top-level 'params' property has no description (0% coverage), and the description's Args section repeats much of what the nested schema already documents. More importantly, it completely omits the 'vault' parameter, which is present in the schema, so an agent relying on the description could miss a supported option.
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 states a precise verb and resource: 'Append to the daily note for today or a given date, creating it if needed.' This clearly distinguishes it from the general obsidian_append_to_note sibling because it specifically targets the daily note and mentions creation and date handling.
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 such as when the daily note is created and that it works regardless of Obsidian running. However, it does not explicitly say when to prefer this tool over obsidian_append_to_note or when not to use it, leaving alternative routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add markdown to the end of a note, creating the note if it does not exist.
Safe by design: nothing already in the note is modified. Repeated calls append repeatedly.
Args: params (AppendNoteInput): - path (str): Vault-relative path - content (str): Markdown to append
Returns: str: JSON of the shape {"status": "ok", "action": "appended", "path": str, "backend": "rest"|"filesystem"} On failure: "Error: "
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description explicitly discloses that existing note content is never modified, that repeated calls append repeatedly, and that failures return an actionable error string. It also documents the exact success response shape, providing strong behavioral 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 opening sentence front-loads the core behavior, and the safety note and return contract are useful. The Args section is somewhat redundant with the schema and incomplete by omitting vault, preventing a top score.
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?
The description covers the essential behavior, side effects, note creation, return format, and failure mode. The only meaningful gap is that the optional vault routing is left to the schema rather than the description, so an agent relying only on this text would miss that option.
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 lists path and content with basic type info, but it largely repeats what the schema already says and omits the optional vault parameter. The schema itself documents the nested fields well enough, so this is acceptable but not additive.
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 operation: 'Add markdown to the end of a note' and adds the create-if-missing behavior, making the tool's purpose unambiguous against siblings like write or patch. It does not explicitly name a sibling alternative, so it stops short of 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 'Safe by design: nothing already in the note is modified. Repeated calls append repeatedly' phrasing gives clear context for using this as a non-destructive, append-only operation. It does not explicitly mention alternatives or when not to use it, but the implied usage is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report, per vault, which backend is live and which capabilities are usable.
Call this first when a tool fails with a connectivity error, or when you need to know whether backlinks, the active note, and commands work right now. With no vault named it probes every configured vault.
Set verify=true to cross-check that each vault's REST port is really serving the vault at its configured path. Worth doing after adding a vault or changing ports, since every vault's plugin defaults to port 27124 and they collide.
Args: params (StatusInput): - vault (Optional[str]): One vault to check; omit to check all - verify (bool): Also cross-check REST endpoint against vault path - response_format (str): unused; JSON is always returned
Returns: str: JSON of the shape {"current_vault": str, "read_only": bool, "vaults": [{"vault": str, "rest_configured": bool, "rest_reachable": bool, "rest_base_url": str|null, "filesystem_configured": bool, "vault_path": str|null, "active_backend": "rest"|"filesystem", "obsidian_only_features_available": bool, "is_current": bool, "identity": {...}}]} On failure: "Error: "
| Name | Required | Description | Default |
|---|---|---|---|
| params | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true and idempotentHint=true, so the bar for description transparency is met by adding context beyond those. The description explains the port collision issue and the verify behavior ('Costs an extra listing per vault' is also in schema, but the description elaborates on the collision and cross-check intent). It also clarifies that response_format is unused ('JSON is always returned'), which is a behavioral trait not declared in annotations. No contradiction exists.
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 structured with a one-line summary, a usage paragraph, a parameter list, and a return shape block. The most important usage guidance ('Call this first...') is front-loaded. Every sentence adds information—no fluff. It is appropriately verbose given the tool's complexity (multiple vaults, verify flag, detailed return). Length is justified.
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?
The tool is moderately complex due to optional vault targeting and a verification flag, yet the description covers all aspects: purpose, when to use, parameter behavior, side-effect cost (extra listing), and even the exact JSON response shape. The output schema exists but the description provides the full payload structure, ensuring an agent knows exactly what to expect. No missing context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description enriches the schema even though the schema already provides descriptions for vault and verify. It reinforces vault semantics ('omit to check all') and verify ('cross-check REST endpoint against vault path'), and critically reveals response_format is non-functional ('unused; JSON is always returned'), which the schema's enum does not imply. It also provides a full return JSON structure, giving concrete meaning to the output. This fully compensates for any perceived schema coverage gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific verb-resource pair: 'Report, per vault, which backend is live and which capabilities are usable.' It immediately distinguishes this tool from siblings like obsidian_get_active_note or obsidian_list_vaults by focusing on backend status and capability probing. It also answers 'what' directly with a detailed return shape, making the tool's 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?
Explicitly states when to invoke: 'Call this first when a tool fails with a connectivity error, or when you need to know whether backlinks, the active note, and commands work right now.' It also provides a concrete trigger for the verify flag: 'Worth doing after adding a vault or changing ports.' This gives both a general when-to-use and a specific condition for an optional flag, fully covering usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a note, by default into the vault's .trash folder.
A default delete is recoverable: the note moves to '.trash' inside the vault and can be restored from Obsidian. Pass permanent=true only when the note should be unrecoverable.
Args: params (DeleteNoteInput): - path (str): Vault-relative path to delete - permanent (bool): True deletes outright and cannot be undone
Returns: str: JSON of the shape {"status": "ok", "action": "trashed"|"deleted", "path": str, "backend": "rest"|"filesystem", "note": str} where path is the .trash location for a recoverable delete. On failure: "Error: "
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true unbeknownst to the description. It transparently discloses the trash and permanent behaviors, including recoverability implicationstelling the agent when to use each variant. A minor gap is not mentioning vault targeting, but that is covered in schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loads the key behavior (default trash) in the first line. Additional details are organized logically with clear sections for parameters and return value. Every sentence adds value, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema is described in detail, including the JSON shape and error semantics. Given the simplicity of the tool and the presence of clear annotations (destructiveHint=true), the description is complete enough for correct usage. It could mention the vault parameter but that is in schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description repeats the schema definitions for path and permanent, but since schema coverage is 0%, it fully compensates by describing both parameters in plain language. It adds no new detail beyond what the schema already states, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool deletes a note by default into the vault's .trash folder, which is specific and distinguishes it from other note operations like write or move. Though it does not explicitly compare with siblings, the unique verb and resource are clear.
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 explicitly explains when to use the default (recoverable delete) versus permanent=true, and it warns about irreversibility. It does not name alternative tools, but for a delete operation, the guidance is sufficient for correct selection and invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read whichever note is currently open in the Obsidian window.
Requires Obsidian to be running with the Local REST API plugin — there is no filesystem equivalent of "the active note".
Args: params (EmptyInput): - response_format (str): 'markdown' or 'json'
Returns: str: Same shape as obsidian_read_note. On failure: "Error: Cannot read the active note: "
| Name | Required | Description | Default |
|---|---|---|---|
| params | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context by disclosing the runtime dependency on Obsidian and the plugin, plus the exact failure message shape, which goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core purpose, and structured into Args and Returns sections. However, the Args section is inaccurate because it omits the vault parameter, which is a small structural flaw.
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 low schema coverage, the description does well by stating prerequisites, return shape, and failure behavior. The only significant gap is the undocumented vault parameter, but the schema does provide a description for vault, so the overall context is nearly 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?
Schema description coverage is 0%, so the description should compensate for parameter meaning. It mentions response_format with allowed values, but that duplicates the schema's enum, and it completely omits the vault parameter entirely. The description's Args section is incomplete and misleading about what parameters 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 states a specific action and resource: read whichever note is currently open in the Obsidian window. This clearly differentiates it from obsidian_read_note (read by path) and obsidian_open_note (open a specific note). It also directly references the active-note concept rather than relying on the title.
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 explains the key operational prerequisite: Obsidian must be running with the Local REST API plugin, and there is no filesystem equivalent of the active note. This implies when this tool is appropriate, though it does not explicitly list alternatives or say 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.
List every command in Obsidian's command palette, with IDs for running them.
Requires Obsidian to be running with the Local REST API plugin.
Returns: str: JSON of the shape {"count": int, "commands": [{"id": str, "name": str}]} On failure: "Error: "
Args: params (VaultOnlyInput): - vault (Optional[str]): Which vault's Obsidian window to query
| Name | Required | Description | Default |
|---|---|---|---|
| params | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the operation read-only and idempotent. The description adds the prerequisite that Obsidian must be running with the Local REST API plugin, and discloses both the JSON return shape and the failure string format. This goes beyond what the annotations alone communicate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with purpose, and uses clearly labeled sections for requirements, returns, and arguments. Every sentence earns its place without verbose filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity read-only tool with one optional parameter, the description covers purpose, prerequisite, exact return shape, failure format, and parameter semantics. The agent has everything needed to call it correctly without requiring additional 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 restates the single optional vault parameter with its purpose, but adds little over the schema's own property description. With only one optional parameter and a clear default, this is adequate; the low schema coverage signal does not create a real gap here.
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 begins with a specific verb-resource pair, 'List every command in Obsidian's command palette', and explicitly mentions IDs for running them, which differentiates it from sibling note/vault tools and connects it to obsidian_run_command. This makes the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when to use the tool—when the agent needs an inventory of commands and their IDs before invoking them—and states the runtime prerequisite (Obsidian running with Local REST API plugin). It does not explicitly list exclusions or alternatives, but the command-ID wording makes the relationship to obsidian_run_command evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List notes and folders in the vault, optionally scoped to one folder.
Use this to discover the vault's structure before reading or writing. For finding a note by its contents, obsidian_search_notes is faster.
Args: params (ListNotesInput): - folder (str): Vault-relative folder, empty for the root - recursive (bool): Walk nested folders too - response_format (str): 'markdown' or 'json'
Returns: str: Markdown list, or JSON of the shape {"folder": str, "count": int, "backend": "rest"|"filesystem", "entries": [{"path": str, "is_folder": bool, "size_bytes": int, "modified_at": str}]} On failure: "Error: "
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is known. The description adds value by detailing the output format (markdown or JSON), including the JSON structure and error format, which are not in annotations. It does not contradict annotations and offers meaningful 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 concise, front-loaded with the main purpose and usage guidance, then structured args and returns. Every sentence carries meaningful information, with no fluff or repetition. The layout is clear and aids quick scanning.
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?
The description covers the tool's purpose, usage context, parameters (mostly), return format, and error handling. The missing vault parameter is present in the schema with a clear description, so an agent can still find it. Given the many siblings, it explicitly mentions one relevant alternative, which is sufficient. Slight gap in not listing all params in prose, but overall 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% (the top-level 'params' property lacks description), so the tool description must compensate. It covers folder, recursive, and response_format but omits the 'vault' parameter. It adds brief explanations but not as detailed as the schema's own properties (e.g., folder examples). This is partially compensating but not fully covering all parameters, so a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List notes and folders in the vault') with the resource (vault) and optional scoping. It differentiates from sibling obsidian_search_notes by noting that content search is better served there, making its purpose distinct and 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 explicitly advises using this tool to 'discover the vault's structure before reading or writing' and explicitly redirects content lookups to 'obsidian_search_notes is faster.' This provides clear when-to-use and when-not-to-use guidance, exceeding a generic statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every tag in the vault with how many notes use it.
Useful for orienting in an unfamiliar vault, or checking which tag spelling is already in use before adding a new one.
Args: params (EmptyInput): - response_format (str): 'markdown' or 'json'
Returns: str: Markdown table, or JSON of the shape {"count": int, "backend": "rest"|"filesystem", "tags": {"": int}} Tag names have no leading '#'. Counts may be 0 when the REST backend reports tags without usage data. On failure: "Error: "
| Name | Required | Description | Default |
|---|---|---|---|
| params | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (read-only, idempotent, non-destructive), the description discloses backend-dependent behavior ('rest'|'filesystem'), that counts can be 0, that tags omit leading '#', and the failure message shape. This gives an agent accurate expectations for output edge cases.
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?
Purpose and use cases are front-loaded, followed by compact Args/Returns sections. Return-format details and edge cases earn their place rather than padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only listing tool, the description covers input, output format, backend variance, zero-count semantics, and error format. The optional vault parameter is handled by the schema, so nothing needed to call it correctly is missing.
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 explains response_format choices and the resulting output shape. It does not repeat the vault parameter, but the schema documents vault's default and meaning ('Omit to use the current vault'), so an agent can resolve all parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with a precise verb-resource pair: 'List every tag in the vault with how many notes use it.' This clearly distinguishes from sibling operations like obsidian_search_notes or obsidian_list_notes, and the title reinforces the same function.
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?
Two concrete use cases are stated: orienting in an unfamiliar vault and checking tag spelling before adding one. It does not explicitly name sibling alternatives or state when not to use it, so it misses the 'when-not/alternatives' bar, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every configured vault, showing which one unqualified calls will hit.
Reads configuration only — it does not contact Obsidian, so it is cheap and safe to call first when you are unsure which vaults exist. For live reachability, use obsidian_backend_status.
Returns: str: JSON of the shape {"current_vault": str, "count": int, "vaults": [{"name": str, "description": str|null, "path": str|null, "rest_base_url": str|null, "backends": ["rest"|"filesystem"], "is_current": bool, "is_default": bool}]} On failure: "Error: "
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations already declare readOnlyHint, idempotentHint, and destructiveHint, the description adds meaningful behavior beyond those: it reads configuration only retaining does not contact Obsidian, and it documents the failure string shape. This gives the agent an accurate model of side effects and cost.
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 core purpose is front-loaded, followed by concise usage guidance and a structured return block. Every sentence earns its place, and the return format block is dense but directly useful rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, comprehensive safety annotations, a clear usage recommendation, a named sibling alternative, and a documented return shape, nothing essential is missing. An agent can reliably decide when to call this tool and correctly interpret its result.
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 zero parameters)Skip, so schema coverage is trivially 100%. The description has no parameter details to provide, which is expected and acceptable; the baseline score of 4 applies given the parameter-less signature.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'list every configured vault' and clarifies the key value of showing which vault unqualified calls will target. This clearly distinguishes it from sibling tools like obsidian_backend_status and vault-mutating tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to call the tool ('call first when you are unsure which vaults exist') and why it is appropriate ('cheap and safe'). It also names the alternative for a different need — obsidian_backend_status for live reachability — providing a clear when-to-use vs. when-not-to-use boundary.
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, creating destination folders as needed.
Wikilinks elsewhere in the vault are NOT rewritten — Obsidian only updates links when the move happens inside the app. Search for links to the old name afterwards if that matters.
Args: params (MoveNoteInput): - source (str): Current vault-relative path - destination (str): New vault-relative path - overwrite (bool): Replace the destination if it exists
Returns: str: JSON of the shape {"status": "ok", "action": "moved", "path": str, "backend": "rest"|"filesystem", "note": str} On failure: "Error: "
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true, and the description adds substantial value beyond that: it warns that wikilinks are NOT rewritten, states that destination folders are created as needed, and documents the return JSON shape and backend values. This is precisely the kind of behavioral context an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: main operation first, then the critical caveat, then parameters, then return contract. Every sentence earns its place, and the format is 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?
The definition covers move/rename semantics, folder creation, link-rewrite behavior, core parameters, and the exact success and failure return shapes. For a mutation tool with annotations and an output schema, this is complete enough for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The Args section explains source, destination, and overwrite, but it omits the optional vault parameter. With the context signal reporting 0% schema description coverage, the description should compensate for all parameters, so covering 3 of 4 is helpful but incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Move or rename a note.' It also adds a distinguishing behavior, 'creating destination folders as needed,' which makes the operation unambiguous against siblings like write, delete, or append.
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?
There is no explicit guidance about when to choose this tool over alternatives such as obsidian_write_note or obsidian_delete_note, and no excluded cases are mentioned. The 'Search for links... afterwards' note is post-action advice, not usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bring a note up in the Obsidian window.
Changes what the user sees but not the vault's contents. Requires Obsidian to be running with the Local REST API plugin.
Args: params (OpenNoteInput): - path (str): Vault-relative path to open
Returns: str: JSON {"status": "ok", "action": "opened", "path": str, "backend": "rest"} On failure: "Error: "
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by specifying that the tool changes the UI but not the vault contents, and it discloses the dependency on the Local REST API plugin. It also details the exact return JSON and error format, giving the agent full awareness of what to expect. No contradiction with annotations; idempotentHint and destructiveHint are consistent with the described behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear 'Args' section and 'Returns' section. It is reasonably concise, though the return format is duplicated in the output schema, making it slightly redundant. The main purpose is front-loaded, and the prerequisite is highlighted. Overall, it is efficiently organized without unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core aspects: purpose, prerequisite, parameter (path only), and return format. It does not mention the vault parameter, but the schema handles that. It also lacks explicit behavior for missing notes or invalid paths, but the error message format is given. For a simple tool, this is sufficient; a 5 would require covering all edge cases, which isn't necessary here.
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 already provides descriptions for both parameters (path and vault), and the tool description only repeats the path parameter without adding new meaning. The vault parameter is entirely omitted from the description. Since schema coverage is effectively 100% (both parameters have descriptions), the baseline of 3 is appropriate; the description adds no extra value for parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to bring a note up in the Obsidian window. It distinguishes the action from modifying vault contents, which separates it from write/delete tools. The verb 'open' and resource 'note' are specific, and the note about not changing contents clarifies its non-destructive nature.
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 a clear prerequisite (Obsidian running with the Local REST API plugin) and implies the use case of displaying a note in the UI. It does not explicitly compare to alternatives like obsidian_read_note (which returns content) or obsidian_write_note, but the UI-focused wording and prerequisite offer sufficient guidance for typical selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert content at a specific heading, block reference, or frontmatter key.
This is the surgical option: it edits one section and leaves the rest of the note byte-for-byte unchanged. Read the note first to confirm the target exists — a missing heading or block ID is an error, not a silent no-op.
Args: params (PatchNoteInput): - path (str): Vault-relative path to an existing note - target_type (str): 'heading', 'block', or 'frontmatter' - target (str): Heading text ('::' separates nesting levels), block ID without '^', or frontmatter key - content (str): Markdown to insert, or the frontmatter value - operation (str): 'append', 'prepend', or 'replace'
Returns: str: JSON of the shape {"status": "ok", "action": "patched", "path": str, "backend": "rest"|"filesystem"} On failure: "Error: ", including when the target heading or block ID does not exist.
Examples: - Add today's entry under a Log heading -> target_type='heading', target='Log', operation='append' - Set a status field -> target_type='frontmatter', target='status', content='active', operation='replace'
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=false), the description discloses the exact return format (JSON with status/action/path/backend), the error behavior ('Error: <actionable message>'), and the non-idempotent nature. It also clarifies that a missing target is an explicit error, not a silent no-op, adding meaningful context the annotations do not cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-line purpose, then a clear breakdown of arguments, return value, and two concrete examples. Every sentence adds value, and the core purpose is front-loaded. Despite its length, it remains focused and avoids 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 complexity (multiple target types, operations, and failure modes), the description covers all necessary information: what it does, preconditions, exact return shape, error handling, and usage examples. The schema handles parameter validation, and the description complements it without omission.
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 explains each parameter in detail, including the format for 'target' (using '::' for nesting, block ID without '^', frontmatter key) and the meaning of 'operation' (append, prepend, replace). It adds examples for both heading and frontmatter use cases, going well beyond the schema's terse descriptions. Although the 'vault' parameter is omitted from the Args list, it is documented in the schema and is optional, so no meaningful gap exists.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Insert content at a specific heading, block reference, or frontmatter key.' It further distinguishes itself as the 'surgical option' that edits one section while leaving the rest byte-for-byte unchanged, clearly separating it from sibling tools like obsidian_write_note and obsidian_append_to_note.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: it instructs the agent to 'Read the note first to confirm the target exists' and warns that a missing heading or block ID is an error. It also positions the tool as the surgical alternative, implying when it is appropriate to use versus whole-note operations. Examples illustrate concrete scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a note's content plus its tags, frontmatter, and links.
Backlinks are only populated when Obsidian is running, since they come from Obsidian's own link index.
Args: params (ReadNoteInput): - path (str): Vault-relative path, '.md' optional - include_content (bool): False for metadata only - response_format (str): 'markdown' or 'json'
Returns: str: Markdown rendering, or JSON of the shape {"path": str, "content": str, "frontmatter": object, "tags": [str], "links": [str], "backlinks": [str], "size_bytes": int, "modified_at": str, "source": "rest"|"filesystem"} On failure: "Error: "
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only and idempotent. The description adds non-obvious behavioral details: backlinks depend on Obsidian's link index and may be empty, the source can be 'rest' or 'filesystem', and failures return actionable error strings.
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 organized into a one-sentence purpose, a necessary caveat, then explicit Args and Returns sections. Every sentence adds information needed to call the tool correctly, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with strong annotations and an output schema, the description is complete: it covers the key parameters, the behavior difference for backlinks, the return JSON shape, and failure output. Nothing needed for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage at the top level, the description compensates by explaining path ('.md' optional), include_content (false for metadata only), and response_format ('markdown' or 'json'). It omits the vault parameter, though the schema itself documents that field.
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 states a specific verb and resource: it reads a note's content, tags, frontmatter, and links. This distinguishes it from siblings like obsidian_write_note, obsidian_get_active_note, and obsidian_list_notes without needing to open the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the natural use case (fetch note content/metadata by path) and notes the backlinks caveat, but it does not explicitly state when to prefer this over obsidian_get_active_note or obsidian_search_notes, nor any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a command from Obsidian's command palette by ID.
Effects depend entirely on the command — some only change the view, others modify notes or invoke other plugins. Check obsidian_list_commands for valid IDs and prefer a specific tool when one exists.
Args: params (RunCommandInput): - command_id (str): ID from obsidian_list_commands
Returns: str: JSON {"status": "ok", "action": "executed", "command_id": str, "backend": "rest"} On failure: "Error: "
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true, but the description goes further by clarifying that effects vary—some commands only change the view, others modify notes or invoke plugins. It also discloses the return format and error behavior, adding context beyond the annotation flags. No contradictions found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the primary purpose, and efficiently covers usage, side effects, and return format in about six sentences. Every sentence adds actionable information with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the annotations (destructive, non-idempotent), the description adequately covers how to get valid IDs, what to expect in return, and the variability of side effects. It lacks specific examples of command IDs or edge cases, but for a generic runner this is sufficient.
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's properties (vault and command_id) each have descriptive text, so the schema already covers parameter meaning. The description only restates command_id as 'ID from obsidian_list_commands', adding minimal value. With high schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it runs a command from Obsidian's command palette by ID. It distinguishes this from other tools by explicitly advising to 'prefer a specific tool when one exists' and by pointing to obsidian_list_commands for valid IDs, making it unambiguous which tool to use for generic command execution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: check obsidian_list_commands for valid IDs, prefer a specific tool if one exists, and warns that effects depend on the command. This tells the agent when to use this tool versus alternatives and gives a clear decision procedure.
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 the vault, returning matching notes with context.
When Obsidian is running this uses its native search index and results are ranked the way they would be in the app. Otherwise it falls back to scanning files directly, which matches all terms as substrings.
Args: params (SearchNotesInput): - query (str): Search text; all terms must be present to match - context_length (int): Characters of context per match, 10-1000 - limit (int): Maximum notes returned, 1-100 - response_format (str): 'markdown' or 'json'
Returns: str: Markdown results, or JSON of the shape {"query": str, "count": int, "backend": "rest"|"filesystem", "results": [{"path": str, "score": float, "context": [str]}]} On no matches: a message suggesting broader terms. On failure: "Error: "
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses the fallback to filesystem scanning, differences in ranking and substring matching, the return format for JSON, and error/no-match messages. This provides significant behavioral context that an agent needs to set expectations about results and potential performance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a concise opening sentence, a behavioral note, a parameter list, and a return section. It is slightly verbose but each section earns its place. The most important scope (full-text search) is front-loaded, and the fallback behavior is highlighted early. A minor redundancy with the schema parameter descriptions prevents a 5.
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?
The description covers the return format, error handling, no-match behavior, and the fallback mechanism, which is quite comprehensive for a read-only search tool. It does not explicitly mention the vault parameter, but the schema provides that detail, and the description says to see obsidian_list_vaults in the schema. Overall, an agent has enough to call this tool correctly.
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 already provides descriptions for each parameter (query, context_length, limit, response_format, vault), and the description text largely repeats this information. It adds no new meaning beyond the schema; for example, the description lists 'all terms must be present' which is also in the schema's query description. The description does not mention the vault parameter, though the schema covers it. Since schema coverage is high, the description's contribution is minimal.
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?
States a specific verb ('full-text search') and resource ('across the vault') with a clear outcome ('returning matching notes with context'). It distinguishes itself from siblings like obsidian_list_notes and obsidian_read_note by focusing on search rather than listing or reading a single note. The fallback behavior also clarifies the scope of what it 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 explains how the tool behaves under different conditions (native index vs. filesystem scan) but never explicitly states when to use this tool over alternatives, such as obsidian_list_notes or obsidian_get_active_note. There is no mention of 'use this when...' or 'do not use this when...'. The purpose is clear, but the usage context is not explicitly delineated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change which vault subsequent unqualified tool calls target.
Changes this server session only — nothing in any vault is modified, and
Obsidian's own open vault is unaffected. Prefer passing vault directly on a
tool call for one-off access; switch when a long stretch of work lives in one
vault. A vault argument on an individual call always overrides this.
Args: params (SwitchVaultInput): - vault (str): Name of the vault to make current
Returns: str: JSON of the shape {"status": "ok", "current_vault": str, "previous_vault": str, "path": str|null, "rest_base_url": str|null, "backends": ["rest"|"filesystem"]} On failure: "Error: Unknown vault ''. Configured vaults: ..."
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses session-only behavior, that nothing in any vault is modified, that Obsidian's own open vault is unaffected, and it documents both success and failure return shapes. These are meaningful traits beyond the annotations, and no annotation conflict exists.
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 core statement is first, followed by targeted scope and usage guidance, then a compact Args/Returns block. No filler; the length is appropriate for the behavioral and precedence information it carries.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, session-state tool, the definition covers every decision an agent needs: what it does, when to switch vs. pass vault directly, precedence, session scope, and the exact success/error response shape.
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?
There is only one parameter, and the description's Args section gives its meaning. Although the context signal reports 0% schema description coverage, the embedded schema itself includes a description for the vault parameter, and the description's failure output tells the agent how to discover valid vault names when a bad one is supplied.
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?
States a precise action and scope: 'Change which vault subsequent unqualified tool calls target.' This makes clear it is a session-level router rather than a note or vault content operation, and it is easily distinguished from the note-reading/writing siblings.
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?
Explicitly instructs when to use the tool vs. the alternative: prefer passing `vault` directly for one-off access and switch only for a long stretch in one vault. Also states precedence: an explicit `vault` argument always overrides the switched value.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a note, or fully replace an existing one.
This overwrites the entire file. To add to a note without losing what is already there, use obsidian_append_to_note or obsidian_patch_note instead. Parent folders are created as needed.
Args: params (WriteNoteInput): - path (str): Vault-relative path - content (str): Complete markdown content - overwrite (bool): Required to replace an existing note
Returns: str: JSON of the shape {"status": "ok", "action": "created"|"replaced", "path": str, "backend": "rest"|"filesystem"} On failure: "Error: "
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint: true, so the description doesn't need to restate that. But it adds value by explaining that the note is fully replaced and that parent folders are created as needed, which is beyond the annotation. It also clarifies that overwrite must be explicitly set true to overwrite an existing note, which is a behavioral nuance not visible in annotations. The description does not contradict annotations and adds valuable 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 concise and well-structured. It leads with the core purpose, immediately says 'This overwrites the entire file' to set expectations, then offers alternatives, then a note about parent folders, then the Args and Returns sections. Every sentence earns its place, and important constraints (overwrite behavior) are front-loaded. It is not verbose and is 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?
The tool has an output schema and a well-detailed input schema. The description provides the return JSON structure and error format, which complements the output schema. It covers the overwrite semantics, folder creation, and alternative tools. Given the tool's complexity and the richness of the schema, the description is complete: an agent can call it correctly without further research. The only minor omission might be the 'vault' parameter, but that is already described in the schema with a cross-reference to obsidian_list_vaults.
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%? Actually, the input schema has descriptions for each parameter, so the coverage is high (the signal says 0% but that seems to refer to schema_description_coverage for the description adding value? Looking at the context, 'Schema description coverage: 0%' means the schema descriptions are already clear, but the tool description adds little beyond them. However, the tool description explicitly mentions 'path', 'content', and 'overwrite' in the Args section, echoing the schema. It also explains the return shape, which is helpful. Since the schema is already descriptive (e.g., 'Required to replace an existing note'), the description adds minimal value over the schema. The description does not introduce new parameter semantics but reinforces the schema. Given the schema is quite descriptive, a baseline of 3 is appropriate; the description's only addition is the return format, which helps but is not parameter-specific. So a 4 is generous; I'll score 3.5, but since we must use integers, I'll give 4 for its clear explanation of overwrite behavior.
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 states a clear verb+resource: 'Create a note, or fully replace an existing one.' It distinguishes between creating and replacing, and names the sibling tools (obsidian_append_to_note, obsidian_patch_note) that serve different purposes. The description clearly identifies the tool as a full-file write operation, which is distinct from other note-related siblings.
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 explicitly says when to use this tool vs alternatives: 'To add to a note without losing what is already there, use obsidian_append_to_note or obsidian_patch_note instead.' It also explains the overwrite requirement: 'Overwrite' is required to replace an existing note, and without it, an existing note is left untouched and an error is returned. This gives clear guidance on when to set the flag and what to expect.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0obsidian_append_to_daily_noteobsidian_append_to_noteobsidian_backend_statusobsidian_delete_noteobsidian_get_active_noteobsidian_list_commandsobsidian_list_notesobsidian_list_tagsobsidian_list_vaultsobsidian_move_noteobsidian_open_noteobsidian_patch_noteobsidian_read_noteobsidian_run_commandobsidian_search_notesobsidian_switch_vaultobsidian_write_noteScored across 17 tools
Every tool targets a distinct resource and action: reading (read_note, get_active_note), discovery (list_notes, search_notes, list_tags), writing (write_note, append_to_note, patch_note), and vault administration (list_vaults, switch_vault, backend_status). Overlapping write tools are clearly differentiated by insertion point and cross-reference each other.
The overwhelming majority follow the obsidian_verb_noun pattern (list_notes, read_note, write_note, delete_note, run_command). Only obsidian_backend_status deviates by using a noun-noun name instead of a verb such as get_status or get_backend_status.
17 tools is slightly above the ideal 3-15 range, but each tool earns its place covering vaults, notes, search, commands, and status. The granularity between append, patch, and append_to_daily_note is justified by real workflow differences.
Note CRUD is fully covered (create via write, read, update via write/append/patch, move, delete), plus discovery, search, tag listing, vault management, and Obsidian command execution. Minor gaps exist—such as no restore-from-trash tool and no explicit folder creation—but agents can work around them.
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Search your Obsidian vault to quickly find notes by title or keyword, summarize related content, a…
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.