Obsidian MCP (pgvector + Ollama, self-hosted)

Server Quality Checklist

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

Latest release: v0.8.0
Disambiguation4/5
Most tools have clearly distinct purposes, and overlapping pairs like keyword_search/semantic_search and get_neighborhood/find_related contain explicit cross-references that prevent misselection. A few pairs require careful reading—read_note/read_file and list_notes/list_files both operate on markdown, and write_file overlaps with create_note—so the set is not perfectly unambiguous.
Naming Consistency4/5
The server overwhelmingly follows a readable verb_noun snake_case pattern (read_note, create_note, delete_file, set_frontmatter). Minor deviations exist: keyword_search and semantic_search invert the pattern, get_recent omits its noun, and retrieval verbs are split among get_, list_, and find_ without a strict convention.
Tool Count3/5
At exactly 25 tools, the server sits at the top of the 'feels heavy' range. The count is justified by the broad scope—note CRUD, search, graph traversal, generic file operations, and human-mediated transfers—but an agent must navigate many similar file/note and upload/download variants.
Completeness5/5
The tool surface is exceptionally complete for an Obsidian vault: full note lifecycle (create, read, edit, move, delete), frontmatter mutation, keyword and semantic search, tag and recent-note discovery, link-graph exploration, orphan detection, generic file operations, and even human-in-the-loop upload/download flows with upload confirmation. There are no obvious dead ends or missing core operations.
Average 4.6/5 across 25 of 25 tools scored. Lowest: 3.6/5.
See the Tool Scores section below for per-tool breakdowns.
- 2 of 2 community issues answered or closed in the last 6 months
- 161 commits in the last 12 weeks
- Last stable release on August 30, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
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.
This repository includes a glama.json configuration file.
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.
View related servers

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

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description does not disclose behavioral traits such as side effects, authorization needs, or limitations beyond the limit parameter.
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 extremely concise, front-loading the purpose and then detailing the parameter with no extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool and presence of an output schema, the description is adequate but lacks details on edge cases or behavior when no tags exist.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explicitly explains the limit parameter's meaning and default value, adding significant value beyond the empty schema description (0% 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 lists all tags with note counts, distinguishing it from sibling tools that operate on notes or perform search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like keyword_search or list_notes.
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?
No annotations are provided, so the description carries the full burden. It explains the filtering capabilities (folder, tags, frontmatter) and the limit parameter, but does not disclose ordering (presumably descending order), what fields are returned, or any side effects (it is read-only). The transparency is adequate but incomplete.
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 concise: a single purpose sentence followed by clear, bullet-like parameter explanations. No extraneous information, and 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 presence of an output schema, the description does not need to detail return values. However, it omits the ordering of results (recentness implies descending by modification date) and any performance considerations. This is a minor gap for an otherwise complete parameter specification.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description adds critical meaning. It explains the default value for limit, the prefix nature of folder, the AND logic for tags, and strict type matching for frontmatter. This goes well beyond the schema alone.
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 retrieves recently modified notes, which is a specific verb and resource. It distinguishes from siblings like list_notes (which likely lists all notes) and keyword_search (which searches by content).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like list_notes or semantic_search. The description focuses solely on parameter details without mentioning use cases or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses index lag, sorting order, tag AND-matching, and strict frontmatter type matching. It does not explicitly state that the operation is read-only or describe error behavior, but the read-only nature is strongly implied by 'List'.
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, then adds a critical caveat about index lag, then lists parameters in a clean Args block. Every sentence adds value and there is no 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 has four parameters, no annotations, and an output schema, the description covers the essential behavior, filter semantics, and the index-lag caveat. It could be slightly more complete by clarifying whether subfolders are included recursively, but overall it is sufficient for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does thoroughly. It explains folder paths with examples and root behavior, limit defaults, tag ALL-matching semantics, and strict frontmatter type matching—all beyond the bare schema.
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 lists notes in a vault folder sorted by modification time, which is a specific verb+resource+scope. It does not explicitly contrast itself with sibling tools like get_recent or list_files, so it misses the highest bar for sibling differentiation.
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 by explaining folder scoping and filter semantics, but it never states when to prefer this tool over alternatives such as keyword_search, semantic_search, or get_recent. There are no explicit exclusions or when-not-to-use conditions.
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?
No annotations provided, so description carries full burden. It mentions both resolved and dangling links, but lacks details on output format, whether it includes embeds, or any side effects. Adequate but not thorough.
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?
Two concise sentences plus param description. Front-loaded with core purpose. No unnecessary 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?
Given output schema exists, description doesn't need to explain return values. Covers essential: links type (outgoing, resolved/dangling) and param. Could be slightly more complete on edges (e.g., limit on links).
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?
Schema coverage is 0%, so description compensates: 'path: Vault-relative path to the source note.' Adds meaning beyond type and title, clarifying the expected format.
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 'Outgoing links from path — both resolved and dangling.' It uses specific verb+resource and distinguishes from siblings like get_backlinks.
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?
Provides clear use cases: 'what does this note depend on?' and 'finding broken references'. Does not explicitly exclude alternatives but gives strong context for when to use.
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 details the two parts of the guide and handles the case of missing CLAUDE.md, providing good behavioral context. No annotations were provided, but the description covers the key aspects.
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 well-structured with bullet points and covers essential details without being overly verbose, though it could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and an output schema, the description is fully complete, explaining the guide contents and behavior when CLAUDE.md is absent.
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?
There are no parameters, so the baseline score of 4 applies. The description does not need to add parameter information.
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 that the tool returns a two-part guide for working with the Obsidian vault, distinguishing it from sibling tools that operate on notes.
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 obtaining guidance about the vault, but does not explicitly state when to use it versus alternatives or exclude scenarios.
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?
With no annotations, the description carries full burden. It discloses that only resolved links are counted (dangling references excluded) and mentions the limit with a hard cap. Additional details like sorting or pagination would improve transparency.
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 concise with a clear introduction, a behavioral note, and a structured Args section. It avoids unnecessary words but could be slightly more streamlined.
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 presence of an output schema (not detailed here), the description adequately covers purpose, constraints (resolved links), and parameters. It provides sufficient context for using the tool.
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?
Input schema has 0% description coverage, so description compensates. It clarifies 'path' as vault-relative and explains 'limit' default and hard cap, adding meaning beyond the raw 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 retrieves notes linking to a given path, with specific examples like 'projects citing a card'. It effectively distinguishes from siblings like 'get_links' by focusing on incoming references.
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 explains when to use ('discover what references a given note') but lacks explicit guidance on when not to use or direct mention of alternatives. However, the examples imply appropriate contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and covers side effects and failure modes thoroughly: write-permission requirements, symlink refusal on the final path component, atomic no-clobber publication, and the staging-fallback error naming VAULT_ALLOW_NAMED_STAGING_FALLBACK. An agent can accurately predict 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is stated in the first sentence, and the content is organized into clear topical paragraphs. It is longer than strictly necessary due to detailed staging and fallback explanations, but those details are behaviorally relevant and no sentence is clearly wasted.
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?
The description covers permissions, path semantics, symlink behavior, atomic no-clobber semantics, and direction to get_vault_guide for vault conventions — quite complete for a two-parameter tool. It does not describe the success response or the exact behavior when the destination file already exists, though an output schema may cover the former.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the Args section fully compensates. Path gets vault-relative semantics, a concrete example, and the behavior of appending .md; content gets its markdown and frontmatter scope. Both required parameters are meaningfully explained.
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 opens with 'Create a new markdown note in the Obsidian vault', a specific verb, resource, and scope. It clearly indicates creation rather than modification through the word 'new' and the no-clobber guarantee, but it never explicitly contrasts itself with sibling tools like edit_note or write_file, leaving some differentiation to inference.
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?
It clearly states the permission prerequisite ('readwrite' API key or OAuth scope) and points to get_vault_guide for vault-specific conventions, providing solid operating context. It does not explicitly enumerate when to prefer this tool over edit_note or write_file, though the no-clobber statement implicitly rules out updating existing files.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral burden and does so exceptionally well. It discloses the trash path and naming scheme, the non-replacing rename guarantee, indexer behavior, reindex timing, accumulation in .trash, permanent unlink irreversibility, symlink refusal, and backlink consequences. This is a model of behavioral disclosure.
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 lengthy but every sentence carries operational meaning. The core action is front-loaded, and the technical details about trash naming, rename semantics, symlink handling, and backlinks are all decision-relevant for an agent. No filler is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with two parameters and no annotations, the description covers prerequisites, failure modes, recoverability, edge cases, and post-delete effects. An output schema exists, so return-value detail is not required. The tool can be invoked correctly and safely from this description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the Args section compensates completely. path is defined as a vault-relative path to the note, and permanent is defined as 'If True, unlink instead of soft-deleting.' Both parameters are fully explained beyond their schema types.
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 opens with a clear statement of action and resource: 'Delete a note from the vault.' The detail about soft-delete vs permanent unlink reinforces what the tool does. It does not explicitly differentiate itself from the sibling delete_file tool, so it falls just short of a 5.
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 gives clear conditional guidance: use the default soft-delete unless permanent=True is desired, and notes that write permission is required. It does not explicitly explain when to choose delete_note over delete_file or move_note, but the context is strong enough for an agent to use it correctly.
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 explains the logic (zero incoming and outgoing links) but does not explicitly state it is read-only or mention any side effects. With no annotations, the agent can infer safety from context, but a direct statement would improve transparency.
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 concise, with a clear first paragraph for purpose and a second for parameters. No unnecessary words, well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage, and parameters adequately. Since an output schema exists, return values are documented elsewhere. The tool is simple, and the description is complete for the given context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description includes an Args section that explains both parameters: folder as a vault-relative prefix and limit with default and hard cap. This compensates fully for the 0% schema coverage, adding complete meaning.
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 it finds notes with zero incoming and zero outgoing resolved links, specifying a verb and resource. It distinguishes from sibling tools like find_related or get_links by focusing on disconnected notes for vault hygiene.
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?
It mentions usefulness for vault hygiene and cleanup decisions, providing context for when to use. However, it does not explicitly state when not to use or compare to alternatives like find_related.
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?
Without annotations, the description fully explains the algorithm (BFS, undirected, depth/limit caps at 5 and 200 respectively). It does not describe error handling for missing paths, but for a read-only graph traversal, this is adequate.
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 well-structured: a clear first sentence describing functionality, a usage paragraph, and a bulleted parameter list. No redundant or unnecessary text.
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 has an output schema, the description focuses appropriately on behavior and parameters. It covers caps and defaults but omits behavior when `path` does not exist. Overall, it is sufficiently complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description carries full burden. It adds meaning by explaining `path` as vault-relative, `depth` as maximum BFS depth with cap, and `limit` as maximum distinct neighbor count with cap, beyond the schema's defaults and types.
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 returns 'the connected subgraph reachable from `path` via links or backlinks, up to `depth` hops (treated as undirected)', which is a specific verb and resource. It distinguishes from sibling `find_related` by contrasting explicit links vs conceptual connections.
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?
Explicit guidance on when to use this tool (local cluster around a topic) and when to prefer alternatives: 'Prefer this over `find_related` when explicit links are the signal you want; prefer `find_related` when the connection is conceptual rather than linked.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It thoroughly discloses permissions, atomic writes, no-clobber defaults, overwrite semantics, dot-path and traversal rejection, symlink handling, size limits, and transport-level 413 behavior. This is exceptionally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and permission, and every section adds useful behavioral meaning. However, it is dense and includes implementation-level details like kernel-atomic inode linking, VAULT_ALLOW_NAMED_STAGING_FALLBACK, and HTTP 413 mechanics that could be trimmed without losing agent-relevant guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, no annotations, and zero schema description coverage, the description is remarkably complete. It covers permissions, parameter semantics, success/failure conditions, edge cases, size limits, overwrite behavior, and encoding safety. The presence of an output schema means return values do not need to be explained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does. The Args section explains each parameter beyond the schema: path is vault-relative, content is base64 or UTF-8 text, encoding defaults to base64, and overwrite is off by default. Prose also clarifies encoding behavior and byte-decoding 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 opens with a specific verb and resource: 'Write a file into the vault' and immediately clarifies it includes non-markdown files. It also names and distinguishes sibling tools create_note/edit_note as 'markdown-only', so an agent can tell this tool apart without inspecting schemas.
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 gives clear context: use this for vault files including non-markdown content, and notes that create_note/edit_note are peers that stay markdown-only. It explains when overwrite is needed and gives encoding guidance, but does not explicitly state 'use create_note/edit_note for markdown-only writes', so the routing guidance is slightly implicit.
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?
With no annotations provided, the description carries the full burden and performs well: it reveals the embedding-based mechanism, notes independence from the link graph, and implies read-only behavior. It stops short of error handling or edge cases, but the available detail is genuinely transparent.
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?
Well-structured: a precise technical summary, followed by contextual guidance, then a concise Args section. Every sentence adds distinct value with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with an output schema and thorough sibling differentiation, this is essentially complete. It covers purpose, mechanism, when to use, alternatives, and parameter semantics in under 100 words.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite zero schema coverage, the description fully compensates: it clarifies `path` is 'Vault-relative', and enriches `limit` with 'maximum results,' a default of 10, and a 'hard cap 50' that is absent from the schema. Everything beyond the structured fields is useful.
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 finds 'semantically similar notes' using averaged chunk embeddings queried via pgvector. It explicitly distinguishes itself from siblings by naming `get_neighborhood` for link-based exploration and `semantic_search` for arbitrary topic queries.
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?
Provides explicit when-to-use guidance: 'useful when the source is sparsely linked or when looking for thematic neighbors.' It also names two concrete alternatives with the conditions under which each should be used instead.
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?
No annotations are supplied, so the description carries the behavioral burden. It discloses key behaviors: uses tsvector, websearch syntax, strict type matching for frontmatter, and ALL-tags matching. It does not explicitly state read-only nature, but the tool name and search semantics imply it. The disclosed details are valuable and go beyond a generic search description.
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 tightly written: a two-sentence purpose and usage intro followed by a structured Args block. Every sentence provides useful information, and the format is easy to scan. No fluffy or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description correctly avoids explaining return values. It covers all parameters, gives usage guidance, and discloses matching semantics. The tool is moderately complex, and the description fully addresses its context, especially given the lack of annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 0% description coverage, but the description compensates fully with an 'Args' section that explains every parameter: query syntax examples, folder prefix, limit, tags requiring ALL match, and strict type matching for frontmatter. This adds substantial meaning beyond the raw schema fields.
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 opens with 'Full-text keyword search via PostgreSQL tsvector' and clearly specifies the tool's function: exact keyword matching for identifiers, codes, proper nouns, and known phrases. It explicitly distinguishes from semantic_search, making its purpose unambiguous and well-separated from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Use this for exact identifiers... anywhere semantic noise hurts' and contrasts with 'For conceptual or paraphrased queries, use semantic_search instead.' This directly tells the agent when to choose this tool and when to choose the alternative, naming the sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, and it excels: it explains side effects on notes_metadata and note_links, link rewriting behavior, self-reference handling, preflight refusals, partial-success outcomes, no rollback, atomic writes, and symlink handling. This is far beyond what an agent could assume from the name alone.
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?
Although long, the description is appropriately sized for a tool with complex link-rewriting behavior and multiple failure modes. It front-loads the core action and permission requirement, then uses structured paragraphs and bold warnings for non-obvious consequences. Each sentence carries meaningful information without filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is fully complete for an agent to invoke the tool correctly: it covers requirements, parameters, side effects, failure modes, limits, partial success handling, and vault conventions. Since an output schema exists, return-value details are not required. Nothing essential is left to inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain all parameters, and it does. It gives precise semantics for from_path, to_path, and rewrite_links, including defaults, constraints ('Must not exist'), side effects, and the destructive nature of opting in. This adds substantial meaning beyond the raw 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 opens with a specific verb and resource: 'Move or rename a note inside the vault.' This clearly distinguishes move_note from siblings like create_note, edit_note, and delete_note. It also clarifies scope (vault-relative paths) and link-rewriting behavior, leaving no ambiguity about what the tool does.
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 the tool, including the required readwrite permission and the optional destructive rewrite_links mode. It names edit_note as the alternative for fixing partial-success results and points to get_vault_guide for folder conventions. It does not exhaustively contrast every sibling tool, but it gives enough guidance for correct selection and invocation.
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?
With no annotations, the description carries the full burden. It clearly discloses that results are deduped notes with a ~200-character best-matching chunk preview, key behavioral detail. It also explains matching semantics for tags ('ALL') and frontmatter (strict type matching). It does not explicitly state non-mutation, but the verb 'search' implies it, so the description goes well beyond a bare schema.
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 dense but efficiently structured: purpose first, then usage guidance, result format, next step, then a cleanly formatted Args list. No filler or redundancy; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, the description covers purpose, when to use it, result shape, parameter semantics, and a suggested follow-up action. An output schema exists, so return values are already structured externally. There are no meaningful gaps for an agent to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must document all parameters itself. It does so thoroughly for all five: query semantics, limit with default, folder prefix example, tags with ALL-match behavior, and frontmatter with a strict-type-matching example. This far exceeds what the schema alone provides.
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 first sentence states a specific verb ('search'), resource ('vault's chunk embeddings'), and method ('vector similarity'). It explicitly contrasts with keyword_search, making it easy for an agent to distinguish this tool from its closest sibling without inspecting schemas.
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 gives explicit when-to-use ('conceptual or paraphrased queries'), when-not-to-use ('exact identifiers, code symbols... use keyword_search instead'), and even a follow-up action ('Call read_note on a result's path'). This fully routes the agent between alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it excels: it discloses write requirements, partial-merge behavior, exact handling of missing frontmatter, strict refusal of malformed blocks, no-op semantics, YAML comment loss, and symlink refusal. This is exceptional behavioral disclosure beyond any structured metadata.
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 long but meticulously organized with bolded section leads, a clear Args block, and no filler. Every sentence adds operational value, and the most important facts (purpose, permission, safety guarantees) are front-loaded before edge-case details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations, the description covers permissions, exact mutation semantics, error behavior, return/no-op behavior, serialization caveats, symlink handling, and cross-references to relevant sibling tools. An output schema exists, so return-value documentation is reasonably delegated; nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fully compensates with an Args section explaining path as vault-relative, updates as a mapping with empty-dict semantics, and remove as a list whose missing keys are ignored. It also clarifies behavioral nuances like type-sensitive comparison and no-op writes, giving the agent far more than the bare 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 opens with a specific verb and resource: 'Mutate a note's YAML frontmatter without touching its body.' It clearly differentiates this from general content editing tools and even points to edit_note as the repair path for malformed frontmatter, so an agent can distinguish it from siblings.
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 gives concrete usage context: write permission is required, symlinked final path components are refused, and get_vault_guide is referenced for frontmatter conventions. It stops short of explicitly stating 'use this tool when you need to modify frontmatter only, use edit_note otherwise,' but the repair reference to edit_note provides a clear alternative for malformed blocks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does so thoroughly. It discloses write-permission requirements, frontmatter byte-identity preservation, atomic same-directory rename semantics, optimistic concurrency checks with 'File changed while editing', dry_run diff behavior, and refusal conditions.
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 exceptionally detailed and well-structured with bolded section headers and front-loaded purpose, but it is very long and repeats some information in the mode list, section-mode deep dive, and Args list. It earns its length overall, but is not maximally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a nine-parameter mutation tool with no annotations and no schema-level parameter descriptions, the definition is complete. It covers every parameter, mode, failure case, concurrency behavior, and round-trip guarantee; since an output schema exists, the absence of return-value prose is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates. The Args section explains all nine parameters in prose, including operation's legacy 'append'/'replace' values, section selector forms like 'Parent/Child' and '#N', replace_frontmatter's default behavior, and find uniqueness semantics with replace_all.
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?
Opens with a specific verb and resource: 'Edit an existing note in the Obsidian vault.' It then enumerates four mutually exclusive modes, which clearly differentiates it from siblings like write_file and create_note, and names set_frontmatter for frontmatter-specific mutation.
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?
Provides explicit when-to-use guidance: it points to get_vault_guide for conventions, names set_frontmatter as the better tool for structured frontmatter mutation, explains that a truncated read must be paged before writing back, and documents explicit refusals such as malformed frontmatter and indented unclosed fences.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and thoroughly discloses edge behaviors: each status meaning, the `unknown` ambiguity (publish can succeed without recorded completion), the deadline after which status settles, principal-based visibility with OAuth grant families, and refusal of non-upload_id inputs without a lookup. It also warns to read/list the path before minting another link or reporting failure. No contradictory annotation 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?
Every paragraph addresses a distinct operational aspect—purpose, statuses, usage trigger, visibility, timeout semantics, and parameter guidance—without repeating schema or annotation information. The core purpose is front-loaded, and the length is justified by the tool's semantic complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers return statuses and their implications, principal scoping, expiration behavior, the unknown-state caveat, and exact input requirements. Together with the existence of an output schema, an agent has everything needed to call this tool correctly and interpret its result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only a bare string type with 0% coverage. The description compensates by defining the exact expected value ('the short handle from `request_upload`'), explicitly excluding the upload URL and the token after the `#`, and stating that anything else is refused without a lookup.
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 first sentence states a specific action ('Ask what happened to an upload link you minted with `request_upload`') and enumerates the possible statuses, distinguishing this status-check tool from transfer-creation siblings like request_upload. It is unmistakable what resource it operates on and what it returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs when to call it: 'Use it to confirm a transfer really finished before you tell the user it did, and to get the sha256 if they want to verify it.' It also clarifies the relationship to request_upload and that handles are scoped to the minting principal, which prevents misuse with other principals.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does so exceptionally. It explains the soft-delete trash path, the naming format that prevents clobbering, the irreversible nature of `permanent=True`, permission requirements, refusal behavior, and the fact that non-markdown files are not indexed.
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 detailed but every sentence earns its place, with clear paragraph breaks for permissions, soft delete, permanent delete, and restrictions. It front-loads the core purpose and then layers essential safety and behavior information in a logical order.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no annotations, the description covers permissions, side effects, recovery, refusal cases, parameter semantics, and indexing impact. The output schema covers return details, so nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates by explaining both parameters. `path` is defined as vault-relative, and `permanent` is clarified with its behavioral consequence: unlink instead of moving to `.trash/`. This adds meaning far beyond the bare 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 opens with a specific verb and resource: 'Delete a non-markdown file from the vault.' It clearly distinguishes itself from the sibling `delete_note`, which 'stays markdown-only,' so an agent can pick the right tool without further investigation.
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 explicitly says when to use this tool vs alternatives: non-markdown files only, and it explicitly routes markdown files to `delete_note`. It also states refusal cases — markdown files, directories, symlinks — and the required write permission, leaving no ambiguity about applicability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full disclosure burden and does so thoroughly. It states permission requirements (readwrite API key or OAuth scope), server-side fetching, security restrictions (https-only, URL rules, redirect re-checking), size cap, 30-second deadline, no-clobber behavior, atomic write guarantee, and preflight conditions. This is comprehensive behavioral transparency with no 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 long but every sentence earns its place, covering security, operational limits, failure modes, and parameter semantics. It is organized into digestible paragraphs with a clear Args section. The length is proportional to the tool's complexity, and the core purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description anticipates the full decision space: how to invoke, what permissions are needed, which security rules apply, what is returned, what can go wrong, and what not to do after a refusal. Even the transfer-tool preflight condition is disclosed. An agent has everything needed to call the tool correctly and diagnose failures.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero description coverage, so the parameter meanings fall entirely on the description. The 'Args:' section explains all three parameters clearly: url as a public https URL, path with a vault-relative example, and overwrite with its boolean semantics. This exceeds what bare parameter names provide.
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 opens with a specific verb-resource pair: 'Fetch a file from a public https URL straight into the vault.' It also differentiates from sibling tools by naming write_file and request_upload and stating exactly when to use this one ('when the bytes are already somewhere public'). This leaves no ambiguity about what the tool does or how it differs from peers.
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?
Explicitly names siblings and gives a decision rule: 'Peer to write_file and request_upload — use this one when the bytes are already somewhere public.' It also explains refusal conditions and explicitly tells the agent not to work around restrictions ('Rewriting the URL to evade the check is never the right next step; ask the user for a public link instead'), which is strong usage guidance beyond simple when-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden, and it delivers thoroughly. It discloses that the tool reads the filesystem directly, reports file sizes and modification times, hides dot-directories and dot-files, rejects folders with such components, and caps results with a default of 200 and a hard cap of 1000, including truncation signaling. This is far beyond minimal disclosure.
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 well-structured and front-loaded: the first sentence states the tool's purpose and key differentiator, followed by a sibling comparison and then precise behavioral details. Every sentence adds value; there is no filler or repetition of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a tool of this complexity. It covers all parameters, defaults, edge cases like hidden files and truncation, and usage context relative to sibling tools. Since an output schema exists, the description does not need to explain return values, and nothing essential is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema description coverage is 0%, the description fully compensates by documenting all four parameters in the Args section: `folder`, `pattern`, `recursive`, and `limit`. It explains defaults, glob semantics, recursion behavior, and the limit cap, adding real meaning beyond the raw 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 opens with a clear, specific statement: 'Browse the vault filesystem (`ls`-style), including non-markdown files.' It names the resource and scope, and immediately differentiates itself from the sibling `list_notes`, which 'lists indexed markdown only.' An agent can tell exactly what this tool does and how it differs from related tools.
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 explicitly positions the tool relative to `list_notes` and `read_file`, explaining that `list_files` reads the filesystem directly and reports sizes 'so you can gauge a binary before `read_file`.' It also gives concrete behavioral context such as default listing behavior, glob filtering, recursion, and hidden-file handling, making usage conditions clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure—and it excels. It discloses that the server does not parse PDFs or interpret binary bytes, describes base64 as opaque client-side transport, explains the 10 MB size refusal, dot-directory/path-traversal rejection, text windowing with truncation offsets, and the ~33% token inflation for base64. This is exemplary transparency.
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?
Though detailed, the description is logically structured: purpose first, then transport semantics, encoding modes, limits, security restrictions, and an Args section. Every sentence carries operational value—no filler or repetition that doesn't inform invocation. The front-loaded purpose and sibling differentiation give immediate orientation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description is remarkably complete. It covers return types for each encoding, error conditions (size, dot-paths, traversal), truncation behavior, continuation via offset, and token-cost warnings. An agent has everything needed to call the tool correctly and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate—and it does. Each parameter gets a dedicated explanation: `path` with a vault-relative example, `encoding` with all three values and their exact behavior, `offset` with instruction to use the truncation notice value, and `limit` clarifying it can only lower the server cap, not raise it. This fully outweighs the lack of 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 opens with 'Read any file in the vault' and immediately differentiates from the sibling `read_note` by noting that `read_note` stays markdown-only. It names the specific resource (vault files including non-markdown types) and the action (read), leaving no ambiguity about what the tool does.
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 explicitly says it is the peer to `read_note` for non-markdown files, giving the agent a clear selection rule. It also advises checking file size with `list_files` before reading large binaries, and explains when to use each encoding mode. This is direct, actionable guidance with alternatives and conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so exhaustively. It discloses normalization behavior (LF terminators, frontmatter byte-identity restoration), truncation semantics including per-field budgets, the error-result model (normal result, absent content fields), and the exact conditions for byte-exact round trips. Nothing about side effects or return behavior is hidden.
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?
Although long, the description is tightly structured: purpose first, then a field-by-field breakdown, then round-trip caveats, then parameter docs. Each sentence carries essential operational meaning—there is no filler. The density is appropriate for the tool's complexity, and the structure makes the content navigable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no annotations and a complex structured response, the description leaves no agent-facing gap: it documents every response field, all parameter behaviors, truncation and paging, failure modes, and integration with editing workflows. The presence of an output schema does not excuse this because the description adds the crucial 'what do I do with this field' semantics that raw schema cannot.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only parameter titles and zero description coverage, so the description must explain each parameter on its own. It does so in depth: path with a concrete example, section with three addressing forms and the '#N' shadowing caveat, offset with next_offset continuation, and limit with the 'cannot raise it' ceiling. Every parameter's semantics are fully compensated.
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 first sentence states a specific verb, resource, and scope: 'Read a note from the Obsidian vault by its relative path.' It further distinguishes itself from a generic file read by emphasizing it returns 'a structured result, not a rendered document,' which separates it from sibling tools like read_file. The purpose is unmistakable.
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 explicitly routes between alternatives: 'To change frontmatter use set_frontmatter, or edit the raw block with edit_note(find=...)' and warns against writing back the JSON view. It also gives clear within-tool guidance ('Read the one section you need with section= rather than paging a large note') and explains when content is safe to pass directly into edit_note. This fully informs when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so richly. It discloses that the token lives in the URL's `#` fragment, that the URL is a secret, that the link is bound to the file's current state and stops working if the file changes, and that it can be used more than once. It also warns about expiration clamping and the credential lifetime limit, which are non-obvious and important behaviors.
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 and usage distinction, then adds security and edge-case behavior in an organized way. The shell example is practical and earns its place. No sentence is filler, and the length is justified by the security sensitivity and behavioral nuance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the absence of annotations, the description covers all decision-relevant aspects: when to use it, how it behaves, security constraints, parameter semantics, and a usage example. The mention that the result may provide an earlier deadline than requested adds important context. Since an output schema is present, the lack of a return-value breakdown is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides almost no semantic detail, with 0% description coverage, but the description explains both parameters fully. It defines `path` as a vault-relative path and `expires_in` with its unit, default value, clamping bounds, and interaction with the credential's lifetime. This fully compensates for the bare 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 uses a specific verb and resource: 'Get a short-lived link a person can use to save a vault file.' It immediately contrasts with the sibling `read_file`, which returns bytes to the caller, making the tool's unique niche clear. Even without reading the schema, an agent can distinguish this tool from the other file-related siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to choose this tool over `read_file`: use it when the file is for a human, not for the caller, and when `read_file` would waste context or cannot render the content. It also contrasts with upload links and clarifies that this is a read operation usable with a read-only key. The guidance is concrete and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and exceeds it: it discloses the short-lived nature, readwrite permission requirement, single-use/no-clobber behavior, overwrite concurrency guard, expiration clamping, and the security-critical fact that the URL must be treated as a secret because the token lives in the fragment. It even warns against putting the token in a query string.
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 long but intentionally so — every section earns its place: purpose, usage context, security warning, overwrite semantics, shell example, and parameter breakdown. Critical guidance is front-loaded, and the structure guides the reader from what to why to how.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three parameters, no annotations, and an output schema, the description provides everything needed to call it correctly: prerequisites, security handling, edge cases, a concrete curl upload path, and a pointer to the confirmation step check_upload. Nothing an agent needs to select and invoke this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate fully. It does: path is explained with a vault-relative example, overwrite is defined as allowing replacement, and expires_in gets detailed semantics including the 60–3600 clamp, the 600-second default, and the nuance that a link cannot outlive the calling credential.
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 opens with a specific verb+resource+mechanism: 'Get a short-lived link a person can use to put a file into the vault.' It immediately sets the tool apart from the sibling write_file by noting it is a peer that takes bytes directly, so an agent can tell them apart without inspecting schemas.
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?
Explicit selection criteria are given: 'Peer to write_file, which takes the bytes directly — use this one when you do not have them.' It also explains why alternatives are not viable ('No MCP client can hand a tool the bytes... your shell cannot reach their machine') and points to check_upload for follow-up and get_vault_guide for context.
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:

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

Score Badge

Copy to your README.md:

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

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/maxkuminov/obsidian-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server