kObsidian MCP

Server Quality Checklist

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

Latest release: v0.3.5
Disambiguation4/5
Tools are generally distinct with clear categories (notes, links, tags, etc.), but some potential overlap exists between dataview.query and dataview.fields.write, and between multiple search tools (notes.search, tags.search, tasks.search).
Naming Consistency5/5
All tools follow a consistent category.tool naming pattern with clear verbs (list, create, read, etc.), making the surface predictable and easy to navigate.
Tool Count3/5
42 tools is a large surface for an Obsidian assistant, covering many features but feeling somewhat heavy. Some tools could be consolidated (e.g., multiple links.* tools).
Completeness3/5
Covers core Obsidian operations well, but missing a notes.move tool for renaming, and no simple tool to list all notes (only search). Wiki tools are extensive but other areas are slightly incomplete.
Average 4.6/5 across 42 of 42 tools scored. Lowest: 4/5.
See the Tool Scores section below for per-tool breakdowns.
- 7 of 7 community issues answered or closed in the last 6 months
- 9 commits in the last 12 weeks
- Last stable release on September 2, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under Apache 2.0.
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?
Annotations already cover readOnly, idempotent, openWorld, and non-destructive behavior, so the description adds value by mentioning plugin prerequisites and vault resolution semantics. However, it claims an explicit `vaultPath` argument 'always wins,' but that parameter is absent from the input schema and additionalProperties is false. This is a misleading behavioral claim that an agent cannot actually act on, which undermines 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 appropriately short and front-loaded: the first sentence defines the operation, the second gives the use case, the third gives prerequisites, and the final paragraph explains vault behavior. The vaultPath sentence is somewhat misleading and the vault.current/vault.select references add a small distraction, but overall the structure is compact and readable.
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 core purpose, prerequisites, vault resolution, and structured output, and the output schema plus annotations handle return values and safety. However, it leaves the vaultPath mismatch unresolved and does not clarify what happens when `fromClause` is omitted, which is relevant for correct invocation. These gaps prevent it from being fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/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 all real parameters; the description only restates that WHERE, SORT, and LIMIT are optional, adding no new meaning. Worse, it introduces a phantom `vaultPath` parameter not present in the schema, actively confusing parameter expectations. This is a net negative beyond the baseline.
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 ('runs') and names the exact DQL TABLE form it wraps. It also explicitly says 'structured columnar output,' which differentiates this tool from list-oriented siblings like dataview.listByTag and dataview.listByFolder. This is a clear, distinguishing statement of 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?
It gives an explicit usage trigger: 'Use this when you need structured columnar output.' It also notes a prerequisite (Dataview and Local REST API plugins), which is useful for pre-call checks. However, it never names alternatives or explains when to prefer dataview.query or listByTag, so exclusions are left implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description references an explicit `vaultPath` argument that does not exist in the input schema. This is misleading and could cause an agent to pass an invalid parameter. While annotations already cover readOnly/idempotent/destructive hints, the description adds inaccurate behavioral context rather than useful information, and the vault-selection behavior is described in a way that conflicts with the actual parameter 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 two short paragraphs. The first paragraph states purpose and plugin requirements; the second clarifies vault selection. Information is front-loaded, and every sentence serves a purpose. There is no fluff or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers plugin requirements and vault behavior, the major inconsistency of referencing a `vaultPath` parameter not present in the schema creates a significant gap. An agent relying on this description might try to pass `vaultPath` and fail. The output schema exists, so that part is not an issue, but the misleading information makes the description incomplete and potentially harmful.
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 every parameter already has a clear explanation. The description adds an example for `sortBy` ('file.ctime desc') and clarifies the DQL mapping for where/sort/limit, but this is marginal. It does not significantly enhance understanding beyond what the schema provides, and the misleading `vaultPath` mention negatively impacts clarity.
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 is a convenience wrapper around `LIST FROM "folder"` with optional DQL clauses. It explains the exact use case ('every note under a vault folder') and naturally distinguishes it from siblings like dataview.query (general DQL) and dataview.listByTag (by tag). The verb and resource are 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 says it is 'useful when you want every note under a vault folder,' which is a clear usage context. It also mentions the Dataview and Local REST API plugin requirement. However, it does not explicitly name alternatives like dataview.query or state when not to use this tool, relying instead on implication from the term 'convenience wrapper.'
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?
The description adds meaningful context beyond the readOnlyHint/idempotentHint annotations by disclosing plugin requirements, authentication configuration, and vault-scoping behavior. However, the statement about a 'vaultPath' argument that overrides vault selection is factually inconsistent with the schema, which undermines trust in the behavioral description. It provides some value but also introduces a false behavioral claim.
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 a clear purpose statement, followed by examples, alternatives, prerequisites, and vault behavior. It is somewhat long but each sentence adds value. The only structural issue is that the vaultPath mention is placed as a final aside, slightly muddling the otherwise clean flow.
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 essential prerequisites, alternative tools, and vault behavior, and an output schema exists so return values are not required. However, the incorrect vaultPath reference is a significant completeness gap: an agent following the description may attempt to pass an invalid parameter. Additionally, the description does not mention error handling or query syntax validation, which would be useful for a raw DQL tool, though not strictly necessary given the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers the 'query' parameter well (100% coverage), so the baseline is 3. The description adds useful clarification that the query is 'raw DQL' and gives examples, which helps. But it also references a 'vaultPath' parameter that does not exist in the schema (additionalProperties: false). This is actively misleading and could cause an agent to include an invalid parameter, so the score is dropped below baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's action: 'Execute an arbitrary Dataview Query Language (DQL) query.' It provides concrete examples (LIST FROM #inbox, TASK WHERE !completed) and distinguishes itself from sibling sugar tools like dataview.listByTag by positioning this as the escape hatch for custom DQL. The verb+resource 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 clearly says to prefer dataview.listByTag/listByFolder/table for common patterns and fall back to dataview.query for custom DQL, which is excellent when-to-use guidance. It also lists prerequisites (Dataview plugin, Local REST API config) and explains vault selection behavior. However, the claim that an explicit 'vaultPath' argument can be passed is misleading because the input schema does not include such a parameter (additionalProperties: false), creating confusion for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description transparently discloses that remove-node is destructive and cascades to incident edges, and explains vaultPath precedence. However, the annotations declare destructiveHint=false, which directly contradicts the description's explicit 'destructive' warning. Per the scoring rule, this contradiction forces a score of 1.
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 purpose sentence, operation-specific parameter requirements, vault behavior, and three concrete JSON examples. Despite its length, every sentence earns its place, and the examples dramatically reduce ambiguity for op-specific payloads.
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 all three op variants with required and optional parameters, the destructive side effect, vault resolution rules, and the standard mutation envelope return. With a full input schema and an output schema present, nothing needed for correct invocation is missing.
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 the baseline is 3. The description adds value beyond the schema by grouping required parameters per op, explaining the content semantics for nodeType text vs file, and stating that vaultPath always wins over the active vault — details that help an agent assemble valid calls.
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 canvas' followed by the three exact mutations (add node, add edge, remove node). This clearly distinguishes the tool from siblings like canvas.create and canvas.parse, and the op-specific breakdown leaves 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 for when to use the tool: any mutation of an Obsidian canvas, with explicit detail on which op needs which parameters. It also clarifies vault resolution (session-active vault vs explicit vaultPath), but it does not explicitly name sibling alternatives or list exclusion conditions, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is transparent about failure behavior and overwrite semantics, but annotations declare destructiveHint:false while the description states that overwrite:true overwrites an existing file. That is a contradiction on a safety-critical behavioral trait, so this dimension must be scored down despite the otherwise strong 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 front-loaded with the core action, then adds only necessary details: failure behavior, file format relevance, next-step sibling, and vault targeting. Every sentence earns its place and there is no 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 create operation with an output schema, the description covers the essential invocation context: target path, overwrite behavior, vault resolution, file type, and follow-up editing tool. An agent has enough information to call it correctly in most scenarios.
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 schema documents filePath and overwrite, but vaultPath has no schema description. The tool description compensates by explaining vaultPath precedence over the session-active vault, which is exactly the missing semantic context an agent needs. It also reinforces the overwrite behavior with the fail-if-exists default.
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 states a specific action ('Create'), a precise resource ('new empty Obsidian canvas (.canvas) file'), and path-based placement. It also distinguishes itself from the sibling canvas.edit by making clear that canvas.edit is for adding nodes/edges after the file exists.
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 says to use this tool first and then canvas.edit for nodes/edges, providing a clear workflow. It also explains the overwrite condition and the session-active vault resolution, including the vault.select/vault.current relationship, which helps an agent decide how to target the right vault.
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?
Description discloses idempotency (consistent with the idempotentHint annotation) and adds meaningful context: 're-running with identical inputs converges on the same line' and 'Fails if the target line is not a task.' It also explains vault selection precedence. These details go beyond the annotations, which only flag idempotentHint, enriching the behavioral picture without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded paragraphs. The first paragraph states the core action and identity; the second covers idempotency, failure mode, and vault selection. Every sentence adds essential information, with no redundancy or filler.
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 mutation tool with an output schema and well-patterned date fields, the description covers identity, failure mode, idempotency, and vault selection. The only gap is explicit guidance for less obvious parameters (recurrence format, vaultPath semantics), but the schema patterns and existing schema descriptions partially fill that gap. Overall, sufficient for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% (priority and lineNumber have descriptions). The description compensates partially by explaining the identity mechanism and partial-update behavior, but it does not clarify the semantics of dueDate, startDate, scheduledDate, recurrence, or vaultPath. With low coverage, the description must carry more parameter detail than it does.
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 ('update'), resource ('task metadata'), and scope (dates, priority, recurrence) with the crucial qualifier 'without touching the task body text.' It also specifies the identity mechanism (sourceFile + lineNumber), which clearly differentiates it from sibling tools like tasks.create and tasks.toggle.
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 contextual guidance: it operates on the session-active vault, with vaultPath as an override, and instructs to 'pass only the fields you want to change.' However, it does not explicitly name alternatives (e.g., tasks.edit for body text) or state conditions for when not to use this tool, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds behavioral context beyond these by stating 'Read-only, runs locally (does NOT require the Local REST API)' and explaining that vaultPath overrides the active vault. This is useful extra information about execution environment and precedence, though it does not detail error handling or output structure (covered by output schema). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two paragraphs: the first front-loads the main purpose and output scope in a compact sentence; the second addresses vault selection. No redundancy, no filler. Every clause adds information. Highly efficient for the information conveyed.
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 tool is moderately complex with an output schema. The description covers the key aspects: what data is returned, the read-only guarantee, local execution (no REST API), vault selection logic, and the intended use case. It does not discuss potential errors (e.g., file not found) but given the output schema and annotations, this is sufficient. Sibling tools are numerous, but the description positions it well.
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 0%, so the description must compensate. It does clarify that vaultPath 'always wins' over the session-active vault, giving meaning to that optional parameter. For filePath, it only implies 'a single note' but does not specify path format or resolution rules. Given two parameters, the description provides some value but not comprehensive compensation for the missing 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 states a specific verb ('Parse a single note') and a resource with explicit detail about what is returned: page-level metadata, list-item fields, task-line fields, and DQL/DataviewJS block locations. It clearly distinguishes from siblings like dataview.query (runs queries) and notes.read (raw content) by positioning itself as 'what Dataview would index'.
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 states the intended use case: 'Use this to understand what Dataview sees in a note without running a query.' It also gives context on vault selection (active vault vs explicit vaultPath). It does not explicitly name alternatives for when to run a query, but the phrase 'without running a query' implies the distinction. Clear enough for an agent to decide appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond the annotations: it explains the merge vs replace strategies, the requirement for at least one of set/unset, and the vault selection precedence. It also confirms idempotency, aligning with the idempotentHint annotation. No contradiction exists.
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-organized: it starts with the core operation, then covers strategy, requirements, idempotency, vault behavior, and provides two clear examples. It is thorough without being bloated, though slightly longer than strictly necessary.
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 5 parameters and nuanced merge/replace behavior, the description covers all key aspects: set/unset semantics, strategy selection, the requirement, idempotency, vault path precedence, and examples. Since an output schema exists, return-value details are handled there, so nothing essential is missing.
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 60%, and while the schema already describes set, unset, and strategy, the description clarifies the semantics further: it explains what 'merge' and 'replace' do to unspecified fields, and it details the requirement that at least one of set/unset be present. It also adds meaning to vaultPath by explaining its precedence over the session-active vault.
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 (set/unset) and resource (YAML frontmatter of a note), and precisely distinguishes between the two operations. It also differentiates from sibling tools like notes.edit or dataview.fields.write by focusing specifically on frontmatter manipulation.
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 when to use the tool (when you need to edit frontmatter fields) but does not explicitly mention alternatives or when not to use it. There is no reference to sibling tools like dataview.fields.read or notes.edit, so the selection guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context beyond annotations, including the cost explosion with higher depth values and the precedence rule for vaultPath over the active vault.
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?
Well-structured and front-loaded: the core behaviour and output come first, followed by cost warning and vault semantics. Slight redundancy exists because 'read-only' and 'result size blow-up' repeat annotation/schema information, but overall 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?
Comprehensive given the annotations, schema, and output schema: it explains scope, output shape, depth risk, and vault resolution. It does not discuss failure modes or when to choose a sibling tool, but the provided context is enough for correct invocation.
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 covers noteName and depth reasonably well, but leaves vaultPath undocumented. The description compensates by explaining that vaultPath overrides the active vault, and reinforces depth semantics with a concrete limit recommendation.
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 and resource: explores the graph neighbourhood around a seed note with direct and multi-hop connections. Clearly distinguishes itself from sibling direct-link tools like links.outgoing and links.backlinks by describing traversal depth and returning reachable notes plus paths.
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 operational context: the active vault is used by default, vaultPath overrides it, and depth should generally stay ≤3 to avoid result blow-up. It does not explicitly name alternatives or say when to prefer this over a sibling tool, but the guidance is sufficient for practical 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?
The description reinforces and extends the annotations: it states 'Never writes', explains vault selection behavior, and explicitly notes that vaultPath always wins. It also discloses the exact grouped output keys and their meanings, adding substantial context beyond what readOnlyHint and idempotentHint already convey.
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 and front-loaded with the core purpose, followed by output details, usage guidance, and examples. It is somewhat long and mildly repetitive with the schema's staleDays documentation, but every major section earns its place and the examples are useful.
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 read-only tool with optional parameters, an output schema, and strong annotations, the description is complete: it covers purpose, return shape, defaults, vault selection, workflow, and examples. No critical calling information appears to be missing.
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 coverage is 100%, so the baseline is 3. The description adds meaningful extra semantics by clarifying that vaultPath takes precedence over the active vault and by giving concrete examples for default usage and staleDays. This goes slightly beyond the schema's own descriptions, though it does not add detail for wikiRoot.
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 identifies a specific operation: a read-only health check across the wiki, with named finding categories such as orphans, brokenLinks, and missingPages. It is sufficiently concrete to distinguish itself from general utilities, though it does not explicitly contrast itself with sibling tools like links.broken or links.orphaned.
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 gives practical usage context: 'Use periodically' and pairs the tool with notes.move/notes.edit/wiki.indexRebuild for fixes. It does not explicitly state when not to use it or name alternative sibling tools for narrower checks, but the periodicity and follow-up workflow are 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?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Read-only.' The description adds value by detailing output variability per part and the precedence of 'slideId' over 'index', which informs expected behavior beyond the static annotations. It also clarifies vault resolution, which is behavioral context not covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-organized: it leads with the action and purpose, then details the three part variants in a compact way, and ends with vault resolution. Every sentence contributes to understanding the tool; there is no filler or redundancy. The structure front-loads the most critical discriminators.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (three variants, multiple parameters, output variations), the description is thorough in explaining the input selection and vault behavior. It does not detail the exact return format, but the presence of an output schema (indicated in context) mitigates this. The only minor gap is lack of error-handling or edge-case notes, but for a read-only tool this is acceptable.
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 schema already covers parameter descriptions heavily (100% coverage per context), but the description enriches this by explaining the semantic differences between 'part' values, the meaning of 'slideId' versus 'index', and the override behavior of 'vaultPath'. This is more than schema repetition; it provides decision-relevant semantics for the agent's invocation.
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 states a specific action ('Read') on a specific resource ('Marp presentation deck') and enumerates three distinct variants via the 'part' field. It also differentiates from the sibling 'marp.update' by explicitly noting it is read-only and that mutation goes through the update tool. This is a clear, unambiguous 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 provides clear usage context: it explains when to use the read tool versus the update tool, and clarifies that it operates on the session-active vault unless an explicit 'vaultPath' is provided. It also explains how to select a slide via 'slideId' or 'index', which are key usage decisions. However, it does not compare against other read tools (e.g., notes.read) for scenarios where a non-Marp markdown is involved, so it lacks full alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, and the description reinforces 'Read-only.' It adds context about the session-active vault and how `vaultPath` overrides it, which is valuable beyond the annotations. It does not detail the output format, but the presence of an output schema covers that.
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 that are front-loaded with the core purpose, then immediately disambiguate from the sibling. No filler or repetition—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 output schema exists and the description clearly explains the tool's scope, usage context, and vault-selection nuances, an agent has enough to call it correctly. The only minor gap is the lack of detail on `vaultPath` formatting, but that's handled by the schema and the explicit 'always wins' note.
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 only 50% — `vaultPath` has no description in the schema. The description partially compensates by stating that `vaultPath` overrides the active vault, but it doesn't explain its format or default behavior in depth. This is adequate but not fully compensating for the low 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 states a specific verb (return), resource (tags in a single note), and the structure of the output (frontmatterTags, inlineTags, allTags). It explicitly contrasts with tags.search, making it unmistakably distinct from the closest sibling.
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 says 'Use this when you have one note and want to know what tags it carries' and names the alternative `tags.search` for whole-vault scans. Also explains the vault selection behavior and precedence of the `vaultPath` argument, leaving no ambiguity about when to call 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?
Beyond annotations (destructiveHint=false, readOnlyHint=false), the description discloses key behaviors: in-place editing, the date-stamping side effect with default and override, and the failure condition when the line is not a task. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core action, and every sentence adds value: main operation, date stamp detail, failure condition, and vault selection rule. No waste.
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 essential operation, failure mode, vault handling, and how to obtain inputs. Since an output schema exists (though not provided), return values are likely covered there. The description is sufficiently complete for an agent to call 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 covers 75% of parameters with descriptions. The description adds meaning to doneDate (default today, override) and clarifies vaultPath's precedence. It complements the schema adequately, leaving only vaultPath's format undefined but its role clear.
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 states a specific verb ('Flip'), a resource (task line), and precise identifying parameters (sourceFile and 1-based lineNumber). It clearly distinguishes from siblings like tasks.search (find) and tasks.create (make new), and the phrase 'in place' clarifies mutation vs. creation.
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 directs agents to use tasks.search to find the right sourceFile/lineNumber pair, which is actionable guidance for correct invocation. It also explains the vault selection rule (active vault vs explicit vaultPath). It does not explicitly state when NOT to use the tool, but the search pointer serves as an effective alternative.
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?
The description goes well beyond the annotations: it discloses that the tool is UI-only, does not create/modify/read file contents, returns { ok: true }, fails when the file is missing or the REST API plugin is unreachable, and may target a different vault than the filesystem session. It also notes the newPane behavior. None of this contradicts the annotations; the non-readOnlyHint is consistent with the UI state change it performs.
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 longer than the minimal case, but each block earns its place: the core behavior, the UI-only caveat, the failure modes, the vault-targeting caveat, and examples. There is minor redundancy in mentioning the Local REST API twice, but overall it is well-organized and front-loaded with the action and key parameter.
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 rich annotations and an output schema, this description is complete. It covers return values, error conditions, relationship to notes.read, interaction with vault.select, and provides examples. An agent has everything needed to invoke it correctly without consulting additional tools.
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 explains both parameters. The description adds some value by clarifying the default newPane behavior ('default reuses the active pane') and providing two concrete examples, but it largely restates the schema's semantic content rather than adding substantial new 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 opens with a precise verb-resource pairing — 'Open a vault-relative note filePath in the live Obsidian UI' — and clarifies the UI scope. It explicitly distinguishes itself from notes.read by saying it does not read file contents. This is enough to separate it from siblings like notes.read and workspace.navigate.
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 gives a clear when-to-use signal: when you need to reveal a note in the live Obsidian UI. It also provides an explicit alternative by saying 'use notes.read for content,' and explains that vault.select does not affect this tool. It does not enumerate all sibling alternatives exhaustively, but it gives sufficient routing context for the common confusion cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description reinforces 'Read-only.' It adds useful behavioral context: the scan operates on the session-active vault unless vaultPath is supplied, and vaultPath always wins. It also discloses the per-result fields, which helps set expectations 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?
The description is compact and front-loaded: the core function, scope options, result contents, read-only nature, and repair workflow all appear in a few sentences. Every sentence adds value, and the vault-selection nuance is placed after the main purpose without bloating the definition.
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 need not fully specify return values, and it still gives a helpful preview (source file, line number, link text, unresolved target). Together with annotations and the vaultPath/directory semantics, an agent has enough context to select and invoke 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 coverage is 50%: directory has a schema description, but vaultPath does not. The description compensates for vaultPath by explaining it overrides the session-active vault, and it clarifies that directory scopes the scan to a subtree. It does not give vaultPath format examples, but the added precedence semantics go 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 states a specific verb and resource: 'Find every link in the vault (or a directory subtree) whose target does not resolve to an existing note.' This clearly distinguishes the tool from sibling link tools like links.outgoing or links.graph by focusing on broken/unresolved targets. The expected result fields further clarify 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 gives clear context: use it to find broken links, and explicitly pairs it with notes.move (updateLinks:true) to fix them after moves. It also clarifies the session-active vault and vaultPath precedence. It does not explicitly list alternatives or when-not-to-use scenarios, but the context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds non-obvious behavioral context: it operates on the session-active vault unless an explicit vaultPath argument overrides it, with the override always winning. This is valuable information beyond the annotations. It doesn't describe return format, but an output schema exists to cover that.
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 compact and well-structured. The first sentence states the core definition, followed by usage context, then the important vault-selection behavior. No unnecessary filler; every sentence contributes to understanding. The structure is logical and front-loaded with the primary 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?
For a simple, read-only tool with one optional parameter and an output schema, the description covers everything an agent needs: the exact condition, usage context, and vault selection behavior. It doesn't explain the output structure, but the output schema handles that. The description is complete for correct invocation.
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 schema has 0% coverage for parameter descriptions, so the description is the only explanation. It clearly explains the optional vaultPath parameter: it overrides the session-active vault and always wins. This gives semantic meaning beyond the raw schema, though it doesn't specify the format (e.g., path syntax), which is a minor gap given there's only one parameter.
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 precisely defines the tool's action: 'Return every note with zero incoming AND zero outgoing links' and explains what that means ('disconnected from the rest of the vault graph'). It clearly distinguishes from sibling tools like links.broken and links.hubs by specifying the dual-direction condition, 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear usage contexts: 'useful for cleanup passes' and 'often paired with links.hubs and links.broken in a weekly vault-health routine.' This gives an agent a good sense of when to invoke it. It doesn't explicitly state when not to use it, but the defined scope and pairing guidance are sufficient for typical 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?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds valuable behavior not in annotations: parameter semantics (include, recursive, dateField interplay), the default modified date, and the vault scoping override. It does not contradict annotations and reinforces the read-only nature. It stops short of describing the exact output structure (e.g., which fields are returned per item), but the output schema covers that. With annotations covering safety, the description adds meaningful context, earning a 4.
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 succinct paragraphs. The first states the action and key parameters; the second addresses vault scoping. Every sentence contributes new information—no filler or redundancy. It is front-loaded with the core purpose and parameter semantics, making it easy to scan. This is appropriately sized for a tool with 7 parameters and no required args.
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 (7 params, 0 required) and the presence of an output schema, the description covers all essential aspects: purpose, parameter behavior, default values, recursion, and the vault selection precedence. It also references sibling tools (vault.current, vault.select) for context. Nothing critical is missing for an agent to call it correctly. The read-only nature is reinforced, and the output format is left to the schema. This is complete.
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 86%, so most parameters already have meaning in the schema. The description adds relational value beyond that: it ties since/until to dateField, explains recursive behavior, clarifies include options as notes, folders, or both (tagged by kind), and spells out the vaultPath precedence. This goes beyond individual parameter descriptions, helping an agent understand how parameters combine. Since coverage is high, the baseline is 3, but the description elevates it to 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 opens with a specific verb (list) and resource (notes/folders), and clarifies optional scoping and filtering. It distinguishes itself from siblings like notes.read (read a single note), notes.search (search), and vault.list (list vaults) by clearly stating what it enumerates in the session-active vault. The purpose is unambiguous and easy to differentiate at a glance.
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: list notes/folders, optionally scoped to a folder and date range. It mentions read-only behavior and explains vault selection precedence (vaultPath wins), which is critical for correct invocation. It does not explicitly name alternatives for when not to use it (e.g., 'for full-text search use notes.search'), but the scope is self-evident and enough for an agent to decide appropriately. A small deduction for not enumerating 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?
Annotations already signal mutation (readOnlyHint=false) and non-destructiveness, and the description adds meaningful behavior: it writes Tasks-plugin emoji metadata, returns the 1-based lineNumber, and respects the active vault unless vaultPath is provided. It doesn't cover edge cases like missing files, but the disclosed behavior is solid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action and format, then moves to return value and vault behavior, and closes with two compact examples. Every sentence and example earns its place; no filler or repetition of schema 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 an 11-parameter creation tool, the description covers the write format, optional metadata, return envelope, vault-selection behavior, and the vaultPath override, and the examples show realistic JSON payloads. The schema and output schema provide the remaining structured 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 45% schema description coverage, the description compensates by listing the optional metadata fields, explaining that they become emoji suffixes, giving examples for dueDate and recurrence, and clarifying that content excludes the checkbox. It doesn't deeply define each date field's semantics, but adds 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 states a specific verb ('Append') and resource ('a new task line to a note'), and further specifies the exact Tasks-plugin format. This distinguishes it from sibling tools like tasks.toggle or tasks.updateMetadata, which modify existing tasks rather than creating new ones.
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 opening sentence gives clear context: use this tool to append a new task line to a note, which implies creation rather than toggling or updating existing tasks. It does not explicitly name alternatives or state when not to use it, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds behavioral detail beyond annotations: it filters to markdown files only and defines the precedence rule for vaultPath over the active vault. This gives an agent useful execution semantics not inferable from annotations 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?
Four sentences, each carrying distinct information: core purpose, usage guidance, return-type restriction, and vault resolution behavior. No redundant prose or schema repetition beyond the necessary 'read-only' confirmation. It is front-loaded and appropriately compact.
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 does not need to enumerate return fields. It covers the default folder, folder override, vault resolution, and file-type restriction, which are the key facts an agent needs before invoking. The explicit tie to templates.use completes the operational context.
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 only 50% because vaultPath lacks a schema description. The description compensates by explaining vaultPath as the explicit path that 'always wins' over the active vault, and clarifies templateFolder as a folder override defaulting to the vault's configured templates folder. This adds meaning beyond the raw schema for both parameters.
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: lists markdown templates in the vault's configured templates folder or a caller-specified folder. It explicitly scopes the return set to .md files and references templates.use as the follow-up, which distinguishes this tool from other list and search siblings. This fully identifies the tool's 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 explicitly instructs to use this tool 'to discover what templates are available before calling templates.use,' giving a clear when-to-use condition and naming the related alternative. It also explains that the tool operates on the session-active vault unless vaultPath is supplied, providing context for correct invocation. It lacks an explicit 'when not to use' for non-template listing, but the named templates.use relationship is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false, and the description adds concrete meaning: running on an already-cleared session is a no-op that reports changed:false. It also explains the precedence-chain fallback and clarifies that per-call vaultPath behavior is unaffected. These details go beyond the structured annotations and provide non-obvious operational context.
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, each earning its place: the core action, the motivating use case, and the idempotency/scope caveats. The primary effect is front-loaded, and there is no redundant restatement of schema or annotation fields. This is appropriately concise for the complexity of the tool.
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 zero-parameter reset operation with an output schema and robust annotations, the description fully covers behavior, idempotency, side-effect scope, and the precedence-chain impact. It states what changes (session selection) and what does not (per-call vaultPath). Nothing needed for safe invocation is missing.
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 tool has zero parameters, schema coverage is 100%, and the schema description is '(none).' There is no parameter documentation burden for the description to carry. The description implicitly confirms the tool takes no arguments by describing a session-level reset rather than a parameterized operation.
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 concrete verb and resource: 'Clear the session-selected vault.' It further clarifies the effect on the precedence chain and explicitly distinguishes itself from per-call vaultPath behavior, which disambiguates it from selection tools like vault.select. This is specific, actionable, and not a tautology.
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 direct intended-use scenario: 'Use this to signal I'm done with the scratch vault, go back to the default.' It does not explicitly name sibling alternatives such as vault.select, but the use-case framing and the note about per-call vaultPath provide enough context for an agent to decide when to invoke it. A more explicit 'when not to use' statement would earn a 5.
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 writes, appends, returns a proposedEdits array, and intentionally does not apply cross-reference writes so edits appear in the transcript. It does not mention overwrite behavior if the slug already exists, but the major behavioral traits are clearly covered.
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 longer than average, but for a 15-parameter write tool the added detail—side effects, routing instructions, override behavior, and two examples—is earned. It is well-organized and front-loads the core mechanism before optional context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description covers the main write path, vault-scoping behavior, alternative-tool routing, and the follow-up workflow via `notes.*` tools. It does not specify overwrite/idempotency semantics, but the output schema and examples make the tool callable with confidence.
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 the schema already documents each parameter; the description adds workflow-level meaning by connecting `relatedConcepts`/`relatedEntities` to proposedEdits, reinforcing the `sourcePath`/`content` exclusivity, and explaining that `vaultPath` always wins. The two examples also show realistic parameter combinations.
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 states a precise action: 'File one new source into the wiki' and specifies concrete side effects: writes `Sources/<slug>.md`, appends to `log.md`, and returns `proposedEdits`. It clearly differentiates from siblings like `wiki.summaryMerge` and `wiki.query` by naming them as alternatives for different goals.
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 says when to use this tool vs alternatives: use `wiki.summaryMerge` for follow-up sections on existing pages, and `wiki.query` for lookups without writing. Also gives direct exclusion guidance for `sourcePath` vs `content` and explains vault selection precedence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it explains the session-active vault resolution and that an explicit vaultPath always wins, which is important for correct invocation.
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 compact and front-loaded: the purpose, output, and primary alternative appear in the first two sentences. The vault-targeting note is the only additional context and is directly relevant to usage. No sentence is 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?
With an output schema present, return-value details are handled structurally. The description covers the tool's purpose, when to use it, the alternative tool, and the vault resolution rule. It is complete for a read-only parsing tool, though it does not mention error behavior for invalid canvas files, which is a minor 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 50%: filePath is documented but vaultPath has no schema description. The description compensates by explaining vaultPath's role and precedence over the active vault, giving the agent enough semantics to use it correctly. It does not detail vaultPath's format, but the core meaning is clear.
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 states a specific verb ('Parse'), a specific resource ('Obsidian canvas file'), and the exact output scope ('full structure: every node ... every edge'). It also explicitly contrasts itself with canvas.connections, so an agent can distinguish it from its closest sibling without opening 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 an explicit usage rule: use this tool for the complete graph, and use canvas.connections for neighbours of a specific node. It also clarifies the vault-targeting behavior and references vault.current and vault.select, providing clear context for when this tool applies.
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?
Annotations already declare destructiveHint=true and readOnlyHint=false. The description reinforces this by stating 'Destructive — the effect depends entirely on what the command does' and adds a verification warning. It also discloses the plugin requirement, the targeting of the live Obsidian vault, and that routing is unaffected by `vault.select`. This adds significant context beyond the annotations 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short paragraphs that are front-loaded with the core purpose and then add relevant contextual warnings. It avoids redundancy with the schema and each sentence contributes either a prerequisite, a caution, or a routing clarification. It could be slightly tighter (e.g., merging the two paragraphs), but it is appropriately sized for a potentially dangerous tool.
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 high risk (executes arbitrary commands) and the presence of a full schema and output schema, the description covers all critical aspects: how to identify a command, optional arguments, required plugin, destructiveness warning, target scope, and routing behavior. It does not describe error handling, but that is not essential when the description already meets the safety and usage needs for an agent.
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 both parameters are already well-documented. The description enhances this by clarifying that `args` is an optional argument map and that most built-in commands take no arguments (matching the schema's note). More importantly, it tells the agent where to obtain a valid `commandId` (via `commands.list`), which is not in the schema. This added guidance slightly exceeds the baseline for full 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 states a specific verb ('Execute') and a clear resource ('an Obsidian command by its internal id'), and references `commands.list` as the source of ids. It also explicitly notes that `vault.select` does not affect this tool, distinguishing it from filesystem-routing tools. This is a precise, unambiguous purpose statement.
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 a clear prerequisite (Requires the Local REST API plugin) and gives a caution to verify the command id before calling, which guides safe usage. It does not explicitly state when to use this tool over alternatives, but the reference to `commands.list` implies a natural sequence and the `vault.select` note clarifies when it is not affected. Lacks an explicit when-not-to-use, so a 4 is appropriate.
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?
Adds significant context beyond the destructiveHint=true annotation: states the file is removed from disk, fails with not_found, and has no undo. It also explains the rationale for not exposing folder deletion to avoid cascading deletes. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise paragraphs: first covers deletion behavior and alternatives, second covers vault context. Information is front-loaded with the core action and no sentences are wasted, though it is slightly longer than strictly necessary.
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?
Covers failure modes, destructive nature, vault selection, and alternative for folders. Output schema presumably handles return values, so nothing critical is missing for an agent to call 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?
With 0% schema description coverage, the description compensates by explaining vaultPath always wins over the session vault and that path refers to the note path. However, path format details and vaultPath structure are not elaborated, leaving some ambiguity for the agent.
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 states the tool deletes a note from the vault, a specific verb and resource. It distinguishes itself from siblings like notes.move (for folders) and other note operations, making it clear what this tool does and does not do.
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 directs folder deletions to notes.move instead, and explains the vault selection mechanism (vault.current/select) with vaultPath override. This provides clear when-to-use and when-not-to-use guidance, including a concrete alternative.
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?
The description independently discloses key behavioral traits: that it is read-only, returns per-task detail (text, source file, line number, status, parsed metadata), and that vaultPath overrides the session-active vault. These go beyond the annotations (readOnlyHint, destructiveHint, idempotentHint) by explaining the vault-selection precedence and the utility of results. No contradiction with annotations; in fact, it reinforces them.
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 and front-loaded with the core action, then result content, then parameters, then context. It is a bit longer than minimal, but each sentence contributes: the read-only note, the alternative, and the vault scope are all useful. It avoids redundancy with the schema and stays focused. Slightly verbose but not wasteful.
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 10 parameters and no required ones, the description covers everything needed to call correctly: what it returns, how to filter, how to limit and order, and the vault selection behavior. It references the output schema implicitly by listing result fields, and points to related tools for further action. Without the output schema shown, the description still conveys the essential information. No missing context that would hinder an agent.
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 90%, so most parameters are already documented. The description adds marginal value by explaining the vaultPath override and noting that sortBy controls ordering and limit caps result count, but those are already in the schema. It does not introduce new syntax or semantics for the filter parameters beyond what the schema provides. Given high coverage, a baseline of 3 is appropriate; the description provides a slight increment.
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 (scan), resource (vault for Tasks-plugin-style markdown task lines), and filtering criteria (status, priority, due date range, recurrence, or tag). It distinguishes itself from siblings like tasks.stats by noting the difference in result granularity, and it references tasks.toggle/updateMetadata for further manipulation. The purpose is unambiguous and specific.
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 an alternative (tasks.stats) and the condition for choosing it ('For vault-wide counts without per-task detail'). It also clarifies the vault scope behavior (session-active vault unless vaultPath is passed, which always wins), giving clear context for when this tool is appropriate. No misleading guidance; the exclusions are 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?
Annotations already carry readOnlyHint, idempotentHint, and destructiveHint; the description adds value by stating 'Read-only' and, more importantly, disclosing the vault-scoping behavior — the tool operates on the session-active vault unless vaultPath is passed, and vaultPath always takes precedence. This precedence rule is real behavioral context not derivable from the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense paragraphs with no filler. The first sentence front-loads the full metric enumeration and defines overdue; the next sentence handles sibling routing; the second paragraph explains vault selection. Every sentence earns its place, with outputs first, alternatives second, and scoping semantics last.
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?
With an output schema present and safety traits covered by annotations, the description covers the remaining essentials: exact return-metric groups, sibling routing, and vault-resolution preconditions. Minor gaps — the precise scope of the 'per-priority breakdown' and the reference date for the horizons — are small enough not to prevent correct invocation.
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 0%, so the description carries the burden. It compensates by explaining what vaultPath does (overrides the session-active vault) and its precedence. It stops short of describing the expected path format, but for a single optional string parameter, the core semantics are clear.
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: 'Return aggregate task statistics for the whole vault' and enumerates the exact metric groups returned (total, incomplete, completed, overdue, upcoming-by-horizon, per-priority). It also defines 'overdue' inline ('due date passed and still incomplete') and differentiates from tasks.search, so an agent can distinguish it from its closest sibling without opening any schema.
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 to the alternative: 'Use tasks.search to get the individual task records', which tells the agent when this aggregate tool is not the right choice. It also provides operational context for vault resolution (session-active vault, vaultPath override with 'always wins' precedence). No when-not guidance is left to inference.
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?
Annotations already declare readOnlyHint and idempotentHint, and the description reinforces this with 'Read-only.' It adds real value beyond annotations: enumerates the reason values (session-selected/env-default/none), discloses the failure condition ('tools will fail until vault.select or an env var is set'), and explains the obsidianLiveInstance note. Consistent with annotations, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense, not terse, but every sentence earns its place: scope, reason semantics, failure mode, and workspace distinction are all load-bearing for correct use. Slightly heavy for a zero-param introspection call, but not padded.
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?
Completely adequate for a zero-parameter read-only tool. The description covers what is returned, the meaning of each reason value, the failure condition when nothing is configured, and the live-process caveat. Nothing an agent needs to call it correctly is missing.
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 tool has zero parameters and the schema is empty with 100% coverage, so the baseline is 4. The description compensates by documenting the return semantics (reason field values and obsidianLiveInstance note), which is more useful than parameter documentation for this introspection 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?
States a specific verb and resource: 'Return the vault that filesystem tools would resolve to right now, plus the full precedence chain.' The enumerated filesystem tool families (notes.*, tags.*, dataview.*) and the explicit contrast with vault.list/vault.select/vault.reset make its role unambiguous among 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?
Explains when the tool matters (to explain why a vault was picked) and clarifies the boundary with workspace.*/commands.* tools, which target the live process vault instead. It doesn't name an explicit alternative for when-not-to-use, but the live-vs-filesystem distinction is clear guidance.
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?
Annotations already declare readOnly, idempotent, and non-destructive, but the description adds substantial behavior: the merged/deduplicated source logic, default env var, discovery flag, 30s cache, refresh behavior, and the experimental obsidian-app caveat. It even names the item fields (source, isDefault, isActive, exists) so an agent understands the output shape despite the output schema existing separately.
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 information-dense but not bloated—it front-loads the core purpose, then details sources, cache, and the experimental note, ending with two concrete examples. Every sentence earns its place; the structure is slightly long but effective given the nuance required.
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 listing tool with a single optional parameter, the description fully covers behavior: source enumeration, merging rules, cache, refresh, and even a warning about the experimental source. With an output schema present and a code‑example that shows usage, an agent has everything needed to call it correctly. 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?
The schema covers the sole `refresh` parameter at 100%, describing its type and default. The description goes further by explaining why you'd set it to true (force a fresh scan when obsidian.json changed or new env vars added), connecting it to the cache behavior. This adds meaningful context 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 verb (List) and resource (every Obsidian vault kObsidian knows about), then gives concrete detail on three sources, merging, and deduplication. It is easily distinguishable from sibling vault tools (vault.current, vault.select, vault.reset) because it explicitly enumerates all known vaults rather than acting on a single 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 implies a clear use case—listing vaults for the LLM to flag stale or missing ones—and explains the refresh flag for rescanning. It doesn't explicitly say 'use vault.current when you need the active vault' but the context makes that obvious from the sibling names and the phrase 'every vault'.
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?
The description goes well beyond the annotations: it explains the source-preserving behavior, language-mismatch failure, fence exclusion, idempotent no-op effect, in-place destructive overwrite, and vault selection semantics. These details align with the idempotentHint and destructiveHint annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently organized: core behavior and constraints first, then vault targeting, then concrete examples. Every sentence earns its place, and the examples are compact yet informative.
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 six parameters and the existence of an output schema, the description covers all essential calling context: block selection, language guard, source format, vault resolution, idempotency, destructiveness, and failure behavior. An agent has enough information to invoke this tool correctly without additional documentation.
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 83%, so the schema already documents most parameters. The description adds value by clarifying that source must exclude fences, that language is a guard, that blockId takes precedence over index, and especially by documenting the vaultPath override semantics that the schema leaves bare. The examples further disambiguate realistic usage.
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 names a specific verb and resource: replace one fenced block's body, with explicit scope boundaries (fences, language tag, and neighboring content untouched). This clearly differentiates it from read-oriented siblings like blocks.list/blocks.read and whole-note tools like notes.edit.
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 operational context: how to locate the block via blockId or index, that language acts as a guard, and that the tool operates on the session-active vault unless vaultPath is supplied. It does not explicitly name alternatives or say when not to use this tool, but the context is strong enough for an agent to apply 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?
Annotations already state readOnlyHint, idempotentHint, and destructiveHint, so the description's 'Read-only' is redundant but not harmful. It adds valuable behavioral context about session-active vault resolution and the precedence of an explicit vaultPath, which is not derivable from 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?
Three tight sentences: operation, use case with alternative, and vault behavior. No filler, and the most important information 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?
Given the output schema exists and annotations cover safety, the description provides the essential context: graph-walking use case, full-graph alternative, and vault resolution rules. Nothing critical is missing for an agent to select and invoke this 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 covers nodeId and filePath with good descriptions, and the description fills the gap for vaultPath by explaining it overrides the session-active vault. This is meaningful added meaning beyond the schema for the undocumented parameter.
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 states a precise verb and resource: 'Return the incoming and outgoing edges of a single canvas node.' It clearly differentiates from canvas.parse, which handles full-graph parsing, and from links.connections, which likely deals with note links rather than canvas edges.
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 says when to use this tool ('to walk the canvas graph one node at a time without loading the full document') and names the alternative for full-graph parsing ('use canvas.parse'). It also clarifies the vault selection behavior with vaultPath taking precedence.
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?
Annotations already mark it as read-only and idempotent, but the description goes further: it discloses that the tool is a convenience wrapper, returns the same shape as dataview.query, requires specific plugins, and operates on the session-active vault unless vaultPath is provided. These are significant behavioral details not encoded in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: it states the core action, then usage guidance, then vault behavior. Every sentence adds value, no filler or repetition.
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 full schema coverage, the presence of an output schema, and rich annotations, the description covers all necessary aspects: purpose, usage, requirements, vault selection, and expected return shape. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage with clear descriptions for all four parameters (e.g., tag accepts leading `#`, sortBy is a DQL clause body). The description does not add further parameter-specific detail; it only restates the optional clauses in prose, so a 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 is a wrapper around `LIST FROM #tag` and explicitly contrasts it with raw DQL ('Use this instead of authoring raw DQL when filtering by a single tag'), making its purpose and differentiation from sibling tools like dataview.query 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 explicit when-to-use guidance ('when filtering by a single tag') and names the alternative (raw DQL). It also adds prerequisites (Dataview and Local REST API plugins) and explains vault selection behavior, leaving no ambiguity about when to call it.
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?
It discloses important behaviors beyond the annotations: missing destination columns are created automatically, card matching for move/toggle is verbatim after checkbox, the result is a {changed, target, summary, ...} mutation envelope, and the tool operates on the session-active vault unless vaultPath is supplied. This adds substantial context that the annotations alone do not convey.
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 longer than average, but every part earns its place: a clear op matrix, side-effect disclosure, vault routing rule, and concrete examples for each op variant. It is front-loaded with the core purpose and avoids 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 complete for a complex oneOf-based mutation tool. It covers op selection, required versus optional fields, automatic column creation, vault selection, and the return envelope shape. Since an output schema exists, not repeating full return details is acceptable.
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 already documents all parameters with high coverage, so the baseline is 3. The description adds value by grouping required parameters by op, explaining positional behavior with 'start'/'end', noting automatic column creation, and providing realistic examples that make the discriminated union much easier to invoke correctly.
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 action set ('Add, move, or toggle') and names the resource ('a card on a Kanban board'), then explains what each op does. This clearly distinguishes the mutation tool from read-only siblings like kanban.parse and kanban.stats, even though the tool's title is somewhat generic.
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 explicit per-op usage rules: add requires columnName/cardText, move requires fromColumn/toColumn, and toggle uses optional columnName to scope the search. It also clarifies vault routing and the precedence of vaultPath. It does not explicitly name alternative sibling tools to avoid for read-only operations, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description's 'Read-only' adds no new safety info. However, it adds valuable behavioral context beyond annotations: compatibility with the obsidian-kanban plugin format and the session-active vault behavior with vaultPath override. This improves the agent's understanding of execution context.
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 tight and front-loaded. The first sentence states the core purpose; the next sentences provide usage guidance, an explicit alternative, and the vault behavior. Every sentence earns its place with no redundant or vague phrasing.
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 output schema exists and annotations cover safety, the description is complete. It explains what the tool does, when to use it, which format is supported, and how vault selection works. No missing critical context for an agent to invoke it 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 coverage is 50%: filePath is documented in the schema, vaultPath is not. The description compensates for vaultPath by explaining it overrides the session-active vault, giving that parameter meaningful semantics beyond its bare type. It could be stronger with path format details, but the description adds real value.
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: 'Parse a markdown Kanban board file into its column/card structure.' It clearly distinguishes itself from kanban.stats by explaining that this tool provides the full board content, not just counts.
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 states when to use the tool: 'Use this when you need the full board content.' It also names the alternative for different needs: 'For completion counts and ratios instead of the full card list, use kanban.stats.' This leaves no ambiguity about 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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds a meaningful behavioral detail: operation on the session-active vault unless vaultPath is passed, and that vaultPath always wins. This goes beyond the annotations and clarifies routing behavior. No contradiction, though it could also mention error conditions or performance implications.
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 terse paragraphs, no fluff. The purpose and metrics are front-loaded, and the vault behavior is placed in a separate sentence. Every sentence adds novel information; nothing is redundant with 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?
An output schema exists, so return format is provided. The description covers purpose, usage context, alternatives, and vault routing. With only two parameters and rich annotations for safety, this is fully complete for agent decision-making.
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 50% — filePath has a description but vaultPath does not. The description compensates by explaining vaultPath's role and precedence ('unless an explicit vaultPath argument is passed, which always wins'). It does not add format details, but the essential semantics are covered.
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 states a specific verb ('Summarise') and resource (Kanban board), and enumerates the exact metrics (total cards, completed, incomplete, completion rate, per-column breakdown). It also distinguishes from kanban.parse by specifying it does not give card content, so the purpose is 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?
Explicit guidance: 'Use this for dashboards or progress checks where you don't need each card's full text' and 'Use kanban.parse when you need the actual card content.' Also clarifies the active-vault vs vaultPath precedence, leaving no ambiguity about when to call this vs alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description's 'Read-only' is consistent. The description adds useful behavioral context beyond annotations: it aggregates across the whole vault, computes ratios and densities, and respects the session-active vault unless vaultPath is supplied. This is meaningful but not exhaustive; the output schema covers return details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with the core purpose and output metrics in the first sentence. The second sentence gives routing guidance, and the third handles vault scoping. 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?
Given the tool's simple optional-parameter shape and the presence of an output schema, the description covers everything needed: what it returns, when to use it, sibling alternatives, read-only behavior, and vault targeting. No critical operational detail is missing.
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 0%, so the description must carry the burden for the single optional vaultPath parameter. It does: vaultPath is explained as an explicit override that 'always wins' over the session-active vault. It doesn't specify path format, but the parameter name and contextual explanation make the semantics clear enough for correct use.
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 ('Summarise') and resource ('link health for the whole vault'), then enumerates the exact metrics returned. It also distinguishes itself from the sibling tools links.broken, links.orphaned, and links.hubs by explicitly framing this as an aggregate dashboard check rather than per-item listing.
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 it ('as a dashboard check') and names the alternatives for full per-item lists. It also clarifies vault selection semantics, including how vaultPath overrides the session-active vault, leaving no ambiguity about which vault is targeted.
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?
Beyond the annotations (destructiveHint=true, idempotentHint=true), the description discloses critical behaviors: it overwrites/replaces existing content at the destination, fails when the source does not exist, and rewrites wiki/markdown links vault-wide when updateLinks is true. It also explains the vaultPath override semantics. This adds substantial operational detail that annotations alone do not convey.
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 tight and front-loaded: the first sentence states the core purpose, then details about kind, updateLinks, destructiveness, failure condition, and vault selection follow. Every sentence adds value with no fluff or repetition. It is well-structured for an agent to quickly grasp the essential information.
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 (moving files/folders with link rewriting and destructive behavior) and the presence of an output schema, the description covers all necessary aspects: what it moves, how it handles links, destructive consequences, failure conditions, and vault selection. Nothing essential is missing for an agent to call it 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 description coverage is 100% (each parameter has a description), so the baseline is 3. The description goes further by explaining the default behavior of updateLinks (true) and how vaultPath overrides the session-active vault, which is not fully captured in the schema. This added context 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 the verb ('Move') and resource ('a note or folder to a new path'), and immediately distinguishes the two kinds ('note' vs 'folder' with 'moves every note beneath it'). It also explains link rewriting, making it distinct from sibling tools like notes.delete or notes.create. No tautology; the description adds specificity beyond the title.
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: it operates on the session-active vault unless vaultPath is passed, and it is destructive. However, it does not explicitly name alternative tools or state conditions like 'use notes.move instead of notes.delete when you need to relocate', so the 'when not to use' is only implied. The vault selection guidance is helpful, but the lack of explicit exclusions prevents a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description restates read-only, which is redundant. It adds meaningful behavior beyond annotations: query filter syntax, default context length, and the session-active vault precedence rule.
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?
Front-loaded with the main purpose, then a compact set of filter semantics, a default, and a routing pointer. The repeated 'Read-only' is minor given annotations, but the definition is appropriately sized and all remaining sentences add information.
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 doesn't need to explain return shape. It covers the active-vault behavior, filter forms, default context length, and sibling alternatives, making the tool callable correctly in context.
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 covers `query` and `contextLength` but leaves `vaultPath` undocumented; the description fills that gap by explaining that it selects a vault and always wins over the active vault. It also adds concrete syntax for `tag:` and `path:` filters and the default context length, adding 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?
States a specific verb and resource: 'Full-text search across every note in the vault.' It also singles out `tags.search` and `notes.list` as alternatives, so an agent can distinguish it from sibling search/list 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?
Gives explicit routing guidance: for pure tag or date filtering, `tags.search` and `notes.list` are faster, implying notes.search is for full-text search. It also specifies that it operates on the session-active vault and that `vaultPath` overrides the active vault.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior. The description adds value beyond those by disclosing that the tool scans every .md file and by explaining how the target vault is resolved. This is meaningful behavioral context that structured annotations do not convey.
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 carry exactly the necessary information: what the tool returns, a pointer to the per-note alternative, and how the vault target is resolved. The most important content is front-loaded and there is no 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?
With an output schema present to document return structure, the description fully covers purpose, scope, alternatives, and parameter behavior. The combination of annotations, output schema, and description leaves no critical gap for an agent deciding whether and how to invoke this 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 description coverage is 0%, but the description compensates by explaining that the optional vaultPath is an explicit override that 'always wins' over the session-active vault. This gives the single parameter clear operational meaning, though it could be improved with path format details.
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 ('Return') and a clearly bounded resource ('aggregate statistics for the whole vault'), then enumerates the exact metrics returned. It also explicitly contrasts itself with per-note statistics via notes.read, making its scope unambiguous relative to 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit when-to-use alternative: 'For per-note statistics use notes.read with include: ['stats']'. It also clarifies operational context by explaining the session-active vault behavior and that an explicit vaultPath overrides it, referencing vault.current and vault.select for 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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description confirms 'Read-only; zero side effects.' It adds value beyond annotations by specifying exactly which runtime details are returned, which is useful behavioral context.
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 short, information-dense sentences. The first states what is returned; the second gives usage guidance. No redundant phrasing; every word 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?
For a zero-parameter, read-only health-check tool with an output schema, the description covers everything an agent needs: the exact data returned, the use case, and the safety profile. Nothing is missing.
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 zero parameters, so the baseline is 4. The description doesn't need to explain any parameters, and the empty schema is fully covered. No additional parameter semantics are necessary.
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 states a specific verb ('Return'), a precise resource ('the running kObsidian server's package name, semver version, host runtime, and runtime version'), and distinguishes itself from all siblings. There is 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?
Explicitly states when to use the tool: 'Use this as a health-check or to confirm which server build a client is talking to.' This provides clear context and intent, leaving no inference required.
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?
The description goes well beyond the annotations: it confirms and elaborates idempotency ('repeated calls with the same op and tags converge'), discloses that leading '#' is stripped, specifies that only the frontmatter block is modified (leaving inline tags untouched), and details the exact behavior of each operation. It also states the return object format. All of this adds behavioral context that annotations alone do not provide.
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 with the core purpose, followed by operation semantics, vault behavior, and concrete examples. It is detailed but every sentence earns its place—there is no filler or redundancy. The examples are minimal and directly illustrate the key operations.
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 four parameters, multiple operations, and vault-selection logic, the description is remarkably complete. It covers the return value, examples for typical use cases, idempotency, and scope limitations. Nothing an agent needs to call the tool correctly is missing.
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 already documents `op`, `path`, and `tags` with detailed descriptions, and the schema coverage is 75%. The description adds meaning to the undocumented `vaultPath` parameter by clarifying that it overrides the session active vault, and it reinforces the behavior of `merge` as an alias for `add`. The examples further illustrate parameter usage, so the description compensates for the missing schema coverage on `vaultPath`.
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 precise statement of purpose: 'Mutate the frontmatter `tags` list of a single note.' This gives a clear verb (mutate), resource (frontmatter tags), and scope (single note), and it immediately distinguishes this from read-only sibling tools like `tags.search` and `tags.list`. The supported operations (add, remove, replace, merge) are explicitly enumerated, 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 explains how vault selection works ('Operates on the session-active vault ... unless an explicit `vaultPath` is passed') and that it only touches frontmatter, implying that inline tag editing would require a different tool. However, it does not explicitly name alternative tools for those cases, and it does not state when to use this over other tag-related tools like `tags.search`. The guidance is present but implicit rather than explicit.
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?
While annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds valuable behavioral detail beyond those: it states 'Read-only.' (redundant but harmless), discloses the output structure `{file, absolutePath, tagLocations: {frontmatter, inline}}` so callers know how to interpret results, and details the leading-# stripping behavior and vault selection precedence. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short paragraphs with front-loaded purpose, followed by the sibling alternative and vault-context behavior. Every sentence contributes: purpose, output shape, read-only note, alternative, and vault selection. No fluff or repetition beyond the harmless 'Read-only' echo of the annotation.
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 an output schema (confirmed by context signals), the description need not detail the full return type, but it still summarizes the result fields. It covers functional scope, usage boundaries, parameter semantics, and operational context (vault selection). An agent has everything needed to invoke it correctly without consulting additional sources.
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 50%: `tag` parameter is described in the schema, but `vaultPath` has no description. The description compensates by clarifying that `vaultPath` overrides the session-active vault setup. For `tag`, the description mirrors the schema's stripping note but adds no new semantics; still, the compensation for `vaultPath` brings the effective clarity above baseline.
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 'Find' and the resource 'every note in the vault that contains a given tag' including both frontmatter and inline locations. It explicitly differentiates from the sibling `tags.analyze` by naming it as the alternative for single-note tag analysis, leaving no ambiguity about scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use guidance: vault-wide tag search. It also gives a direct exclusion and alternative: 'For analyzing tags of ONE specific note (not a vault-wide search), use `tags.analyze` instead.' Additionally, it explains the vault selection behavior (session-active vault or explicit `vaultPath`), which is essential context for correct invocation.
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?
Adds essential behavioral details beyond annotations: 'UI-only: does not modify file contents', 'No-op when no file is active', and 'errors when the Local REST API plugin is unreachable'. It also specifies the exact return shape { ok: true, mode: 'edit' | 'preview' }. These details go well beyond the minimal readOnlyHint false, openWorldHint true in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action and then efficiently adds caveats (UI-only, no-op, error), a use case, and the vault.select clarification. Every sentence adds value, and the example is minimal. It is concise yet comprehensive for a tool of this simplicity.
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 no-op behavior, error conditions, UI-only nature, target vault (via Local REST API), and the return structure. The output schema is present but the description already explains the return. The only minor omission is whether it works on non-markdown files, but that's likely implicit in Obsidian's context.
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 zero parameters, and the schema coverage is 100% (empty properties). The description confirms 'Takes no arguments' and explains that it always toggles the current mode. Since there are no parameters to describe, the baseline for 0 params is 4, and the description adequately covers this.
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 'Flip the active file in Obsidian between edit (source) mode and preview (reading) mode.' It specifies the action, target, and scope. It also distinguishes itself from vault-related tools by explicitly noting it is not affected by vault.select, which prevents confusion among 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?
Provides a concrete use case: 'Useful when an agent has finished a multi-step edit and wants the user to see the rendered result.' It also indicates when it's a no-op (no active file) and warns about plugin unavailability. While it doesn't list alternative tools, the context is clear enough for an agent to decide when to invoke it.
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?
Beyond the readOnly and idempotent annotations, the description discloses key behaviors: blockId takes precedence over index, index defaults to 0 within the language group, failure returns not_found, and vault resolution prefers vaultPath over the session-active vault. This is substantial behavioral context that cannot be inferred from annotations 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?
The description is front-loaded with the core action and then adds only high-value details: locator rules, language requirement, failure behavior, and vault scoping. Every sentence contributes operational guidance, and the examples for metadata (Mermaid directives, Dataview DQL parts) clarify the abstraction.
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 an output schema exists and annotations cover safety, the description needs only to explain selection, error behavior, and vault scoping — all of which it does. Nothing required for a correct call is missing; the parameter semantics, failure mode, and vault override are all explicit.
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 coverage is already 80%, the description adds meaningful semantics: blockId is 'stable' and 'takes precedence,' index is '0-based within the language group' with a default of 0, language is required for parser dispatch, and vaultPath 'always wins.' It fully compensates for the undocumented vaultPath parameter and enriches the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Read one fenced block's source and language-specific metadata,' which is a specific verb+resource statement. It clearly differentiates this from sibling tools like blocks.list (reads one vs. lists) and blocks.update (read vs. modify), so an agent can identify the right operation without inspecting other 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 provides clear usage context: locate by blockId (preferred) or index, language is required, and vaultPath overrides the active vault. It does not explicitly name alternatives like blocks.list for finding blocks or blocks.update for modifying them, so it stops short of full when/when-not guidance.
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?
The description goes beyond the annotations by explaining exactly what each op does, including that remove 'deletes every occurrence' of a key, and explicitly discloses idempotence and vault selection behavior. No contradiction with annotations is apparent: idempotentHint matches, and the scoped field-write semantics are compatible with destructiveHint=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?
The description is front-loaded with the core purpose, followed by compact parameter semantics, one behavioral caveat (idempotence/vault), and two worked examples. No sentence is filler; the length is justified by the two-branch op and several interacting options.
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 a discriminated union, multiple enums, and optional interactions, the description plus schema is complete enough to call it correctly: it covers both ops, placement, syntax, scope, vault selection, and default behavior for insertAt. The output schema exists, so return values are not the description's burden.
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?
Even with 100% schema coverage, the description adds substantial meaning: it defines how syntaxType renders the field, how insertAt and lineNumber interact, how scope restricts removal, and that vaultPath overrides the active vault. The two JSON examples tie the parameters together into valid call patterns.
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 precise verb+resource: 'Insert or remove a Dataview field in a single note.' It then explains the two op modes and rendering options, making the tool's function unmistakable and distinct from read-only siblings like dataview.fields.read.
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 establishes when the tool is appropriate: whenever a single note's Dataview field needs to be added or removed, and it explains vault targeting (session-active vault versus explicit vaultPath). It does not explicitly name sibling alternatives or state when not to use it, so it falls just short of full routing guidance.
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?
Annotations already declare destructive and idempotent behavior, and the description adds valuable context: slides are replaced without touching neighbors, unspecified frontmatter fields are preserved, `null` unsets a field, and identical re-runs are a no-op on file contents. This goes beyond the annotation flags and gives an agent a precise side-effect model.
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 behavior, then gives branch-specific semantics and closes with two illustrative examples. Despite its length, every sentence earns its place, and the detail is justified by the oneOf/two-mode design.
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 mutating tool with two distinct modes and an output schema, the description covers selection, side effects, vault routing, and example payloads. Nothing required to select or invoke the correct branch 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?
The schema documents `source`, `fields`, and `part`, but the description adds meaning not present in the schema: slide lookup by `slideId` or `index`, the precedence behavior of `vaultPath`, and the merge/unset semantics for frontmatter. The examples provide concrete payload shapes for both branches, making invocation unambiguous.
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 ('Mutate') and resource ('a Marp deck in place'), then distinguishes the two `part` modes: slide-body replacement and frontmatter merge. The tool is clearly separable from its read sibling and from general note-editing tools by the Marp deck scope and the named mutation targets.
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 clearly explains when to use the `slide` branch versus the `frontmatter` branch, and how vault targeting is resolved, including the rule that an explicit `vaultPath` overrides the active vault. It does not explicitly state when to use an alternative like `notes.edit` or `marp.read` instead, so it stops short of full exclusion guidance.
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?
The description richly discloses behavior beyond the annotations: `ifExists` semantics (`error`, `replace`, `skip`), idempotent folder creation, automatic creation of intermediate folders, and explicit precedence of `vaultPath` over the session-active vault. It also notes the return is a standard mutation envelope, which is useful given the annotations do not describe side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently organized: a lead sentence with the core operation, then mode-specific behavior, then operational context, then examples. Every section adds information, and the examples are compact and illustrative without padding.
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 discriminated-union mutation tool, the description covers all necessary decision points: note vs. folder, collision handling, path behavior, vault selection, and idempotency. The output schema exists, so the vague 'standard mutation envelope' reference is acceptable and does not leave a critical gap.
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 the schema already documents parameters well, the description adds meaningful cross-parameter semantics: how `kind` switches the object shape, how `ifExists` interacts with existing notes, how folder creation behaves idempotently, and how `vaultPath` overrides the active vault. The two concrete JSON examples further clarify expected usage.
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 states a specific action — 'Create a new note or folder in the vault' — and clearly distinguishes the two modes via `kind:'note'` and `kind:'folder'`. It also differentiates from siblings like `notes.edit`, `notes.move`, and `notes.delete` by naming creation as the operation and specifying the resulting artifacts (markdown files or directories).
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 operational context: it explains that the tool operates on the session-active vault unless `vaultPath` is passed, and the schema-level note says to use `kind:'folder'` when the target should be a directory rather than a file. It does not explicitly contrast this tool with sibling creation-like tools (e.g., `tasks.create`, `templates.use`), so it stops short of full alternative routing.
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?
Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description adds crucial behavioral detail: 'replace mode is idempotent-destructive; the others are additive,' plus failure conditions and vault precedence rules. This is rich context that annotations don't provide.
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: purpose, mode semantics, failure condition, vault behavior, and three illustrative examples. It's front-loaded with the core action, and the structured examples make the modes unambiguous. No fluff.
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 tool is complex (five modes, two anchor types, vault selection), and the description fully covers all required knowledge: mode differences, anchor syntax, default vault behavior, and error scenarios. With an output schema present, return values need no explanation. Nothing an agent needs 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?
Despite 100% schema description coverage, the description supplements the schema with examples illustrating the exact format for anchor (no leading '#' for headings, no '^' for blocks), clarifies placement for prepend ('after frontmatter'), and demonstrates real-world usage. This goes beyond what the schema's oneOf branches state.
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 ('mutate') with a clear resource ('existing note') and enumerates the distinct modes, which immediately differentiates it from notes.create, notes.delete, and other note-related siblings. It's specific enough for an agent to know exactly what this 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?
Explicitly states when NOT to use it ('Fails if the note does not exist — use notes.create first') and clarifies vault selection ('Operates on the session-active vault... unless explicit vaultPath'). It doesn't contrast this with blocks.update or blocks.read, which might be plausible alternatives for fine-grained edits, but the guidance given is clear 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?
Beyond the readOnlyHint and idempotentHint annotations, the description discloses the `not_found` error on missing paths and explains the vault selection behavior (session-active vault vs. explicit vaultPath). This adds meaningful operational context that the annotations do not cover.
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 compact and well-organized. The first sentence states the purpose and options; the second gives practical usage guidance; the third clarifies vault context. Every sentence earns its place without redundant information.
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 read tool with an output schema, the description covers the essential aspects: return sections, error behavior, vault selection, and parameter semantics. No critical information for correct invocation 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?
The description enriches the `include` parameter with explanation of what each value returns and the default, and clarifies `vaultPath` precedence. Since schema coverage is 67%, the description compensates for the undocumented `vaultPath` and adds nuance beyond the schema's enum for `include`.
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 a note and returns selected sections (body, metadata, stats). It specifies the resource (note) and action (read), and the mention of the `include` parameter distinguishes it from listing/searching tools. This 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?
It gives clear context for when to use this tool (reading a specific note by path) and even provides guidance on using `include` to request stats only. However, it does not explicitly name alternative sibling tools or state when not to use it, so it falls short of the 'explicit when/when-not/alternatives' criterion.
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?
Although annotations already declare readOnly/idempotent/non-destructive, the description adds behavioral nuance: tags from frontmatter and inline are combined, includeCounts changes the returned item shape, sortBy=count requires includeCounts, and vaultPath overrides session-active vault. This goes well beyond the structured 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?
The description is front-loaded and compact, with options and routing in the first paragraph and vault behavior in the second. The standalone 'Read-only' sentence is redundant with annotations, but it does not undermine clarity.
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 and annotations covering safety, the description supplies the remaining needed context: parameter dependencies, vault scoping behavior, and the sibling for a different use case. Nothing essential for calling the tool correctly is missing.
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 covers sortBy and includeCounts well, but vaultPath is undocumented in the schema. The description compensates by explaining that vaultPath always overrides the session-active vault. Minor gap remains on the exact expected vaultPath 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?
Description starts with a specific action and object: 'List every unique tag used across the vault (frontmatter and inline combined).' It clearly defines scope and uniqueness, and explicitly contrasts with tags.search, so an agent can distinguish this tool from its closest sibling.
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 an explicit routing rule: for finding notes carrying a specific tag, use tags.search. It also clarifies the active-vault context and the vaultPath override, so when to invoke this tool vs alternatives is unambiguous.
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?
Annotations are minimal (all false), so the description carries the full burden and delivers richly. It discloses the state-mutating nature (sets session selection), the precedence chain behavior, that OBSIDIAN_VAULT_PATH is never filtered by KOBSIDIAN_VAULT_ALLOW/DENY gating, the non-effect on the live Obsidian process, and the shared-selection caveat for HTTP deployments. No contradiction with annotations — readOnlyHint=false aligns with this being a state-setter.
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?
Purpose is front-loaded in the first sentence, then scoping and behavioral notes follow, then examples. The description is long but information-dense — the precedence, gating, workspace-scope, and HTTP notes each earn their sentences. The three concrete JSON examples add real clarity. Slightly verbose for a simple setter, but nothing is wasted.
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?
Complete coverage for a targeting/selection tool: purpose, identifier selection rules, precedence, env-var interaction, operator-gating behavior, scope exclusions, HTTP deployment caveat, and worked examples. Combined with the output schema, an agent has everything needed to invoke this correctly without further lookup.
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% and each parameter is already documented with mutual-exclusivity. The description adds genuine value beyond the schema: name matching is case-insensitive, path need not appear in vault.list (enabling fresh-vault initialization), and the interaction of each identifier with the precedence chain. It enriches but doesn't merely duplicate 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 opens with a specific verb+resource: 'Set the session-active vault for subsequent filesystem tool calls.' It clearly differentiates from sibling vault tools (vault.list, vault.current, vault.reset) by explaining the selection mechanism with three distinct identifiers. The sibling distinction is precisely stated.
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 each parameter: `id` for stable lookups, `name` for case-insensitive matching, `path` for ad-hoc/fresh vaults to initialize. The precedence chain is fully documented (per-call vaultPath > session selection > OBSIDIAN_VAULT_PATH), and it specifies exclusions — workspace.*/commands.* tools remain tied to OBSIDIAN_API_URL, and HTTP deployments should pass vaultPath per call. Nothing is left to inference.
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 burden of behavioral disclosure. It details what happens on both existing pages (section insertion, sources list update, `updated:` frontmatter bumped to today, summary/aliases set) and new pages (canonical frontmatter, entityKind requirement). It also explains the vault override hierarchy and the rendering of citations and quotes. Nothing is left opaque.
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 longer than minimal but every sentence carries information: purpose, conditional behavior, sibling distinction, vault handling, and two illustrative examples. It is front-loaded with the core action and usage guidance. Slightly verbose relative to the high-calibration example, but appropriate for an 11-parameter tool with nuanced merge semantics.
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 of this complexity, the description covers the full decision space: when to use vs. alternatives, required/optional parameters, defaults, side effects on frontmatter, vault overrides, and entityKind constraints. The examples make the expected JSON shape concrete. Nothing an agent needs to invoke it correctly is missing.
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 the baseline is 3. The description adds meaningful semantics beyond the schema: it explains that `citationSource` pushes onto the page's `sources:` frontmatter list, that `heading` defaults to a timestamped value, and how `vaultPath` overrides the session-active vault. The two examples also illustrate realistic parameter combinations, adding practical nuance.
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 precise action verb ('Add a cited section') and names the exact resources (`Concepts/` or `Entities/` pages) plus the conditional create behavior. It distinguishes itself from the sibling `wiki.ingest` by stating that this tool targets existing pages, whereas ingest handles new sources. That makes selection 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?
Explicit when-to-use guidance is present: 'Use this when filing a follow-up onto a known page; use `wiki.ingest` instead when bringing in a NEW source'. It also describes the vault selection behavior and notes when `entityKind` is required. This is more than adequate routing.
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?
Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses three behavioral traits: the no-op behavior on an empty stack, the hard dependency on the Local REST API plugin, and the fact that the tool always targets the currently open vault rather than any vault selected via vault.select. This usefully enriches the annotation data.
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 compact (~65 words), front-loads the core purpose and analogy, then packs direction semantics, no-op behavior, plugin requirement, and the vault.select caveat into two tight paragraphs. No sentence is redundant.
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 single-parameter tool with an output schema and annotations, the description covers the critical execution context: plugin requirement, target vault, stack-empty behavior, and independence from vault.select. An agent has everything needed 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?
Although the schema already documents `direction` with an enum and 100% coverage, the description adds precise semantics for each enum value ('back' = back one step, 'forward' = forward one step) and clarifies the no-op edge case, going beyond the schema's terse 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?
Description uses a specific verb ('Navigate') and resource ('Obsidian back/forward file history') and anchors it to an everyday UI analogy ('like the arrow buttons in the top-left'). It is clearly distinct from sibling workspace tools like workspace.openFile and vault.select, leaving no ambiguity about scope.
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 states the exact invocation semantics (`direction:'back'` = back one step; `direction:'forward'` = forward one step) and the no-op condition when the stack is empty. It explicitly cautions that vault.select does not affect this tool, which prevents a likely misuse, though it doesn't enumerate broader alternative tools.
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?
Annotations already carry readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: it requires the Local REST API plugin, targets the currently open vault, and is unaffected by vault.select. These are non-obvious traits an agent needs to know and are not present in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tight paragraphs. The first sentence delivers the core action, then each subsequent sentence adds necessary behavior, usage, or routing context. There is no redundant filler, and the most important facts (purpose, query behavior, read-only, usage) are 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?
For a simple listing tool with one optional parameter and an output schema, the description is complete. It covers purpose, query semantics, read-only safety, plugin dependency, vault targeting, and routing independence. Nothing essential for an agent to call it correctly is missing.
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 fully covers the query parameter (100% coverage), so the baseline is 3. The description adds specific detail: case-insensitive substring matching and that it returns both built-in and plugin-provided commands, which enriches meaning beyond the schema's minimal 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 verb 'List' and the resource 'Obsidian commands', and explains behavior with and without the query parameter. It distinguishes itself from siblings like commands.execute by explicitly stating it is for discovering command ids before executing, making its purpose 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?
It explicitly says 'Use this to discover command ids before calling commands.execute', giving a clear when-to-use scenario and differentiating from the primary sibling. It also notes it is read-only and not affected by vault.select, which helps an agent decide when to invoke it.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds meaningful behavior beyond that: the exact semantics of `extract` (combining page, list-item, and task-line fields) and `search` (coercion via `valueType`, scope restrictions). It also discloses the vault selection rule (`vaultPath` always wins), which is not derivable from the schema 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?
The description is information-dense but logically structured: it opens with the core purpose, then details each operation, then addresses read-only status and vault selection. Every sentence earns its place—no filler or 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 tool's moderate complexity (two operation modes, optional parameters), the description covers all necessary invocation details: the meaning of both ops, the role of `scope`, the vault selection mechanism, and the pointer to the write counterpart. An output schema exists, so return-value documentation is not needed here. Nothing essential is missing.
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% and the schema itself provides descriptions for `key`, `scope`, and `valueType`, so the parameters are well-documented. The description adds value by explaining how parameters interact across the two `op` variants (e.g., `extract` requires `filePath`, `search` requires `key` and optional `value`/`valueType`). This goes beyond the schema's per-field 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 resource (Dataview fields) and the two distinct operations (`extract` and `search`) with precise scoping. It differentiates from the sibling `dataview.fields.write` by explicitly labeling itself read-only, so an agent can immediately tell which tool handles 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?
The description gives a direct pointer to the alternative (`For mutating fields, use dataview.fields.write`) and explains when to use each operation: `extract` for a single note, `search` for whole-vault matching. It also clarifies the `vaultPath` precedence rule, which is essential for correct invocation in multi-vault sessions.
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?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds meaningful behavioral context: it supports both wiki-style and markdown-style links, describes the includeContext/contextLength snippet behavior, and explains vault resolution precedence. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight paragraphs with the core purpose front-loaded. Each sentence adds useful routing or behavioral information; only 'Read-only.' slightly duplicates the annotation, but it is brief and does not hurt clarity.
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 output schema exists and annotations cover safety, the description covers purpose, alternatives, vault behavior, and parameter semantics. An agent has everything needed to decide when to use this tool and how to invoke it 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 covers path, contextLength, and includeContext, while the description adds the missing meaning of vaultPath ('explicit vaultPath argument ... always wins') and clarifies how includeContext and contextLength interact. This goes beyond the schema, though a touch more detail on contextLength's default could strengthen it.
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 and resource: 'Find every note that links TO a target note (inbound references).' It clearly differentiates from the links.outgoing sibling, so an agent can identify the tool's purpose without opening the schema.
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 the alternative for outbound links ('use links.outgoing') and explains when an explicit vaultPath wins over the active vault. It also points to vault.current and vault.select for vault selection, making usage conditions concrete.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds meaningful behavioral context beyond those: performance cost, return shape, and vault-scoping semantics. The 'Read-only' statement is consistent with the annotations, so there is 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 compact and every sentence earns its place: graph definition, return shape, performance guidance, read-only confirmation, and vault selection. The most important scoping and routing information 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 provides enough information for an agent to call the tool correctly: what the output contains, when to avoid it, how vault context is resolved, and how vaultPath affects behavior. An output schema exists, so detailed return typing is not the description's burden.
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 only parameter, vaultPath, has no schema description (0% coverage), but the description compensates by explaining when it applies and that it overrides the session-active vault. It does not specify path format or expected values, leaving a small gap, but the core meaning is communicated.
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 states a specific verb and resource ('Build a full vault link graph'), defines the exact graph model (nodes for notes, directed edges for outbound links), and clearly differentiates itself from targeted siblings like links.backlinks and links.outgoing. An agent can immediately understand what this tool does and how it differs.
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 warns that the tool is expensive for large vaults and recommends alternatives ('prefer links.backlinks, links.outgoing, or links.connections for targeted queries'). It also clarifies the active-vault behavior and that an explicit vaultPath overrides it, giving clear selection and invocation guidance.
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?
Descriptions adds meaningful behavioral context beyond the annotations: it discloses that both wiki-style and markdown-style links are extracted, that checkValidity adds a valid flag based on path resolution in the vault, and that vaultPath overrides the session-active vault. It also confirms the read-only nature, consistent with readOnlyHint and idempotentHint. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured. Every sentence serves a purpose: purpose, validity flag behavior, read-only confirmation, sibling alternative, and vault scoping. It front-loads the main function and keeps supporting details 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?
The description is complete for a tool with an output schema that already explains return values. It details the link extraction scope, validity flag semantics, vault behavior, and explicit alternative. The references to vault.current and vault.select provide useful context without being excessive.
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 only 33% (only checkValidity has a description). The description compensates by explaining vaultPath (overrides session vault) and checkValidity (adds valid flag). The path parameter is not explicitly described, but it's implied as the note from which links are extracted. The added semantics cover two of three parameters well, though path could have been more explicit.
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 'Extract' and the resource 'links FROM a note', specifying both wiki-style and markdown-style link formats. It explicitly distinguishes itself from the sibling 'links.backlinks' by naming the alternative and its purpose, so an agent can readily tell them apart.
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 usage guidance: 'For inbound references (what points AT the note), use links.backlinks.' It also explains the vault scoping rule (session-active vault vs explicit vaultPath) and which argument wins. This leaves no ambiguity about when to use this tool versus 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?
Description discloses that the operation is destructive, replacing the existing `index.md` body wholesale and losing hand-edits, which complements the destructiveHint and idempotentHint annotations. It also adds useful behavioral context about grouping, sorting, and vault resolution beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with purpose first, then side effects, usage guidance, vault behavior, and minimal examples. Every section earns its place without unnecessary 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 destructive rebuild tool, this covers all essential operational context: target file, scan sources, side effects, when to use, alternatives, and vault selection. The output schema is present, so return-value details are not needed in the description.
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 already covers all three parameters with descriptions, so the baseline is 3. The description adds value by explaining that `vaultPath` always wins over the active vault and by demonstrating `includeCounts` behavior with concrete examples.
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 and resource: Regenerate `wiki/index.md` from a fresh scan of `Sources/`, `Concepts/`, and `Entities/`. It clearly distinguishes this full rebuild from incremental tools like `wiki.ingest` and from linting with `wiki.lint`. 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?
Explicitly says when to use: after bulk-creating pages outside the wiki tools, or as the cleanup step after `wiki.lint` reports `indexMismatch`. It also names the preferred alternative for incremental upkeep (`wiki.ingest`) and clarifies the vault selection behavior with `vaultPath` precedence.
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?
Beyond the idempotentHint annotation, the description details exactly what happens: existing files are preserved, folders are never deleted, and force:true re-seeds specific files. It discloses the return shape ({ created, skipped }) and the resolution order for the wiki location. This is rich behavioral context that goes well beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: purpose, idempotency, return value, resolution order, vault selection, and examples. It is detailed but every sentence contributes useful information. The two examples cover the main use cases (first-time scaffold and forced re-seed) without being repetitive.
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 3 optional parameters, no required input, and an idempotent, non-destructive behavior, the description covers everything an agent needs: what gets created, what force does, what is returned, how the target vault is determined, and that it should be run before other wiki.* tools. No critical information is missing.
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 all parameters are documented in the schema. The description adds extra meaning by explaining the precedence order (wikiRoot arg → KOBSIDIAN_WIKI_ROOT env → wiki/) and that vaultPath always wins over the session-active vault. This synergy between parameters is not in the schema, adding genuine value.
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: 'Scaffold the LLM-Wiki layout under the vault: creates Sources/, Concepts/, Entities/ folders and seeds index.md, log.md, and wiki-schema.md'. This clearly states what the tool does. It also distinguishes itself from siblings by noting 'Use this once per vault before calling any other wiki.* tool', making its unique role 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 gives explicit usage context: 'Use this once per vault before calling any other wiki.* tool.' It also explains the idempotent default and when to pass force:true, and clarifies vault selection rules ('Operates on the session-active vault... unless an explicit vaultPath argument is passed, which always wins'). This is full guidance on when and how to use it.
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?
While annotations already declare readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral context: the weighting order (filename > aliases > tags > summary > body), the return shape (`{path, type, score, hitFields}`), and the dynamic vault resolution logic. It explicitly states 'Read-only; never writes,' consistent with annotations and goes beyond them by disclosing internal ranking mechanics.
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 with a clear lead sentence, explicit usage guidance, a dedicated paragraph on vault behavior, and two illustrative JSON examples. Every sentence serves a purpose, and the information density is high without being verbose. The front-loaded purpose allows quick scanning.
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 (4 parameters, output schema present, dynamic vault context), the description covers all necessary aspects: operational scope, ranking logic, return format, vault selection, and alternatives. It also includes concrete examples that demonstrate typical usage. An agent can invoke this tool correctly after reading the description alone.
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 documentation already covers all four parameters at 100% coverage, which establishes a baseline of 3. The description adds marginal value by clarifying the default limit, hard cap, and the per-call override semantics for `wikiRoot` and `vaultPath`. The examples further reinforce parameter usage. This slightly exceeds baseline without being redundant.
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 ('Rank'), a clear resource ('wiki pages'), and a precise scope ('Sources/Concepts/Entities pages'). It immediately distinguishes itself from siblings by naming the alternatives (`wiki.lint`, `notes.search`) and their different purposes, making selection 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?
Explicitly states when to use ('what does the wiki know about X?'), what to use instead (`wiki.lint` for whole-vault audits, `notes.search` for raw full-text search), and explains vault selection behavior. This covers both use cases and exclusions, leaving no room for misinterpretation.
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?
Annotations already provide readOnlyHint and idempotentHint, but the description adds valuable behavioral context: the Local REST API plugin requirement, the needed environment variables, and the fact that it targets the live Obsidian vault process. This goes beyond the structured annotations without contradicting them.
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 compact and front-loaded with the core behavior. Each sentence adds a distinct fact: what it returns, that it is read-only, the plugin prerequisite, the intended usage, and the vault.select caveat. The only small redundancy is repeating 'read-only,' but it is minimal and reinforces a key safety signal.
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 zero-parameter tool with full annotation coverage and an output schema, the description is complete: it covers prerequisites, return fields, usage intent, and the routing caveat. Nothing an agent needs to decide whether or how to call this tool is missing.
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 tool has zero parameters and the input schema is fully descriptive with additionalProperties false, so the baseline for this dimension is 4. There is no parameter detail needed, and the description appropriately does not invent any.
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 starts with a specific verb ('Return information') and names the exact resource: the file currently open and focused in Obsidian. It enumerates the returned fields (path, modification time, edit/preview mode) and the read-only nature clearly separates it from mutation siblings like workspace.openFile and workspace.closeActiveFile.
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 gives explicit usage context: use this to orient the agent before other workspace-level mutations. It also clarifies a potential routing confusion with vault.select, stating that vault.select does not affect this tool and only changes filesystem-tool routing, which serves as a clear when-not/alternative guideline.
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?
The annotations declare destructiveHint=false, but the description adds rich behavioral context beyond that: it documents the no-op behavior when no file is active, the return shape ('Returns { ok: true }'), the error condition (Local REST API plugin unreachable), and the vault targeting nuance. It also clarifies the operation is UI-only and does not persist changes. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence carries real information: purpose, negative scope, no-op behavior, return/error contract, usage pairing, vault routing, and an example. The core statement is front-loaded, and the content is fully justified given the behavioral nuance of this UI-only mutation tool.
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?
An output schema exists to cover return values, and the description covers everything an agent needs: what it does, when to use it, what it doesn't do, the no-op case, error conditions, and vault targeting. For a zero-parameter tool this is complete with no 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?
This tool has zero parameters, so the baseline is 4. The schema is empty at 100% coverage, and the example shows an empty JSON invocation. Nothing more is needed since there are no parameters to document.
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 states the specific verb (close), resource (active file), and scope (in the Obsidian UI). It explicitly enumerates what it does NOT do ('does not delete, save, or modify file contents'), which cleanly distinguishes it from siblings like notes.delete and notes.edit. An agent can immediately tell this apart from the close-related and edit-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?
Gives explicit when-to-use guidance: 'Use after workspace.openFile when you want to dismiss a temporarily-revealed note.' Also names the companion tool ('Pair with workspace.activeFile first if you need to know what was closed'), and clarifies it is not affected by vault.select. This is model guidance that routes the agent correctly.
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?
Even though annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description goes well beyond that. It reveals the return shape (`{total, items}` with item fields), the session-vault behavior with the `vaultPath` override rule, and the language-specific scanning restrictions. None of this is available in the annotations, and it contradicts nothing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured across two paragraphs, front-loading the purpose and usage in the first sentence. Every sentence adds distinct value—scope, usage trigger, parameter behavior, return format, and vault context—with no filler. It is long but information-dense, and the structure makes it easy to scan.
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 list tool with three optional parameters, the description is comprehensive. It covers scoping (single note vs vault), language filtering, vault selection, return shape (though the output schema presumably details it further), and language-specific requirements. There is no missing information that would prevent a correct call, and the output schema handles return-field specifics.
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% and each parameter has a description, but the explanation text adds critical interplay semantics not present in the schema: omitting `language` lists all three types in one call, vault-wide scanning is only for Mermaid, and `filePath` is mandatory for Dataview languages. It also clarifies that `vaultPath` always overrides the ambient vault. This is exactly the kind of cross-parameter behavior an agent needs.
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: 'List fenced code blocks' of three named languages, scoped to a single note or the entire vault. It explicitly differentiates itself from the sibling tools blocks.read and blocks.update by stating it is for discovery 'before reading or updating them.' No ambiguity remains about what this 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 tells the agent exactly when to use it: 'Use this to discover what DQL, DataviewJS, or Mermaid blocks exist before reading or updating them.' It also gives concrete usage constraints: omitting `language` lists all three types, vault-wide scanning works only for Mermaid, and a `filePath` is required for Dataview languages. This is explicit, actionable guidance with no need for inference.
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?
Annotations already declare readOnly, idempotent, and non-destructive behavior, so the bar for added value is lower. The description still adds meaningful behavior: minimum threshold with default 10, descending sort by outbound count, result shape `{path, title, outbound, inbound}`, and vaultPath precedence over the session-active vault. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly packed: core behavior, default, sorting, result fields, read-only note, usage guidance, alternatives, and vault-selection semantics are all covered in two focused paragraphs. No filler or 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 output schema exists, the description need not re-explain return values, but it still provides the threshold, ordering, vault behavior, and sibling routing. Everything an agent needs to decide when and how to invoke this tool is present.
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 only documents `minOutlinks`; the description compensates for `vaultPath` by explaining that it overrides the session-active vault. It also restates the default for `minOutlinks` and clarifies that the count refers to outgoing links, making both parameters actionable.
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: 'Return notes with at least `minOutlinks` outgoing links', then adds sorting criteria and conceptual framing ('connective tissue / MOCs / curated indexes'). It clearly distinguishes this hub-finding operation from sibling tools like `links.outgoing`, `links.graph`, and `links.health`.
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 states when to use this tool — to find navigational anchors and seeds for `links.connections` — and names the alternatives: `links.health` for a single vault-wide score and `links.graph` for the full raw edge list. It also clarifies vault-targeting behavior via `vault.current` and `vaultPath`.
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?
Annotations provide no safety or readOnly hints, so the description carries the full burden of behavioral disclosure. It discloses all relevant behaviors: filesystem is pure text substitution without script evaluation, templater requires Obsidian API credentials, different actions have different effects (render vs create-note vs insert-active), and it explains vault path resolution. This is thorough and goes beyond what annotations offer.
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?
Despite being detailed, the description is well-organized with sections for each engine, bullet points for actions, and three comprehensive examples. It front-loads the core purpose and then methodically elaborates. Every sentence adds value, and the structure aids comprehension without verbosity.
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 complexity of a dual-engine tool with multiple actions and parameter combinations, the description is remarkably complete. It covers all engines, all actions, required environment variables, vault path resolution, and provides examples for each major use case. The presence of an output schema means return values need not be described, and the description fills all other gaps.
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 already describes parameters with 100% coverage, but the description adds substantial meaning: it explains what engine and action mean, how variables map to placeholders, and provides concrete examples that demonstrate parameter usage. For instance, it clearly illustrates how to set variables and which parameters are required for each combination.
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: 'Render or apply a template using one of two engines.' It specifies the verb (render/apply), the resource (template), and distinguishes between the filesystem and templater engines, making it unambiguous and distinct from sibling tools like templates.list.
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 states when to use which engine, e.g., 'Use engine:'templater' when you need dynamic evaluation' and clarifies that the filesystem engine does NOT evaluate Templater scripts. It also explains the vault selection behavior and when vaultPath takes precedence, providing clear usage context.
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 disclosure burden. It explicitly states that every call appends a new entry, that the tool may auto-run `wiki.init` if the wiki is not scaffolded, and how the active vault is resolved. These are meaningful side effects an agent needs to know before invoking.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action and format, followed by usage guidance, side effects, and examples. Every sentence earns its place, and the examples are placed at the end where they complement rather than obscure the operational 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 7 parameters, sibling logging tools, and no annotations, the description covers the critical context: purpose, exact file format, when to use it, side effects, vault resolution, and concrete examples. The presence of an output schema means the response shape does not need to be spelled out in the 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?
Schema coverage is 100%, but the description adds real value beyond the schema: it explains how `op` and `title` map into the heading, how `refs` render, that `date` defaults to today, and that `vaultPath` overrides the session-active vault. The two JSON examples clarify realistic usage for multiple parameters at once.
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 names the exact resource (`wiki/log.md`), the verb (`Append`), and the canonical heading format, making the tool's function immediately clear. It also differentiates itself from sibling tools by noting that `ingest` and `merge` log themselves, so an agent can tell which actions belong here.
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 an explicit trigger: 'Use this when the agent makes a wiki-meaningful action that no other `wiki.*` tool already logs', with concrete examples like `decision` and `note`. It also names exclusions (`ingest` and `merge` log themselves) and explains the vault-selection precedence with `vaultPath`.
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:

[![kObsidian MCP server](https://glama.ai/mcp/servers/bezata/kObsidian/badges/card.svg)](https://glama.ai/mcp/servers/bezata/kObsidian)

Score Badge

Copy to your README.md:

[![kObsidian MCP server](https://glama.ai/mcp/servers/bezata/kObsidian/badges/score.svg)](https://glama.ai/mcp/servers/bezata/kObsidian)

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/bezata/kObsidian'

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