Provides tools for semantic search, knowledge graph analytics, and vault editing (create, read, update, delete notes) directly on an Obsidian vault.
Click on "Install 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-brain search for notes about quantum computing"
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 standalone Node MCP server that gives Claude (and any other MCP client) semantic search + knowledge graph + vault editing over an Obsidian vault. Runs as one local stdio process — no plugin, no HTTP bridge, no API key, nothing hosted. Your vault content never leaves your machine.
📖 Full docs → sweir1.github.io/obsidian-brain Companion plugin →
sweir1/obsidian-brain-plugin(optional — unlocksactive_note,dataview_query,base_query)
Contents — Why · Quick start · What you get · How it works · Companion plugin · Troubleshooting · Recent releases
Works without Obsidian running — unlike Local REST API-based servers, obsidian-brain reads .md files directly from disk. Obsidian can be closed; your vault is just a folder.
No Local REST API plugin required — nothing to install inside Obsidian for the core experience.
Chunk-level semantic search with RRF hybrid retrieval — embeddings at markdown-heading granularity, fused with FTS5 BM25 via Reciprocal Rank Fusion. Finds the exact chunk, ranks on meaning.
The only Obsidian MCP server with PageRank + Louvain + graph analytics — ask for your vault's most influential notes, bridging notes, theme clusters. Nobody else ships this.
Ollama provider for high-quality local embeddings — switch to qwen3-embedding:0.6b, nomic-embed-text, bge-m3, etc. with one env var.
All in one npx install — no clone, no build, no API key, no hosted endpoint. Vault content never leaves your machine.
Related MCP server: obsidian-mcp-complete
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/sweir1/obsidian-brain/main/scripts/install.sh)"Installs Homebrew + Node 20+ if you don't already have them, adds the /usr/local/bin symlinks that Claude Desktop needs, merges obsidian-brain into your claude_desktop_config.json, opens the Full Disk Access pane for you to toggle Claude on, and relaunches Claude. You'll be asked for your macOS password once (for Homebrew + the symlinks) and your vault path once. Everything else is automatic. Audit what it does: scripts/install.sh.
Requires Node 20+ and an Obsidian vault (or any folder of .md files — Obsidian itself is optional).
Wire obsidian-brain into your MCP client. Example for Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"obsidian-brain": {
"command": "npx",
"args": ["-y", "obsidian-brain@latest", "server"],
"env": { "VAULT_PATH": "/absolute/path/to/your/vault" }
}
}
}Quit Claude Desktop (⌘Q on macOS) and relaunch. That's it.
On first boot the server auto-indexes your vault and downloads a ~34 MB embedding model. Tools may take 30–60 s to appear in the client. Subsequent boots are instant.
Not a developer? The macOS walkthrough covers Homebrew, Node, the GUI-app PATH fix, and Full Disk Access step-by-step.
For every other MCP client (Claude Code, Cursor, VS Code, Jan, Windsurf, Cline, Zed, LM Studio, JetBrains AI, Opencode, Codex CLI, Gemini CLI, Warp): see Install in your MCP client.
→ Full env-var reference: Configuration → Model / preset / Ollama details: Embedding model → Migrating from aaronsb's plugin: Migration guide
18 MCP tools grouped by intent:
Find & read — search, list_notes, read_note
Understand the graph — find_connections, find_path_between, detect_themes, rank_notes
Write — create_note, edit_note, apply_edit_preview, link_notes, move_note, delete_note
Live editor (requires companion plugin) — active_note, dataview_query, base_query
Maintenance — reindex, index_status
→ Arguments, examples, and response shapes: Tool reference
flowchart LR
Client["<b>MCP Client</b><br/>Claude Desktop · Claude Code<br/>Cursor · Jan · Windsurf · ..."]
subgraph OB ["obsidian-brain (Node process)"]
direction TB
SQL["<b>SQLite index</b><br/>nodes · edges<br/>FTS5 · vec0 embeddings"]
Vault["<b>Vault on disk</b><br/>your .md files"]
Vault -->|"parse + embed"| SQL
SQL -.->|"writes"| Vault
end
Client <-->|"stdio JSON-RPC"| OBRetrieval and writes both go through a SQLite index: reads are microsecond-cheap, writes land on disk immediately and incrementally re-index the affected file. Embeddings are chunk-level (heading-aware recursive chunker preserving code + LaTeX blocks), and search's default hybrid mode fuses chunk-level semantic rank with FTS5 BM25 via Reciprocal Rank Fusion.
→ Deeper write-up — why stdio, why SQLite, why local embeddings: Architecture → Live watcher behaviour + debounces: Live updates → Scheduled reindex (macOS launchd / Linux systemd): Scheduled indexing (macOS) · (Linux)
An optional Obsidian plugin at sweir1/obsidian-brain-plugin exposes live Obsidian runtime state — active editor, Dataview results, Bases rows — over a localhost HTTP endpoint. When installed and Obsidian is running, active_note, dataview_query, and base_query light up. Install via BRAT with repo ID sweir1/obsidian-brain-plugin.
Ship plugin and server at the same major.minor — server v1.7.x pairs with plugin v1.7.x. Patch-version drift is fine.
→ Security model, capability handshake, Dataview / Bases feature coverage: Companion plugin
Four most common:
"Connector has no tools available" in Claude Desktop — usually the server crashed at startup. Check ~/Library/Logs/Claude/mcp-server-obsidian-brain.log. Fix: npm install -g obsidian-brain@latest, quit Claude (⌘Q), relaunch.
ERR_DLOPEN_FAILED / NODE_MODULE_VERSION mismatch — better-sqlite3 built against a different Node ABI. Fix: PATH=/opt/homebrew/bin:$PATH npm rebuild -g better-sqlite3.
Vault path not configured — VAULT_PATH is unset. Set it in the env block of your client config or shell.
Old version loading via npx (your client still shows the previous release after a publish) — stale npx cache. Fix: rm -rf ~/.npm/_npx, then restart your client. Keeping @latest in your config prevents this.
→ Full troubleshooting guide (watcher not firing, stale index, running multiple clients, timeouts, embedding-dim mismatch, log locations): docs/troubleshooting.md
v1.7.24 (2026-05-16) — embeddings.md BYOM callout + 5 devDep bumps
v1.7.23 (2026-05-16) — BYOM Ollama auto-pull gate + logger sweep + SIGTERM unit test
v1.7.22 (2026-05-15) — structured stderr (NDJSON) + Ollama preparing-state + dependabot security bumps + SIGTERM drain integration test
v1.7.21 (2026-04-27) — install.sh vault-picker fix + auto ollama pull + docs/test polish
v1.7.20 (2026-04-27) — Ollama prefix-lookup bug + 13 audit polish items
→ Full changelog: docs/CHANGELOG.md · Forward plan: docs/roadmap.md · Build from source: docs/development.md
Thanks to obra/knowledge-graph and aaronsb/obsidian-mcp-plugin for the ideas and code this project draws on. Also Xenova/transformers.js (local embeddings), graphology (graph analytics), and sqlite-vec (vector search in SQLite).
apple-notes-brain — sibling
MCP server for Apple Notes on macOS: read, write, and search with full
Markdown round-trip in both directions.
Apache License 2.0 — Copyright 2026 sweir1.
Return the note currently open in Obsidian, including cursor position and selection. Requires the obsidian-brain companion plugin installed and Obsidian running against the same vault.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states the prerequisites but does not confirm it is read-only or mention potential failure modes. It adds some context but could be more thorough.
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?
Two concise sentences with no wasted words. The first states the core functionality, the second states prerequisites. Well-structured and front-loaded.
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 does not specify the return format or structure, which is a gap given no output schema. It also lacks error handling info. Adequate but not fully complete for an agent.
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 are no parameters (0), so the description does not need to explain parameters. The baseline is 4, and the description adds context about what the return includes, which is sufficient.
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 returns the currently open note in Obsidian with cursor position and selection. It uses specific verbs and resource, distinguishing it from siblings like read_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 context on when to use (to get the active note) and prerequisites (requires plugin and running Obsidian). It does not explicitly state when not to use or list alternatives, but the sibling tools imply alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply a previously previewed edit. Pass the previewId returned by edit_note with dryRun: true. Previews expire after 5 minutes. Fails with a descriptive error if the target file changed since the preview was generated — in that case, regenerate the preview and try again.
| Name | Required | Description | Default |
|---|---|---|---|
| previewId | Yes | The previewId returned by `edit_note` with `dryRun: true`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description discloses key behaviors: preview expiration (5 min) and error on file change. It doesn't detail other aspects like idempotency or asynchronous execution, but covers the most critical constraints.
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?
Three sentences with no wasted words. Front-loaded with the main action, followed by prerequisite, expiration, and error handling. Efficient and clear.
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 tool with one parameter and no output schema, the description covers prerequisite, parameter, expiration, and error handling. Minor gap: no mention of success behavior or return value.
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 coverage is 100%, so baseline is 3. The description repeats the schema's parameter info (the previewId) without adding new semantics or format details.
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 applies a previously previewed edit, linking to the sibling edit_note. It specifies the verb 'apply' and the resource 'preview', making the action 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?
It explains the prerequisite (obtain previewId from edit_note with dryRun: true) and handles failure scenarios (expiry, file change). Lacks explicit when-not-to-use but provides strong contextual cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Evaluate an Obsidian Bases .base file and return its rows. Requires the obsidian-brain companion plugin installed, a recent Obsidian (1.10.0+) running against the same vault, and the Bases core plugin enabled (Obsidian → Settings → Core plugins → Bases). Obsidian does not yet expose a public API for headless Bases query execution (Plugin.registerBasesView() is a view-factory hook only). The plugin uses its own YAML parser + a whitelisted expression subset (Path B). See docs/plugin.md#bases for the full supported subset. Supported subset: tree ops (and/or/not), comparisons (==, !=, >, >=, <, <=), leaf boolean (&&, ||, !), file.{name, path, folder, ext, size, mtime, ctime, tags}, file.hasTag("x"), file.inFolder("x"), frontmatter dot-paths. Arithmetic (+, -, *, /, %), method calls other than hasTag/inFolder, function calls (today(), now(), etc.), regex literals, formulas:, summaries:, and this context references all return 400 unsupported_construct errors — they ship in subsequent plugin patches as users hit them. Provide either file (vault-relative path to a .base file) or yaml (inline .base YAML source); view names which view inside the file to execute. Returns { view, rows, total, executedAt } — rows contain {file: {name, path}, ...projected columns}, total is the pre-limit count. Default 30s timeout (override with timeoutMs). Timeout only cancels the HTTP wait; the plugin has no cancellation API, so a running evaluation keeps going inside Obsidian. Prefer a limit: in the view for open-ended queries over large vaults.
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | Vault-relative path to a `.base` YAML file (e.g. "Bases/Books.base"). Either `file` or `yaml` is required. | |
| yaml | No | Inline `.base` YAML source. Either `file` or `yaml` is required. | |
| view | Yes | The name of the view inside the `.base` file to execute, e.g. "active-books". | |
| timeoutMs | No | HTTP timeout in ms (default 30000). The plugin evaluator itself cannot be cancelled; this just bounds how long this tool waits. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses plugin dependency, limitations of Obsidian API, unsupported construct errors, timeout behavior (only cancels HTTP wait, not plugin execution), and return format. Exceptionally transparent.
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?
Front-loaded with purpose and prerequisites. Well-structured with clear sections. Slightly verbose on unsupported constructs list, but justified by complexity. No wasted sentences.
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?
Complete coverage for a complex tool: prerequisites, parameter details, return structure, error cases, limitations, and timeout behavior. No output schema, but description adequately fills the gap.
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 covers 100% of parameters (baseline 3). Description adds value by clarifying mutual exclusivity of file/yaml, giving example for view, and explaining timeoutMs behavior beyond schema.
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?
Explicitly states the verb 'evaluate', the resource '.base file', and the output 'return its rows'. Clear distinction from sibling tools by focusing on Obsidian Bases, with prerequisites listed.
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?
Provides explicit prerequisites (plugin, Obsidian version, core plugin) and when-not-to-use (unsupported constructs return 400). Suggests using limit: for open-ended queries. However, lacks direct comparison to sibling tool dataview_query.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new note in the vault with a title, body, and optional YAML frontmatter. The new note is indexed immediately so semantic search and graph tools can find it. Auto-injects a title: field into frontmatter matching the note title unless frontmatter already has one.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Note title. Used as the filename base and auto-injected into frontmatter. | |
| content | Yes | Markdown body (do not include frontmatter here). | |
| directory | No | Vault-relative subdirectory to create the note in. | |
| frontmatter | No | YAML frontmatter key/value map. `title` is auto-injected unless explicitly set. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses immediate indexing and title auto-injection, but does not mention error conditions (e.g., overwrite behavior) or required permissions. As no annotations exist, more details would enhance 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?
Three concise sentences with no redundancy. Each sentence adds essential information: creation, indexing, and auto-injection nuance.
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?
Covers parameters well but omits return value (e.g., note path or ID) and does not specify behavior on duplicate titles. Given no output schema, this gap is notable.
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?
Adds significant value beyond schema: explains title as filename and frontmatter injection, clarifies content excludes frontmatter, and describes directory and frontmatter behavior. Schema coverage is 100%, but description elevates 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 verb (create) and resource (new note in vault), and distinguishes from sibling tools like edit_note and delete_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 implies when to use (create a new note) but lacks explicit when-not-to-use or alternatives. It provides behavioral details like auto-injection but no direct comparison to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a Dataview DQL query against the vault. Requires the obsidian-brain companion plugin v0.2.0+ installed, Obsidian running against the same vault, and the Dataview community plugin enabled. Returns a normalized discriminated-union shape. kind='table' gives {headers, rows}. kind='list' gives {values}. kind='task' gives {items: [{task, text, path, line, tags, children, ...STask fields when task=true}]}. kind='calendar' gives {events: [{date, link, value?}]}. DQL reference: https://blacksmithgu.github.io/obsidian-dataview/queries/structure/. Default 30s timeout (override with timeoutMs). NOTE: timeoutMs only cancels the HTTP wait; Dataview has no cancellation API, so the query keeps running inside Obsidian to completion. Prefer LIMIT N in DQL for open-ended queries.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | DQL source, e.g. 'TABLE file.name, rating FROM #book WHERE status = "reading" LIMIT 50' | |
| source | No | Optional origin file path (vault-relative) to set the DQL origin. Affects `FROM ""` and relative link resolution inside the query. | |
| timeoutMs | No | HTTP timeout in ms (default 30000). The Dataview query itself cannot be cancelled; this just bounds how long this tool waits. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral traits: the return shape (discriminated union with details for each kind), the timeout behavior (only cancels HTTP wait, not the query itself), and the need for specific plugins. This is comprehensive and honest.
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 and front-loaded with purpose, then prerequisites, then return shapes. It is slightly long but every sentence is informative. Could be tightened slightly, but overall effective.
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 complexity of the tool (multiple output kinds, no output schema, external dependencies), the description is remarkably complete. It covers prerequisites, return structures, timeout nuance, and best practices. No gaps for an AI agent.
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 coverage is 100%, but the description adds significant value: example DQL for 'query', explanation of 'source' as optional origin for relative links, and timeoutMs details (default, no cancellation). This goes well beyond the schema.
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 Dataview DQL query against the vault, with a specific verb 'Run' and resource 'Dataview DQL query'. It distinguishes itself from sibling tools like search or list_notes by focusing on Dataview's query language.
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 prerequisites (plugin versions, Obsidian running, Dataview enabled) and practical guidance like using LIMIT and understanding timeout limitations. It lacks explicit 'when not to use' or direct alternatives, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a note. Removes the file from disk AND its index rows (edges, embedding, node). Requires confirm: true to guard against accidents. When the delete removes inbound edges, the response is wrapped in a next_actions envelope suggesting a follow-up rank_notes(method=pagerank, minIncomingLinks=0) to spot newly orphaned notes.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Path or fuzzy match of the note to delete. | |
| confirm | Yes | Must literally be `true` to execute. Guards against accidental deletion. | |
| dryRun | No | If true, report what would be deleted without removing any files. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses permanence, what gets destroyed (file, edges, embedding, node), guard condition, and suggests next steps.
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?
Three sentences, no fluff. Front-loaded with main action. Every sentence provides value.
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 no output schema, it thoroughly describes the effect and even suggests follow-up. Covers behavior fully.
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 coverage is 100%, baseline 3. Description adds meaning: 'confirm: true' guard, 'dryRun' reports what would be deleted. Adds context beyond schema.
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?
Clearly states 'Permanently delete a note' and specifies what is removed (file, index rows). Distinguishes from siblings like move_note or edit_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?
Explicitly requires 'confirm: true' to guard against accidents and suggests a follow-up action (rank_notes) after deletion. Does not explicitly state when not to use, but provides clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List auto-detected topic clusters across the vault (served from the community-detection cache). Pass a theme id or label to drill into one cluster. To recompute with a different Louvain resolution, call reindex({ resolution: X }) first — detect_themes itself is a read-only tool. Each returned cluster carries staleMembersFiltered — the number of cached nodeIds that no longer exist in the vault and were dropped on this read. A positive value means the cached community row is lagging; the filter also regenerates summary so it stays consistent with the filtered nodeIds. Broken-wikilink stub targets are excluded by default; pass includeStubs: true to include them. When the overall vault graph has LOW modularity (<0.3), the response includes { warning, modularity } at the envelope top-level — the clusters aren't clearly separable on this graph and may not reflect meaningful themes.
| Name | Required | Description | Default |
|---|---|---|---|
| themeId | No | Drill into a single cluster by its id or label. | |
| includeStubs | No | Default `false`. Set `true` to include unresolved wiki-link targets (`frontmatter._stub: true`) in cluster membership. Older cached community data may still carry stub-dominated clusters until the next reindex regenerates the community table. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It details read-only nature, caching, staleMembersFiltered, filtering of stubs, and modularity warnings. Very comprehensive.
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?
Description is front-loaded with main purpose and then provides necessary details in a logical order. 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?
Despite no output schema, description explains response contents (staleMembersFiltered, warning, modularity) and edge cases. Fully adequate for a read-only tool.
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 coverage is 100%, but description adds meaning for both parameters: themeId explains drilling, includeStubs explains default behavior and caching implications.
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 clearly states it lists auto-detected topic clusters (specific verb+resource). It distinguishes itself from siblings like reindex by noting that computation is done elsewhere.
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 tells when to use reindex instead for recomputation. Also explains drilling into a cluster with themeId or label.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Modify an existing note. Supports six edit modes: append (add to end; defensively inserts a leading newline if the source didn't end with one), prepend (insert after frontmatter if present, otherwise at file start), replace_window (find a block of text and replace it — optionally fuzzy; fuzzy extends match to consume trailing .?! so the replacement has no doubled punctuation), patch_heading (insert or replace content under a specific heading; headingOp: 'before' | 'after' inserts immediately before/after the heading line — use before on the NEXT heading to append to a section's end; headingOp: 'replace' with scope: 'section' (default) replaces to the next same-or-higher heading or EOF — CAREFUL on the LAST heading, this consumes everything below including content separated by blank lines — pass scope: 'body' to stop at the first blank line after the body; if the target heading text appears MORE THAN ONCE the call throws MultipleMatches listing each occurrence with its line number — pass headingIndex: 0 | 1 | ... (0-indexed, top-to-bottom) to pick one), patch_frontmatter (set a single YAML key; pass value: null to clear — or from XML-stringifying clients use valueJson: 'null' for true null, valueJson: 'true' for a real boolean, valueJson: '42' for a number, valueJson: '["a"]' for an array; valueJson wins over value when both are set), at_line (insert or replace at a 1-indexed line number that counts from file start including frontmatter lines). Pass edits (array) to apply multiple edits atomically — all succeed or none are written.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Path or fuzzy match of the note to edit. | |
| mode | No | Edit mode. Required unless `edits` array is provided. | |
| content | No | New content to insert or replace (meaning is mode-dependent). | |
| search | No | For `replace_window`: the block of text to locate and replace. | |
| fuzzy | No | For `replace_window`: tolerate whitespace and trailing-punctuation drift. | |
| fuzzyThreshold | No | Similarity threshold for fuzzy replace_window matches (0-1, default 0.7). Higher = stricter. 0.9 is recommended for typo-tolerant matching of known-good text. | |
| heading | No | Target heading text for `patch_heading` mode. | |
| headingOp | No | For `patch_heading`. `replace` (default) replaces section; `before`/`after` inserts adjacent to the heading line. | |
| scope | No | For `patch_heading replace`: `section` (default) consumes to next same-or-higher heading; `body` stops at first blank line. | |
| headingIndex | No | For `patch_heading` when the heading appears more than once — 0-indexed top-to-bottom picker. | |
| key | No | For `patch_frontmatter`: the YAML key to set. | |
| value | No | For `patch_frontmatter`: value to set. Use `null` to clear a key. Prefer `valueJson` from clients that stringify params. | |
| valueJson | No | For `patch_frontmatter`: JSON-encoded value (wins over `value`). Use `"null"` to clear, `"true"` for boolean, `"42"` for number. | |
| line | No | For `at_line`: 1-indexed line number (counts from file start including frontmatter). | |
| lineOp | No | For `at_line`: insert before/after the target line, or replace it. Default `replace`. | |
| dryRun | No | If true, return a unified-diff preview without writing. Pass the returned previewId to apply_edit_preview to commit. | |
| from_buffer | No | If true, retry a previously failed replace_window edit using the cached content + search with fuzzy: true, fuzzyThreshold: 0.5. Use when the prior edit failed with NoMatch. Cleared on success. | |
| edits | No | Array of edits to apply atomically to a single file. If any edit fails, no edit is written. Applied in order against the accumulated state (each edit sees the result of previous edits in the batch). Use replace_window / patch_heading for content-anchored edits; at_line references the accumulated state, not the original file. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behaviors: defensive newline in append, fuzzy trailing punctuation handling, heading duplication throwing MultipleMatches, atomic edits via 'edits' array, dry-run preview, and detailed patch_heading scope behavior. No contradictions with 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 detailed and front-loaded with a summary of modes, but it is verbose. Every sentence adds necessary detail given the tool's complexity, though a more structured format (e.g., bullet points) could improve readability.
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 18 parameters, no output schema, and complex behavior, the description covers all modes, error handling, edge cases, and best practices. It is sufficiently complete for an AI agent to use the tool effectively.
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?
While schema coverage is 100%, the description adds significant meaning beyond schema labels, such as explaining fuzzy threshold recommendation, scope='body' behavior, and valueJson nuances. This adds value for correct parameter usage.
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 'Modify an existing note' and details six distinct edit modes (append, prepend, replace_window, etc.), making the tool's purpose specific and distinct from sibling tools like create_note, delete_note, and move_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 explains when to use each edit mode and provides contextual guidance (e.g., fuzzy trailing punctuation handling, scope for section replacement). However, it does not explicitly compare with alternative tools or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find notes linked to (from or to) a given note, up to N hops. Optionally return the full subgraph instead of a flat list. Response is wrapped as {data, context} where context.next_actions suggests follow-ups like clustering a dense neighbourhood via detect_themes or tracing a path to the furthest neighbour via find_path_between. Broken-wikilink stub neighbours are excluded by default; pass includeStubs: true to include them.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Starting note (path or fuzzy match). | |
| depth | No | Number of hops to traverse. Default 1, max 3. | |
| returnSubgraph | No | Return all edges in the neighborhood as a full subgraph instead of a flat list. | |
| includeStubs | No | Default `false`. Set `true` to include broken-wikilink stub neighbours (`frontmatter._stub: true`). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses stub exclusion behavior, optional includeStubs, and response wrapping with context.next_actions. However, it does not explicitly state whether the operation is read-only or mention any side effects.
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?
Three sentences with no wasted words. First sentence states purpose, second adds optional return format and response wrapping, third explains stub exclusion. Front-loaded and efficient.
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 adequately covers key aspects: purpose, parameters, response format, and follow-up hints. Without an output schema, it provides enough context for an agent to select and invoke the tool correctly. Slight miss on explicit performance or auth hints.
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 coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining the default behavior of excludeStubs and the response structure including next_actions hints.
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 'Find notes linked to (from or to) a given note, up to N hops,' specifying action, resource, and constraints. It distinguishes from siblings like find_path_between and detect_themes by noting follow-up suggestions.
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 context for usage, including follow-up actions like clustering or path tracing. It does not explicitly state when not to use but offers alternative suggestions in the response context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find link paths between two notes. Returns all simple paths up to maxDepth edges, optionally including their shared neighbors. Broken-wikilink stub nodes are excluded by default — they are degree-1 dead ends in the undirected graph and will block legitimate paths if left in. Pass includeStubs: true to include them.
| Name | Required | Description | Default |
|---|---|---|---|
| from | Yes | Source note (path or fuzzy match). | |
| to | Yes | Target note (path or fuzzy match). | |
| maxDepth | No | Maximum path length in hops. Default 3. | |
| includeCommon | No | Also return notes that both `from` and `to` link to (shared neighbors). | |
| includeStubs | No | Default `false`. Set `true` to include broken-wikilink stub nodes (`frontmatter._stub: true`) in the path search. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explains the default exclusion of stub nodes, why they are excluded (degree-1 dead ends), and the option to include them. Also describes that it returns simple paths up to maxDepth.
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 two sentences plus an additional sentence about stubs, all front-loaded. Every sentence adds value, 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 no output schema and no annotations, the description is quite complete. It covers core function, parameters, and a key behavioral detail. Could mention return format, but not essential.
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 100%, so baseline is 3. The description adds value beyond schema by explaining the default behavior of includeStubs and the rationale for stubs. Brief explanation of includeCommon also provided.
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 starts with 'Find link paths between two notes,' which is a specific verb+resource. It clearly distinguishes from siblings like 'find_connections' and 'list_notes' by focusing on path finding between two specific notes.
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 implicit usage context (finding paths between notes) but does not explicitly state when to use this tool over alternatives or when not to use it. No mention of other tools for path finding.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report the current state of the vault index: embedder model + dim, count of notes / chunks indexed, chunks skipped during the last reindex (if any), advertised vs discovered max tokens, last reindex reasons, whether a reindex is currently in flight, and the last init error. Read-only — does not mutate anything.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses that it is read-only and non-mutating, listing all reported components. This provides complete transparency about the tool's 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 a single, well-structured sentence that front-loads the purpose and then lists the reported items concisely. Every word adds value.
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 no output schema, the description fully explains the return values by listing all reported fields. It covers all necessary information for a diagnostic tool, including edge cases like skipped chunks and errors.
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 has zero parameters, so no parameter description is needed. The description adds value by detailing what the tool reports, compensating for the lack of a output schema.
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 reports the current state of the vault index, listing specific items like embedder model, dimensions, counts, and reindex status. This distinguishes it from siblings like 'reindex' which performs an action, and other read-only tools like 'read_note' which focus on content.
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 states it is read-only and does not mutate anything, guiding when to use it for checking index state without side effects. However, it does not explicitly mention alternatives or 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.
Add a wiki-link from one note to another with a context sentence describing why they're connected. Appends the link to the source note and records the edge in the graph so analytics pick it up.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Source note to add the link from (path or fuzzy match). | |
| target | Yes | Target note to link to (path, title, or new wiki-link ref). | |
| context | Yes | One-sentence explanation of why these notes are connected. | |
| dryRun | No | If true, return the line that would be appended without writing. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It discloses that the tool 'appends the link to the source note and records the edge in the graph,' and mentions a dryRun parameter. However, it does not specify permissions, reversibility, idempotency, or what happens if a link already 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?
Two sentences, no wasted words. The first sentence states the core action, the second explains the effect (appending and recording). Information is front-loaded and efficient.
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 explains the action and side effects, but with no output schema and no annotations, it should clarify the return value (e.g., success message or the appended line). It also omits error conditions, such as when source or target notes do not exist, and does not mention prerequisites (e.g., notes must exist).
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 100%, so the baseline is 3. The description adds meaning by explaining the overall purpose of the context parameter ('why they're connected') and the effect of dryRun. However, it does not provide additional nuance beyond the schema for each parameter.
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 the specific action: 'Add a wiki-link from one note to another with a context sentence.' It clearly identifies the verb (add), resource (wiki-link), and the linking action, distinguishing it from sibling tools like create_note or edit_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?
No guidance on when to use this tool versus alternatives (e.g., find_connections). The description implies usage for creating connections, but does not provide contexts where it is appropriate or when to avoid it, nor mentions prerequisites or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List notes in the vault. Optionally filter by directory prefix or by frontmatter tag. Pass includeStubs: false to exclude unresolved wiki-link targets (nodes with frontmatter._stub: true) and see only real on-disk notes.
| Name | Required | Description | Default |
|---|---|---|---|
| directory | No | Restrict to notes under this subdirectory prefix. | |
| tag | No | Restrict to notes containing this frontmatter tag. | |
| limit | No | Max results to return. Default 100. | |
| includeStubs | No | Default `true`. Set `false` to exclude unresolved wiki-link targets. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description is adequate: it notes the default for includeStubs and what it does. However, it omits details like pagination behavior, ordering, or error conditions, which would help an agent.
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?
Two sentences, no redundant words, and the important instructions about includeStubs are front-loaded. Every sentence adds value.
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 no output schema, the description does not explain what is returned (e.g., full note objects vs. names), nor does it mention empty results or ordering. It covers filter options but leaves gaps for a complete 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?
Schema coverage is 100%, so baseline is 3. The description adds context for includeStubs and mentions limit default but does not significantly enrich the schema's definitions for directory or tag.
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 explicitly states 'List notes in the vault' with optional filters by directory or tag, clearly defining the verb and resource. It distinguishes from sibling tools like search or read_note as a listing operation.
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 gives clear guidance on using includeStubs and filter options but does not explicitly contrast with sibling tools (e.g., when to use this vs. search). The context is implied but could be more direct.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename or move a note. Inbound wiki-links in other notes are rewritten in place immediately (bare [[old]], [[old|alias]], ![[old]] embeds, and [[old#heading]]/[[old^block]] suffixes all handled). If the note's frontmatter has a title: field matching the old basename, it's auto-rewritten to the new basename (custom titles and missing titles are left alone). Response includes linksRewritten: { files, occurrences }.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Current path or fuzzy match of the note to move. | |
| destination | Yes | New vault-relative path (including `.md`). `.md` is appended automatically if omitted. | |
| dryRun | No | If true, report what would be rewritten without mutating any files. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
In the absence of annotations, the description fully discloses key behaviors: immediate in-place rewriting of wiki-links (detailing link variants), frontmatter title auto-rewrite logic under specific conditions, and the dryRun option. Response format is also mentioned.
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 purpose, then explains behavior and response in 3 concise sentences. Every sentence adds value without repetition or 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?
Given no output schema, the description adequately covers the tool's behavior, parameter implications, and return structure. Could mention error handling or constraints, but overall complete for its complexity.
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 100% with detailed parameter descriptions. The tool description adds no extra meaning beyond what the schema provides, so it meets baseline but does not exceed.
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 starts with a clear verb+resource: 'Rename or move a note.' It distinguishes itself from siblings like edit_note, delete_note, etc., by explicitly describing its core renaming/moving functionality and the link-rewriting behavior.
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 tool is for renaming/moving notes but does not explicitly state when to use it vs. alternatives or provide exclusion criteria. The sibling list is provided but not referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rank notes by importance: 'influence' (densely-connected hubs), 'bridging' (notes that connect otherwise-separate topic clusters), or both. Credibility guards (I): by default, influence excludes notes with fewer than minIncomingLinks: 2 incoming edges — this filters out random-orphan noise that makes PageRank feel meaningless on personal vaults. Pass minIncomingLinks: 0 to see the unfiltered ranking. Bridging scores are normalized by graph size (divided by n*(n-1)/2) so values compare across vaults of different sizes — a bridging score of 0.5 means the same thing in any vault. Broken-wikilink stub targets are excluded by default; pass includeStubs: true to include them.
| Name | Required | Description | Default |
|---|---|---|---|
| metric | No | Ranking metric. Default `"both"`. `"influence"` = PageRank; `"bridging"` = betweenness centrality. | |
| limit | No | Max results to return. Default 20. | |
| themeId | No | Restrict ranking to members of one theme cluster. | |
| includeStubs | No | Default `false`. Set `true` to include unresolved wiki-link target stubs (`frontmatter._stub: true`) in the ranked set. With stubs in, popular link targets dominate eigenvector-style centrality even when they have no real content behind them. | |
| minIncomingLinks | No | Minimum incoming links for influence ranking. Default 2. Pass 0 to see unfiltered PageRank. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses filtering defaults (minIncomingLinks: 2), normalization of bridging scores, stub exclusion, and the rationale for defaults. It does not explicitly state read-only behavior or output format, but the behavioral details are rich.
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?
A single paragraph of 6 dense sentences, front-loading the main purpose and then efficiently detailing each parameter's effect. No redundant information; every sentence earns its place.
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 5 parameters, no output schema, and no annotations, the description is mostly complete but lacks an explanation of the return format, error conditions, or prerequisites (e.g., existence of graph structure). This minor gap prevents a perfect score.
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?
Despite 100% schema coverage, the description adds substantial meaning: mapping metric enum to algorithms, explaining the purpose of minIncomingLinks and includeStubs beyond defaults, and clarifying limit and themeId. Every parameter's behavior is enriched.
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 ranks notes by importance using two specific metrics (influence and bridging), defined in graph theory terms. It distinguishes itself from sibling tools like find_connections or search by focusing on centrality-based ranking.
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 to choose between metrics (influence vs bridging) and parameter effects, but does not explicitly state when to use this tool over sibling tools like find_connections or dataview_query. Usage context is implied but not contrasted.
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. Brief mode (default) returns title + metadata + linked-note titles; full mode returns full content + edge context. Full mode also reports truncated: true when the body exceeded maxContentLength (default 2000 chars) and was sliced. Response is wrapped as {data, context} where context.next_actions suggests follow-ups like creating missing linked notes or exploring outgoing connections.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Path, filename, or fuzzy match for the note to read. | |
| mode | No | Default `"brief"` (metadata + linked-note titles). `"full"` adds the body + edge context. | |
| maxContentLength | No | In `full` mode, max body chars before truncation. Default 2000. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully handles behavioral disclosure. It details truncation behavior in full mode (maxContentLength, truncated flag) and the response structure including context.next_actions. No side effects are relevant since it's a read operation.
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 (three sentences) and front-loads the main purpose. It could be slightly more structured (e.g., bullet points for modes), but it is efficient and clear.
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 has no output schema and three parameters, the description adequately covers the behavior, output structure, and follow-up suggestions. It is complete enough for an agent to use 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?
Schema coverage is 100%, but the description adds value by explaining that 'name' can be a path, filename, or fuzzy match, and clarifies the behavior of 'mode' and 'maxContentLength' beyond the schema descriptions.
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 'Read a note's content' and distinguishes between brief and full modes, specifying what each returns. However, it does not explicitly differentiate from sibling tools like search or list_notes, which also retrieve note information.
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 when to use brief vs full mode and mentions follow-up actions from context.next_actions. However, it lacks guidance on when to use this tool over alternatives (e.g., search for finding notes, list_notes for listing).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-index the vault: re-embeds notes whose mtime changed, prunes orphan stubs, and re-runs community detection only when something actually changed. Pass resolution to force a Louvain rerun and tune cluster granularity (0.5 = fewer/broader clusters, 2.0 = more/finer); without it, a no-op vault skips Louvain entirely.
| Name | Required | Description | Default |
|---|---|---|---|
| resolution | No | Louvain resolution. Omit to skip community detection on no-op reindexes. Pass a value to force-rerun: 1.0 = equal-weight clusters (default); 0.5 = fewer/broader; 2.0 = more/finer. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses behavioral traits: re-embeds only changed notes, prunes stubs, and conditionally runs community detection only if something changed or if resolution is passed. This is good transparency, though it could mention safety (non-destructive) or permissions.
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 consists of two sentences, the first front-loading the main purpose and actions, the second detailing the optional parameter. Every sentence adds essential information without 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 sub-actions) and the absence of an output schema, the description is fairly complete. It explains behavior for both change and no-op scenarios. However, it does not mention what the tool returns (e.g., reindex summary), which would be helpful for the agent.
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 only parameter `resolution` is fully described in the schema (100% coverage). The description adds significant value by explaining that omitting it skips community detection on no-op reindexes, while passing a value forces a rerun and tunes granularity. This goes beyond the schema's description.
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 re-indexes the vault and lists specific actions (re-embeds changed notes, prunes orphan stubs, re-runs community detection). The verb 're-index' and noun 'vault' are specific, and the description distinguishes it from sibling tools like 'index_status'.
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 when to use the tool (re-indexing) and the effect of the `resolution` parameter, but does not explicitly state when not to use it or mention alternatives (e.g., for status checks use 'index_status'). The guidance is present but not comprehensive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search vault notes. hybrid (default) fuses semantic + full-text ranks via Reciprocal Rank Fusion — no tuning needed, best for most queries. semantic is concept-only (better for abstract/paraphrased queries). fulltext is literal-token (better when you know the exact phrase exists). Semantic search is chunk-level — results are deduped to one-per-note by default. Set unique: "chunks" to return chunk-level hits with chunkHeading, chunkStartLine, and chunkExcerpt; supported by semantic and hybrid modes. fulltext is note-level only and ignores unique (full-text chunk search is not yet supported). Response is wrapped as {data, context} where context.next_actions suggests the agent's most useful follow-up call (read top hit, explore connections, or retry with broader phrasing on zero hits).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural-language query or keyword phrase. | |
| mode | No | Default `hybrid`. Semantic-only queries chunk vectors; fulltext-only queries FTS5. | |
| limit | No | Max results to return. Default 20. | |
| unique | No | Default `"notes"` (one row per note). Set `"chunks"` for raw chunk rows with chunkHeading, chunkStartLine, chunkExcerpt. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: default mode, RRF fusion, chunk-level semantics, dedup behavior, unique parameter effects, fulltext note-level-only, and response format including context.next_actions. No contradictions.
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 fairly detailed (~150 words) but well-structured: starts with purpose, then mode explanations, unique behavior, fulltext limitation, and response format. Each sentence adds value, though slightly verbose.
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 no output schema, the description covers response format and context.next_actions. It explains mode, unique parameter, and limitations. Minor gaps: pagination or sorting not mentioned, but overall complete for search tool.
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 coverage is 100%, providing baseline of 3. The description adds significant meaning beyond schema: explains hybrid RRF, semantic vs fulltext, chunk-level dedup, unique parameter details, and response context. Adds value beyond bare schema.
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 searches vault notes and explains three search modes (hybrid, semantic, fulltext) with specific behaviors. It differentiates mode usage within the tool but does not explicitly distinguish from sibling tools like list_notes or base_query.
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 guidance on when to use each search mode: hybrid for most queries, semantic for abstract, fulltext for exact phrases. It also explains the unique parameter behavior. However, it does not mention when not to use the tool or alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose: note CRUD, linking, search, graph analysis, indexing, and specialized queries. Even overlapping areas like search and dataview_query are delineated by their descriptions. No two tools appear to do the same thing.
All tool names follow a consistent snake_case verb_noun pattern (e.g., create_note, find_path_between). No mixed conventions or inconsistencies.
18 tools is slightly above the typical 3-15 range, but each tool addresses a distinct aspect of vault interaction, such as note management, linking, searching, graph analysis, and indexing. The count is well-justified for the domain's complexity.
The tool surface covers core note operations (CRUD, search, linking, graph analysis, indexing) and includes specialized query systems (Bases, Dataview). Minor gaps exist (e.g., bulk operations, attachment management), but the set is comprehensive for typical agent workflows.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
Token-free MCP server for structured RevoGrid Core, Pro, and Enterprise knowledge retrieval.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/sweir1/obsidian-brain'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
