Obsidian MCP (pgvector + Ollama, self-hosted)

Change feed

get_changes

Read-onlyIdempotent

List notes created, modified, moved, or deleted in an Obsidian vault since a cursor, returning a next_since cursor to continue without gaps or duplicates.

Instructions

List what changed in your vault after a cursor: one line per note created, modified, moved or deleted, oldest first.

`since` is either the `next_since` cursor a previous call returned
(`ev:<number>`, exclusive and exact) or a UTC date/datetime
(`YYYY-MM-DD`, or ISO 8601 with `Z`/`±HH:MM`). A date or datetime *starts*
a feed and is approximate; `next_since` *continues* one without losing or
repeating an event. Store `next_since` (it is in the header and the last
line) in your own notes and pass it next session. A cursor means
something only for your own vault; one above this vault's last event is
refused (`invalid_argument`).

Each line: `- ev:<n> <UTC time> <kind> "<path>"` (a move shows
`"<from>" -> "<to>"`; paths are JSON-quoted, so a newline in a name is
`

), then reason=…where it applies, then who:by api_key "" via orby oauth "" via , marked (you)when it was your own credential, orby human/syncfor anything the index discovered — edits outside MCP (Obsidian, a sync client, git, a shell) are human/sync. createdmeans first seen at this path: a new note, one half of a rename that could not be paired, or a note that became indexable. deletedalways carriesreason=: removed(the file is gone), not_indexable(still on disk but cannot be indexed) orquarantined`.

Two meta lines are always shown, whatever the filters: `gap` (events not
itemised, with a count) and `reset` (the index was rebuilt from empty).
After either, resync with `get_recent(order_by="content_changed",
since=…)`. `history_truncated: true` in the header means events older than
the retained history (default 90 days) were removed.

Args:
    since: A `next_since` cursor (`ev:<n>`) or a UTC date/datetime.
    folder: Only events whose path or source path is under this prefix (a
        move out of the folder counts).
    kinds: Subset of `created`, `modified`, `moved`, `deleted`.
    by: `any` (default); `me` (your exact credential — the same API key,
        or the same OAuth grant across token refreshes); `agents` (any MCP
        caller of this vault); `human` (`human/sync`, discovered by the index).
    limit: Events per page (1–500, default 50). A full page says
        `more: true`; pass its `next_since` to continue.

Input Schema

Name	Required	Default
`by`	No	any
`kinds`	No
`limit`	No
`since`	Yes
`folder`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.10.0Oct 31, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses cursor exclusivity, date approximation, invalid_argument behavior for out-of-range cursors, gap and reset meta lines, and history truncation. It also explains credential attribution and the meaning of created/deleted reasons, which is substantial 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.

Conciseness4/5

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

The description is front-loaded with purpose and then structured into cursor semantics, line format, meta lines, and Args. It is dense and mostly earns its length, but some output-format detail could potentially live in the output schema, making it slightly longer than strictly necessary.

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?

For a complex change-feed tool, the description covers the critical operational details: cursor handling, filtering, pagination, error conditions, meta lines, truncation, and resync behavior. With an output schema present, it does not need to explain every return field, and the remaining behavioral gaps are minimal.

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 carry parameter meaning, and it does: since accepts either ev:<n> or UTC date/datetime, folder filters by path prefix including move-out cases, kinds restricts event types, by defines credential scope, and limit documents range and pagination behavior. This fully compensates for the sparse input 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 and resource: list what changed in the vault after a cursor, with one line per created/modified/moved/deleted note, oldest first. It also distinguishes the cursor-based continuation model from date-starting feeds and names get_recent for the resync case, so the agent can identify the tool's role among siblings.

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?

It explicitly explains when to pass a next_since cursor versus a date/datetime, why a cursor continues without loss or repetition, and how to handle gap/reset by resyncing with get_recent. It also states that a cursor is vault-specific and that a cursor above the vault's last event is refused, giving clear usage boundaries.

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