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

No annotations are provided, so the description must carry the full burden. It discloses that 'clear' deletes entries, which is a destructive action, and that it shows tool calls across sessions. However, it does not warn about the irreversibility of clear, whether filters apply to clear, or any authentication or rate-limit concerns. This leaves some behavioral 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 sentences, front-loaded with the core purpose, and contains no filler. Every word contributes to understanding the tool's function, making it highly concise and well-structured.

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 adequate for a tool with 7 parameters and no output schema, but it leaves important ambiguities. It does not clarify whether 'clear' respects the filter parameters or affects all entries, nor does it describe the output format for 'query' beyond mentioning timestamps and arguments. These gaps mean the description is not fully complete 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 schema description coverage is 100%, so the baseline is 3. The description does not add meaningful semantics beyond the schema; it only restates the 'action' parameter ('query' and 'clear'). The schema already documents all parameters well, so no extra value is provided.

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 queries or clears the activity log, with a specific verb and resource. It distinguishes itself from sibling tools by explicitly focusing on activity logs, making its 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 clear context for when to use the tool (to view or clean activity logs) and even explains the two actions ('query' and 'clear'). While it does not explicitly mention alternatives or when not to use it, the context is clear and no exclusions are needed given the unique purpose.

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, yet the description discloses several key behaviors: deduplication by basename, automatic section creation, exact path requirement, and the special markdown link format for output. This transparency goes well beyond the bare schema and gives the agent essential operational knowledge.

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 and well-structured: it front-loads the core action, then adds crucial behavioral details and path formatting instructions. Every sentence contributes unique information 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 tool with four parameters and no output schema, this description covers essential aspects: link addition, deduplication, section creation, and path handling. It slightly lacks explicit error behavior (e.g., nonexistent path), but this is not critical for correct usage.

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 provides full descriptions for all four parameters (100% coverage). The tool description adds extra meaning by explaining how the path parameter should be represented when relaying to other tools and clarifies dedupe behavior for links, elevating it slightly above 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 the verb 'add', the resource 'annotated wikilinks', and the target context 'a note's section'. This distinguishes it from sibling tools like vault_write or vault_append, which handle different content modifications.

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 context by detailing behavior (dedupe, section creation, exact path requirement) and provides a specific note about how to pass paths to other vault tools. It does not explicitly name alternatives, but the scope is clear enough for an agent to select 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses a non-obvious output format ('Paths in this tool's output are formatted as markdown links...') and a precondition ('heading is required and must exist in the file'). This adds significant context beyond a simple append operation. However, it omits error behavior (e.g., file not found) and permission details, though a 4 is justified given the specific behaviors shared.

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, each with a distinct purpose: the first states the core action and its optional heading feature, the second explains the output path formatting, and the third gives a practical instruction for relaying paths. No filler or redundancy; the most important information is front-loaded.

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

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

For a tool with 4 parameters, no output schema, and no annotations, the description covers the core append action, the position/heading dependency, and a key output-format behavior that affects how results should be interpreted. It stops short of describing error handling or the exact return format, but these are not critical for selecting or invoking the tool. The description feels sufficient 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 already provides descriptions for all 4 parameters (100% coverage), so the baseline is 3. The description adds meaningful semantic value by clarifying the relationship between heading and position ('When 'position' is specified, heading is required and must exist in the file') and by noting how paths should be handled ('pass only the bracket text... never the full markdown link'). This goes beyond the schema's individual parameter descriptions.

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 begins with a specific verb+resource combination: 'Append content to an existing file', which clearly distinguishes it from sibling tools like vault_write (creation) and vault_edit (modification). It also adds a distinguishing feature: 'optionally under a specific heading', making the tool's unique purpose and scope immediately clear.

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 existing files ('Append content to an existing file') but does not explicitly state when to prefer this over alternatives. It does provide a clear constraint for position usage ('When 'position' is specified, heading is required and must exist in the file'), but this is a parameter rule, not tool-selection guidance. No explicit exclusions or alternative references are given.

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 transparency burden. It adds meaningful behavioral details beyond the schema: the 'must appear exactly once' safety check and the markdown-link output format for paths. This gives an agent useful knowledge about safety and how to handle output, though it does not disclose error behavior or permission requirements.

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 core action, then the safety constraint, and finally the output-format note. Every sentence provides necessary information with no redundancy or filler. It is an model of 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 is moderately simple, but the description omits the full return value or output structure (only path formatting is mentioned). With no output schema and many sibling tools, more detail about what to expect after editing would improve completeness. Still, the core behavior and key constraints are covered.

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 parameters are documented in the schema. The description adds extra value by clarifying how the `path` parameter should be used (pass only bracket text) and reinforces the `old_string` uniqueness requirement. This is above the baseline for high 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 verb ('Edit') and resource ('a file'), with a specific method ('replacing an exact string match'). This distinguishes it from sibling tools like vault_write, vault_append, and vault_update_frontmatter, which imply other edit mechanisms. The exact-once constraint further clarifies the tool's specific behavior.

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 when an exact string replacement is needed, and the uniqueness constraint gives a clear precondition. However, it does not explicitly compare with alternatives like vault_write or vault_append, nor does it state when *not* to use this tool. Usage guidance is left to inference rather than direct instruction.

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 that the tool scans all markdown files or a specific folder and formats paths as markdown links, which is useful behavioral context. However, it doesn't explicitly state that the operation is read-only or that it makes no modifications, though 'finds' and 'audit' imply this. The description could be more explicit about potential performance implications or side effects.

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

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

The description is three sentences: purpose, usage, and a crucial output-handling note. It is front-loaded with the core function, then gives practical guidance, and ends with an important formatting caveat. Every sentence earns its place without redundancy.

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

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

Given the absence of an output schema, the description explains the output format (markdown links) and how to relay paths to other tools, which is critical for usability. It covers the scoping (all files or a folder) and the checks. It could be slightly more complete by explicitly stating the tool is read-only, but overall it provides sufficient context for an agent to select and 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 description coverage is 100%, so the schema already documents the limit, checks, and folder parameters. The description adds a brief example of fuzzy folder resolution ('e.g., 'MyApp'') but doesn't significantly extend parameter semantics beyond the schema. It mentions the default of all four checks but the schema already states that.

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 'Graph health report' and explicitly lists the four detection categories (orphan notes, broken wikilinks, weakly connected notes, ambiguous links), providing a specific verb+resource+scope. It distinguishes from siblings like vault_links by focusing on link quality auditing rather than just listing links.

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 states 'Use to audit link quality and find notes that need better connections,' giving clear context for when to use it. It also adds practical guidance about how to handle the output (preserving markdown links and passing only the bracket text to other vault tools), which further clarifies usage. However, it doesn't explicitly mention when not to use it or directly contrast with sibling tools.

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 a non-obvious behavior: output paths are formatted as markdown links with obsidian:// protocol, and it warns against passing full markdown links to other tools. This adds significant context beyond the schema.

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

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

The description is exactly two sentences, front-loaded with the core purpose and followed by a critical output-formatting instruction. Every sentence adds necessary value with no 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?

Given no output schema or annotations, the description adequately covers purpose, output format, and a usage caveat. It is sufficiently complete for a simple retrieval tool, though it could explicitly mention the response structure (e.g., grouping by direction) for fuller transparency.

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 50%; only the path parameter has a description, and direction has none. The description clarifies that path arguments for other vault tools expect plain vault-relative paths, adding some meaning, but it does not explicitly explain the direction parameter or further refine path syntax, leaving 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 first sentence 'Get incoming and outgoing links for a note' clearly states the tool's purpose with a specific verb and resource. It distinguishes from sibling tools like vault_add_links (which adds links) and vault_link_health (which checks link health) by focusing on retrieval.

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 retrieving links but provides no explicit when-to-use or alternatives among sibling tools. The path-handling instruction about preserving link form and passing bracket text is useful but addresses output handling, not tool selection.

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 behavior burden. It discloses the markdown-link output format and instructs how to extract plain paths for other tools, which is key behavioral context beyond the schema.

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

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

Three purposeful sentences, each earning its place: purpose stated first, then output format, then a crucial usage instruction. No waste.

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 adequately covers the tool's output format and path-handling behavior, which are the main non-obvious aspects. Schema covers parameters. It could mention sorting or hidden files, but these are minor for a listing 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?

Schema coverage is 100%, so the schema fully documents parameters. The description adds only a minor example of a path value, not substantial semantic detail beyond the schema.

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 'List files and folders in the vault' with a specific verb and resource, distinguishing it from sibling tools like vault_read or vault_write.

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 is implied as a listing tool, but the description offers no explicit guidance on when to prefer it over alternatives like vault_search or vault_recent, and no 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 transparently states the automatic wikilink update side effect, the exact-path requirement, and the markdown link output format. It does not detail error conditions or reversibility, but covers the most impactful behaviors.

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 tightly written, with each sentence serving a distinct purpose: the action, the side effect, the path constraint, and the output format usage. It wastes no words and front-loads the primary function.

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, the description effectively explains the output shape (markdown links) and the side effect of link updating. It does not cover error scenarios (e.g., missing old_path) or the return value for a successful move, but overall it provides sufficient context for an agent to use the tool correctly.

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

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

The schema covers all three parameters (100% coverage), so the baseline is 3. The description adds value by reinforcing the exactness of both paths and providing crucial guidance on how to interpret and pass path values (using only the bracket text, not the full markdown link) to other tools.

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: 'Move or rename a markdown file within the vault.' It also specifies the key side effect of automatically updating wikilinks, which distinguishes it from sibling tools like vault_write or vault_edit.

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 operational context: paths must be exact, and it explains how to handle the output path format when passing paths to other vault tools. However, it does not explicitly mention when to use this tool instead of alternatives or provide exclusion criteria.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior. It clearly states the output structure (grouped by hop distance, frontmatter metadata) and a significant output formatting quirk (paths as markdown links with obsidian:// URLs). This adds substantial behavioral context beyond the schema, though it doesn't cover failure modes or performance characteristics.

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, well-organized paragraph of three sentences, each serving a distinct purpose: stating what the tool does, articulating its value, and providing essential formatting usage. No filler, and the critical markdown-link caveat 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?

Given no output schema, the description adequately explains the return format (grouped by hop distance, with frontmatter metadata) and the special link formatting. It also includes use-case context and integration guidance for other vault tools. Minor gaps include not specifying what happens for missing paths or very large result sets, but that's beyond the essential context for a read-only exploration 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?

Schema description coverage is 100%, so every parameter is already well-documented in the input schema. The description adds no further parameter-specific detail; the only related note (passing bracket text to other tools) concerns output handling rather than input semantics. 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 opens with a specific verb and resource: 'Explore the graph neighborhood around a note by traversing wikilinks.' It further differentiates the tool by stating output is 'grouped by hop distance from the starting note' with frontmatter metadata, which distinguishes it from sibling tools like vault_links or vault_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?

Provides explicit use-case guidance: 'Useful for understanding clusters, finding related context, and discovering connections.' It also includes a critical practical instruction about preserving markdown link formatting when relaying paths to users and passing only bracket text to other tools. However, it doesn't explicitly name when not to use this tool or compare directly with sibling 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?

With no annotations provided, the description carries full burden and discloses return values (size, frontmatter, headings, preview), the non-reading behavior, and the markdown link format for paths. It omits edge-case behaviors but provides solid transparency for a read-only inspection 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 compact and front-loaded, with the core purpose in the first sentence. It efficiently combines return value details, usage guidance, and path formatting instructions with no wasted words.

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 schema, no annotations, and no output schema, the description fully covers what the tool does, what it returns, when to use it, and how to handle its output paths. This is complete enough for an agent to select and invoke the tool correctly.

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

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

The input schema already describes the path parameter with fuzzy resolution (100% coverage), so the description adds no direct parameter details. The path formatting instruction is about output handling rather than the input parameter, keeping this at 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 that the tool inspects a file's metadata and structure without reading full content, and enumerates specific outputs (file size, frontmatter, heading outline, preview). This distinguishes it from vault_read, which reads full 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?

Explicitly instructs to use this tool to plan which sections to read from large files, and the phrase 'without reading full content' implies an alternative to vault_read. However, it does not explicitly name alternatives or state when not to use this tool.

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 exist, so the description carries the burden. It discloses a key behavioral trait: output paths are markdown links with instructions on how to handle them. This goes beyond the schema, though it does not explicitly state read-only behavior (implied by 'Query').

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: the first states the purpose, the second and third explain a unique output format and usage rule. No wasted words, information is front-loaded.

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 output schema, the description partially explains return values by revealing the link format and how to use paths. It lacks an explicit statement of full return structure, but for a query tool, this is sufficient given the detailed input schema and the tool's simple output concept.

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 the baseline is 3. The description does not add parameter-specific meaning beyond listing categories already in the schema. The link-handling note is about output, not parameters, so no extra semantic value for params is provided.

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 action and resource: 'Query notes by YAML frontmatter metadata', listing key filter fields. This differentiates it from siblings like vault_search (full-text) by emphasizing metadata-based querying.

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 metadata-based queries, which provides clear context. It also gives specific handling instructions for output paths (preserve link form, pass bracket text to other tools), but does not explicitly exclude alternatives or mention when to use a different tool.

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 full burden and delivers. It discloses auto-redirect behavior for large files, a hard cap of ~400k chars, performance degradation warnings for force, and the markdown-link output format. It also instructs the agent on how to transform paths before passing to other tools, adding operational nuance beyond a simple read.

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 compact, front-loaded block of four sentences. Each sentence earns its place: purpose, pagination capabilities, auto-redirect behavior, and path-link handling. No filler or redundant restatement of the schema.

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?

Despite having no output schema, the description explains what data is returned (file contents or peek structure on redirect), how paths are formatted, and the performance envelope. The auto-redirect resolution and force cap address edge cases, making the description complete 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 coverage is 100%, so baseline is 3, but the description adds semantic grouping by summarizing the pagination modes (heading, tail, sections, chunks, line range) and links them to the auto-redirect threshold. The force parameter's warning and the chunk param's reference to vault_peek go beyond the raw schema, enriching parameter understanding.

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 'Read the contents of a markdown file from the vault', a specific verb+resource pairing that clearly distinguishes the tool from siblings like vault_peek, vault_search, or vault_write. It further elaborates on pagination modes, reinforcing what the tool does and its 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?

Guidance is explicit: large files auto-redirect to peek data unless a pagination param or force=true, and force is discouraged unless essential. It names vault_peek as an alternative for browsing chunks and outlines when to use pagination params, giving clear when-to-use vs 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 carries the burden of behavior disclosure. It usefully reveals that output paths are markdown links with obsidian:// URIs and instructs how to handle them. However, it does not clarify what 'recent' means or mention ordering, but the disclosed link behavior is significant.

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: the first states the purpose, and the next two provide critical output-handling instructions. Every sentence contributes value, though the guidance about markdown links could be more compact.

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 explain return values. It explains the path format but omits what other fields are returned, how files are ordered, or how 'recent' is defined. This is a notable gap for a list 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?

Schema description coverage is 100%, so the schema already documents both 'limit' and 'folder' clearly. The description adds no extra meaning about these parameters, so it meets the baseline but does not exceed 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 starts with 'Get recently modified files', which clearly states the verb and resource. The 'recently modified' qualifier distinguishes it from sibling tools like vault_list or vault_search, even though it doesn't explicitly name them.

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 clear context that this tool is for retrieving recently modified files, but it does not explicitly state when to use it over alternatives like vault_activity or vault_list. There are no exclusions or alternate tool references, so usage is implied rather than explicit.

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 transparency burden. It discloses the output format (markdown links with obsidian://) and instructs on converting links to vault-relative paths. This is valuable behavioral context beyond the schema, though it doesn't mention read-only nature explicitly (implicit in 'search').

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, both essential. The first states the core function; the second gives critical usage guidance. 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?

For a search tool with no output schema, the description explains the output format and gives actionable integration guidance. Combined with complete schema coverage, this is fully sufficient for an agent to select and invoke the tool correctly.

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

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

All three parameters are already described in the schema (100% coverage). The description adds no new information about query semantics (case-insensitive, folder filtering) beyond what the schema provides, so baseline score 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?

States a specific verb ('Search') and resource ('markdown files in the vault'). Clearly distinguishes from sibling tools like vault_read (read a single file) and vault_tags (search tags).

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 clear context on how to use the output (pass bracket text only to other tools) but does not explicitly mention when to prefer this tool over alternatives like vault_query. Still, the use case is obvious and well-scoped.

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 bears the full burden of behavioral disclosure. It only states 'Discover' which implies a read operation, but it doesn't explicitly confirm the tool is non-mutating, nor does it describe the return format or potential performance implications, leaving gaps for the agent.

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 two-sentence description is compact and front-loaded with the main purpose, followed by usage context. Every sentence adds value with no 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-only tool with all-optional parameters and no output schema, the description gives the core function and use cases. However, without annotations or output schema, it leaves out specifics about the returned structure and safety profile, making it adequate but not fully 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?

The schema provides 100% coverage with detailed descriptions for all three parameters (folder, pattern, include_inline), so the baseline is 3. The tool description itself adds no extra parameter semantics, staying at that 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 the tool discovers all tags used across the vault with per-note occurrence counts, using a specific verb and resource. This distinguishes it from sibling tools like vault_search or vault_list, which address other facets of vault access.

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 includes 'Useful for exploring tag conventions, finding hierarchical tag trees, and understanding vault organization,' which gives clear context for when to use it. However, it does not mention any alternatives or exclusions for when this tool should not be used, so it is slightly below the top score.

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 full responsibility for behavioral disclosure. It discloses the key behavior (soft-delete via moving to .trash/), the side effect of reporting broken incoming links as warnings, and the output format (markdown links with obsidian://). It also provides crucial handling instructions for output paths, which goes beyond basic expectation.

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, each serving a distinct purpose: what it does, the alternative, and output formatting instructions. It is front-loaded with the main action and contains no fluff or 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?

The description is quite complete for a simple one-parameter tool with no output schema. It covers the operation, the alternative, the output format, and path handling. A minor gap is the lack of explicit return value details (e.g., success message or structure of warnings), but the 'Reports files with broken incoming links as warnings' partially addresses output. Overall, it provides sufficient context for correct 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 already covers the path parameter with a description, so the baseline is 3. The description adds meaningful value by clarifying that paths in output are formatted as markdown links, and instructs to pass only the bracket text (e.g., '01-Projects/Foo/note.md') to other tools' path arguments. This is essential for correct cross-tool usage and thus elevates the score.

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: 'Soft-delete a file by moving it to .trash/ (Obsidian convention).' It uses a specific verb and resource, and also distinguishes itself from the sibling tool vault_move by explicitly recommending it for relocation. The mention of broken incoming link warnings adds further specificity.

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 explicit guidance on when to use an alternative: 'Use vault_move to relocate files instead.' It also clarifies the output format and how to handle paths when interacting with other tools, providing context for when to use this tool for soft-deletion and how to avoid misusing the returned path format.

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 fully carries the behavioral disclosure burden. It explains null-removal semantics, protected fields, validation rules (with concrete examples), and the markdown link output format, giving the agent comprehensive insight into expected 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?

The description is dense but every sentence earns its place, covering purpose, edge cases, validation, and output formatting. It is well-structured and front-loaded with the primary action.

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 parameters and no output schema, the description is remarkably complete. It addresses behavioral edge cases, parameter constraints, and cross-tool usage, leaving little ambiguity for an agent.

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 has 100% coverage for both parameters. The description adds meaningful context for the 'fields' parameter by specifying protected fields and validation against note type, going beyond the schema's basic null-removal and array-replacement notes.

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 explicitly states 'Update YAML frontmatter fields in an existing note' with a specific verb and resource. It clearly distinguishes from sibling tools like vault_edit or vault_write by focusing solely on frontmatter and detailing its behavior (parses, updates specified fields, preserves everything else).

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 the tool's specific use case for updating frontmatter, but it does not explicitly state when to use it over alternatives or provide exclusions. It does include cross-tool guidance on how to pass paths to other vault tools, which offers contextual usage hints.

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 adds useful behavioral context: template requirement, built-in variables, required frontmatter, and the markdown-link path format for output. However, it omits key behavioral traits such as whether it overwrites existing files, error handling, or the exact return value, which are important for a create/mutation tool.

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

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

The description is front-loaded with the primary purpose and then organized into clear sections (templates, variables, requirements, path formatting). It is relatively long but each section earns its place by conveying necessary usage details. The 'No templates found' note is somewhat environment-specific but does not detract much.

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 output schema and no annotations, the description needs to explain what the tool returns and its failure modes. It partially does this by describing the output path format, but it does not mention overwrite behavior, success/failure indicators, or how to interpret the response. This leaves important gaps for a tool with 5 parameters and nested objects.

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 well. The description adds some extra meaning by explaining built-in variable substitution and reiterating that frontmatter.tags is required, but it does not significantly expand on the schema's parameter descriptions. The 'variables' parameter description in the schema is already adequate.

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: 'Create a new note from a template.' This clearly distinguishes it from sibling tools like vault_edit and vault_append, which modify or extend existing notes. The template requirement is explicit and ties directly to the tool's core function.

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: to create new notes and to ensure proper frontmatter via templates. It also explains required tags and variable handling. However, it does not explicitly name alternatives or state when not to use this tool (e.g., for editing existing notes, use vault_edit).

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