Synapse

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.2.4
Disambiguation4/5
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.
Naming Consistency5/5
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.
Tool Count5/5
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.
Completeness5/5
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.
Average 4.2/5 across 15 of 15 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose4/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior4/5
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.
Conciseness4/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![synapse-obsidian MCP server](https://glama.ai/mcp/servers/tomjrworks/synapse-obsidian/badges/card.svg)](https://glama.ai/mcp/servers/tomjrworks/synapse-obsidian)

Score Badge

Copy to your README.md:

[![synapse-obsidian MCP server](https://glama.ai/mcp/servers/tomjrworks/synapse-obsidian/badges/score.svg)](https://glama.ai/mcp/servers/tomjrworks/synapse-obsidian)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

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