Synapse is an MCP server that connects AI clients to your Obsidian vault, enabling comprehensive management, ingestion, querying, and maintenance of your personal knowledge base.
Content Saving & Ingestion
synapse_save — Fetch a webpage and convert it to markdown, or paste raw text directly into your vault's sources folder
synapse_ingest — Process a source into organized pages with summaries, concepts, entities, and [[wikilinks]]
synapse_compile — Scan for unprocessed sources and batch-ingest them all
Knowledge Querying & Health
synapse_query — Research a question across your knowledge base and synthesize a cited answer
synapse_lint — Detect broken wikilinks, orphan pages, missing frontmatter, stale content, and contradictions
synapse_status — Get a full snapshot of vault configuration, file counts, recent activity, and suggested actions
Vault File Operations
vault_read / vault_write — Read or create/overwrite any file, with automatic directory creation
vault_list — Browse files recursively or flat in any folder
vault_search — Case-insensitive full-text search with context and line numbers
vault_stats — Get file counts, folder structure, and initialization status
vault_frontmatter — Extract YAML metadata (title, tags, date, status, etc.) from any file
Setup & Configuration
synapse_setup — Onboarding wizard to adapt to existing vault conventions or set up a new structured knowledge base
synapse_configure — Persist your chosen folder paths, naming conventions, and setup mode
synapse_init — Scaffold a fresh vault with folder structure, a CLAUDE.md schema, and index/log files around a specific topic
Enables exposing the Synapse MCP server via Cloudflare tunnels for remote AI client access, allowing browser-based AI services to connect to local Obsidian vaults.
Provides hosted mode integration with Google Drive OAuth (coming soon) for cloud-based access to Obsidian vaults through the Synapse MCP server.
Connects AI assistants to Obsidian vaults, providing read/write access to markdown files, wikilinks, frontmatter, and vault structure for content management and knowledge base operations.
Your notes. Your AI's memory.
MCP server that connects any AI client — Claude, ChatGPT, Cursor, Windsurf — to your Obsidian vault. Save anything from anywhere, ask questions across your notes, keep the knowledge base your AI reads from.
Open config: Mac ~/Library/Application Support/Claude/claude_desktop_config.json | Windows %APPDATA%\Claude\claude_desktop_config.json
Add Taproot to the mcpServers object:
{
"mcpServers": {
"taproot": {
"command": "npx",
"args": ["-y", "synapse-obsidian", "/path/to/your/obsidian-vault"]
}
}
}Restart Claude Desktop. Taproot tools appear automatically.
Add to .claude/.mcp.json in your home directory:
{
"mcpServers": {
"taproot": {
"command": "npx",
"args": ["-y", "synapse-obsidian", "/path/to/your/vault"]
}
}
}Run Taproot locally and expose it with a free tunnel:
# Terminal 1: Start Taproot
npx synapse-obsidian /path/to/vault --http --port 3777
# Terminal 2: Expose it (free, no account needed)
npx cloudflared tunnel --url http://localhost:3777Copy the tunnel URL. Add https://your-tunnel-url.trycloudflare.com/mcp as a custom MCP integration in your AI client.
Related MCP server: Vault Cortex
Once connected, say:
"Help me get started with Taproot"
Taproot scans your vault and gives you three options:
Use my existing vault — Detects your folder structure, wikilinks, naming conventions. Nothing moved or overwritten. Taproot adapts to you.
Set up a knowledge base — Creates organized folders: sources/ for raw content, notes/ for compiled knowledge, outputs/ for query results. Best for a focused research topic.
Custom — You tell Taproot how you want things organized.
It also asks what you'll use the vault for (research, business, academic, life OS) so it can tailor the experience.
"Save this article: https://example.com/interesting-post"
Fetches the page, converts to markdown, saves to your vault. Works from your phone.
"What do my notes say about pricing strategy?"
Searches your vault, reads relevant files, synthesizes a cited answer.
"Process all new articles in my vault"
Turns raw sources into summaries, concept pages, entity pages — all cross-linked with wikilinks. Every answer feeds back into the knowledge base.
"Run a health check on my vault"
Finds broken links, orphan pages, missing frontmatter, stale content. Fixes what it can.
Tool | What it does |
| Onboarding — scans vault, presents options, configures Taproot |
| Saves your vault preferences |
| Save content from a URL or pasted text |
| Full vault overview with suggested actions |
| Process a source into organized pages |
| Find and process all unprocessed sources |
| Research a question across your knowledge base |
| Health-check for broken links, orphans, gaps |
| Scaffold a new knowledge base from scratch |
| Read any file |
| Create or update any file |
| List files in vault or subdirectory |
| Full-text search |
| File counts and structure |
| Read YAML metadata from a file |
Taproot is an MCP server — an open protocol for connecting AI to tools and data. It gives your AI read/write access to your vault (and nothing else — sandboxed to the vault directory).
Stdio (default) — For desktop AI apps (Claude Desktop, etc.)
HTTP (--http) — For browser-based AI (Claude.ai, ChatGPT, etc.) behind Tailscale or another tunnel
Your vault is just a folder of markdown files. Taproot doesn't need Obsidian to be running — it works with any folder.
Node.js 18+ (check with node -v)
An Obsidian vault or any folder of markdown files
Any MCP-compatible AI client
MIT — Taproot
Scan for all unprocessed sources and compile them into organized pages. Lists which sources exist in the sources folder but don't have corresponding summaries yet. Use synapse_ingest on each one to process them.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover key behavioral traits (read-only, non-destructive, idempotent, closed-world), but the description adds valuable context about scanning for unprocessed sources and listing them, which goes beyond the 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 front-loaded with the core purpose in the first sentence, followed by specific usage guidance, with no wasted words—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 the tool's complexity (scanning and compiling), no output schema, and rich annotations, the description is mostly complete but could benefit from clarifying the output format or what 'organized pages' entails.
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?
With 0 parameters and 100% schema description coverage, the baseline is 4. The description appropriately explains the tool's behavior without needing to detail parameters, as there are none.
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's purpose with specific verbs ('scan', 'compile') and resources ('unprocessed sources', 'organized pages'), and distinguishes it from sibling tools by explicitly mentioning when to use synapse_ingest instead.
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 provides explicit guidance on when to use this tool (to find and compile unprocessed sources) and when to use an alternative (synapse_ingest for processing individual sources), with clear context about the sources folder.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save Synapse configuration based on the user's choice from synapse_setup. Three modes:
"existing": Auto-detect conventions from the vault and save config. No folders created.
"structured": Set up an organized knowledge base (creates sources/, notes/, CLAUDE.md). Requires a topic.
"custom": Save whatever folder paths and conventions the user specified.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | Configuration mode chosen by the user ('kb' accepted as alias for 'structured') | |
| sourcesFolder | No | Where to save raw articles (default: auto-detect or 'sources') | |
| wikiFolder | No | Where organized notes go (default: 'notes' for structured mode, null for existing) | |
| outputsFolder | No | Where to save query outputs (default: auto-detect or 'outputs') | |
| topic | No | Topic for the knowledge base (required for kb mode) | |
| fileNaming | No | File naming convention (default: auto-detect or kebab-case) | |
| purpose | No | What the user will use this vault for | |
| purposeDescription | No | Custom purpose description (when purpose is 'custom') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond annotations: it explains what each mode does (auto-detection vs. folder creation vs. custom paths), specifies requirements ('Requires a topic' for structured mode), and clarifies that 'existing' mode creates no folders. Annotations cover safety (non-destructive, idempotent) but the description adds operational specifics that help the agent understand 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 efficiently structured with a clear opening sentence followed by bullet points for the three modes. Each bullet point is concise yet informative, explaining key behaviors without unnecessary elaboration. The entire description is front-loaded with the main purpose and wastes no words.
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 configuration tool with 8 parameters, 100% schema coverage, and comprehensive annotations, the description provides good contextual completeness. It explains the three operational modes clearly and references the prerequisite synapse_setup tool. The main gap is lack of output information (no output schema), but the description compensates somewhat by explaining what each mode accomplishes.
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?
With 100% schema description coverage, the schema already documents all 8 parameters thoroughly. The description adds some context about mode behaviors that indirectly relates to parameters (e.g., 'Requires a topic' connects to the topic parameter for structured mode), but doesn't provide significant additional parameter semantics beyond what's in 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 the tool's purpose: 'Save Synapse configuration based on the user's choice from synapse_setup.' It specifies the verb ('Save'), resource ('Synapse configuration'), and distinguishes from siblings by referencing synapse_setup. The three modes provide specific operational details that differentiate this from other configuration or setup tools.
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 clear context about when to use each mode ('existing', 'structured', 'custom') with specific behaviors for each. It references synapse_setup as the source of user choice, establishing a workflow relationship. However, it doesn't explicitly state when NOT to use this tool or name specific alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Process a source file into the knowledge base. Reads the source, generates organized pages (summaries, concepts, entities), adds [[wikilinks]], and updates the index and log.
You MUST read the source file content first, then generate all pages. Follow the CLAUDE.md schema in the vault root for conventions and folder paths.
Steps:
Read the source file
Create a summary page in the configured notes folder
For each key concept: create/update a concept page
For each key entity: create/update an entity page
Add [[wikilinks]] connecting related pages
Update the index
Append to the log
| Name | Required | Description | Default |
|---|---|---|---|
| sourcePath | Yes | Path to the source file relative to vault (e.g. 'sources/my-article.md') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false. The description adds valuable behavioral context beyond annotations by detailing the 7-step workflow, mentioning that it creates/updates multiple pages, adds wikilinks, and updates index/log. This provides operational transparency about what the tool actually does.
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 perfectly structured with a clear opening sentence stating the purpose, followed by a numbered list of specific steps. Every sentence earns its place by providing essential operational guidance. It's front-loaded with the core purpose and appropriately sized for the complexity.
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 (7-step workflow) and lack of output schema, the description provides substantial operational context about the processing steps and references external conventions (CLAUDE.md). However, it doesn't describe the format or location of generated outputs (pages, index, log) or error handling, leaving some gaps for a tool with no output schema.
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?
With 100% schema description coverage for the single parameter (sourcePath), the schema already fully documents the parameter. The description doesn't add any additional parameter semantics beyond what's in the schema, so it meets the baseline of 3 for high schema coverage.
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 specific action ('Process a source file into the knowledge base') and distinguishes it from siblings by detailing the multi-step ingestion workflow (reading, generating pages, adding wikilinks, updating index/log). It goes beyond a simple 'ingest' verb to explain what processing entails.
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 clear context for when to use this tool (processing source files into organized knowledge base pages with wikilinks) and references the CLAUDE.md schema for conventions. However, it doesn't explicitly state when NOT to use it or name specific alternatives among the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Initialize a structured knowledge base in the vault. Creates the folder structure, generates CLAUDE.md with the schema, and creates the initial index and log files. Safe to run on an existing vault — won't overwrite existing files.
For new vaults only. If you have an existing vault, use synapse_setup instead — it detects your conventions and adapts.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | The topic or domain for this knowledge base (e.g. 'DeFi protocols', 'machine learning', 'competitive intelligence') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond annotations: it specifies that it's 'Safe to run on an existing vault — won't overwrite existing files,' which clarifies idempotent behavior in practice. Annotations already indicate idempotentHint=true and non-destructive, but the description enhances this with real-world implications. 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 front-loaded with the core purpose, followed by key behavioral details and usage guidelines. Every sentence adds value: the first explains what it does, the second clarifies safety, and the third provides critical usage context. No wasted words, and it's structured for quick comprehension.
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 (fully covered by schema), rich annotations, and no output schema, the description is nearly complete. It covers purpose, behavior, and usage context effectively. A minor gap is lack of detail on output (e.g., what files are created), but given the annotations and simplicity, this is acceptable.
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 100% description coverage, with the 'topic' parameter fully documented in the schema. The description does not add any additional parameter semantics beyond what the schema provides, such as examples or constraints. Baseline score of 3 is appropriate since the schema carries the full burden.
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 specific action ('Initialize a structured knowledge base') and the resources involved ('creates the folder structure, generates CLAUDE.md with the schema, and creates the initial index and log files'). It explicitly distinguishes from sibling 'synapse_setup' by specifying 'For new vaults only' versus existing vaults, providing clear differentiation.
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 this tool ('For new vaults only') and when not to ('If you have an existing vault, use `synapse_setup` instead'). It names the alternative tool and explains the context for each, making it clear when to choose this over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Health-check the knowledge base. Scans for contradictions, orphan pages, broken wikilinks, missing frontmatter, stale content, and missing pages. Returns a report and instructions for fixing issues.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering safety and idempotency. The description adds valuable behavioral context by specifying what gets scanned (e.g., contradictions, broken wikilinks) and that it returns a report with fix instructions, which is not covered by annotations. No contradiction 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 front-loaded with the core purpose ('Health-check the knowledge base'), followed by specific scanning targets and output details. Every sentence adds value without redundancy, making it efficient and well-structured for quick understanding.
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 (diagnostic scanning) and rich annotations, the description is mostly complete: it explains the scanning targets and output. However, without an output schema, it could benefit from more detail on the report format (e.g., structure, severity levels). It adequately covers the tool's purpose and behavior but has a minor gap in output specifics.
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?
With 0 parameters and 100% schema description coverage, the baseline is 4. The description appropriately does not discuss parameters, as none exist, and instead focuses on the tool's scanning scope and output, which adds meaningful context beyond the empty 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's purpose with specific verbs ('health-check', 'scans') and resources ('knowledge base'), and lists concrete scanning targets like contradictions and orphan pages. It distinguishes itself from sibling tools like synapse_query or synapse_status by focusing on diagnostic analysis rather than querying or status reporting.
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 usage context for knowledge base maintenance ('health-check'), but does not explicitly state when to use this tool versus alternatives like synapse_status (which might report status without detailed diagnostics) or vault_stats (which might provide metrics without issue detection). It lacks explicit exclusions or named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Research a question against the knowledge base. Reads the index, identifies relevant pages, and returns their content so you can synthesize an answer. You MUST save the synthesized answer to the outputs folder using vault_write after responding.
| Name | Required | Description | Default |
|---|---|---|---|
| question | Yes | The question to research | |
| save | No | Whether to save the answer to the outputs folder (default: true). Set false for quick lookups. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond annotations: it explains the multi-step process (reads index, identifies pages, returns content), mentions the need for post-processing synthesis, and specifies a required follow-up action (saving with vault_write). While annotations cover safety (readOnlyHint=true, destructiveHint=false), the description provides operational details that help the agent understand workflow expectations.
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 appropriately sized with two sentences that each serve distinct purposes: the first explains the tool's function, and the second provides critical usage instruction. It's front-loaded with the core purpose, though the second sentence could be slightly more concise.
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 moderate complexity, rich annotations, and complete parameter documentation, the description provides good contextual coverage. It explains the research process and output expectations well, though without an output schema, it could benefit from more detail about return format (e.g., structured content vs raw text).
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?
With 100% schema description coverage, the schema already documents both parameters thoroughly. The description doesn't add significant semantic details about parameters beyond what's in the schema, though it implies the 'question' parameter drives the research process. This meets the baseline for high schema coverage.
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's purpose with specific verbs ('research', 'reads', 'identifies', 'returns') and resources ('knowledge base', 'index', 'pages', 'content'). It distinguishes from siblings like vault_search by emphasizing research synthesis rather than just searching, and from vault_write by focusing on querying rather than writing.
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 clear context for when to use this tool ('research a question against the knowledge base') and explicitly mentions a follow-up action ('MUST save the synthesized answer... using vault_write'). However, it doesn't explicitly state when NOT to use it or compare it to alternatives like vault_search for simpler lookups.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save content to the vault's sources folder from a URL or pasted text. Ideal for mobile users who find articles and want to save them without a web clipper.
If a URL is provided, fetches the page and converts it to markdown. If content is provided directly, saves it as-is. Always adds frontmatter with metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Title for the saved note | |
| url | No | URL to fetch and convert to markdown | |
| content | No | Raw text or markdown content to save directly | |
| folder | No | Where to save, relative to vault root (default: 'sources') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond annotations: it explains the dual behavior (URL fetching vs direct content saving), mentions frontmatter addition, and specifies the default folder. Annotations already indicate this is a non-readonly, non-destructive, non-idempotent operation with open-world data, but the description provides practical implementation details.
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 efficiently structured in three sentences: first states purpose and use case, second explains the dual input behavior, third mentions frontmatter addition. Every sentence earns its place with no wasted words, and key information is 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?
For a content-saving tool with no output schema, the description provides good context about behavior and use cases. However, it doesn't mention error conditions, file naming conventions, or what happens when both url and content are provided. Given the annotations cover safety aspects and schema covers parameters well, this is reasonably complete.
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?
With 100% schema description coverage, the schema already fully documents all 4 parameters. The description mentions URL fetching/conversion and direct content saving, which aligns with the url and content parameters, but doesn't add significant semantic value beyond what's in the schema descriptions. Baseline 3 is appropriate when schema does the heavy lifting.
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 specific action ('save content to the vault's sources folder') and distinguishes it from siblings by specifying the target folder and use case for mobile users. It explicitly differentiates from web clipper tools and other vault operations like read, write, or search.
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 clear context about when to use this tool ('ideal for mobile users who find articles and want to save them without a web clipper'), but doesn't explicitly state when NOT to use it or name specific alternatives among the sibling tools. It implies usage for saving content from URLs or direct input.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Onboarding entry point for Synapse. Scans the vault to detect existing structure, conventions, and CLAUDE.md, then returns configuration options for the user to choose from:
Option A: Use existing vault conventions (adapts to what's already there)
Option B: Set up a structured knowledge base (organized folders for a specific topic)
Option C: Start fresh with custom settings
After the user chooses, call synapse_configure with their selection.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond annotations: it explains the scanning process, the three configuration options presented to users, and the workflow (calling synapse_configure next). Annotations already cover safety (readOnlyHint=true, destructiveHint=false, idempotentHint=true), so the description appropriately focuses on operational behavior without contradiction.
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 highly concise and well-structured: it starts with the core purpose, details the scanning and options in a bulleted list for clarity, and ends with the next step. Every sentence adds value without redundancy, making it easy to parse.
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 (an onboarding entry point with scanning and user choices), the description is mostly complete: it explains what the tool does, the options, and the workflow. However, without an output schema, it doesn't detail the return format of the configuration options, leaving a minor gap. Annotations provide safety context, so this is adequate but not perfect.
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?
With 0 parameters and 100% schema description coverage, the schema fully documents the lack of inputs. The description adds no parameter information, which is appropriate here. A baseline of 4 is given since no parameters exist, and the description doesn't need to compensate for any gaps.
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's purpose: 'Onboarding entry point for Synapse' that 'scans the vault to detect existing structure, conventions, and CLAUDE.md, then returns configuration options for the user to choose from.' It specifies the exact action (scanning and returning options) and distinguishes itself from sibling tools like synapse_configure (which is called after this tool).
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 usage guidance: it's the 'onboarding entry point' and states 'After the user chooses, call synapse_configure with their selection.' This clearly indicates when to use this tool (for initial setup) versus alternatives (synapse_configure for the next step), with no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One-shot status overview. Returns everything needed to understand the vault state: configuration, file counts, recent activity, CLAUDE.md schema, and suggested next actions. This is THE tool to call when a user first connects or asks "what can you do?"
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false. The description adds valuable behavioral context beyond annotations: it's a 'one-shot' operation that returns a comprehensive overview including suggested next actions. However, it doesn't mention rate limits, authentication requirements, or detailed response structure.
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 perfectly front-loaded with the core purpose in the first sentence, followed by specific return details and explicit usage guidance. Every sentence earns its place with no wasted words, making it highly efficient for agent comprehension.
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 (comprehensive status overview), rich annotations, and no output schema, the description provides good context about what information is returned. However, it doesn't detail the exact structure of the return data or error conditions, leaving some gaps for a tool with potentially complex output.
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?
With 0 parameters and 100% schema description coverage, the baseline would be 4. The description reinforces this by stating it's a 'one-shot status overview' with no parameters needed, which aligns perfectly with the empty input 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 explicitly states the tool's purpose: 'One-shot status overview' that returns 'configuration, file counts, recent activity, CLAUDE.md schema, and suggested next actions.' It clearly distinguishes from siblings by positioning itself as the initial diagnostic tool for new connections or 'what can you do?' questions, unlike query/ingest/configure tools that perform specific operations.
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 usage guidance: 'This is THE tool to call when a user first connects or asks "what can you do?"' It clearly indicates when to use this tool versus alternatives by establishing it as the entry point for understanding vault state before using other tools for specific operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the YAML frontmatter metadata from a vault file. Returns parsed key-value pairs (title, tags, date, status, etc.).
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path to the file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering safety and idempotency. The description adds useful context about what is read (YAML frontmatter metadata) and the return format (parsed key-value pairs), which goes beyond annotations. No contradiction 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 two concise sentences with zero waste: the first states the purpose and action, the second specifies the output. It is front-loaded and 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 the tool's low complexity (1 parameter, no output schema), rich annotations (covering read-only, non-destructive, idempotent behavior), and clear purpose, the description is mostly complete. It could improve by mentioning error handling or format specifics, but it adequately covers the core functionality.
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 the parameter 'path' fully documented in the schema. The description does not add any additional meaning or examples for the parameter beyond what the schema provides, so it meets the baseline of 3.
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 specific action ('Read the YAML frontmatter metadata'), resource ('from a vault file'), and output ('Returns parsed key-value pairs') with examples (title, tags, date, status). It distinguishes from siblings like vault_read (likely reads full content) and vault_write (writes).
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 usage for extracting metadata from vault files, but does not explicitly state when to use this versus alternatives like vault_read (which might return raw content) or vault_search (which might search metadata). No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List markdown files in the vault or a subdirectory. Returns relative paths.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Subdirectory to list (e.g. 'sources'). Omit for entire vault. | |
| recursive | No | Whether to list files in subdirectories (default: true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false. The description adds useful context about the return format ('relative paths') and scope ('markdown files'), which helps the agent understand what to expect beyond the safety profile indicated by 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 a single, efficient sentence that front-loads the core purpose and includes essential output information. Every word serves a clear purpose with no redundancy or unnecessary elaboration.
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 low complexity (2 parameters, no output schema), good annotations, and high schema coverage, the description is mostly complete. It covers purpose, output format, and scope, but could slightly improve by mentioning file type limitations (only markdown) more explicitly in context of siblings.
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 schema fully documents both parameters (path and recursive). The description does not add any parameter-specific details beyond what the schema provides, such as examples or constraints, so it meets the baseline for high schema coverage.
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 specific action ('List markdown files'), resource ('in the vault or a subdirectory'), and output format ('Returns relative paths'). It distinguishes from siblings like vault_read (reads file content) and vault_search (searches 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 implies usage for listing markdown files in a vault structure, but does not explicitly state when to use this vs. alternatives like vault_search (for content-based queries) or vault_stats (for metadata). It provides basic context but lacks explicit exclusions or named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a file from the Obsidian vault. Returns the full content including frontmatter.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path to the file (e.g. 'notes/my-note.md') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering safety and idempotency. The description adds value by specifying the return format ('full content including frontmatter'), which isn't covered by annotations. However, it doesn't disclose other behavioral traits like error handling (e.g., if file doesn't exist) or performance aspects.
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, efficient sentence that front-loads the core action ('Read a file from the Obsidian vault') and adds necessary detail about the return value. Every word earns its place with no redundancy 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 the tool's low complexity (1 parameter, no output schema), rich annotations (covering read-only, non-destructive, idempotent behavior), and clear purpose, the description is mostly complete. It specifies the return content, which compensates for the lack of output schema. A minor gap is no mention of error cases (e.g., missing files).
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 the schema fully documenting the single 'path' parameter. The description doesn't add any parameter-specific details beyond what the schema provides (e.g., no examples of valid paths beyond the schema's example). Baseline 3 is appropriate as the schema carries the full burden.
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 specific action ('Read a file') and resource ('from the Obsidian vault'), distinguishing it from siblings like vault_list (list files) or vault_write (write files). It also specifies the scope of what's returned ('full content including frontmatter'), making the purpose 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?
The description implies usage for reading file content, but doesn't explicitly state when to use this tool versus alternatives like vault_frontmatter (which might extract only frontmatter) or vault_search (which searches content). It provides basic context but lacks explicit guidance on exclusions or comparisons with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the vault for files containing a text query. Returns matching files with line numbers and context. Case-insensitive.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Text to search for | |
| path | No | Subdirectory to limit search to (e.g. 'notes') | |
| maxResults | No | Maximum number of matching files to return (default: 20) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering safety and idempotency. The description adds valuable behavioral context beyond annotations: it specifies that results include 'line numbers and context' and that the search is 'case-insensitive', which are not captured in annotations. No contradictions exist.
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, efficient sentence that front-loads the core purpose and includes key behavioral details (line numbers, context, case-insensitivity) without redundancy. Every word adds value, making it appropriately concise and well-structured.
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 moderate complexity (search with three parameters), rich annotations (covering safety and idempotency), and no output schema, the description is mostly complete. It explains the return format ('matching files with line numbers and context') and case-insensitivity, but could benefit from mentioning limitations (e.g., search scope, performance) for full completeness.
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 schema fully documents the three parameters (query, path, maxResults). The description does not add any parameter-specific details beyond what the schema provides, such as format examples for 'path' or constraints for 'maxResults'. Baseline 3 is appropriate given high schema coverage.
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 specific action ('Search'), target resource ('the vault for files'), and scope ('containing a text query'), distinguishing it from siblings like vault_list (list files) or vault_read (read file content). It provides a complete purpose statement without redundancy.
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 usage for text-based file searches but does not explicitly state when to use this tool versus alternatives like vault_list (for listing files without content search) or synapse_query (for querying a different system). No exclusions or prerequisites are mentioned, leaving usage context partially inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get vault statistics: file counts, folder structure, and whether the knowledge base has been initialized.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide strong behavioral hints (read-only, non-destructive, idempotent, closed-world), so the description's burden is lower. It adds useful context by specifying what statistics are returned, but doesn't disclose additional traits like performance characteristics, error conditions, or data freshness. No contradiction with annotations 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?
The description is a single, efficient sentence that front-loads the core action ('Get vault statistics') and lists the specific outputs. Every word adds value without redundancy or fluff, making it easy to parse quickly.
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 low complexity (0 parameters, read-only operation) and rich annotations covering safety and behavior, the description is reasonably complete. It specifies the statistics returned, which compensates for the lack of an output schema. However, it could briefly mention the response format or data structure for better completeness.
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?
With 0 parameters and 100% schema description coverage, the schema fully documents the input (none required). The description doesn't need to add parameter details, but it implicitly confirms no inputs are needed by not mentioning any. This aligns with the schema, earning a baseline 4 for zero-parameter tools.
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's purpose with a specific verb ('Get') and resource ('vault statistics'), listing the exact types of statistics returned (file counts, folder structure, initialization status). It distinguishes from siblings like 'vault_list' (which likely lists files) and 'vault_status' (which might check operational status), though it doesn't explicitly name these alternatives.
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 usage for retrieving statistical overviews of a vault, but provides no explicit guidance on when to use this tool versus alternatives like 'vault_status' or 'synapse_status'. It lacks context on prerequisites (e.g., whether the vault must be initialized) or exclusions, leaving usage inferred rather than clearly defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write or overwrite a file in the Obsidian vault. Creates parent directories automatically. Use this to create new wiki pages, update existing ones, or save any markdown content.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path for the file (e.g. 'notes/my-concept.md') | |
| content | Yes | Full markdown content to write (including frontmatter if needed) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a non-readOnly, non-destructive, idempotent operation. The description adds valuable context beyond annotations: it specifies that parent directories are created automatically and clarifies the tool's behavior for both new and existing files (overwrites). This enhances understanding of the tool's operational traits without contradicting 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 front-loaded with the core action and key behavioral detail (automatic directory creation), followed by usage examples. Both sentences are necessary and efficient, with no redundant information, making it appropriately sized and well-structured for quick comprehension.
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 moderate complexity (write operation with two parameters), rich annotations, and no output schema, the description is mostly complete. It covers purpose, behavior, and usage context, but lacks details on error handling or response format. However, annotations provide safety cues, making it sufficient for effective use.
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 clear descriptions for both parameters (path and content). The description adds minimal semantic value beyond the schema—it implies the path is for file storage and content is markdown, but doesn't provide additional details like format constraints or examples. Baseline 3 is appropriate as the schema adequately covers parameter semantics.
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 ('write or overwrite') and resource ('a file in the Obsidian vault'), distinguishing it from sibling tools like vault_read, vault_list, and vault_search. It specifies the action includes automatic parent directory creation and mentions use cases (creating wiki pages, updating existing ones, saving markdown content), making the purpose explicit and differentiated.
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 clear context on when to use this tool ('to create new wiki pages, update existing ones, or save any markdown content'), but it does not explicitly state when not to use it or name alternatives. For example, it doesn't contrast with vault_frontmatter or other write-related tools, though the context is sufficient for basic guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have distinct purposes, but some overlap exists between synapse_setup and synapse_configure, as both handle configuration setup, which could cause confusion. The vault_* tools are clearly separate from the synapse_* tools, with minimal ambiguity within each group.
All tools follow a consistent snake_case naming pattern. The synapse_* tools use verb_noun format (e.g., synapse_compile, synapse_ingest), and the vault_* tools use noun_verb format (e.g., vault_read, vault_write), with clear and predictable conventions throughout.
With 15 tools, the count is well-scoped for a knowledge base management server. It covers core operations like initialization, ingestion, querying, and vault interactions without being overwhelming, and each tool serves a clear purpose in the workflow.
The tool set provides comprehensive coverage for managing a knowledge base, including setup (synapse_init, synapse_setup), ingestion (synapse_ingest, synapse_save), organization (synapse_compile), querying (synapse_query), maintenance (synapse_lint), and vault operations (read, write, search, etc.). No obvious gaps are present for the domain.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/tomjrworks/synapse-obsidian'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
