Obsidian MCP (pgvector + Ollama, self-hosted)

Create note

create_note

Create a new Markdown note in an Obsidian vault with atomic no-clobber publishing; existing files are never overwritten.

Instructions

Create a new markdown note in the Obsidian vault. Requires write permission — a readwrite API key, or an OAuth token carrying the readwrite scope.

See get_vault_guide for Obsidian syntax and any vault-specific conventions (naming, folder placement, frontmatter, tags).

Refuses a path whose final component is a symlink, naming its target, so a write never lands on a note other than the one named; symlinked folders inside the vault work normally.

The note is published no-clobber: the content is staged out of sight and linked into place in one kernel-atomic step, so an existing file at path can never be replaced by this tool. A vault filesystem that cannot stage an unnamed file refuses the write with an error naming VAULT_ALLOW_NAMED_STAGING_FALLBACK rather than staging under a visible name.

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. Two windows, both live: expected_hash covers your read → this call's read, the server's own pre-publication compare covers this call's read → its publication, and a match on the first does not exempt the second. Every refusal the server raises ends with one machine-readable MCP-REFUSAL {"code":…} line (an undeclared or mistyped argument is rejected by protocol validation before the tool runs and carries no such 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.

Here there are no incumbent bytes to bind: a supplied hash is answered no_incumbent before any filesystem work, nothing is created, and the remedy is to call again without it. A malformed hash is still reported as malformed first. Success reports the content_hash of the note this call published.

Args: path: Vault-relative path for the new note (e.g. "Cards/New Topic.md"). The .md extension is added if missing. content: Full markdown content for the note, including any frontmatter. expected_hash: Accepted and always refused as no_incumbent, so the refusal is a normal result rather than a protocol error.

Input Schema

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

Output 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"
+}

Addedv0.7.0Aug 19, 2026
Removedv0.5.4Jul 21, 2026
First observedMay 17, 2026

TDQS

A4.2/5.0

Behavior5/5

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

The description adds substantial behavioral information beyond the annotations: write permission requirements, refusal of symlink paths, kernel-atomic no-clobber publication, staging fallback errors, and the exact refusal codes an agent may encounter. These details clarify auth, failure modes, and mutation semantics rather than merely repeating the annotation hints.

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

Conciseness3/5

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

The description is front-loaded and structured with Args, which helps. However, the expected_hash section is lengthy and repetitive, restating the always-refused no_incumbent outcome several times, so it is not as concise as it could be.

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 complexity and the presence of an output schema, the description supplies everything needed for correct invocation: permissions, symlink behavior, no-clobber guarantees, expected_hash semantics, and refusal handling. Return values are covered by the output schema and briefly referenced.

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 description coverage is 0%, so the description must compensate, and it does: it explains the path format and automatic .md extension, what content includes, and the unusual expected_hash behavior including malformed and no_incumbent refusal handling. Each parameter is given operational meaning beyond the bare schema.

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

Purpose4/5

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: 'Create a new markdown note in the Obsidian vault.' That is clear enough to identify the operation. It does not explicitly name sibling alternatives such as edit_note or write_file, so it falls short of full sibling differentiation.

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

Usage Guidelines3/5

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

The description states important context — write permission is required and get_vault_guide should be consulted for conventions — but it does not explicitly say when to use create_note instead of write_file, edit_note, or import_from_url. Usage is implied by 'new note' and the no-clobber behavior, but the agent must infer the boundaries.

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