Obsidian MCP (pgvector + Ollama, self-hosted)

delete_note

Delete a note from your Obsidian vault with a safe soft-delete to .trash by default, or choose permanent removal. Use expected_hash to ensure you only delete the version you last read.

Instructions

Delete a note from the vault. Requires write permission — a readwrite API key, or an OAuth token carrying the readwrite scope.

By default this is a soft-delete: the file is moved to .trash/<YYYYMMDD-HHMMSS>-<basename>-<8 hex> inside the vault root, by a single non-replacing rename, so an existing trash entry is never overwritten and two deletes in the same second land on distinct names. The indexer skips dot-prefixed directories, so search and embeddings drop the note automatically on the next reindex pass (≤ 5 minutes). Soft-deleted files accumulate in .trash/ — emptying that directory is the user's responsibility.

A vault filesystem that cannot perform that non-replacing rename into .trash/ makes the soft delete refuse with an error naming the limitation rather than fall back to a rename that could overwrite; pass permanent=True to unlink instead.

With permanent=True, the file is unlinked directly with no recovery path inside this server. Existing backups are the rollback story.

A path whose final component is a symlink is refused, naming its target, so a delete never removes a note other than the one named; symlinked folders inside the vault work normally.

Dangling backlinks left behind by a delete are surfaced via get_backlinks and find_orphans. See get_vault_guide for context.

expected_hash — binding a write to the bytes you read. Optional; omit it and nothing changes. Pass the content_hash a read returned, verbatim and canonical (sha256:<64 lowercase hex>), and the call is refused with nothing written if the file changed in between. It is always the whole file's hash, never a hash of the text you received. expected_hash covers your read through this call's preflight read. The delete acts through the pinned parent directory but does not compare the bytes again: an in-place edit after that comparison can still be deleted. Precondition refusals end with one machine-readable MCP-REFUSAL {"code":…} line — stale_precondition (with the file's current hash, ready to resend), concurrent_write, no_incumbent, malformed_precondition, precondition_unavailable, precondition_required — and each states what resolves it.

It applies in both modes, and the comparison runs before the .trash rename and before the unlink, so a refused delete leaves the note where it was and creates no trash entry. A successful delete reports no content_hash: nothing remains to hash.

Args: path: Vault-relative path to the note. permanent: If True, unlink instead of soft-deleting. expected_hash: The note's content_hash as you last read it. Refuses the delete, changing nothing, if the note has changed since.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`path`	Yes
`permanent`	No
`expected_hash`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.8.2Sep 24, 2026
- addedInput schema / additionalProperties
```
Added value: +false
```

Changed1 schema field changedv0.8.1Sep 16, 2026

addedInput schema / properties / expected_hash

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Expected Hash"
+}

First observedMay 17, 2026

TDQS

A4.9/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains the soft-delete mechanism (renaming to .trash), the refusal on symlink paths, the expected_hash precondition semantics, error handling, and the absence of recovery for permanent deletes. It clearly details the order of operations and what happens on refusal, leaving no ambiguity.

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 long, but every section adds critical operational detail that cannot be inferred from the schema. It is well-structured with paragraph breaks and a clear flow: mode details, symlink handling, backlinks, hash semantics, and argument descriptions. It is front-loaded with the most essential behavioral details before the parameter list.

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?

Despite the tool's complexity (multiple modes, precondition checks, edge cases), the description covers all relevant aspects: side effects, error conditions, interaction with other tools, and the meaning of the output schema (no content_hash on success). The presence of an output schema reduces the need to explain return values, but the description still covers behavioral outcomes thoroughly.

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?

Schema coverage is 0% and the schema only lists parameter names without descriptions. The tool description compensates fully by explaining each parameter: 'path' is the vault-relative path, 'permanent' flips between unlink and soft-delete, and 'expected_hash' is described in depth—its format, purpose, and the precondition refusals it can trigger. This goes far beyond the 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 states a specific verb ('delete'), a clear resource ('a note from the vault'), and distinguishes it from sibling tools like 'delete_file' and 'move_note' by emphasizing the two deletion modes (soft vs permanent) and the safety checks. It is not a tautology and clearly identifies what the tool accomplishes.

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 explicitly explains when to use soft-delete (default) vs permanent deletion, warns about trash accumulation, and mentions related tools for handling backlinks ('get_backlinks', 'find_orphans') and context ('get_vault_guide'). It clarifies the behavior for symlinks and the expected_hash precondition, providing clear guidance for safe usage.

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