Headless Obsidian MCP

by emguide

Overview Schema Related Servers Score Discussions

TypeScript

Local

Server Quality Checklist

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

Latest release: v1.0.0
Disambiguation5/5
Each tool has a clearly distinct purpose. For example, search_notes vs search_notes_ranked serve different search paradigms, and frontmatter tools (get_frontmatter, get_property, list_properties, list_property_values, query_notes) each target a different aspect. No two tools overlap significantly.
Naming Consistency5/5
All tools follow a consistent `verb_noun` pattern (e.g., get_frontmatter, list_notes, search_notes_ranked). The verbs vary (get, read, search, list, find, resolve, query) but the structure is uniform and predictable, making navigation easy.
Tool Count5/5
25 tools is well-scoped for a feature-rich Obsidian server. The number covers reading, searching, listing, metadata, vault analysis, and more without being excessive. Each tool earns its place, and the count aligns with the complexity of the domain.
Completeness2/5
The tool set is heavily read-focused, with no write operations (create, update, delete notes) present. While read coverage is thorough, the lack of write tools is a significant gap for an Obsidian server, limiting agent actions to inspection only.
Average 4.3/5 across 25 of 25 tools scored. Lowest: 3.5/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 282 commits in the last 12 weeks
- Last stable release on August 1, 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.
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

Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses pagination behavior with returned fields, explains line_number and body_line conventions, and notes special cases (null for frontmatter hits or untracked files). No annotations provided, so description carries burden well.
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?
Single paragraph with front-loaded core action. Dense but efficient; no unnecessary words. Could be slightly more structured for readability.
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 12 parameters, no output schema, and no annotations, description covers pagination output, match fields, and nuance of body_line. Lacks details on performance bounds or error conditions, but sufficient for selection.
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 coverage is 100%, so baseline is 3. Description adds context on return structure and index-resolved approach, but does not significantly enhance parameter meanings beyond 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?
Clearly states 'Search notes with ripgrep' and describes scoping by folder, tags, or frontmatter filters. Distinguishes from sibling search_notes_ranked by not mentioning ranking, but does not explicitly differentiate.
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 on when to use this tool versus alternatives like search_notes_ranked or query_notes. Does not mention when-not-to-use or prerequisites.
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 burden. It discloses that retrieval is 'high-precision based on human curation' and clarifies that 'match governs the tag set only', which explains parameter behavior. It does not mention rate limits or authorization, but for a read tool, the description is sufficiently 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?
Two sentences: first states purpose, second adds narrowing options and clarifies match scope. No redundant words; front-loaded with key information. Excellent conciseness.
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?
Despite covering purpose and parameter interactions, the description lacks explanation of the output format ('note headers') and does not discuss pagination or return structure. For a tool with 6 parameters and no output schema, this is a gap.
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 100%, so baseline is 3. The description adds value by explaining that match only applies to tags and how folder/where narrow the search. This contextualizes parameters beyond the schema's descriptions.
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 'Find notes matching one or more tags, as note headers', specifying the verb, resource, and key criterion. It adds context about 'high-precision retrieval based on human curation', which helps differentiate from full-text search tools like search_notes. However, it does not fully define what 'note headers' entails compared to full note content.
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 tag-based retrieval and mentions narrowing with folder and frontmatter filters. However, it lacks explicit direction on when to use this tool versus alternatives (e.g., search_notes, query_notes) and does not provide exclusion criteria.
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 full burden. It states it reads only frontmatter (not body) and is cheap, but does not disclose potential issues like missing frontmatter behavior, error handling, auth requirements, or rate limits. More behavioral context would be beneficial.
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 sentences with no waste. First sentence states core functionality, second sentence adds valuable use case context. Every word 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 no output schema, the description could clarify the return format (e.g., parsed YAML object). However, the tool's narrow scope and clear input minimize ambiguity. The description adequately covers the essential context for an agent to use it correctly.
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 has 100% documentation coverage for the single parameter 'path' ('Note path (.md optional)'). The description does not add additional semantic meaning beyond what the schema already provides, so baseline score of 3 is appropriate.
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 reads parsed frontmatter (YAML metadata) without the body. It specifies the verb 'Read' and resource 'frontmatter', and distinguishes from siblings like 'read_notes' by focusing only on metadata. The use case of inspecting status, aliases, dates, or custom fields is explicit.
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 when to use: when you want a cheap inspection of metadata before reading or editing the whole note. It does not explicitly exclude alternatives or provide when-not-to-use scenarios, but the use case is clearly stated and aids agent decision-making.
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 carries full burden and discloses important behavioral traits: it returns a specific tuple ({path, key, value, present}) and explains that 'present' distinguishes between an absent key and a key set to null. This adds value beyond the 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?
Two concise sentences that front-load the action and purpose. Every sentence adds value, with no wasted 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 simple read tool with a well-defined output shape (explicitly documented), the description is mostly complete. It omits error handling or non-existence cases, but the core functionality and return value are clear.
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 baseline is 3. The description does not add any additional meaning or details about the parameters beyond what the schema already 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 description uses a specific verb ('Read'), a specific resource ('single frontmatter property value'), and clarifies the scope ('from one note'). It also distinguishes from siblings like get_frontmatter (which presumably returns all frontmatter) and read_notes (full note content).
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 a single property and notes the distinction between absent and null values, but it does not explicitly state when to use this tool versus alternatives like get_frontmatter, or provide exclusion criteria.
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?
Discloses index-backed for performance, lists return fields, and implies read-only nature. Lacks explicit statement about side effects, but no annotations to contradict. Solid for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently convey purpose, output format, and scoping. No wasted 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?
Explains return structure, status values, and scoping well. Could mention pagination parameters (limit, offset) more explicitly, but overall sufficient given complexity.
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 coverage is 100% with adequate descriptions. Description adds slight context (status values listed, scoping phrasing) but does not significantly enhance understanding beyond 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?
Clearly states the tool lists checkbox tasks as structured rows with specific fields (path, text, status, etc.). Distinguishes from siblings by focusing on tasks rather than general notes or files.
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?
Describes scoping options (folder, tags, where, match, status) and implies use for filtered task listing. Does not explicitly say when not to use or compare to siblings like search_notes.
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 discloses the output components (outbound resolved, broken, backlinks) and explains the include_context parameter behavior (adds linking lines, call-time file reads). It does not mention side effects or permissions, but for a read-only operation this is sufficient.
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?
Three sentences, front-loaded with the core purpose, and no superfluous words. Every sentence adds value: action, use case, and optional parameter explanation.
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 no output schema, the description explains the output categories (outbound, broken, backlinks) and the effect of include_context. It references a 'link-context convention' without elaboration, which is a minor gap, but overall it provides enough context for the agent to understand what the tool returns.
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 already documents both parameters well. The description adds only a brief rephrasing for include_context ('who references this note, and why'), which provides some added context but not substantial new meaning beyond the 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 resolves the Obsidian link graph for a note, including outbound wikilinks, broken links, and backlinks. This is a specific verb+resource that distinguishes it from sibling tools like search_notes or get_related_notes, which serve different purposes.
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 explicitly says 'Use it to traverse related knowledge,' providing a clear context for when to use the tool. However, it does not offer alternatives or when-not conditions, so it stops short of a full 5.
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 full burden for behavioral traits. It implies a read-only query but does not explicitly state safety, performance implications, or any potential side effects. This is adequate but leaves some uncertainty.
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 sentences long, front-loading the specific outputs and ending with a clear usage context. Every sentence earns its place with no wasted 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 no output schema and no annotations, the description covers the main output components (counts, health, size, time bounds). It does not detail exact return format but is complete enough for an agent to understand the tool's purpose.
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?
The input schema has no parameters (0 params), so the baseline score is 4. The description adds value by explaining what the output contains, which is sufficient for a parameterless tool.
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 specifies exactly what the tool summarizes: note and tag counts, link-graph health, total size, and modification-time bounds. This clearly distinguishes it from sibling tools focused on reading individual notes, searching, or listing specific items.
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 phrase 'Use it to get a quick sense of the vault's scale and health' provides clear guidance on when to use it. However, it does not explicitly state situations when it should not be used or mention alternatives, which would improve differentiation among siblings.
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. Description does not disclose read-only status, authorization needs, or side effects. It adds that the tool never includes notes, which is behavioral context, but more transparency could be added.
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 sentences, no fluff. Key information is front-loaded: purpose, output format, and sibling distinction.
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?
Description lists output fields, so no output schema is needed. Covers 4 parameters with minimal ambiguity. Could mention recursion behavior (e.g., recursive listing) but overall sufficient for a simple listing tool.
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 coverage is 100% with good descriptions for all 4 parameters. Description adds no new parameter-level detail beyond the schema, earning baseline 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?
Description clearly states 'List non-markdown files in the vault (attachments, images, PDFs)' and specifies output fields. It explicitly distinguishes from list_notes, 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a concrete example use case ('e.g. to find a file to move') and explicitly states when not to use it ('Never includes notes (use list_notes)'). This effectively guides tool selection.
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 provided, so the description carries the full burden. It discloses sorting behavior (by mtime or date field), scoping (folder/tags/where/match), and result type ('lightweight headers'). It does not mention destructive actions (unnecessary for read) but could clarify pagination details. Overall, it sufficiently describes 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 three sentences, front-loaded with the main action. Every sentence adds value: first states what, second details sorting/scoping, third gives use case. 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 8 parameters and no output schema, the description covers the core functionality: ordering, scoping, and use case. 'Lightweight headers' hints at output format. It might need more on pagination or default behavior, but it's sufficient for a list tool.
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 coverage is 100%, so baseline is 3. The description adds some value by explaining the relationship between 'match' and 'tags' and that 'where' conditions all apply. However, it does not elaborate on 'limit', 'offset', or 'date_field', which are left to the schema. This is adequate but not exceptional.
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 'List', resource 'notes', ordering 'by recency', and result format 'lightweight headers'. It differentiates from siblings like 'list_notes' (no recency) and 'search_notes' (full text). The phrase 'find current material' further reinforces the purpose.
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 a clear use case: 'Use it to find current material.' It implies when to use (recent notes) by specifying recency sorting and optional cutoff. However, it lacks explicit exclusions or alternatives, e.g., when to use 'list_notes' or 'search_notes' 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?
With no annotations, the description bears full responsibility for behavioral disclosure. It reveals that results are 'note headers' (not full content), comparisons are type-aware, and the 'match' mode only affects 'where' conditions. It does not explicitly state read-only status, but the query nature implies no side effects. Overall, it provides sufficient behavioral insight.
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 two sentences, front-loaded with the purpose, and then details the condition format. It is efficient but slightly ambiguous with 'as note headers' – could be clearer about what that means. Still, no wasted words and well-structured.
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?
The description covers the query mechanism well but lacks details on the return format (what fields are in 'note headers') and pagination behavior (limit/offset defaults). Given no output schema, these gaps reduce completeness. It adequately explains condition syntax and filters but misses output structure.
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 100%, so baseline is 3. The description adds significant value by detailing condition formats (scalar vs. operator objects), the list of operators, and type-awareness. It also clarifies semantics of 'match' and how additional filters work, enhancing understanding beyond the 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 finds notes based on frontmatter conditions and returns note headers. It distinguishes from sibling tools like search_notes (full-text) and list_notes (simple listing) by specifying the frontmatter query capability and the types of conditions supported.
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: for structured frontmatter queries. It does not explicitly state when not to use it or compare to alternatives, but the sibling tool list implies its niche. It offers guidance on the 'match' parameter and additional filters, which helps in decision-making.
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 fully discloses the read-only behavior and the specific data returned (headings with level, line number, path, ambiguity flag). It does not mention error handling, but the behavior is well-described.
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 sentences with no fluff: the first details what is returned, the second gives usage context. Every sentence adds value.
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 simple tool with one parameter and no output schema, the description provides sufficient behavioral context and usage guidance. It covers the key aspects needed for an agent to decide and invoke correctly.
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 schema has 100% coverage with a single parameter 'path' described as 'Note path (.md optional)'. The description does not add additional meaning beyond that, so baseline score applies.
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 a note's heading structure (outline) without reading its body, listing specific return fields (level, line number, heading-path, ambiguity flag). It distinguishes from siblings that read the body or sections.
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 explicitly says 'Use it to see what sections exist before reading or editing one', providing clear when-to-use guidance. It implies alternatives (read_notes, read_section) but does not explicitly state exclusions.
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 provided, so description carries full burden. It discloses sorting by path, exclusion of attachment-only folders, and that root-level notes contribute no folder. It could mention pagination behavior, but the schema covers limit/offset.
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?
Front-loaded with purpose in first sentence. Second sentence packs exclusions and alternatives but is slightly long. No wasted words, but could be 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 4 parameters, no output schema, and many siblings, description explains return fields, sorting, exclusions, and contrasts with two sibling tools. Missing explicit return structure but fields are listed. Adequate for complexity.
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 already covers all 4 parameters with descriptions. Description adds minimal context (e.g., depth cap, immediate children), but does not significantly augment schema. Baseline 3 is appropriate.
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 enumerates vault's folders with specific fields ({path, notes, total_notes, subfolders}) and contrasts itself with list_notes, making the purpose and resource explicit.
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?
Description explicitly says it's the 'folder-level counterpart to list_notes, for seeing the vault's shape before searching or reading,' and notes when to use list_files instead for attachment-only folders.
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?
With no annotations, the description carries the full burden. It discloses pagination behavior ('offset still pages; truncated is always false') and states there is no limit. However, it does not explicitly state that it is a read-only operation or any authorization requirements, though 'list' implies read-only.
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 with two sentences. The first sentence covers the core functionality, and the second adds important behavioral context. No unnecessary words.
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 simplicity (one optional parameter, no output schema), the description adequately explains what it does, what it returns (count of notes per tag), and pagination behavior. It feels 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'offset' is fully covered by the schema (100%). The description adds value by clarifying that there is no limit to results and that pagination works with offset, which is not in the schema description.
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 action (list), the resource (tags), and additional details (count of notes, sorted by frequency, unification of inline and frontmatter tags). It distinguishes itself from siblings like 'find_by_tag' by focusing on listing all tags rather than searching for a specific one.
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 says 'Use it to see the vault's topic index', providing clear context for when to use the tool. It does not explicitly mention when not to use it or compare with alternatives, but the purpose is sufficiently clear for an agent to decide.
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 must bear full weight. It explains what is returned (heading + body) and the effect of include_subsections, but does not mention error behavior (e.g., missing section) or confirm read-only nature.
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, front-loaded with purpose, no fluff. Every sentence adds useful information.
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?
Covers main usage and return content for a simple read tool, but lacks details on error handling and output format, which would be helpful given no output schema.
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?
Adds significant value beyond schema: explains how to interpret the 'section' parameter (bare heading vs. heading-path) and the role of 'include_subsections', while schema already describes 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?
States a specific verb ('Read') and resource ('a single section of a note'), and distinguishes from siblings like 'read_notes' and 'get_outline' by emphasizing partial loading.
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 explicit guidance on addressing sections (bare heading vs. path) and the include_subsections option, but does not explicitly contrast with sibling tools or state when not 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?
With no annotations provided, the description carries full burden. It discloses the algorithm (blend of tags, links, co-reference, co-citation), result format (note headers with score and reasons), and a key constraint ('the source note is never itself a candidate'). It is transparent about what the tool does and does not do, though it omits performance or rate limit details, which are not critical for this read-only operation.
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 three sentences long, no fluff. It front-loads the core functionality, follows with a use case, and ends with narrowing options and a constraint. 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 no output schema, the description explains return format (note headers with score and reasons) and filtering parameters. It covers algorithm, constraints, and usage context. It is complete enough for correct invocation, though it doesn't explicitly mention pagination (offset/limit are in schema) or the required path parameter's format, which are minor gaps.
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 100%, baseline 3. The description adds value by explaining how parameters work together: 'Narrow the scored candidate pool with folder/tags/where/match (match governs tags; where conditions all apply).' This clarifies parameter semantics beyond the schema descriptions, earning an extra point.
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: 'Find the notes most related to a given note, ranked, without embeddings: a transparent blend of shared tags, direct links, shared out-links, and shared backlinks.' It specifies the verb (find), resource (notes related to a given note), and methodology, distinguishing it from siblings like search_notes_ranked (which may use embeddings) and get_links.
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 explicit use case guidance: 'Use it for associative recall - "I'm looking at X, what else is relevant?".' It also mentions narrowing options with folder/tags/where/match, helping the agent understand when to apply these parameters. However, it does not explicitly contrast with alternative sibling tools like search_notes or find_by_tag, so it loses a point for lacking exclusions.
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 provided, so the description carries the full burden of behavioral disclosure. It reveals key behaviors: array-valued properties count each element, results are ordered by frequency, and pagination via limit/offset. However, it does not mention scope (e.g., vault-wide) or any side effects, though the tool appears read-only.
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: three short sentences that front-load the purpose and add essential detail on array handling and ordering. Every sentence serves a purpose with no redundancy.
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 simple tool with 3 parameters, no output schema, and no annotations, the description reasonably covers purpose, output format, ordering, and counting behavior. It is complete enough for an agent to use correctly, though it could mention what happens if the property does not exist (likely empty list).
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 description coverage is 100%, providing baseline at 3. The description adds value by explaining that 'Array-valued properties count each element' for the 'key' parameter, and implicitly links 'most frequent first' to ordering related to the key. This extra context exceeds the 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 verb 'List' and the resource 'distinct values of one frontmatter property' with output format '{value, count} rows, most frequent first'. It also adds 'A faceted index for a single key', distinguishing it from siblings like list_properties and get_property.
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 the tool (to list distinct values of a property with counts), but does not explicitly mention when not to use it or present alternatives among the sibling tools. The context is sufficient for an agent to decide, but lacks explicit exclusions.
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 covers behavioral traits: it is read-only, resolves the folder from .obsidian/templates.json or an override, errors if not configured, and excludes Templater scripting. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that front-load the action and output format, 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?
For a tool with no output schema, it specifies the output headers. It explains error conditions and plugin limitations. A minor gap: it doesn't explicitly state the return type (array of objects), but this is implied by the listed headers.
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 coverage is 100% with clear descriptions for both parameters (limit and offset). The description does not add extra meaning beyond the schema, so a baseline of 3 is appropriate.
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 enumerates the vault's core Templates-plugin template folder and specifies the output format as { path, name, size, modified } headers. It distinguishes itself from Templater scripting, ensuring no confusion with sibling 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 mentions read-only behavior, that it errors if no template folder is configured, and that it only supports core Templates (not Templater). However, it does not explicitly state when to use this tool over siblings like list_files or when not to use it (e.g., for Templater templates).
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 provided, so description carries full burden. It discloses return format (notes, errors), behavior for missing/too large files, and that path traversal errors fail the whole call. It doesn't mention auth or rate limits, but for a read tool 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?
Two concise sentences that front-load the main purpose and efficiently add critical behavioral details. No wasted 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 a single parameter, no output schema, and no annotations, the description is nearly complete. It covers input format, return structure, and error modes. Missing potential limit on number of paths, but otherwise thorough.
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 100% with parameter description 'Note paths (.md optional)'. The description adds that paths are relative and explains error handling per path, providing valuable context beyond the 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 reads notes by path, using a specific verb and resource. It distinguishes from siblings like search_notes and get_frontmatter by focusing on reading by relative path.
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 this tool (to read notes by path) and provides nuanced guidance on error handling: one bad path doesn't fail the batch but path traversal does. It implicitly suggests alternatives like search_notes for content search, though not explicitly.
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?
Discloses return format (lightweight headers) and clarifies scoping behavior (match governs tags, where conditions all apply); no contradictions with missing 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?
Two focused sentences covering purpose and usage scope with no wordiness.
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 6 parameters, the description sufficiently explains the lightweight header output and scoping options, enabling correct tool use.
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 100%, but description adds value by explaining interaction between match and where conditions, going beyond schema definitions.
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?
Clearly states 'List notes in the vault as lightweight headers' with specific output fields, distinguishing from sibling tools like read_notes (full contents) and search_notes.
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?
Explicitly advises using it to 'discover what exists and orient before searching or reading', implying when-to-use context; could be improved by naming alternative tools for other scenarios.
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?
Despite no annotations, the description fully discloses behavior: return structure, null values for unconfigured fields, interpretation of writes_enabled, and the read-only nature. It is comprehensive.
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, front-loading the main purpose and then detailing the return object. It is dense but each sentence adds value; no redundancy.
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 absence of an output schema, the description fully specifies the return shape and handles edge cases (null values, interpretation of flags). It is complete for the tool's complexity.
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 100% with one enumerated parameter. The description adds that omitting the parameter returns the whole config and that the section is 'unwrapped', adding clarity beyond the 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 reports the server's own configuration, not vault contents, with a specific verb and resource. It distinguishes from siblings like get_vault_stats and other tools that deal with notes.
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 clarifies that the tool is read-only and never excluded by OBSIDIAN_TOOLS, implying it's always available. It does not explicitly state when not to use it, but the context of discovery for tool policy is clear.
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 provided, so the description must disclose behavior. It does so by noting that the tool is index-backed, describing limit/offset semantics per kind, and specifying that include_context errors on certain kinds. However, it does not explicitly state that the operation is read-only or mention authorization needs, leaving minor gaps.
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 yet thorough, with every sentence contributing essential information. It is well-organized: first a general statement, then enumeration of kinds, then pagination details. No redundant or filler 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?
Given the absence of an output schema, the description covers what each kind returns and how parameters interact. It addresses all four parameters and their nuances, leaving no obvious gaps for an agent to misinterpret the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds substantial value: it explains each enum value of 'kind' in detail, clarifies that limit/offset count groups for grouped kinds, and details the behavior and error conditions of 'include_context'. This goes well beyond the schema's minimal 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 uses the verb 'list' and specifies the resource as 'vault-hygiene issues', clearly distinguishing four kinds. It contrasts with sibling 'get_vault_stats' by stating that the latter only counts, while this tool returns the actual issues. The purpose is specific and unambiguous.
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 each kind and how pagination works differently for grouped kinds. It implicitly distinguishes from 'get_vault_stats' but does not explicitly state when not to use this tool or list alternatives beyond that one sibling. The guidance is clear but not exhaustive.
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 the ranking algorithm, result format (headers with score and snippet), boost for title/heading/tag matches, and pagination cap. It does not explicitly state read-only nature or error conditions, but for a search tool 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 three well-structured sentences. First sentence gives core purpose and scoping, second explains results and boosting, third contrasts with sibling and adds cap detail. Every sentence earns its place without redundancy.
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 complexity (7 parameters, no output schema, no annotations), the description covers the main behavioral aspects: ranking, scoping, result structure, and pagination. It lacks explicit details on error handling or the exact return format fields, but overall is sufficient for selecting and 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?
Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond schema by mentioning 'title/heading/tag matches boosted' (ranking behavior) and 'offset pages past the cap' (pagination nuance). This extra information justifies a 4.
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 performs 'full-text search ranked by BM25 relevance' and lists scoping options. It distinguishes itself from the sibling 'search_notes' by contrasting relevance ranking vs literal/regex unranked search.
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 'Complements search_notes (which is literal/regex, unranked),' guiding when to use this tool vs the alternative. It also notes the positive limit cap at 100 and offset pagination, providing clear usage boundaries.
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 burden. It discloses behavior such as sorting by frequency, no limit, pagination offset, and important edge cases about nested YAML handling (rejecting writes but allowing reads). It also states 'truncated is always false'.
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 sentences, front-loaded with the main purpose and key details. Every sentence adds essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 2 params and no output schema, the description fully explains what is returned (keys, counts, types, sorted), the pagination mechanism, and edge cases like nested YAML. No gaps remain.
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 100%, providing baseline 3. The description adds value by explaining offset behavior ('offset still pages; truncated is always false') and implying the effect of include_tags, which are not in 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 lists all frontmatter property keys with counts and value types, sorted by frequency. It explicitly distinguishes itself from siblings by comparing to list_tags and mentioning arbitrary properties.
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: 'the vault's property schema' and mentions pagination and no limit. It implicitly differentiates from tools like list_tags and get_property, but lacks an explicit when-to-use vs alternatives statement.
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?
Discloses exact, case-insensitive, index-backed lookup; no destructive actions; details return structure (matches array with path, title, matched_on; resolved field). Completely transparent given no annotations.
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?
Concise yet comprehensive; all sentences add value, but could be slightly tighter. Front-loaded with core purpose.
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?
Thorough coverage of return values, edge cases, and behavioral details despite no output schema. Fully equips agent to use the tool correctly.
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 describes query parameter; description adds context about name types and matching semantics, exceeding baseline for 100% 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?
Clearly states the tool resolves note names to canonical paths, lists valid name types (title, alias, basename), and distinguishes from siblings by emphasizing exact, not fuzzy, matching.
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 tells when to use (known name, need exact path) and when not to (approximate matching, use search_notes_ranked). Explains behavior for ambiguous or no matches.
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?
Despite no annotations, the description fully discloses behavioral traits: read-only operation, error conditions (when daily notes not configured), path format (no .md, slashes nest folders), and the template expansion caveat. This is comprehensive beyond what annotations would typically provide.
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, starting with the main purpose, followed by return details, usage guidance, and a caveat. While slightly long, every sentence contributes meaning; a minor trim could improve conciseness.
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 this tool: it explains output fields, error scenarios, and how it fits with sibling tools. No output schema is needed given the detailed return description.
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 single parameter 'date' is fully described in the schema (100% coverage). The description adds value by listing accepted string values ('today', 'yesterday', 'tomorrow', 'YYYY-MM-DD') and the default behavior, enhancing the schema's 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 the tool maps a calendar date to a canonical daily-note path using the Daily Notes plugin configuration. It specifies the verb 'map' and resource 'daily-note path', and distinguishes it from sibling tools like note resolution or file search.
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 tells when to use this tool (to get the path) and what to do next: 'existing tools do the rest: apply_template, write_note, append_note, etc.' It also mentions the caveat about template expansion for past/future dates, which guides appropriate usage.
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:

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

Score Badge

Copy to your README.md:

[![headless-obsidian-mcp MCP server](https://glama.ai/mcp/servers/emguide/headless-obsidian-mcp/badges/score.svg)](https://glama.ai/mcp/servers/emguide/headless-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/emguide/headless-obsidian-mcp'

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