Skip to main content
Glama
Sign In
Vault Cortex Obsidian MCP Server

Vault Cortex Obsidian MCP Server

by aliasunder
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Find Orphans

vault_find_orphans
Read-onlyIdempotent

Find notes with no incoming links from other notes or canvases to identify orphaned notes for vault maintenance and graph integration.

Instructions

Find notes with no incoming links from other notes or canvases. A note that only links to itself still counts as an orphan.

Example: vault_find_orphans({}) Example: vault_find_orphans({ exclude_folders: ["Templates", "Archive"], limit: 20 })

When to use: Vault maintenance — surfacing notes to integrate into the graph. Link an orphan by mentioning it from a relevant note with vault_patch_note. Prefer vault_get_backlinks to check the connectivity of one specific note rather than scanning the whole vault.

Parameters:

  • exclude_folders replaces the defaults, it does not add to them — list a default yourself to keep it. Pass [] for no exclusions. Each entry names a whole folder, subfolders included: "Projects" covers "Projects/Archive" but not "ProjectsOld/", ignoring ASCII letter case. Excluded notes are left out of the results; links from them still count as incoming links. To keep the daily notes folder excluded, list the folder vault_get_daily_note's path starts with.

  • limit applies after exclusions and sorting; nothing in the response signals truncation; raise limit for more.

Behavior: Results can lag a file change by a few seconds.

Errors:

  • An empty array means no orphans were found (after exclusions), not an error.

  • "too many excluded folders" — pass at most 994 exclude_folders entries, then retry.

  • "[SqliteError]: …" / "[IndexIntegrityError]: …" — the index failed, not the call; the message says what to do

Returns: JSON array of note metadata: path, title (the title property; file name without .md when missing or not text), tags (the tags property; vault_update_properties edits it), body_tags (#tags in the note's text, one per spelling; vault_replace_in_note edits them; absent when none), related ([] when missing), folder (top-level, "" at the root), type (null when missing or not text), created (null when missing or not an ISO date), modified (ISO 8601 file time), bytes (on-disk size), and when present leading_callout (the opening callout, { type, title, body }) and additional_properties (every property but title, type, created, related and tags). Sorted by most recently modified.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "vault_find_orphans"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMax results (default 50)
exclude_foldersNoFolder paths to exclude (e.g. Projects; default: the daily notes folder, "Templates", "About Me")

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.54.16
    • addedInput schema / additionalProperties
      Added value: +false
  2. Changed1 schema field changedv0.54.13
    • changedInput schema / properties / exclude_folders / description
      Previous value: -"Folder paths to exclude (e.g. Projects; default: daily notes folder, Templates, \"About Me\")"New value: +"Folder paths to exclude (e.g. Projects; default: the daily notes folder, \"Templates\", \"About Me\")"
  3. Changed1 schema field changedv0.54.9
    • changedInput schema / properties / exclude_folders / description
      Previous value: -"Folders to exclude — replaces the defaults ([\"Daily Notes\",\"Templates\",\"About Me\"]), not merged"New value: +"Folder paths to exclude (e.g. Projects; default: daily notes folder, Templates, \"About Me\")"
  4. Changed4 schema fields changedv0.50.0
    • addedInput schema / properties / limit / default
      Added value: +50
    • addedInput schema / properties / limit / maximum
      Added value: +9007199254740991
    • addedInput schema / properties / limit / minimum
      Added value: +1
    • changedInput schema / properties / limit / type
      Previous value: -"number"New value: +"integer"
  5. Changed1 schema field changedv0.22.1
    • addedInput schema / properties / exclude_folders / items / minLength
      Added value: +1
  6. Changed1 schema field changed
    • changedInput schema / properties / exclude_folders / description
      Previous value: -"Folders to exclude (default: [\"Daily Notes\",\"Templates\",\"About Me\"])"New value: +"Folders to exclude — replaces the defaults ([\"Daily Notes\",\"Templates\",\"About Me\"]), not merged"
  7. Added

TDQS

A4.7/5.0
Behavior4/5

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

Annotations already cover readOnly/idempotent/non-destructive/closed-world, and the description adds genuinely non-obvious traits: results can lag a file change by a few seconds, nothing in the response signals truncation, and excluded notes still contribute incoming links. It also documents error strings and the 994-entry cap, though it does not explain the default exclusion list beyond the schema's parenthetical.

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?

Content is front-loaded with two runnable examples and then labeled sections (When to use, Parameters, Behavior, Errors, Returns), so it is navigable despite its length. The Returns block is long but justified because no output schema exists; some field annotations (e.g. vault_update_properties, vault_replace_in_note parentheticals) could be trimmed without losing call-critical information.

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?

With no output schema, the description fully carries the return-shape burden — field-by-field semantics, null/absent conventions, sort order, and folder depth. Combined with the lag warning, silent-truncation warning, empty-array semantics, and error-string triage guidance, an agent has everything needed to call and interpret this tool correctly.

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 100%, yet the description still adds substantial meaning: exclude_folders replaces rather than augments defaults, [] means no exclusions, entries match whole folders including subfolders but not prefix-similar ones, and matching ignores ASCII case. For limit it clarifies that the cap applies after exclusions and sorting and that truncation is silent, which the schema's 'Max results (default 50)' alone does not convey.

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 opening sentence names a specific verb and resource with a precise definition of the search target: 'Find notes with no incoming links from other notes or canvases,' and even resolves the edge case that a self-linking note still counts. It is clearly separable from siblings like vault_get_backlinks and vault_search_by_folder without opening any schema.

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 gives an explicit 'When to use: Vault maintenance — surfacing notes to integrate into the graph' and names the alternative for the adjacent use case ('Prefer vault_get_backlinks to check the connectivity of one specific note rather than scanning the whole vault'). The follow-up remediation path via vault_patch_note further anchors the workflow.

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

Deploy Server

Other Tools