Obsidian MCP Extended

by aleksakarac

Overview Schema Related Servers Score Discussions

Python

Local

Server Quality Checklist

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

Latest release: v2.1.0
Disambiguation2/5
There is substantial overlap among tools, particularly for tag operations (add_tag_fs_tool vs add_tags_tool, remove_tag_fs_tool vs remove_tags_tool) and link analysis (multiple backlink and broken link tools). This makes it difficult for an agent to select the correct tool.
Naming Consistency3/5
Naming follows a verb_noun pattern but is inconsistent: some tools include '_fs' suffix, some don't; pluralization varies (add_tag vs add_tags); and verbs like 'get', 'find', 'search', 'list' are used interchangeably. While readable, the pattern is not uniform.
Tool Count2/5
With 63 tools, the server is overly large and includes many redundant variations. This exceeds the typical well-scoped range (3-15) and would benefit from consolidation or splitting into focused sub-servers.
Completeness4/5
The tool set covers nearly all Obsidian operations: note/folder CRUD, tag management, search, link analysis, tasks, Kanban, Canvas, Dataview, templates, and command execution. Minor gaps exist (e.g., no explicit rename or attachment management), but overall it is very comprehensive.
Average 3.9/5 across 63 of 63 tools scored. Lowest: 2.4/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not explicitly state read-only behavior, side effects, or what 'metadata and statistics' entails (e.g., creation date, tags, links). The phrase 'without retrieving its full content' is the only behavioral clue.
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 short and front-loaded with the main purpose, but the Args/Returns section repeats information that could be integrated. No wasted words.
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?
For a tool with no output schema and only 0% schema coverage, the description should detail return values (e.g., list of metadata fields) and clarify any constraints, but it does not.
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 coverage is 0%; description only mentions 'path: Path to the note' (redundant) and completely omits the optional 'ctx' parameter, leaving its purpose unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it retrieves metadata without full content, which distinguishes it from read_note_tool, but is vague about what specific metadata ('statistics') and does not differentiate from note_statistics_fs_tool or get_note_connections_tool among many siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like read_note_tool or note_statistics_fs_tool; no exclusions or prerequisites mentioned.
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 simply states it deletes a note, but does not disclose whether deletion is permanent, if it can be undone, or what side effects occur (e.g., cascading deletions). With no annotations, the description carries full burden and fails to provide sufficient 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear Args/Returns structure, but it is too brief, lacking sufficient detail. It achieves minimum viability but could be more informative without being verbose.
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?
Given that this is a delete operation with no output schema or annotations, the description is incomplete. It does not explain the return value, error handling, or confirm the deletion action, leaving critical gaps for an agent.
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 description adds a brief explanation of the 'path' parameter (path to the note), but does not specify format or constraints. The 'ctx' parameter is not explained at all. Since schema description coverage is 0%, the description does not compensate adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it deletes a note from the vault, which is a specific verb-resource pair. It distinguishes from siblings like create_note or update_note, but does not explicitly contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., moving or archiving). No when-not or prerequisite information is provided.
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?
With no annotations provided, the description carries the full burden. Only 'offline' hints at behavior, but it does not disclose whether the tool modifies files, requires specific permissions, or returns any output. The behavior beyond parsing is opaque.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one sentence) but this sacrifices useful detail. It is concise but lacks structure to convey essential information.
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?
Given the absence of an output schema and annotations, the description should explain what parsing returns and how parameters affect behavior. It fails to do so, leaving significant gaps for an agent.
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 33% (only file_path has a description) and the description does not explain the purpose of vault_path or ctx. The description adds no meaning beyond the schema's minimal parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it parses a Canvas file and notes it is filesystem-native and offline. 'Parse' is a specific verb and 'Canvas file' is a distinct resource, differentiating it from sibling tools like parse_kanban_board_tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, when not to use it, or compare with similar tools.
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?
No annotations provided, so description carries full burden. It only mentions the plugin requirement, but does not disclose behavioral traits like side effects, output, or whether it modifies files.
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 efficiently short (two sentences) with no unnecessary words. However, the prerequisite could be integrated into a more comprehensive description.
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?
Given lack of output schema and only moderate schema coverage, more context is needed. No mention of return values, errors, or what the rendered output does.
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 67% (2 of 3 parameters described), and the description adds no parameter-level information beyond what's in the schema. No compensation for undocumented 'ctx' parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Render Templater template' which is a verb+resource, but does not differentiate from the sibling 'expand_template_tool'. The prerequisite mention adds context but does not clarify unique purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The only usage hint is the prerequisite requirement, but no when-to-use or when-not-to-use information is provided.
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?
With no annotations, the description carries full burden. It mentions 'filesystem-native, offline' but does not disclose effects like file creation, position constraints, or error cases.
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 extremely concise with a single sentence, front-loading the purpose. It could be more structured but attains conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, and no annotations, the description is severely incomplete. It omits details about return values, side effects, and parameter interactions.
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 71% (5/7 params have descriptions). The description adds 'filesystem-native, offline' which provides context but does not improve parameter understanding beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Add' and the resource 'node to Canvas'. It is specific enough to distinguish from other tools like parse_canvas_tool, though it does not explicitly contrast with siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or exclusions. The description is purely functional.
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 adds 'filesystem-native, offline' indicating local-only operation without network dependencies, which is useful. However, it does not disclose important behavioral traits such as whether the tool modifies the template file in place, what happens if variables are not provided, or if there are side effects like file creation. Since no annotations are provided, the description carries the full burden but falls short.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single sentence that conveys the core function and two key attributes (filesystem-native, offline). No wasted words, and the information is front-loaded. It is appropriate in size for a simple tool.
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?
Given the lack of output schema and annotations, the description should be more comprehensive. It omits crucial details such as the format for the 'variables' parameter, how 'vault_path' is used, and what the output looks like (e.g., expanded content). The tool has 4 parameters with only one required, yet no guidance on optional ones. This incompleteness could lead to incorrect 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%, and the tool description does not explain any of the parameters despite the low coverage. The description (outside the schema) provides no additional meaning for 'variables' or 'vault_path', which are partially described in the schema. The context parameter is completely undocumented. This is insufficient for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: expanding template variables. It adds specificity with 'filesystem-native, offline' which helps differentiate from sibling tools like render_templater_template_tool that might use a different engine. However, the purpose could be more explicit about the scope (e.g., which template systems it supports).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description does not mention prerequisites, such as the need for a template file to exist, nor does it advise on cases where variables are missing or invalid. There is no comparison with sibling tools that might offer similar functionality.
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?
No annotations are provided, so the description carries full burden. It only states a prerequisite, missing details about read-only nature, return value, or 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, efficient and front-loaded with key information; no redundant text, though could include more detail without being verbose.
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?
For a simple tool with no output schema and no annotations, the description fails to explain what 'active file' means or what the tool returns, leaving significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and description does not mention the 'ctx' parameter at all, adding no meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool gets the currently active file, which differentiates it from tools like open_file_tool or read_note_tool, but does not explicitly mention sibling alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions a prerequisite ('requires Obsidian running'), but provides no guidance on when to use this tool vs. alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description only adds the prerequisite condition. It does not disclose read-only nature, output format, or other behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys purpose and a key requirement with no wasted words.
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?
The description lacks details about the output format (e.g., list of command names, IDs) and does not specify the return structure, making it incomplete for a list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for the sole parameter 'ctx', and the description provides no additional meaning, leaving the parameter completely opaque.
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 'List all available commands' with a specific verb and resource, and distinguishes from siblings like execute_command_tool.
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 mentions the prerequisite 'requires Obsidian running' but provides no explicit guidance on when to use versus alternatives like execute_command_tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided; the description adds context about filesystem-native and offline behavior but omits details on side effects, permissions, or output format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently short but too brief to cover essential information, balancing conciseness with inadequacy.
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?
Given no output schema, no annotations, and minimal parameter coverage, the description fails to provide sufficient context for an AI agent to use the tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not mention any of the three parameters (template_folder, vault_path, ctx), leaving their purpose unexplained.
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 lists available templates and specifies they are filesystem-native and offline, distinguishing it from template expansion tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing offline, filesystem-based templates but lacks explicit when-to-use or alternatives guidance, especially given siblings like expand_template_tool.
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?
No annotations are provided, so the description carries full burden. It only states the runtime requirement, but does not disclose what opening a file entails (e.g., effect on current workspace, whether it replaces or opens in new pane).
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?
Single sentence with no wasted words. Front-loads the core purpose and critical prerequisite.
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?
The description is too brief for a tool with three parameters (one required) and no output schema. It omits details on the effect of new_pane, ctx, and what happens on success or failure.
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?
With schema description coverage at 33%, the description should compensate, but it only repeats 'Open file' which mirrors the file_path description. It adds no meaning for new_pane or ctx 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 clearly states the tool opens a file in Obsidian, with a specific verb and resource. It distinguishes from siblings like read_note_tool (which reads content) and create_note_tool (which creates).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Only mentions the prerequisite 'requires Obsidian running', but gives no guidance on when to use this tool versus alternatives (e.g., read_note_tool, create_note_tool) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must fully disclose behavior. It only mentions what it returns ('Vault structure and note paths') but omits key traits such as file type filtering (e.g., only .md), performance limitations, or sorting order. The defaults are given but not the behavioral 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?
The description is extremely concise, using clear sections (Args, Returns) and front-loading the purpose. Every sentence adds value without redundancy.
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 tool is simple and the description covers its core function, but it omits explanation of the 'ctx' parameter and does not differentiate from similar sibling tools (e.g., list_notes_by_folder_dql_tool). No output schema is provided, but the return description is adequate for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 0%, so the description adds essential meaning for the directory and recursive parameters, including defaults. This goes beyond the schema's basic types. However, the 'ctx' parameter is completely undocumented, which lowers the score slightly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list) and resource (notes) with scope clarification ('in the vault or a specific directory'). It distinguishes from list_folders_tool but does not explicitly differentiate from list_notes_by_folder_dql_tool or search_notes_tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus siblings like list_notes_by_folder_dql_tool (for DQL-based listing) or search_notes_tool (for content search). Missing context about prerequisites or alternative tools.
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?
With no annotations, the description should fully disclose behavioral traits. It mentions link updating but does not state whether the tool is destructive, if it overwrites existing notes, or any permission requirements. The return value is vague ('Move status').
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a single summary line followed by clear args and returns. Every sentence is necessary and well-structured, with no redundancy.
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?
Given the tool is a mutation with no output schema, the description should explain what happens if the destination already exists, what 'updating links' means in detail, and the exact format of the return value. It falls short on these details.
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 description explains source_path, destination_path, and update_links with their roles. However, it omits the 'ctx' parameter present in the schema (despite schema coverage being 0%), so not all parameters 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 clearly states the action ('Move a note to a new location') and key behavior ('optionally updating all links'). It distinguishes from sibling tools like create_note or delete_note by specifying the move operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like move_folder or create_note. The description lacks context about prerequisites or scenarios where this tool is appropriate.
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?
No annotations are provided, so the description must carry the full burden. It mentions the dependency on Obsidian and Dataview and states returns table results, but does not disclose whether the tool is read-only (likely yes) or any side effects, permissions, or performance considerations.
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 with a clear first sentence, bullet points for usage, and a return section. It is concise and front-loaded, though the bullet points could be more precise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the number of parameters and lack of output schema, the description covers the core purpose and typical use cases. However, it omits practical details like valid field names, query limitations, or how it differs from execute_dataview_query_tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 83%, so most parameters have descriptions. The description adds minimal extra meaning beyond the schema, only providing examples of fields. It does not explain how parameters interact or format details.
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?
Description clearly states it executes a DQL TABLE query to create tabular views of note metadata. It lists use cases like creating reports and dashboards, but does not explicitly distinguish from sibling tools like execute_dataview_query_tool that might handle other DQL query types.
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 'When to use' section provides four scenarios, giving some context. However, it lacks explicit guidance on when not to use this tool or how it compares to alternatives like list_notes_by_folder_dql_tool or search_by_dataview_field_tool.
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?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It describes the action ('Execute') but provides no information about side effects, error behavior, or whether it modifies data. The one additional detail is the requirement for Obsidian to be running.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 7 words, front-loaded with the action, and contains no redundant information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema), the description is minimally adequate. It includes a crucial prerequisite but does not explain what constitutes a valid command_id, whether the command returns output, or safety considerations.
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 50%: only command_id has a description. The tool description does not add any meaning beyond what the schema already provides, nor does it compensate for the missing description of the 'ctx' 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 'Execute Obsidian command' uses a specific verb and resource, clearly stating what the tool does. It distinguishes itself from sibling tools, as no other tool is dedicated to executing arbitrary Obsidian commands.
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 mentions a prerequisite ('requires Obsidian running'), which gives some usage context. However, it does not explicitly state when to use this tool versus alternatives, nor does it provide examples or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses performance metrics and return content, but lacks details on return format or potential edge cases. The tool is read-only, which is implied but not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections (main description, statistics list, when to use, performance, returns). It is front-loaded with the key action. Minor redundancy could be trimmed, but overall efficient.
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 (aggregate task statistics with optional grouping), the description provides sufficient context: what statistics are returned, optional grouping, performance guidance. Missing output schema is compensated by the 'Returns' summary. Edge cases are not addressed.
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?
Input schema has 80% coverage with descriptions for 4 of 5 parameters. The description adds value by explaining the overall output, but does not elaborate on parameter details beyond the schema. The 'ctx' parameter remains undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get aggregate task statistics for a note or entire vault' and lists specific statistics. It distinguishes the tool's focus on tasks, but does not explicitly differentiate from similar sibling tools like note_statistics_fs_tool or vault_statistics_fs_tool.
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 includes a 'When to use' section with relevant scenarios (project progress tracking, workload analysis, etc.). However, it does not mention when not to use this tool or compare it to alternatives such as search_tasks_tool or note_statistics_fs_tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It covers key actions (creates frontmatter, handles duplicates, supports nested tags, performance <200ms) but omits details like file existence requirements, permission needs, or error handling. The mutation implicit in 'add' is clear, but more depth would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for usage, performance, and returns. While it is slightly verbose with the 'When to use' list, every sentence serves a purpose. It could be trimmed but remains concise for the information provided.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given four parameters and no output schema, the description covers the main function and key behaviors. However, it lacks details on prerequisites (e.g., file must exist), side effects on other frontmatter fields, and error scenarios. This is adequate for a simple tool but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75% (ctx lacks description). The description adds value by providing an example of nested tags for the 'tag' parameter and contextualizing the tool's purpose, but does not elaborate on filepath or vault_path beyond the schema. The ctx parameter remains undefined, leaving a gap.
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 adds a tag to a note's frontmatter, creating frontmatter if needed, handling duplicates, and supporting nested tags. This specific verb-resource combination distinguishes it from other tag tools like 'add_tags_tool' which likely operate on different structures.
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 'When to use' section lists use cases like organization and bulk tagging, but does not mention when to avoid this tool or compare it to alternatives such as 'add_tags_tool' or 'remove_tag_fs_tool'. This leaves the agent without guidance on tool selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description partially covers behavior: scans markdown files, identifies wikilinks to non-existent notes, and gives performance timing. However, it misses details like error handling, limitations (e.g., only markdown), and whether it's read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections for introduction, usage, performance, and returns. Efficiently conveys key information without unnecessary words, though the 'Returns' section could be omitted if output schema existed.
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?
Covers main purpose, use cases, and performance. Lacks details on output format (only says 'grouped by source note') and edge cases (e.g., handling of non-markdown files, errors). Adequate but could be more 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 coverage is 50% (only vault_path described). The description explains vault_path's default usage from env var but does not mention the ctx parameter, leaving it undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it finds broken wikilinks using filesystem access without requiring Obsidian, and distinguishes itself from sibling find_broken_links_tool by emphasizing 'no Obsidian required'.
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 bullet list of when to use (after renaming/deleting notes, maintenance, etc.) and performance estimates, but lacks explicit when-not-to-use or comparison to alternatives like find_broken_links_tool.
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 is adequate, stating it removes tags and returns an updated list. However, with no annotations, it doesn't disclose side effects, error behavior for non-existent tags or notes, or permission requirements. It's neither misleading nor highly informative.
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?
Extremely concise with a clear title line and structured Args/Returns sections. Every sentence is necessary and front-loaded.
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?
Covers the basic semantics for parameters and return value. However, it does not explain the 'ctx' parameter, error scenarios, or edge cases like removing non-existent tags. Given the simplicity of the tool and lack of output schema, it meets minimum viability but has 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?
The description explains the required parameters 'path' and 'tags' with context (e.g., tags without '#' prefix), adding significant value beyond the input schema which has no descriptions. The optional 'ctx' parameter is not described, but since it's not required, the coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (remove tags) and the resource (a note's frontmatter). It distinguishes from sibling tools like add_tags_tool and update_tags_tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like add_tags_tool or update_tags_tool. The description only states what the tool does, not when it should be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses it is filesystem-native and offline, and includes performance estimates. However, it does not explicitly state it is read-only, nor mention any permissions or side effects, leaving some behavioral uncertainty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with clear sections for purpose, usage, performance, and return value. Every sentence earns its place with no redundancy.
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?
For a simple tool with minimal parameters and no output schema, the description covers the main functionality, use cases, and performance. However, it could be more precise about the return format (e.g., relative vs absolute paths) and whether subfolders are included.
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?
With only 50% schema description coverage, the description adds no parameter information. The 'ctx' parameter is undocumented in both schema and description, and the description does not elaborate on how vault_path is used beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Find orphaned notes with no connections', which is a specific verb+resource. It distinguishes from siblings like find_broken_links_tool and find_hub_notes_tool by targeting completely isolated notes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Lists specific use cases (vault cleanup, finding forgotten notes, etc.), providing clear context for when to use. However, it does not mention when not to use or explicitly name alternatives among the 60+ sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the tool is offline and gives performance estimates (<500ms for 100 cards, <5s for 1000 cards). However, it does not state that the tool is read-only, discuss permissions, or describe error conditions or edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points, sections, and front-loaded purpose. It is reasonably concise at about 10 lines, though the 'Returns:' line is somewhat redundant with the earlier list. Overall efficient and easy to scan.
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 main use cases and return values, and with no output schema, it provides enough detail on what is returned. However, it lacks information on error handling (e.g., missing file, empty board), and the ctx parameter is undocumented. These gaps reduce completeness for a tool with moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 67% description coverage (file_path and vault_path have descriptions, ctx does not). The description adds no parameter-specific information beyond what the schema provides. Without further elaboration on parameter formats or constraints, it meets the baseline for a 3 but does not compensate for the uncovered 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 clearly states the tool gets comprehensive statistics for a Kanban board, specifying 'filesystem-native, offline'. It details what statistics are provided (total cards, per-column counts, completion rates) and distinguishes itself from related sibling tools like parse_kanban_board_tool and note_statistics_fs_tool.
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 includes an explicit 'When to use' section listing four scenarios: project progress tracking, sprint velocity analysis, board health monitoring, and generating board reports. This provides clear context for usage, though it does not explicitly mention when not to use the tool or suggest alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions requirements (Obsidian, Dataview plugin, local REST API) and that results are in Dataview's structured format, but does not disclose potential errors, timeouts, or side effects. More details on error behavior would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clear sections (purpose, types, clauses, when-to-use, requirements). It is concise at ~150 words and every sentence adds value, though the 'Returns' line could be slightly more specific.
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 query tool with no output schema, the description covers the DQL language components, usage scenarios, and prerequisites. It lacks details on error handling or result format specifics, but overall it is fairly complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description adds value to the 'query' parameter by listing examples and supported syntax, which supplements the schema. However, the optional 'ctx' parameter is not described at all in the description, and schema coverage is only 50%. 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 executes DQL queries and enumerates supported query types (LIST, TABLE, TASK, CALENDAR) and clauses. It distinguishes from sibling tools like list_notes_by_tag_dql_tool and search_notes_tool which are simpler.
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 'When to use' section provides four clear scenarios (complex queries, computed fields, metadata indices, real-time results). It implies this tool is for advanced queries beyond basic filesystem capabilities, though it does not explicitly exclude simpler cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It explains block ID format, performance, and return type, but lacks detail on error handling, side effects, and whether content insertion creates a new line. Ambiguities remain.
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 (10 lines) with clear sections (When to use, Performance, Returns). Each sentence is purposeful and front-loaded with the core action.
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 purpose, usage, performance, and return type, but lacks details on error cases (e.g., block not found), exact insertion behavior, and return value structure. With no output schema, more completeness would be beneficial.
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 80% (4 of 5 parameters documented). The description adds minimal value beyond the schema, only reiterating that block_id can omit the ^ prefix, which the schema already states.
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: 'Insert content immediately after a block reference.' It explains block references and differentiates from sibling tools like insert_after_heading_fs_tool by specifying block-level insertion.
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 'When to use' section lists relevant scenarios (e.g., adding follow-up content, expanding paragraphs). However, it does not explicitly exclude alternatives or mention when to use sibling tools like insert_after_heading_fs_tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. It discloses the prerequisite (Dataview plugin) and states the return format. However, it does not mention side effects, permissions, or whether it is read-only, which would enhance 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?
Description is fairly concise with clear sections (purpose, when-to-use, returns). It is front-loaded with key action. Could be slightly tighter by removing some redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description explains return value ('list of matching notes with Dataview metadata'). Covers prerequisites, inputs, and high-level behavior. Lacks details on limit usage or error cases.
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 80% schema coverage, the description adds little beyond schema: 'optional filtering and sorting' maps to where_clause and sort_by. It does not provide constraints, syntax examples, or defaults beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description starts with clear verb and resource: 'List notes in a folder using DQL'. It distinguishes from siblings like list_notes_tool by specifying the method (DQL) and prerequisites (Obsidian + Dataview plugin).
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?
Includes a 'When to use' section with three specific scenarios, providing context for appropriate usage. However, it does not explicitly mention when not to use or compare to alternatives like list_notes_tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must handle transparency. It mentions prerequisites (Obsidian + Dataview plugin) and hints at read-only behavior by noting it 'returns' results, but does not explicitly state non-destructiveness, rate limits, or error handling for missing dependencies.
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?
Description is brief and well-structured with a summary, usage guidelines as bullet points, and return type. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description only states 'List of matching notes with Dataview metadata,' which is vague. It does not specify exact fields or structure. Also, it does not distinguish from similar sibling tools like search_by_tag_fs_tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (80%), so baseline is 3. Description reinforces that filtering and sorting are optional but adds no new semantic detail beyond the schema. The 'ctx' parameter lacks description in both schema and 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?
Clearly states it lists notes by tag using DQL, and differentiates from siblings like list_notes_tool or search_by_tag_fs_tool by specifying it's a simplified interface for tag-based queries with optional filtering and sorting.
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?
Includes a 'When to use' bullet list with three specific scenarios (complex filters, Dataview's indexing, real-time queries), providing clear context. However, it does not explicitly state when not to use or directly compare to sibling tools.
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?
Without annotations, the description mentions preserving metadata and performance (<500ms for 1000 cards). It lacks details on side effects, idempotency, or permissions, but provides reasonable 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear title, usage lists, and return section. It is moderately concise and front-loaded, with no unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description includes return values. It covers tool purpose, parameters, and performance. Missing explanation of the 'ctx' parameter, but overall it is comprehensive for a simple toggle operation.
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 75%; description adds context like exact match requirement and relative path interpretation. However, parameter 'ctx' is unexplained, and the description does not significantly enhance the schema information beyond 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 it toggles a Kanban card's completion status between incomplete and complete, specifying the exact checkbox format. It distinguishes itself from siblings like add_kanban_card_tool and toggle_task_status_tool.
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 'When to use' section lists clear use cases like marking cards complete and batch updates. However, it does not explicitly mention when not to use this tool or provide comparisons to alternatives like toggle_task_status_tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description states metadata is updated while preserving content, and null removes fields. Lacks details on permissions, idempotency, or side effects for unchanged fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with key purpose, then usage and returns. Structure is clear but could slightly reduce verbosity (e.g., remove redundant 'filesystem-native' explanation).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, parameters usage, and return value. Lacks error handling or behavior when task not found. Given 9 params and no output schema, it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (89%). Description adds the concept of passing null to remove fields, but otherwise does not add meaning beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates task metadata (priority, dates, recurrence) without changing content, and differentiates from siblings like create_task_tool by specifying it modifies existing tasks. The phrase 'filesystem-native' indicates direct file modification.
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?
Includes a 'When to use' section listing rescheduling, changing priorities, and adding/removing recurrence. Does not explicitly state when not to use or mention alternatives like update_note_tool for content changes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behaviors itself. It mentions performance metrics for different note counts, which provides some transparency. However, it does not explicitly state that the operation is read-only or safe, nor does it discuss required permissions or 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 around 10 lines with clear sections: purpose, explanation, when to use, performance, and returns. Every sentence serves a purpose and there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema and no annotations, the description covers purpose, usage context, performance expectations, and the output format (list sorted by outlink count). The only gap is the undocumented ctx parameter, which prevents a perfect score.
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 67%; two of three parameters have descriptions. The description adds context like default values and range for min_outlinks, and explains vault_path optionality and environment variable fallback. However, the ctx parameter remains undocumented, and the description does not add significant new semantic detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Find hub notes with high outlink counts' and elaborates on what hub notes are. It distinguishes this tool from siblings like find_broken_links_tool and get_outgoing_links_tool by focusing on outlink count centrality.
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 'When to use' section lists four concrete scenarios (finding index/MOC notes, identifying navigation points, etc.). While it doesn't explicitly state when not to use it or mention alternatives, the context is clear and helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description adds value by noting performance characteristics and stating it is 'filesystem-native, offline'. It implies read-only operation and provides return expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections, bullet points, and front-loaded purpose. Efficiently conveys necessary information without excessive verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers purpose, usage, performance, and return type fairly well. Some details like exact output format could be added but not critical.
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 coverage is 50% with only vault_path described in schema. The description adds no extra parameter details; ctx remains undocumented. Parameter semantics are weak.
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 fetches a 'complete link graph for the vault', specifying verb 'get', resource 'link graph', and details inlinks, outlinks, and link types. This distinguishes it from sibling tools like get_note_connections_tool or get_backlinks_tool.
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 'When to use' section lists appropriate scenarios like understanding vault structure and building visualization data. It does not explicitly mention when not to use or alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It covers performance (<1 second), exclusions (word count excludes frontmatter and code blocks), and return details. It lacks mention of side effects or dependencies, but overall is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections for purpose, analyzed elements, returned metrics, usage, and performance. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and absence of an output schema, the description effectively lists all returned metrics (e.g., word count, tags, headings). It lacks exact structure but provides sufficient context for understanding tool output.
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 67% (2 of 3 parameters have descriptions). The description adds examples and clarifications (e.g., relative vs absolute path, optional vault_path), but doesn't significantly extend beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get comprehensive statistics about a single note' and lists detailed analysis areas, distinguishing it from vault-wide tools like vault_statistics_fs_tool. However, it does not explicitly differentiate from all sibling tools, so it scores 4.
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 'When to use' section provides clear use cases such as analyzing note complexity and tracking growth. It does not mention when not to use or alternatives, but the context is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. It discloses performance benchmarks and metadata formats but does not explicitly state safety aspects (e.g., read-only nature) or required permissions.
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 clear sections: summary, format details, metadata, usage, performance, returns. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Describes input, process, and return value (board structure with columns, cards, etc.). Lacks edge-case handling (e.g., malformed boards) but is adequate for a read-only parsing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% (ctx param undocumented). Description adds examples for file_path and explains vault_path uses env var, but ignores ctx parameter entirely.
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 explicitly states the tool parses a Kanban board file and extracts its structure, with specific details on supported markdown formats. It distinguishes from siblings like add_kanban_card_tool and get_kanban_statistics.
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?
Lists clear when-to-use scenarios such as analyzing board structure and extracting card data. However, it does not mention when not to use or compare to similar tools like get_kanban_statistics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses performance (<500ms for 1000 cards), card format details, and that it preserves existing board structure. While it could mention conflict handling or authentication, it provides sufficient behavioral context for an add operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (card format, when to use, performance, returns). It is slightly verbose but each sentence adds value, and it avoids redundancy with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (8 parameters, no output schema), the description covers purpose, usage, performance, and return format. It lacks details on optional parameters like due_date format but schema covers those. It is complete enough for an add operation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 88% (high), so baseline is 3. The description adds general context about optional metadata and insertion position but does not significantly elaborate beyond what the schema provides for each 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 explicitly states 'Add a new card to a Kanban board column' and details the card format, distinguishing it from sibling tools like create_task_tool or toggle_kanban_card_tool. It provides specific verb and resource with clear context.
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?
A 'When to use' section lists specific scenarios such as adding tasks to project boards and batch card creation. Although alternatives are not mentioned, the contexts are clear and practical.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions returning an 'Updated tag list for the note,' but does not disclose whether tags are appended or overwritten, or if frontmatter is created when absent. The description provides some behavioral context but lacks depth for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a front-loaded main sentence, bullet points for usage, and a returns line. It is efficient, though the 'Returns' section could be integrated into the main description to reduce redundancy. Overall, well-structured without unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the absence of an output schema, the description covers the basic operation and return value. However, it lacks details on side effects, concurrency, or validation of tags. This is adequate but could be more complete for a tool that modifies note content.
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 67%, and the description does not add any parameter-specific meaning beyond the schema. For example, it does not explain the 'ctx' parameter or provide additional context for 'path' or 'tags' beyond what is already in the schema. Baseline is 3 given the moderate coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Add tags to a note's frontmatter.' It uses a specific verb and resource, and the 'When NOT to use' section explicitly distinguishes from update_note for replacing all tags or adding tags in content, removing ambiguity.
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 includes explicit 'When to use' and 'When NOT to use' sections, providing concrete scenarios (organizing notes, bulk tagging) and alternatives (update_note) for incorrect usage. This helps the agent decide when to invoke this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It states the return format but does not disclose potential side effects, performance implications, or scope limitations (e.g., external links). Lacks explicit safety cues for a scanning tool.
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?
Extremely concise with clear sections (purpose, when to use, when not to use, returns). No redundancy; 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?
Covers usage scenarios and return format. Lacks details on how broken links are detected (internal vs external) and any performance notes, but is fairly complete for a simple scanning tool given no 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?
Schema coverage is 50% (ctx parameter undocumented in schema and description). Description adds no new parameter information beyond the schema's directory description. Does not compensate for the undocumented ctx 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 clearly states it finds all broken links in the vault or a directory, using specific verbs and resources. It explicitly distinguishes from sibling tools like get_outgoing_links and get_backlinks by listing when not to use them.
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 scenarios (e.g., after renaming notes, regular maintenance) and when-not-to-use with alternative tool names, giving clear context 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?
No annotations are provided, so the description carries the full burden. It discloses filesystem access, scanning of all markdown files, and performance estimates. It does not mention error handling or limitations (e.g., only wikilinks), but overall provides good 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?
The description is well-structured with sections for purpose, explanation, usage, performance, and returns. It is front-loaded with the main purpose and every sentence adds value without redundancy.
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?
No output schema is provided, so the description must clarify return values. It states 'returns all notes containing wikilinks with context', but 'context' is vague (e.g., surrounding lines?). It also lacks details on error cases (e.g., note not found) or response structure, leaving some gaps for a data-returning tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% (two of three params have descriptions). The description adds little beyond the schema: it mentions note_name as 'target note' and vault_path as optional with env fallback, but does not elaborate on parameter usage or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Find all notes that link to a specified note') and the resource (filesystem-native backlinks). It distinguishes from siblings by emphasizing 'no Obsidian required' and 'direct filesystem access', which differentiates it from get_backlinks_tool.
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 'When to use' bullet points provide clear scenarios (e.g., building connection graphs, high-performance discovery). However, it does not explicitly state when to avoid using this tool or mention the alternative get_backlinks_tool for comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses case-sensitive matching, first-occurrence insertion, and a performance note (10k words <500ms). Lacks details on error handling (e.g., heading not found) or side effects, but covers core behavior adequately.
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 sections for purpose, details, when to use, performance, and returns. Front-loaded with purpose, each sentence adds value, no fluff. Efficient and clear.
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 simplicity of tool, high schema coverage, and no output schema, description covers all necessary aspects: behavior (case-sensitivity, first occurrence), usage scenarios, performance, and return value. Complete for task of inserting after a heading.
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 80% (ctx parameter lacks description). Description adds examples for filepath and heading, clarifies heading should be without #, and explains content parameter. Does not elaborate on 'ctx' parameter, but overall adds marginal value over 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?
Description clearly states 'Insert content immediately after a specific heading in a note,' with specific verb (insert), resource (content after heading), and behavior (case-sensitive, first occurrence). Distinguishes from sibling insert_after_block_fs_tool which inserts after a block rather than a heading.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'When to use' list (e.g., adding tasks to Tasks section, inserting notes under Notes heading) giving clear context for appropriate use. Does not explicitly contrast with alternatives or state when not to use, but the listed scenarios are specific enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It mentions the return type but lacks details on permissions, hidden folders, performance, or error handling, leaving gaps.
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 with clear headings and concise sentences. Some slight redundancy in the 'Returns' section could be integrated, but overall effective and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description adequately explains the return structure. It covers key use cases and parameters, though missing pagination or error handling details for a complete picture.
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 67% (two of three parameters described). The description adds minimal extra parameter info beyond the schema, repeating 'directory' context but not enriching the semantics further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists folders in the vault or a specific directory, with explicit use cases and differentiation from sibling tools like list_notes.
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 dedicated 'When to use' and 'When NOT to use' sections with specific alternatives (e.g., list_notes, search_notes), offering clear guidance on appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It mentions 'filesystem-native, offline' and provides performance estimates, giving insight into behavior. It does not explicitly state read-only but implies non-destructive analysis.
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 bullet points and clear sections. It is concise yet informative, front-loading the purpose and key details without unnecessary text.
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 necessary aspects: purpose, metrics, usage scenarios, and performance. Even without an output schema, it describes the return values sufficiently. It is complete for its complexity.
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 50%, and the description does not elaborate on parameters beyond what the schema provides. It adds no value for the 'ctx' parameter or usage details for vault_path.
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 what the tool does: 'Analyze vault-wide link health metrics (filesystem-native, offline).' It lists comprehensive metrics and distinguishes from siblings like find_broken_links_tool and find_orphaned_notes_tool.
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 'When to use:' section provides explicit scenarios for using the tool, such as vault health assessment and identifying maintenance needs. No exclusion or alternative guidance is given, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses performance (<100ms) and the return structure, but could explicitly state the tool is read-only and has no 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 well-structured with clear sections (what, outputs, when to use, performance, returns). Every sentence adds value, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 params, no output schema), the description provides sufficient context: output details, usage guidance, and performance. It could be improved by mentioning prerequisites like note existence.
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 67% (two of three parameters described). The description does not add meaning beyond the schema; it focuses on output. With moderate coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'extract' and the resource 'tags from a note', and distinguishes it from siblings like list_tags_tool by specifying it operates on a single note and returns tags by source.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'When to use' scenarios, giving clear context for appropriate usage. It does not mention exclusions or alternatives, but the context is sufficient for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It clearly states the behavior (appends at end, not modifies existing content) and performance (<100ms). It does not mention authorization or side effects, but the append operation is inherently low-risk. The 'Returns' section adds clarity on outcome.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise: a single lead sentence followed by bullet-pointed 'When to use', 'Performance', and 'Returns' sections. Every sentence adds utility without redundancy. It is front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description appropriately covers the return value and performance. The sibling list is large but not directly addressed; however, the tool's distinct append-only purpose is clear. It could briefly note that the tool does not create the note if missing, but this is evident from the name and siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, and the description adds minimal value beyond schema definitions. For 'content', it simply restates 'append to the end of the note' and for 'filepath' it references the schema. The description does not elaborate on formatting or constraints beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Append content to the end of a note.' It specifies the verb ('append'), resource ('note'), and exactly where the content goes ('very end of the file'). This distinguishes it from sibling tools like insert_after_heading_fs_tool or update_note_tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'When to use' scenarios (appendices, logs, chronological content). However, it does not mention when NOT to use it or suggest alternatives (e.g., for mid-note insertion use insert_after_* tools). Siblings include relevant alternatives, making this a minor gap.
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?
Discloses that the tool moves folder and contents, returns move status with counts, and warns about circular references. However, lacks details on overwriting behavior, error scenarios, or any side effects beyond what is stated.
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?
Concise and well-structured: a purpose statement, bullet lists for usage and non-usage, and a returns line. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the main aspects of the tool's behavior and usage, including return value. Could mention what happens on conflict (e.g., if destination exists), but given no output schema, it provides sufficient context for a folder move tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (75%) with parameter descriptions and examples already provided. The tool description adds the circular reference warning but does not significantly extend parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'move' and the resource 'entire folder and all its contents', distinguishing it from sibling tool move_note_tool which moves individual notes.
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 lists when to use (reorganizing, archiving, consolidating, seasonal) and when NOT to use (moving individual notes, moving to subfolder causing circular reference), with a direct alternative mentioned (use move_note).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool preserves metadata, subtasks, formatting, and mentions performance (<500ms for 1k cards) and return value structure. However, it does not discuss error handling (e.g., card not found) or reversibility, but the core behavioral traits are adequately covered.
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 clear sections: main action, when to use, performance, returns. It is concise, front-loaded with the core task, and contains no redundant sentences. Every element adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters (4 required) and no output schema, the description covers purpose, usage, behavioral traits, performance, and return values. It lacks details on error cases but is otherwise thorough. The presence of sibling tools and context signals adds to completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 86%, so the schema already documents parameters well. The description adds general context (e.g., 'Finds a card by matching its text') but does not provide additional semantic meaning beyond what the schema offers. 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 the tool's purpose: 'Move a card between columns on a Kanban board' and elaborates on the process. It differentiates from sibling tools like add_kanban_card_tool and toggle_kanban_card_tool through its specific verbs and context.
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 a 'When to use' list with concrete scenarios (e.g., moving tasks through workflow stages, batch updates). While it doesn't explicitly state when not to use or list alternatives, the context signals show many sibling tools, and the guidelines are clear enough for typical use 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?
No annotations provided, but description discloses key behaviors: graceful handling of non-existent tags, scope (frontmatter only), performance estimate, and return value. Lacks details on error handling for missing filepath.
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?
Description is well-structured with clear sections, no redundancy, and all sentences add 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?
Covers purpose, usage, behavior, performance, and return. Could elaborate on error cases or prerequisites like file existence, but adequate for typical usage.
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 descriptions cover 75% of parameters; description adds no new parameter-level information beyond restating the action. The tag format (without #) is already in 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 'Remove a tag from a note's frontmatter' and distinguishes from inline tag removal, aligning with sibling tools like remove_tags_tool which likely remove all occurrences.
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 'When to use' section with three specific scenarios, though does not explicitly mention alternative tools like remove_tags_tool for comparison.
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?
Since no annotations are provided, the description bears full responsibility. It discloses search behavior (frontmatter/inline, nested tags, entire vault), performance benchmarks (e.g., '1,000 notes: < 3 seconds'), and return format (list of notes with tag locations). No side effects are omitted as the tool is read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with clear sections (purpose, when to use, performance, returns). Every sentence adds relevant information without redundancy. Front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the primary parameter (tag) well, mentions optional vault_path, and describes the return output. However, it omits guidance on the ctx parameter and provides no comparison with closely related siblings like list_notes_by_tag_dql_tool. Overall sufficient for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (2 of 3 parameters documented). The description adds value by confirming tag syntax ('with or without #') and supporting nested tags, but does not elaborate on the undocumented 'ctx' parameter. Baseline 3 is appropriate as schema does most of the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Find all notes containing a specific tag (frontmatter or inline)'. It distinguishes itself from sibling tools like list_notes_by_tag_dql_tool by specifying it searches both frontmatter and inline tags, supports nested tags, and includes tag locations in results.
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 includes a 'When to use' section with four specific use cases (e.g., 'Finding all notes in a category'). However, it does not explicitly mention when not to use this tool or directly compare with alternatives like list_notes_by_tag_dql_tool, which slightly reduces guidance completeness.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions the return value includes 'Search results with matched notes, relevance scores, and context' but does not disclose other behavioral traits like read-only nature, performance characteristics, or error handling. The description is adequate but not comprehensive.
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, front-loading the main purpose, followed by bullet-pointed usage guidelines and a brief note on returns. No unnecessary words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the many sibling tools and lack of output schema, the description does a good job of differentiating usage. It covers core use cases and alternatives but lacks details on pagination, max results, sorting, and exact return format, which would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (query and context_length have descriptions). The description does not add meaning beyond what the schema provides; it repeats the search criteria concept. The 'ctx' parameter has no description in schema or description, so the description does not compensate for the gap.
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 'Search for notes containing specific text or matching search criteria,' providing a specific verb and resource. It distinguishes from siblings by listing when NOT to use this tool (search_by_date, list_notes, read_note), making the purpose clear.
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 includes a 'When to use' section with three concrete scenarios (content keywords, tags, folders) and a 'When NOT to use' section naming alternative tools with reasons (e.g., 'use list_notes for better performance'). This is explicit guidance for correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the toggle behavior, optional done date, and return values. However, it does not mention side effects like file modification, permissions needed, or error cases when the line is not a task.
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?
Highly concise and well-structured: a brief purpose, detailed explanation, 'When to use' list, and return values. Every sentence adds value, and the main verb is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main behavior, use cases, parameters, and return values. No output schema, but includes return details. Missing explanation of error handling and the ctx parameter, but overall sufficient for a toggle 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 80%, baseline 3. Description adds meaning by explaining the checkbox format and the role of add_done_date. It contextually describes file_path and vault_path beyond schema, but does not explain the ctx 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 clearly states the tool toggles task completion status between incomplete and completed, specifying the checkbox format and optional done date. It distinguishes itself from sibling tools like create_task_tool and update_task_metadata_tool by focusing on toggling state.
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?
Includes a 'When to use' section listing explicit use cases (marking tasks complete, unchecking accidentally completed tasks, batch updates). Does not explicitly mention 'when not to use' or name alternatives, but the described use cases 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?
No annotations exist, so description carries burden; it discloses overwrite capability and return value, but lacks detail on side effects or permissions.
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 with sections and bullet points, concise without waste; minor improvement possible by further condensing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 params, no output schema, and many siblings, the description provides sufficient context for an agent to decide when to use it.
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 covers 75% of params; description adds small extra value (e.g., suggesting tags) but doesn't mention ctx param. Adequate but not exceptional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates or overwrites a note, distinguishing it from siblings like update_note_tool which is mentioned for updates.
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 lists when to use (new notes, templates) and when not to (updating, appending) with alternative tool named (update_note).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description covers all behavioral aspects: offline filesystem-native operation, canonicalization rules, performance estimates for typical vault sizes, and return format (grouped by file with counts). This is complete and transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections, bullet points, and examples. It is concise but could be slightly shortened. Every sentence adds value, and the format aids readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters and no output schema, the description covers purpose, behavior, canonicalization, performance, and returns. It lacks explanation of the ctx parameter, but overall provides sufficient context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 80% of parameters with descriptions. The description adds canonicalization details for 'key' but does not significantly enhance meaning for other parameters beyond schema. Performance and return info are not parameter-specific. 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 finds notes containing a specific Dataview field, using verbs 'Find all notes' and specifying the resource. It distinguishes from siblings like search_by_date, search_notes, and search_tasks by focus on Dataview fields.
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 'When to use' section lists specific scenarios like finding notes with metadata and building dynamic collections, providing clear context. It does not explicitly exclude other cases, but the list guides appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It describes the tool as a read operation and mentions return fields (paths and timestamps), but it does not disclose potential side effects, authentication requirements, rate limits, or whether the search is case-sensitive or limited to certain note types. The disclosure is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise with no redundant sentences. It uses bullet points for clarity and front-loads the core purpose in the first sentence. Every section earns its place.
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 basic purpose, usage guidance, and return types, but it lacks details about result sorting, pagination, or limits. Given the tool has no output schema, the description could be more complete by specifying the format or ordering of results.
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 75% schema coverage, three parameters (date_type, days_ago, operator) already have descriptions. The description adds context by explaining when to use specific parameter combinations (e.g., 'recently modified notes' for days_ago, 'specific time period' for date_type). This adds value beyond the schema, though it does not elaborate on every parameter's nuances.
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: searching notes by creation or modification date. It uses a specific verb ('Search') and resource ('notes'), and distinguishes itself from sibling tools like search_notes which handle content-based or tag-based searches.
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 provides 'When to use' and 'When NOT to use' sections, with concrete examples and clear alternatives (e.g., 'use search_notes' for content-based search). This fully informs the agent when to select this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses key behaviors: auto-detection of value types, syntax variants, insertion positions, and returns success info. It does not mention file permissions or potential conflicts, but covers core behavior well.
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 clear sections and bullet points. Every sentence adds value, and the most important information (purpose, usage) is front-loaded. Concise without missing critical details.
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 lack of output schema, the description usefully states return values (success, formatted field string, key). It covers purpose, parameters, and behavior adequately. Missing error handling or prerequisite info, but sufficient for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (86%), but the description adds value by explaining 'value' auto-typing and detailing 'syntax_type' and 'insert_at' with examples and defaults. It goes beyond just restating the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add'), the resource ('Dataview inline field to a note'), and the scope ('filesystem-native, offline'). It distinguishes from sibling tools like remove_dataview_field_tool and search_by_dataview_field_tool by specifying it is for adding new fields.
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 includes a 'When to use' section listing appropriate scenarios (e.g., adding metadata, batch tagging). However, it does not explicitly state when NOT to use the tool or compare it to alternatives like update_frontmatter_field_fs_tool for frontmatter fields.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description shoulders the full burden. It discloses that the tool creates a checkbox task, inserts it at a specified location, creates the file if missing, and formats metadata with emoji syntax. The return value is also described. No contradictions are present.
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, starting with a clear purpose statement, followed by details on metadata formatting, a 'When to use' list, and a description of the return value. It is concise (about 15 lines) with no superfluous content; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 parameters (2 required), no output schema, and no annotations, the description covers the most crucial aspects: creation behavior, insertion location, file creation, metadata formatting, and return format. It could be slightly more complete by mentioning error handling or limitations, but it is generally sufficient.
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 high (91%), so the baseline is 3. The description adds valuable context beyond the schema, such as explaining the emoji syntax for priority, dates, and recurrence, and the insert_at options. This enriches understanding of how parameters affect the output.
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 'Create a new task with Tasks plugin metadata (filesystem-native, offline).' It clearly specifies the verb (Create), resource (task), and context (Tasks plugin). This distinguishes it from sibling tools like toggle_task_status_tool or update_task_metadata_tool, which handle existing tasks.
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?
Includes a 'When to use:' section listing four concrete scenarios (e.g., 'Adding tasks to project notes', 'Creating recurring task templates'). This provides clear context for when to invoke this tool, though it does not explicitly state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses performance characteristics (fast for small vaults, slow for large) and return value structure. However, it could mention more about output format or potential side effects, though none expected for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections, bullet points, and no extraneous information. 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 no output schema, the description explains return values adequately. It also includes performance notes. Could be more specific about return format, but sufficient for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, so many parameters already have descriptions. The description adds minimal extra value beyond the schema, mostly repeating the context parameter behavior. 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 'Find all notes that link to a specific note (backlinks)' with a specific verb and resource. It also explicitly distinguishes from siblings by noting when to use alternatives like get_outgoing_links and find_broken_links.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides dedicated 'When to use' and 'When NOT to use' sections with explicit alternatives, giving clear context for when this tool is appropriate versus siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. States it returns outgoing links with types and validity status, implying read-only operation. Lacks details on error handling or prerequisites, but sufficient given simplicity.
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?
Concise, well-structured with bullet points for usage guidance and returns. No redundant information, 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?
Describes return values (outgoing links with types and validity status) despite no output schema. Usage guidelines add context. Slightly incomplete on edge cases like embedded content, but generally sufficient.
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 67% (two of three parameters have descriptions). The description does not add extra parameter meaning beyond the schema, which is adequate but not improved.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool lists outgoing links from a specific note, distinguishing it from siblings like get_backlinks_tool (which finds backlinks) and find_broken_links_tool (which searches across notes).
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 provides 'When to use' and 'When NOT to use' sections, including concrete scenarios and alternative tools, giving clear guidance on 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?
With no annotations, the description bears full responsibility. It explains how removal works for inline vs full-line fields, canonicalized matching, and the effect of providing line_number. It also mentions return values. It does not mention reversibility or permissions, but this is sufficient for a mutation tool.
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 first sentence, then a breakdown of behavior, usage guidelines, and return info. Every sentence is relevant and no filler. It is concise yet informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters and no output schema, the description covers purpose, behavior, usage scenarios, and return values well. It could elaborate on error conditions or side effects, but overall it is comprehensive.
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 80%, and the description adds context by explaining canonicalized matching and the optional line_number's role. It ties parameters to behavior, e.g., how key and line_number affect removal. This adds value beyond the schema's base descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Remove a Dataview inline field from a note'. It specifies the verb 'remove', the resource 'Dataview inline field', and the context 'from a note'. It also distinguishes from sibling tools like add_dataview_field_tool and extract_dataview_fields_tool by being explicitly about removal.
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 includes a 'When to use:' section listing specific scenarios like cleaning up metadata and migrating fields. However, it does not explicitly state when not to use the tool or provide alternatives, which would make it 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?
No annotations provided, so description carries full burden. It discloses creation, update, add behavior, supported types, and performance (<200ms). Adds value beyond schema without contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections for purpose, when-to-use, performance, and returns. Concise and front-loaded with no unnecessary content.
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 behavior, types, performance, and return value. Lacks details on error handling or 'ctx' parameter, but overall adequate for a 5-parameter tool without output schema.
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 80%, and description reinforces with examples for field and value, and mentions environment variable for vault_path. Context on 'ctx' missing but overall adds meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool updates or adds a field in note's YAML frontmatter, with specific verb and resource, and distinguishes from siblings that modify notes in other ways.
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?
Includes a 'When to use' section listing specific scenarios like updating note status or adding timestamps, providing clear guidance. Does not explicitly state when not to use or name alternatives, but context is sufficient.
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 provided, so description fully bears the burden. It details three syntax variants, value type detection, code block skipping, and performance metrics (<100ms/note, 10k fields/sec). Also states return structure, ensuring transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-organized with sections: purpose, syntax variants, behavior, use cases, performance, return. Every sentence adds value, no redundancy. Front-loaded with key 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?
With no output schema, description fully explains return values (fields, keys, values, types, syntax, line numbers). Covers performance and edge cases (code blocks). Complete for an extraction tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% (file_path and vault_path have descriptions, ctx only has title). Description adds little beyond schema; vault_path default behavior is implied in schema. For ctx, no additional meaning. Baseline 3 due to coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Extract all Dataview inline fields'), the resource ('from a note'), and distinguishes from siblings like execute_dataview_query_tool and search_by_dataview_field_tool by focusing on field extraction and offline capability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'When to use' scenarios (extracting metadata, auditing, migrating), though lacks explicit 'when not to use' or alternatives. Still, the context is clear and covers primary use 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?
No annotations provided, so the description carries the burden. It implies read-only behavior and advises using before updates to preserve content. However, it does not explicitly state it is non-destructive or mention any potential side effects, but the context is clear.
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 bullet points for usage guidance and a returns section. Each sentence adds value, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description covers return values (content, metadata, tags, aliases, frontmatter). Distinguishes from key siblings and provides sufficient context for a read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (ctx parameter undocumented). The description adds examples and constraints for path but does not explain ctx. Baseline 3 is appropriate as it partially compensates.
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 'Read the content and metadata of a specific note.' It uses a specific verb and resource, and explicitly distinguishes from sibling tools like search_notes and get_note_info.
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 scenarios (displaying, analyzing, before updating, verifying existence) and when-not-to-use conditions (searching multiple notes, getting only metadata) with named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description takes full responsibility for behavioral disclosure. It includes performance metrics (1k notes <3s, 10k <30s), details the metadata format, and specifies the return structure (tasks with metadata, file locations, line numbers). It implies read-only behavior but does not explicitly state it, slightly reducing completeness.
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-organized into clear sections: purpose, metadata format, use cases, performance, and returns. Each section provides essential information without redundancy, and the structure is front-loaded with the core functionality.
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 12 parameters with high schema coverage and no output schema, the description compensates by detailing return values (tasks with full metadata, file locations, line numbers) and providing performance benchmarks. It covers typical use cases comprehensively, making it self-sufficient for the 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?
The input schema already describes parameters well (92% coverage). The description adds value by explaining the Tasks plugin metadata format (emoji symbols for priority and dates), which clarifies the meaning of filters like priority and due dates beyond the schema's enum values and date 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 clearly states it searches and filters tasks by metadata across the vault, distinguishing it from sibling tools like search_notes_tool (note content search) and get_task_statistics_tool (statistics). It specifies filesystem-native, offline operation, and Tasks plugin metadata, 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?
The description provides explicit use cases (overdue tasks, high-priority tasks, weekly schedules, recurring reviews) which guide when to use this tool. However, it does not explicitly state when NOT to use it or mention alternative tools, which would have improved the score further.
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 provided, but the description details how it works (walks directory, uses generator-based iteration, excludes .obsidian) and includes performance estimates. This fully compensates for missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections, bullet points for returns and use cases. Each sentence adds value; no redundancy. Front-loaded purpose and returns.
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?
Despite no output schema, description lists all return fields. Covers performance, exclusions, and usage intent. Complete for the tool's single-purpose aggregation function.
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 50% (vault_path described, ctx not). The description adds meaning by noting vault_path is optional and defaults to env variable, but fails to explain the ctx parameter. Partial compensation.
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 gets aggregate statistics for the entire vault and lists specific metrics (total notes, words, links, tags, average words). It implicitly distinguishes from sibling note_statistics_fs_tool by focusing on vault-wide aggregation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use scenarios like understanding vault size, content inventory, and tracking growth. Does not mention when not to use or alternatives, but the use cases are clear and helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that it creates all necessary parent folders and returns creation status. However, it does not mention what happens if a folder already exists or any permission requirements, which would strengthen transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clear sections for usage, not-usage, and returns. It is concise yet thorough, with every sentence adding 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 no output schema, the description covers purpose, usage, behavior, and return format. It could be improved by detailing error scenarios or the exact placeholder file behavior (e.g., .gitkeep vs README.md), but overall it is sufficiently complete for a folder creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%, so baseline 3. The description adds value by explaining that folder_path supports nested paths and that placeholder creation defaults to true. However, the 'ctx' parameter is not described, and the schema already covers the other two parameters adequately.
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 creates a folder including all parent folders. It distinguishes itself from sibling tools like create_note_tool by focusing on folder creation only, and provides explicit examples of when to use.
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 lists when to use (e.g., setting up project structure, deep hierarchies) and when NOT to use (e.g., when notes create folders automatically). This provides clear decision rules for the agent.
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 provided, so description carries full burden. It discloses performance estimates for each depth level, mentions 'filesystem-native, offline', describes the return type (connection graph with multi-level links and depth annotations), and explains that it provides both inlinks and outlinks.
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 clear sections: depth explanation, usage scenarios, performance expectations, and return description. Every sentence adds value and is front-loaded with the most important information (depth behavior).
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?
Despite no output schema, the description adequately explains what the tool returns (connection graph with depth annotations). Given the tool's complexity (4 parameters, multi-level graph building), the description provides sufficient context for an AI agent to understand and use 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?
Input schema covers 75% of parameters with descriptions (note_name, depth, vault_path). The description adds semantic context beyond schema by explaining depth levels and the relationship between parameters (e.g., note_name is the starting point). ctx parameter is undocumented but appears optional and not critical.
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 gets a connection graph for a specific note, with explicit depth levels (1=direct, 2=second-degree, 3=third-degree). It distinguishes from sibling tools like get_backlinks_tool and get_outgoing_links_tool by focusing on multi-level connections.
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 dedicated 'When to use' section listing four clear use cases (understanding relationships, exploring neighborhoods, finding related content, building visualizations). Missing explicit 'when not to use' or alternatives, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It explains the merge flag behavior and return values (previous/new tags, operation). However, it does not mention that the note file is modified or any potential side effects like overwriting, though the behavior is clear enough for a tag update.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and well-structured with bullet points for usage guidelines. Every sentence adds value, and the formatting aids quick scanning. No 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?
Given no output schema, the description provides return info (Previous tags, new tags, operation performed). It thoroughly explains the two modes and usage context, making the tool fully understandable without external references.
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 75% (ctx parameter lacks description but is optional without default). The description adds value by explaining the merge parameter behavior and clarifying that tags are without # prefix (though schema also says that). It compensates adequately for the missing ctx documentation.
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 updates tags on a note, specifying two modes (replace all or merge). It explicitly distinguishes itself from sibling tools add_tags and remove_tags, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use scenarios (e.g., after analyzing content, reorganizing tags) and when-not-to-use cases (e.g., adding few tags, removing specific tags), directly referencing sibling tools for 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?
No annotations provided, so description carries full burden. Discloses performance characteristics based on vault size and mentions use of batched concurrent requests, adding valuable behavioral context beyond a simple read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections: main purpose, when to use, when not to use, performance note, and returns. Every sentence adds value, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all essential aspects: purpose, usage guidelines, behavioral traits (performance), and return values. No output schema but returns are described sufficiently. Complete for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 67% description coverage (2 out of 3 parameters described). Description adds context about usage counts and sorting in 'Returns' section, but does not detail parameter defaults or formats beyond schema. Still, it compensates adequately with provided use cases.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'List all unique tags used across the vault with usage statistics.' It uses a specific verb and resource, and distinguishes well from sibling tools like add_tags_tool and search_notes_tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'When to use' and 'When NOT to use' sections with bullet points and alternative tool names, offering clear guidance on invocation 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?
With no annotations, the description fully discloses default replace behavior, the merge_strategy parameter, and return value. The warning about replacement is prominently highlighted.
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?
Concise with clear sections and bold/emoji for emphasis. Every sentence adds value, with 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?
Given no output schema, the description adequately describes return value (update status, path, metadata, operation). Covers all key behaviors and edge cases.
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 high (80%), but the description adds value by emphasizing the replace behavior and merge options beyond schema definitions. The ctx parameter lacks description but is less critical.
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 'Update the content of an existing note' and specifies operations like replace and append. It distinguishes from sibling tool 'create_note' by noting when not to use it.
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 lists when to use (new content, append, programmatic) and when not to use (small edits, creating new notes). Includes important prerequisite: 'Always read the note first if you need to preserve existing content.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

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

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

Card Badge

Copy to your README.md:

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

Score Badge

Copy to your README.md:

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

Latest Blog Posts

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

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/aleksakarac/obsidian-mcp'

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