Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the disclosure burden. It clearly states the mutating action ('append') and the non-destructive create-if-missing behavior, which is valuable context. However, it does not mention return values, permissions, or directory creation, leaving some gaps for a write tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences with no filler. The primary action is front-loaded, and the edge-case behavior (creating missing files) is added efficiently. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple, and the schema covers parameters fully. The description explains the core behavior and an important edge case, which is sufficient for correct invocation. Given no output schema or annotations, a bit more detail on return values could improve it, but it is largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with all three parameters well-documented. The description adds no additional meaning beyond the schema; it merely restates the append action. Baseline 3 applies because the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses the specific verb 'append' and resource 'file', clearly distinguishing it from siblings like put_content (which likely overwrites). The additional clause 'Creates the file if it does not exist' clarifies behavior, 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The append semantics imply when to use the tool (add content to a file, create if missing), but there is no explicit comparison to put_content or other alternatives. No exclusions or when-not scenarios are stated, so guidance is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 the observable behavior of concatenating contents with headers, but does not explicitly state that it is read-only, how errors are handled, or what the header format looks like. The read-only nature 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the core purpose. Every word earns its place with no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple batch read tool with two well-documented parameters and no output schema, the description covers the essential return formatting (headers, concatenation). It could mention behavior on missing files or an explicit alternative to get_file_contents, but overall it's sufficient for a tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both vaultId and filepaths adequately described in the input schema. The description adds no additional parameter details, which is acceptable given the schema's thoroughness.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action ('Return the contents') and resource ('multiple files') with a distinctive behavior ('concatenated with headers'). This differentiates it from sibling tools like get_file_contents, which handles a single file.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'multiple files' implies the tool is for batch reading, which provides some context. However, there is no explicit mention of when to use this instead of get_file_contents or other alternatives, nor any exclusions or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of disclosing behavioral traits. It indicates a read operation ('Search') and mentions operator support, but does not describe the return format, potential performance concerns, or search scope (e.g., file names vs. content).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences, front-loaded with the main action and followed by a key feature. Every word earns its place; no redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with nested JsonLogic query objects and no output schema, the description is somewhat minimal. It adequately explains purpose and operator capabilities, but lacks information about return values or when to prefer it over simpler search tools, leaving some gap for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already covers both parameters with descriptions (100% coverage), so baseline is 3. The description adds value by explicitly mentioning regexp support, complementing the schema's glob example and enriching the query parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Search') and the specific query mechanism (JsonLogic), distinguishing it from sibling search tools by mentioning glob and regexp operators. However, it doesn't explicitly state what is being searched (e.g., 'files in vault'), which would make it fully explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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 like 'search', 'pattern_search', or 'semantic_search'. It implies usage through the name and mentions supported operators, but lacks explicit when-to-use or when-not-to-use context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully carries the transparency burden. It discloses recursive deletion, single-call operation, and importantly the timeout verification behavior ensuring the response reflects actual post-condition. This is exemplary given the destructive nature of the tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise yet packed with useful information across three sentences, front-loading the primary purpose and adding crucial behavioral details without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a straightforward delete tool with two parameters and no output schema, the description provides sufficient context: it explains recursion, the single-call nature, and the post-condition guarantee. While it does not cover error cases explicitly, the timeout verification statement implicitly addresses outcome reporting, making it complete for its complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers 100% of parameters, so the baseline is 3. The description reinforces the recursive behavior for filepath but does not add significant new parameter-level details beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool deletes a file or directory from the vault, with specific detail on recursive behavior. It effectively distinguishes itself from all sibling tools, none of which perform deletion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool, especially for recursive directory deletion, and clarifies that no prior emptying is needed. However, it does not explicitly discuss alternatives or when not to use the tool, though no alternative delete tool exists.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It mentions the required environment variable and graph-analysis approach, but does not disclose whether the operation is read-only, what the return format is, or how failures (e.g., missing vault path) are handled.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that front-loads the primary action and includes the necessary prerequisite without unnecessary detail. Every part earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with only two optional parameters and no output schema, the description gives the core concept but omits expected return values and edge-case behavior. Given the complexity of graph analysis, additional context about output semantics (e.g., what a cluster looks like) would be helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers 100% of parameters with descriptions for vaultId and minClusterSize. The description adds no parameter-level information beyond what the schema already provides, so it meets the baseline but does not enhance it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool detects communities/clusters of related notes using graph analysis, with a specific verb and resource. It distinguishes itself from sibling tools like find_similar_notes or get_most_connected_notes by focusing on clusters/communities rather than pairwise similarity or ranking.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a prerequisite (OBSIDIAN_VAULT_PATH must be set) but provides no explicit guidance on when to use this tool vs alternatives like semantic_search or find_similar_notes. Usage context is implied by the description itself but lacks exclusions or alternative references.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden for behavioral disclosure. It adds useful context that commands execute in a specific order and that note-operating commands require an open note. However, it does not disclose what happens on failure (e.g., whether execution aborts), whether there are side effects, or any permission requirements. This is a moderate level of transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, each serving a distinct purpose: the first states the tool's action and sequencing, the second gives a critical usage tip. It is concise, front-loaded with the verb, and contains no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given there is no output schema and no annotations, the description should explain return behavior and error handling to fully equip an agent. It does not mention what the tool returns (success/failure, results), what happens if a command fails, or whether it requires Obsidian to be running. For a tool that executes potentially side-effectful commands, this is a significant gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%: both vaultId and commands have descriptions. The tool description does not add parameter-level meaning beyond the schema; it merely reiterates that commands are Obsidian commands. Therefore, the baseline of 3 applies, as the schema already documents parameters adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Execute' with resource 'Obsidian commands' and adds 'in order' to clarify sequencing. This clearly distinguishes it from sibling tools like list_commands, which only lists commands, and content-modification tools like put_content or append_content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear usage condition: 'For commands that operate on notes, open a note first.' This indicates when a prerequisite step is needed and implies that executing such commands without an open note may not work. However, it does not explicitly compare with alternatives, such as using list_commands to discover command IDs, so it stops short of a full when-to-use vs alternatives explanation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so thoroughly: it discloses in-place rewriting, last-write-wins concurrency overwrites, dot-directory exclusions, case-sensitivity, and the 5MB per-file cap. This is far beyond minimal disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but each sentence earns its place for a destructive tool. Safety guidance is front-loaded ('DESTRUCTIVE' warning, dryRun first). Minor redundancy with schema text (e.g., pathPrefix case-sensitivity) costs the fifth point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 12 parameters and no output schema, so return behavior must be self-described. The description covers dryRun structured previews and verbose per-file arrays, but does not fully describe the non-dryRun success response or no-match case. Overall it is rich but has a small gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds operational meaning beyond the schema: dryRun previews, per-file size cap, dot-directory exclusions, and vault-wide scope, which help the agent interpret parameters like dryRun and pathPrefix.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Find and replace text vault-wide across every .md file', which names a specific verb, resource, and scope. This clearly distinguishes it from read-only siblings like search, patch_content, and append_content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides strong context: run dryRun first, ensure clean git tree/backup, close Obsidian/pause sync before mutations. It does not explicitly name alternatives like 'use search for read-only queries', so it stops short of a full when/when-not matrix.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of behavioral disclosure. It does describe the tool's core behavior (scanning for notes without links) and the environment requirement, but it does not disclose side effects, return format, pagination, or performance implications. This is moderate transparency but leaves some gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences, front-loaded with the primary action. The second sentence adds a necessary environmental precondition. No redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with no output schema, the description should clarify what the tool returns (e.g., note paths, names, counts). While the env var prerequisite and core behavior are mentioned, the lack of return format reduces completeness. The 0 required params make invocation easy, but the output is unspecified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides full descriptions for both parameters (vaultId and includeBacklinks), so coverage is 100%. The description adds no additional parameter-specific meaning beyond the schema, only reiterating the 'targeted vault' concept. Baseline 3 is appropriate since schema handles parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds 'notes with no incoming or outgoing links', which is a specific verb and resource. This differentiates it from siblings like get_note_connections or find_similar_notes, which focus on connections or similarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions an explicit prerequisite (OBSIDIAN_VAULT_PATH must be set), which is helpful context. However, it does not provide guidance on when to use this tool versus alternatives like get_note_connections or detect_note_clusters, nor does it mention exclusions or specific use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description shoulders the transparency burden. It discloses meaningful behavior: the environment variable requirement and the distinction between a 'note not found' precondition error and a 'no path between endpoints' outcome. It does not, however, describe the success return format or whether there are side effects (likely none).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, front-loaded with the primary action, and each sentence contributes distinct information (purpose, prerequisite, error semantics). There is no redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

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 moderate complexity, the description covers purpose, key prerequisites, and error behavior, which is fairly complete. Gaps include the lack of explicit success return shape and precise semantics of 'link path' or maxDepth, though the schema partially addresses maxDepth. Overall, sufficient for an agent to use correctly in most cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides descriptions for all 4 parameters (100% coverage), so the baseline is 3. The description adds context about OBSIDIAN_VAULT_PATH that relates to the vaultId parameter, but does not further explain source, target, or maxDepth beyond the schema. The added value is marginal.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear and specific action: 'Find the shortest link path between two notes.' This distinguishes it from siblings like get_note_connections (which likely retrieves connections for a single note) by the focus on path-finding between two endpoints. The purpose is immediately transparent.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions a prerequisite (OBSIDIAN_VAULT_PATH) and contrasts two error conditions, providing some contextual guidance. However, it does not explicitly state when to use this tool versus alternatives like get_note_connections or search, nor does it describe exclusions or fallback scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the core action and does not explain how similarity is computed, return format, sorting, error handling, or that it is a read-only operation. The description lacks meaningful 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, directly states the action, and contains no fluff. Every word contributes to understanding the tool's purpose, making it efficiently sized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

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 is too brief. It does not clarify the return value, ranking behavior, default thresholds, or error cases. While parameters are well-documented, the overall context for the agent is incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers 100% of parameters with descriptions for filepath, limit, threshold, and vaultId. The description text adds no parameter-level meaning, so it does not go beyond what the schema already provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Find') + resource ('notes') + qualifier ('semantically similar to a given note'). It clearly distinguishes from sibling tools like semantic_search by indicating the input is an existing note (filepath) rather than a free-text query.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage context is implied: use when you have a note and want to find semantically related notes. However, there is no explicit when-to-use vs alternatives, nor exclusions or comparison to sibling tools like semantic_search or search.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the action without describing the return format, edge cases (e.g., no active file), or confirming read-only behavior. This leaves significant behavioral ambiguity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that does not waste words. It is front-loaded and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple get tool with one optional parameter and no output schema, the description provides sufficient context for basic invocation. However, it lacks usage guidance and behavioral details, so it's not exhaustive, but adequate for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage for the single optional vaultId parameter, which has its own description. The tool description adds no additional parameter semantics, so the baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Get') and a clear resource ('currently active file in Obsidian'), which distinguishes it from sibling tools like get_file_contents or open_file. It clearly states what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no explicit guidance on when to use this tool versus alternatives. The usage is implied by the name and description, but there are no exclusions or alternative suggestions, making it a 3.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description bears full burden. It accurately states the read-only nature ('Returns the content'), but does not disclose edge cases such as missing files, encoding issues, or size limits. It is minimal but not misleading.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no filler. Every word contributes meaning, making it highly concise and readable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-file read with two well-documented parameters, the description is largely sufficient. However, the lack of an output schema means the return format (e.g., raw string, text content) is not clarified, leaving a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for both parameters (vaultId and filepath), so the description adds no additional semantic value beyond what the schema already provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Returns') and resource ('content of a single file'), clearly distinguishing it from siblings like batch_get_file_contents or put_content. It is unambiguous about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'single file' implies a distinction from batch operations, but the description offers no explicit guidance on when to use this tool versus alternatives like batch_get_file_contents or get_heading_contents. Context is clear but exclusions are absent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries the full burden. It discloses key behaviors: type preservation of the return value and propagation of upstream 4xx errors. It doesn't mention auth or rate limits, but those are likely less relevant for a simple getter; the provided disclaimers are valuable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core action, and every phrase earns its place. It efficiently conveys the return type, error behavior, and a sibling alternative without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read tool with well-described parameters and no output schema, the description covers the essential context: what is returned, type preservation, error handling, and an alternative for broader reads. The tool is simple enough that this is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for all parameters (filepath, field, vaultId). The description adds no parameter-level semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Returns') and identifies the resource ('named frontmatter field's value') with added detail about type preservation. It also distinguishes itself from sibling get_file_contents by noting that tool reads all fields at once.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies when to use this tool (reading a single field) and explicitly recommends an alternative for reading all fields. It does not explicitly say 'use this when you need one field' but the guidance is clear enough to steer the agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 the return content (raw markdown body), exclusions (frontmatter, tags, metadata), path constraints, and unreachable cases. This is comprehensive behavioral transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is somewhat long but well-structured, front-loading the action and then providing exclusions and constraints. Every sentence adds value, though the 'unreachable' cases could be slightly more compact. It is appropriately sized for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with significant behavioral constraints (heading path format, unreachable top-level headings, literal '::' limitations), the description covers all necessary context. It explains what is returned, what is excluded, and exactly when to use alternatives. The absence of an output schema is acceptable since the return type (raw markdown body) is implicitly clear.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description reinforces the heading format and adds context about when to use fallbacks, but it does not add meaning beyond what the schema already provides. It meets the baseline without exceeding it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Returns the raw markdown body content under the targeted heading.' It also explicitly differentiates from sibling tools like get_file_contents (whole note) and get_frontmatter_field (frontmatter values), 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use guidance, including exclusions: top-level headings and headings containing '::' are unreachable, with direct fallback instructions to get_file_contents. This is outstanding usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry the burden of behavioral disclosure. It adds the environment requirement for OBSIDIAN_VAULT_PATH, which is useful. However, it does not explicitly state read-only behavior, return format, or potential side effects, though the verb 'get' implies a safe read operation. The omission of output details is notable since no output schema is provided.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that efficiently conveys the tool's purpose and a critical environment prerequisite. No redundant wording or filler; every word contributes to the core message.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is minimally viable: it states what the tool does and the environment requirement, but lacks details about the return structure, how metrics are computed, or when to use this tool versus graph-focused siblings. Given the absence of an output schema and annotations, more contextual guidance would improve completeness, yet the core purpose is clear enough for straightforward use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema fully describes all three parameters with detailed descriptions and an enum for metric, so the description adds little beyond what is already structured. The description's mention of 'link count or PageRank' actually under-covers the metric parameter by omitting 'backlinks', which is a minor inconsistency. Baseline 3 applies due to high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves the most connected notes and specifies the ranking options as 'link count or PageRank'. This identifies a distinct purpose from sibling tools like get_note_connections, which targets connections for a specific note. However, it does not explicitly differentiate from siblings and omits the 'backlinks' metric from the schema enum.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a key prerequisite by noting that OBSIDIAN_VAULT_PATH must be set for the targeted vault. No guidance is given on when to choose this tool over alternatives like get_note_connections or find_path_between_notes, nor are any exclusions mentioned. The usage context is implied but not fully articulated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 discloses a prerequisite (OBSIDIAN_VAULT_PATH) and a specific error format ('note not found: <path>'), and clarifies the distinction between 'found but no connections' and 'no path between endpoints'. This is substantial behavioral context, though it does not mention rate limits, return structure, or mutation behavior (though 'Get' implies read-only).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core purpose, and every clause adds value. It is concise without being underspecified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the main purpose, prerequisite, and error behavior. There is no output schema, so the description does not reveal the exact response format, but it gives enough for an agent to select and interpret the tool's core behavior. The tool is relatively simple, and the description is complete for typical use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters. The description adds a small amount of meaning by clarifying what 'connections' includes (outgoing links, backlinks, tags), but this is not essential for parameter understanding. The baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states what the tool does with a specific verb and resource: 'Get all connections for a note'. It enumerates the types of connections (outgoing links, backlinks, tags) and distinguishes from sibling tools like get_file_contents and find_path_between_notes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context by stating the prerequisite (OBSIDIAN_VAULT_PATH) and by differentiating its error behavior from 'no path between endpoints', which hints at a distinction from path-finding tools. However, it does not explicitly state alternative tools or when-not-to-use conditions, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 only says 'Get', which implies a read operation, but it does not disclose whether the tool creates a note if missing, what the default return type is (content vs metadata), or any edge-case behaviors. The lack of detail makes side effects unpredictable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single succinct sentence with no redundant wording. It is front-loaded with the primary action, but its brevity borders on under-specification for a tool with multiple parameters and a sibling alternative. Still, it earns near-top marks for conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no output schema and no annotations, yet the description provides only the basic operation. It omits crucial context such as the distinction between content and metadata returns, how 'current' is determined, and the tool's relationship to get_recent_periodic_notes. This is incomplete for an agent to invoke the tool confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides 100% coverage with descriptions for all three parameters, including enums for type and period. The description adds no extra parameter-level meaning beyond what the schema already offers, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'periodic note', with a specifier for the period. It distinguishes the tool's core function but doesn't explicitly differentiate it from the sibling tool get_recent_periodic_notes, leaving some ambiguity about 'current'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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 like get_recent_periodic_notes. There is no mention of exclusions, prerequisites, or specific use cases that would help an agent choose this tool appropriately.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It only states the basic action, omitting defaults (e.g., 90 days, limit 10), sort order, return format, or whether folders are included. This is comparable to the mid-tier 'update_drive' example, which also scored 2 for missing such context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no redundant words. It effectively communicates the core purpose while staying appropriately sized for a simple list tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations and no output schema, the description must supply more context but doesn't. It fails to explain what 'recently modified' means (timeframe, file types), whether it returns paths or content, or how the result is structured. This leaves the agent with significant ambiguity about the tool's behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (all three parameters have descriptions), so the description doesn't need to add parameter details. Per the baseline rule, a score of 3 is appropriate when the schema fully documents parameters and the tool description doesn't contradict or mislead.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Get recently modified files in the vault' uses a specific verb ('get') and resource ('recently modified files'), clearly distinguishing it from sibling tools like list_files_in_vault or get_vault_structure. The purpose is unambiguous and directly aligns with the tool name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives such as search or list_files_in_vault. The description provides no context for choosing this tool, no exclusions, and no mention of use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 does not mention the default limit, whether content is included by default, ordering behavior, or what happens when no notes are found. The description is too sparse to convey these important 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that is front-loaded with the action and resource. It contains no unnecessary words or repetition, making it highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 4 parameters, no output schema, and no annotations, the description is insufficiently complete. It does not explain the return format, default behavior, or how the tool differs from related tools. Agents may not know what 'recent' means or whether metadata vs content is returned.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description does not add meaning beyond the schema; the mention of 'specified period type' merely echoes the 'period' parameter. It does not clarify the semantics of 'most recent' or how 'limit' and 'include_content' interact.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Get most recent periodic notes for a specified period type.' The verb 'Get' and the resource 'most recent periodic notes' are specific. It distinguishes from sibling 'get_periodic_note' by indicating multiple recent notes rather than a single note.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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 such as 'get_periodic_note' or 'search'. It merely states what it does, leaving the agent without explicit context on when this tool is the appropriate choice or any exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite no annotations, the description discloses a key requirement (OBSIDIAN_VAULT_PATH must be set) and the read-only nature of the operation is clear from 'Get'. It does not state performance implications or confirm lack of mutation, but for a stats tool no side effects are apparent. It adds the environment prerequisite which is valuable context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with the core purpose, and lists outputs compactly. Every word contributes.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

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, it lists the five statistics returned and the required environment variable. However, it does not specify the output shape (e.g., counts vs arrays), which could be ambiguous for an agent. Still, enough for a basic understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema documents the single optional vaultId parameter with a description (100% coverage), so the baseline is 3. The tool description provides no additional parameter semantics beyond the schema, so it neither helps nor hurts.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides overview statistics (total notes, links, orphans, tags, clusters) about a vault. This distinct, specific purpose differentiates it from sibling tools like find_orphan_notes or detect_note_clusters, which focus on individual detailed operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies a use case for high-level vault metrics but does not explicitly contrast with alternatives or mention when to use them. It does provide a clear prerequisite (OBSIDIAN_VAULT_PATH) that helps an agent decide if the tool is usable. However, it lacks explicit 'use this instead of X' guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does disclose an environmental requirement (OBSIDIAN_VAULT_PATH), which is useful, but it does not describe the response format, whether files are included by default, or any side effects. Given it is a read operation, the lack of detail is a gap but not critical.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, consisting of two sentences with no fluff or redundant information. Every word earns its place, and it is front-loaded with the core purpose. This is an example of ideal conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description should ideally clarify what the returned tree structure looks like (e.g., nested objects, relative paths). However, for a straightforward 'get structure' tool with optional parameters and a clear prerequisite, the description is adequate for basic usage but lacks completeness regarding return format and edge cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all three parameters (vaultId, maxDepth, includeFiles) are already documented in the schema. The description does not add any additional meaning or context beyond what the schema provides, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: getting the folder tree structure of the vault. It uses a specific verb ('get') and resource ('folder tree structure'), which distinguishes it from sibling tools like list_files_in_vault (flat list) and list_files_in_dir (specific directory). However, it does not explicitly name any alternative tools, so it lacks explicit sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a prerequisite (OBSIDIAN_VAULT_PATH must be set) and implies usage for retrieving folder hierarchy, but it does not explicitly state when to use this tool versus alternatives such as list_files_in_vault or list_files_in_dir. There are no exclusions or alternative tool references.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry the burden of behavioral disclosure. 'List' implies a read-only operation, but it does not explicitly state safety, side effects, or return format. The note-opening hint adds context but is more about using the listed commands than the behavior of this tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences front-load the core function and add a practical caveat. No redundant wording, perfectly sized for the tool's simplicity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given low complexity and no output schema, the description adequately conveys what the tool returns (list of commands) and the necessary precondition. It could mention the format of returned commands, but for a listing tool this is not a critical gap. The sibling context is clear enough from the description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with vaultId already described as 'Optional vault ID (defaults to configured default vault).' The description adds no additional parameter meaning beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb+resource ('List all available commands in Obsidian') and clearly distinguishes it from sibling tool execute_command, which runs commands. The purpose is immediately obvious without ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The second sentence provides a clear prerequisite: 'For commands that operate on notes, open a note first.' While it doesn't explicitly name alternatives, the contrast with execute_command is implied. The guidance is actionable and helpful for the user.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must carry the burden of behavioral disclosure. It states the core action but does not mention whether the listing is recursive, how hidden files are handled, or what happens if the path is invalid. The schema's note about empty directories adds some context, but the description itself lacks depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that effectively states the tool's purpose without unnecessary words. It is front-loaded with the key action and resource.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple listing tool, the description is adequate. The schema covers parameter semantics, and the tool's behavior is reasonably clear. However, missing details about recursion or return format prevent a perfect score, as these are common ambiguities for directory listing tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with clear descriptions for both dirpath and vaultId. The description adds no additional parameter-level meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the action ('lists all files and directories') and the target resource ('a specific directory within your Obsidian vault'). It distinguishes this from sibling tools like list_files_in_vault by emphasizing the scoped directory focus.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for inspecting a single directory, but it does not explicitly state when to choose this over alternatives like list_files_in_vault or get_vault_structure. The context is clear enough to infer, but there are no explicit exclusions or alternative mentions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It correctly implies a read-only operation ('Lists') and non-recursive root-level scope, but it does not clarify details such as whether hidden files are included, the output format, or behavior with an invalid vaultId. It adds basic behavioral context but lacks completeness.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no unnecessary words. It efficiently conveys the core purpose without wasting tokens.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one optional parameter, no output schema), the description is mostly complete. It states what the tool does and the scope. However, without an output schema, it does not describe the return format (e.g., relative vs absolute paths), which is a minor gap. Overall, it is adequate for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter (vaultId) is fully described in the schema (100% coverage), so the description need not repeat it. The tool description does not add extra semantic detail about the parameter beyond the schema, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Lists') and the specific scope ('all files and directories in the root of your Obsidian vault'). This distinguishes it from siblings like list_files_in_dir (which targets a specific directory) and get_vault_structure (which implies a broader or recursive tree). The use of 'root' clarifies the non-recursive scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by specifying 'root', but it does not explicitly mention alternatives or exclusions. There is no phrase like 'for subdirectories, use list_files_in_dir'. The usage guidance is only inferred from the scope wording, not explicitly stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does so excellently. It discloses the data source (Local REST API GET /tags), inclusion rules (inline and YAML tags), exclusion rules (fenced code blocks), and hierarchical tag counting behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences deliver a precise definition, source attribution, behavior contrasts, and hierarchical behavior—all without unnecessary filler. The information is front-loaded and each sentence contributes meaningful detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one optional parameter and no output schema, the description is remarkably complete. It explains what is returned (tags with counts), how the result is sourced, edge cases (code blocks), and hierarchy behavior, leaving little ambiguity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter (vaultId) is fully described in the schema with 100% coverage, so the description adds no extra parameter-level detail. This meets the baseline for schema-driven parameter clarity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'List every tag present in the vault, together with its usage count.' It clearly distinguishes this tool from sibling search tools by emphasizing tag enumeration through Obsidian's index.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains that the tool is more accurate than text or frontmatter search for tag enumeration, giving clear context on when to prefer it. However, it does not explicitly state when NOT to use it or mention alternative scenarios beyond search.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It communicates that the tool lists all vaults and returns their IDs and capabilities, implying a read-only operation. However, it does not disclose any potential side effects, authentication requirements, or limitations, though the simple nature of the tool likely makes these minimally relevant.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that efficiently conveys the tool's purpose and output. Every word earns its place, with no redundancy or extraneous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple no-parameter tool without an output schema, the description adequately covers what the tool does and what it returns. It mentions IDs and capabilities, which is sufficient for basic invocation. The description is complete enough given the tool's straightforward nature.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema is trivially 100% covered. No parameter descriptions are needed, and the baseline of 4 applies here because there is nothing for the description to add about parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action ('List all configured Obsidian vaults') with a distinct resource and additional output details ('with their IDs and capabilities'). It distinguishes itself from sibling tools like list_files_in_vault or get_vault_stats by focusing on vaults themselves rather than their contents or statistics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool: to discover all configured vaults. While it doesn't explicitly state when not to use it or name alternatives, the phrasing and resource specificity make the usage context obvious without needing exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 does not state whether opening a file has side effects (e.g., changing the active pane), requires specific permissions, or what the return behavior is. This is a significant transparency gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no wasted words. It is maximally concise and avoids redundancy, earning a perfect score for structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple nature of the tool, the description still incomplete. It lacks critical context such as what 'open' implies versus 'read', return values, error handling, and how it relates to sibling tools. Without annotations or an output schema, this minimal description is insufficient 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides 100% description coverage for both parameters, so the baseline is 3. The description itself adds no additional meaning beyond what the schema already defines, but it does not need to compensate for any gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Open') and the resource ('a file in Obsidian'), making it specific and unambiguous. However, it does not explicitly differentiate from sibling tools like get_file_contents, which could lead to confusion about whether 'open' means read or open in the UI.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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, no prerequisites, and no exclusions. It simply states the action without contextual direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 goes beyond basic function by revealing important constraints: the requirement for at least two heading segments, the unreachability of top-level headings and headings with literal '::', and the lack of escape syntax. This gives the agent critical knowledge about edge cases and limitations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, with three sentences total. It front-loads the main purpose, then addresses constraints with specific examples and an explicit alternative for a common edge case. Every sentence earns its place with no redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (6 parameters, 2 enums) and the absence of an output schema, the description adequately covers the core behavior and the most important edge cases. It clearly delineates the valid target format and provides an alternative for unsupported targets. No significant information gaps remain for an agent to correctly select and invoke this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already covers all parameters with descriptions (100% coverage), so the baseline is 3. The description adds value by providing a concrete example of the heading path format ('H1::H2[::H3...]') and reiterating the critical validator behavior, which slightly exceeds what the schema describes. However, it doesn't add much for other parameters, so it doesn't merit a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Insert content relative to a heading, block, or frontmatter in a file.' This specifies the action (insert), the resource (content in a file), and the context (relative to specific target types), distinguishing it from sibling tools like put_content or append_content which target entire files or append at the end.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance by stating when NOT to use the tool ('Top-level headings (no parent) are unreachable through this tool') and names the alternative ('use get_file_contents + put_content for those edits'). It also warns about a specific edge case (headings containing '::') and explains the path format requirement, giving clear context for when to use this tool versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full responsibility for disclosing behavior. It mentions 'extraction with context' but does not state whether the tool is read-only, what the return format is, default behavior, or limitations, which is a significant gap for a tool with no annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences, with the first stating the core function and the second listing use cases. It is front-loaded and contains no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has a moderately complex schema with nested objects and no output schema, so the description should explain expected return values, defaults, and operational context. The terse summary leaves the agent to infer critical behavior from the schema alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds no parameter-level detail beyond the schema. With schema description coverage at 50%, the description should compensate for undocumented parameters, but it does not mention patterns, scope, options, or vaultId at all.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('extraction') and resource ('pattern') with 'Regex' to define what the tool does. The use cases (data mining, format analysis, content auditing) clarify the intended purpose, but it does not explicitly distinguish from sibling search tools such as 'search' or 'complex_search'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'Use for...' gives some context on when to use the tool, but it lacks explicit exclusion or comparison with alternative tools. Given the presence of numerous sibling search and extraction tools, missing selection guidance leaves usage somewhat ambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 the destructive 'overwrite entire content' behavior and the create-if-not-exists edge case. However, it does not mention other behavioral aspects such as confirmation prompts, atomicity, or return values, which could be relevant for a write operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences, front-loaded with the primary action and followed by a key edge case. Every word contributes meaning, with no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple file write tool with fully described parameters and no output schema, the description covers the core behavior and the main edge case sufficiently. It lacks usage guidance, but that is captured in a separate dimension, so overall it is complete enough for the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with all three parameters (content, vaultId, filepath) adequately described in the schema itself. The tool description adds no extra parameter semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'Overwrite' with the resource 'entire content of a file', clearly stating the exact operation. It also notes file creation if missing, which distinguishes it from siblings like append_content and patch_content that imply partial modification.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no explicit when-to-use guidance or alternatives. It implies use for full replacement but does not mention that append_content or patch_content should be used for partial edits, leaving the agent to infer context from sibling tool names rather than explicit direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It only states the action and scope, but gives no information about whether the operation is read-only, what the return format looks like, performance characteristics, or any potential 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that conveys the essential purpose without redundancy. It is appropriately front-loaded and contains no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

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 more about what the tool returns and any relevant limitations. It lacks usage guidance and result semantics, making it incomplete for a tool with several close siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides 100% coverage with clear descriptions for all three parameters, so the description does not need to add much. It does add the context of 'across all files' and 'keyword' which aligns with the schema, but no additional parameter-level detail is necessary.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifies a clear action ('keyword search') and scope ('all files in the vault'), making the tool's basic function evident. However, it does not explicitly differentiate this from sibling search tools like complex_search, pattern_search, or semantic_search, though 'keyword' implies a simple text query.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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. The description does not mention use cases, prerequisites, or why a user might choose this over complex_search or semantic_search.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite having no annotations, the description only covers the conceptual approach and does not disclose result format, behavior around threshold/filters, or any side effects. This leaves the agent without critical behavioral context for a search operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences, immediately front-loading the core concept ('Concept-based search via Smart Connections') with no redundant filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the tool has a fairly complex input schema with nested filters and a threshold parameter. The description does not mention these features, return behavior, or how to distinguish this tool from many search-sibling tools, making it incomplete for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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), so the baseline is 3. The description adds no additional parameter semantics, such as how threshold or filters affect the search, so it does not exceed the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Concept-based search via Smart Connections' and contrasts with 'keyword matching,' giving a specific verb+resource+scope. However, it does not explicitly differentiate from sibling semantic search tools like find_similar_notes, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'rather than keyword matching' implicitly suggests using this tool for conceptual/semantic queries and others for literal matches, but no explicit when-to-use/when-not-to-use guidance or alternative tool names are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.