Vault Cortex

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

The description goes well beyond the sparse annotations (readOnlyHint=false, destructiveHint=false) by disclosing the exact write behavior: the task is always created as [ ] (todo) with ➕ auto-stamped, metadata ordering, format auto-detection, and a comprehensive list of error conditions. It even explains the return value shape. Nothing contradicts the annotations; it adds rich behavioral context that the annotations only hint at.

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 structure is exemplary: a clear opening purpose, five illustrative examples, a succinct 'When to use' section, a well-organized parameter list (every parameter described with purpose and constraints), followed by an error catalog and return format. Despite length (necessary for a 15-parameter tool), every sentence earns its place — no filler, no repetition. The content is front-loaded with the most decision-relevant 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 tool with 15 parameters, 3 required, and no output schema, the description is remarkably complete. It covers return values (JSON shape), error conditions (every plausible failure), formatting conventions, and edge cases like concurrent writes and parent/task relationships. An agent has everything needed to call the tool correctly, including examples that demonstrate the full range of usage. Nothing essential is missing.

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% — each parameter already has a description. However, the description adds substantial meaning beyond the schema: the field-ordering guarantee, the relationship between parent_block_id/parent_line and heading, the position default nuance ('Kanban boards with new-card-insertion-method set to prepend default to top instead'), and the subtasks vs. full sub-task distinction. This is far above the baseline 3 and earns 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 states a specific verb ('Create a correctly-formatted task in one call'), the resource (a task card in a note), and enumerates the key fields. It differentiates from vault_update_task by noting the task is always created as [ ] (todo) and that starting work is vault_update_task's job. Examples concretely illustrate the purpose.

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?

It explicitly states when to use: 'When to use: Creating a new task card on a board or in a note.' It also gives a clear exclusion and alternative: 'For lightweight checklist items under an existing card (no metadata), use vault_update_task's add_subtasks param instead.' This is exactly the kind of when/when-not guidance that the dimension asks for.

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?

The description fully informs the agent about behavioral traits beyond annotations. It discloses the exact matching requirement, case-insensitive section matching, common errors (ambiguous, no entry, dot-prefix error), the safety guard that blocks writes shrinking content by more than half, and return value. The annotation shows destructiveHint: true, and the description aligns with this by detailing deletion behavior and blockers.

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 thorough and front-loaded with the core purpose, but it is somewhat lengthy. Every sentence adds value, but the error details could be slightly compressed. Still, it is well-structured with clear paragraphs for when to use, parameters, and errors.

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 (4 required parameters, sibling tools for deletion and update), the description is remarkably complete. It covers usage boundaries, error cases, safety blocks, and return values. No output schema exists, but the return is simple ('Confirmation message') and the errors are enumerated, making the agent well-equipped to handle the 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 description adds significant meaning beyond the schema. It explains how 'date + entry together uniquely identify the bullet line', notes that identical entries cause ambiguity, details section matching behavior (case-insensitive, ignoring suffix), and provides a full example. Schema coverage is 100% but the description enriches every parameter with context on errors and usage.

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 'Delete a single dated entry from an About Me/ memory file'. It identifies the specific verb (delete) and resource (dated entry from a memory file), and distinguishes this from sibling tools like vault_delete_span, vault_delete_note, and vault_update_memory by specifying exact matching and alternative use cases.

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 extensive guidance on when to use and when not to use this tool. It explicitly says 'do NOT delete to reflect a change', advises preferring vault_update_memory for superseding changed entries, and mentions exceptions for 'living' files. It also recommends calling vault_get_memory first and lists alternatives like vault_delete_span for ambiguous 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?

While annotations already declare destructiveHint=true, the description adds substantial behavioral context: no trash/undo, link breakage detectable via vault_get_backlinks, protected path refusal, best-effort folder pruning that never fails the delete, concurrent write errors, and hidden path blocking. This far exceeds what annotations alone convey.

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 tightly structured and front-loaded: key destructive behavior first, then examples, usage guidance, error handling, and return value. Every section earns its place, especially for a destructive tool where edge cases and failure modes are critical for safe invocation.

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 invocation, examples, protected paths, error conditions with remedies, pruning semantics, and the return value. Given the destructive nature and lack of an output schema, this is a complete and well-rounded definition that leaves 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?

Schema coverage is 100% with strong descriptions for both parameters, so the baseline is 3. The description adds value beyond the schema through concrete invocation examples and clarifies that prune_empty_folders is best-effort and never causes the deletion to fail. This is useful extra meaning, though not dramatically more than 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 opens with a specific verb and resource: 'Permanently delete a markdown note', and immediately clarifies the destructive scope (removed from disk, no trash, no undo). It also distinguishes itself from vault_delete_memory by noting that memory entries should go through that sibling tool instead.

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 'When to use' section explicitly states the intended use case and names the preferred sibling alternative (vault_delete_memory) for memory entries. The errors section also routes remediation, such as using vault_delete_memory for protected About Me paths and vault_list_notes to verify paths before deleting.

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?

Beyond the destructiveHint annotation, the description discloses line-level selection (never mid-line), case-sensitive matching, end_anchor search order preventing backward spans, first_match behavior, blank-line collapse, property preservation with possible YAML normalization, and specific error modes with recovery steps. This is rich behavioral context for a destructive 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 long but every section earns its place: primary behavior, examples, usage guidance, parameter semantics, error handling, and return value. Information is front-loaded and organized with clear labels and bullets, avoiding rambling prose.

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 destructive, nuance-heavy tool, the description covers prerequisites (read the block first), anchor selection guidance, edge cases including ambiguous anchors and concurrent writes, hidden path restrictions, and return value. There is no output schema, so the explicit return description closes the last 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?

Though schema coverage is 100%, the description adds crucial semantics not present in the schema: anchors select whole lines, end_anchor must be at or after the start line, omitting end_anchor means single-line deletion, and first_match applies independently to each anchor. The two worked examples demonstrate valid start/end anchor choices.

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: 'Delete a contiguous block of whole lines from a note's body' via anchor substrings. It clearly differentiates this from write/replace siblings by emphasizing that it only deletes and operates on the body only.

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 an explicit 'When to use' section describing the ideal case (removing an already-read block where reproducing old_text is error-prone) and naming alternatives: prefer vault_replace_in_note for small edits and vault_replace_span for block replacement, with a fallback workflow. This makes the selection decision unambiguous.

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?

Annotations already indicate read-only, non-destructive, idempotent behavior. The description adds nuance: self-links ignored, exclude_folders replaces defaults with prefix matching, sorting by most recently modified, and empty array means no orphans (not error). No contradictions.

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

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

Well-structured with clear sections (purpose, example, usage, parameters, errors, returns). Every sentence adds value without 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?

Given no output schema, the description fully covers return format (JSON array of note metadata sorted by modified), error cases (empty array), and parameter behavior, leaving no ambiguity for the 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?

Despite 100% schema coverage, the description adds crucial details: exclude_folders replaces defaults (not merges), includes prefix recursion behavior, and reminds to include defaults. For limit, clarifies default and sorting impact.

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 links, using the specific term 'orphans'. It differentiates from sibling `vault_get_backlinks` by explicitly noting the alternative for single-note connectivity checks.

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 'when to use' (vault maintenance) and alternative (`vault_get_backlinks` for specific notes). Includes a concrete example of usage with parameters.

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?

Discloses numerous behavioral nuances: handles heading anchors/aliases, ignores code blocks, self-links appear, return format and error behavior. This goes well beyond the annotations (read-only, idempotent) and gives the agent a solid understanding of edge cases.

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

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

Though lengthy, the description is tightly organized with clear sections (summary, examples, when to use, parameters, returns, errors). Each sentence provides operational value, and the main purpose is stated upfront. No redundancy or unnecessary 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 tool with no output schema, the description fully documents return structure (path, backlinks, count, item fields), link resolution rules, and error handling. It also covers both .md and .canvas inputs, making the description complete and self-sufficient.

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?

Despite 100% schema coverage, the description adds meaning: emphasizes case-sensitivity, exact path format, file extensions, and provides explicit examples. The Errors section clarifies path rejection and non-indexed path behavior, enriching schema 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's function: finding all notes and files linking to a given note or canvas. It enumerates specific link types (wikilinks, markdown links, embeds, frontmatter, canvas references), which distinguishes it from any sibling tool.

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 provides 'When to use' context, listing use cases like assessing connectivity before edits. It names alternative tools (vault_get_outgoing_links, vault_find_orphans) with clear differentiation, satisfying the when/alternatives criteria fully.

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?

Annotations already declare readOnly, idempotent, and non-destructive. The description adds behavioral details beyond annotations: returns exists:false if note missing, resolves path automatically, explains timezone handling, and lists error conditions. No contradictions.

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

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

The description is well-structured with clear sections, but contains redundancy: the error text and 'exists: false' behavior are repeated. Could be tightened without losing clarity, but is still acceptable.

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?

No output schema exists, yet the description fully explains the return JSON structure (path, content, exists), default behavior, error cases, and interaction with other tools. It is complete for the tool's function.

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% but the description enriches the date parameter by explaining default to today, server timezone usage, invalid format error, and that the path is derived automatically. This adds meaning 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 'Read a daily note by date' with a specific verb and resource, and distinguishes itself from siblings like vault_read_note by specifying it uses the daily notes folder and format. It is unambiguous and specific.

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

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

Explicitly states when to use ('When you need today's or a specific date's daily note') and contrasts with vault_recent_notes ('not date-filtered'). Also suggests using vault_patch_note for appending, providing clear guidance on 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds behavioral context beyond annotations: it notes that returning no args yields all files concatenated ('can be large'), returns empty string when no memory files exist, and details each error case. The only gap is not explaining the exact return format (raw markdown is mentioned) or pagination, but that's minor given the tool's simplicity.

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 well-structured with clear sections: mode behavior, example, when to use, error list, return type. Every sentence provides useful information. Minor inefficiency: repeating 'call vault_list_memory_files first' in both the guidelines and the schema description could be consolidated, but overall it's concise.

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 complete for a read-only tool with two optional parameters. It covers all input modes, error cases, appropriate prerequisites (list files first), and return type. With no output schema, the description adequately explains return values (raw markdown, empty string). The only minor gap is not explaining how large concatenated output might be limited or truncated, but that's acceptable for this use case.

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 adds significant value by explaining how the parameter combos affect output (file, file+section, no args) and giving a concrete example. It also clarifies the section matching behavior (case-insensitive, optional suffix). However, it doesn't explain the exact format of the section heading beyond saying 'H2 heading', which is already clear from the example.

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 reads semantic memory from 'About Me/' files and describes three modes of operation (file, file+section, no args). It distinguishes itself from sibling tools like vault_read_note, vault_memory_recall, and vault_get_daily_note by focusing specifically on structured memory files with bullet entries.

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 explicitly tells the agent when to use this tool (reading user preferences, principles, opinions) and when not to ('Prefer vault_read_note for reading non-memory notes'). It also advises calling vault_list_memory_files first to discover valid file and section names, which is a valuable usage guideline.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context beyond annotations: it ignores links in code blocks, includes self-links, explains the daily_note_forward_ref flag, details bytes meaning vs delivery cost, and specifies error behavior for non-indexed paths. No contradictions.

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

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

The description is well-structured with sections for purpose, examples, when to use, parameters, returns, and errors. Every sentence seems necessary, though it is somewhat lengthy. The information is front-loaded and clearly organized.

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 single parameter and no output schema, the description thoroughly covers return structure, error handling, and edge cases (e.g., empty results, daily note forward refs). It provides complete guidance for an agent to use the tool effectively.

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 meaning by explaining that the path must be indexed and that the file watcher processes new files within seconds, which is not in the schema. This extra context justifies a 4.

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 it finds outgoing links from a note or canvas, specifying wikilinks, markdown links, and canvas file-node references. It distinguishes itself from the sibling tool vault_get_backlinks by noting the direction of 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 explicitly tells when to use this tool: navigating the graph forward, auditing broken links, or checking dependencies before editing. It also directly names the alternative vault_get_backlinks for incoming links.

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?

The description goes well beyond the annotations by disclosing key behavioral traits: case-sensitive matching, ambiguity errors unless first_match is set, whole-line insertion that never splits a line, verbatim content handling with trailing-newline effects, properties being preserved, YAML normalization to block style on first edit, and operation on the body only. It also enumerates specific error conditions such as 'concurrent write in progress' and 'hidden path blocked.' No contradiction with the annotations exists.

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 exceptionally well structured, with clear sections for behavior, examples, when-to-use, parameters, errors, Obsidian syntax, and return value. Every section contributes actionable information, and the core behavior is front-loaded. It loses one point for some redundancy with the schema's parameter descriptions and for being longer than strictly necessary, but the length is largely justified by the tool's complexity and the absence of an output 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?

The description is fully self-contained for an agent to invoke the tool correctly: it defines matching semantics, insertion direction, error handling, return message format, hidden-path restrictions, concurrent-write behavior, and Obsidian Markdown escaping caveats. With no output schema, the explicit 'Returns' section fills the gap completely. The sibling routing and examples also make the tool's place in the broader API 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?

Although schema coverage is 100%, the description adds meaningful behavioral semantics beyond the schema: the anchor is a 'short unique substring' that must be case-sensitive and can match multiple lines; content is inserted as whole lines and never splits the anchor line; first_match changes ambiguity handling from error to first-match. The clear examples further illustrate parameter usage by showing concrete path, anchor, position, and content values. This is more than the baseline 3 expected when schema coverage is high.

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: 'Insert content as whole lines before or after a specific line identified by a short anchor substring.' It clearly differentiates from siblings by naming vault_patch_note and vault_replace_span as alternatives for different insert/replace scenarios, and even notes the shared anchor resolution with vault_delete_span. An agent can immediately tell what this tool does and how it differs from other vault mutation tools.

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 'When to use' section is explicit about the intended scenarios: precise location by nearby line text, table row insertion, and list positioning. It also gives direct exclusions: 'Prefer vault_patch_note for heading-targeted inserts' and 'Prefer vault_replace_span when replacing a block rather than inserting next to it.' This gives an agent clear routing logic among 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description goes well beyond: it explains that extension_counts/total reflect the full set even with truncation, describes path-traversal errors, hidden-folder blocking, and the difference between on-disk size vs delivery cost for images vs text, which annotations cannot convey.

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 well-structured with examples, usage guidance, parameter details, error cases, and return format—all clearly separated. It is slightly longer than strictly necessary (the bytes/large image detail could be condensed), but every section serves a distinct purpose.

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 fully documents the return format (files array, extension_counts, total, truncated). For a 3-parameter tool with zero required params, 100% schema coverage, and clear annotations, the description covers all behavioral and edge-case details an agent needs, including error conditions and cost considerations.

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 significant value beyond the schema: explains case-insensitivity and leading-dot flexibility for extensions, clarifies default 50 for limit, and describes the recursive search behavior of folder. One deduction because it does not mention that bytes/large image behavior detail belongs more in the tool description than parameter semantics, but still adds substantial context.

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 non-markdown files in the vault or a folder' and explicitly contrasts with sibling tools like vault_search, vault_list_notes, and vault_search_by_folder that cover only markdown notes, making the scope 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, naming specific sibling tools (vault_search, vault_list_notes, vault_search_by_folder) and indicating when to prefer vault_get_outgoing_links instead, plus three clear examples showing common 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?

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds value by detailing that an empty or nonexistent memory folder returns an empty array (not an error) and by explaining the return structure including the leading callout and entry_policy fields. No contradictions with annotations.

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

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

The description is well-structured with a clear first sentence stating purpose, followed by an example, usage guidance, error behavior, and return format. It is appropriately detailed without being excessively verbose.

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 no parameters and no output schema, the description provides a complete picture: it explains what the tool returns (JSON array of file outlines with key fields), how to use it, and error handling. There are no gaps.

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?

There are no parameters, so the baseline is 4 as per the guidelines. The description does not need to provide parameter information and correctly omits 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 it's a discovery tool for listing memory files with their heading structure, entry counts, and entry policy. It explicitly distinguishes its purpose from sibling tools by noting it should be called before vault_get_memory, vault_update_memory, or vault_delete_memory.

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 guidance on when to use the tool: always before getting, updating, or deleting memory files to get valid file and section names and to check entry policy. This effectively differentiates its usage from sibling memory 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's safe. The description adds crucial behavioral context: returns paths-only (not content), empty array for nonexistent folders, and hidden folder blocking ('hidden path blocked' error). This goes beyond 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 well-structured: purpose upfront, then usage guidelines, then sibling differentiation, then parameter details, then error cases, then return format. Every sentence adds value with no redundancy. Front-loading works well.

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 (2 optional params, no output schema, clear annotations), the description fully covers everything an agent needs: purpose, filtering semantics, return format, error cases, and comparison to siblings. No gaps remain.

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 significant value: explains folder scopes subfolders, clarifies glob/folder combination behavior, and details glob semantics (* and **). This elevates 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 tool lists .md file paths, optionally filtered by folder or glob pattern, and explicitly says it returns paths only. This distinguishes it from sibling tools like vault_search_by_folder (which adds metadata) and vault_read_note (which reads 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 explicit when-to-use guidance (browsing by filename or path pattern) and contrasts with alternatives: vault_search_by_folder for metadata, vault_search for content, and vault_read_note to read results. This helps the agent decide correctly.

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?

Annotations already declare readOnlyHint and idempotentHint; the description adds behavioral details like sorted output and sample_values top 3, plus folder recursion behavior. No contradiction.

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

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

Well-structured: purpose with example, usage guidance, parameter explanation, return format. Front-loaded with key information, no 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?

Given the tool's simplicity (1 param, no output schema), the description fully covers parameter behavior, output format, usage context, and sibling differentiation. Complete and actionable.

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 for 'folder' is minimal; the description adds crucial behavior: path prefix matching and recursion into subfolders. Schema coverage is 100%, but description adds extra value.

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 property keys with note counts and sample values, and distinguishes it from siblings like vault_list_property_values and vault_search_by_property.

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 states when to use as a first step for vault orientation, and provides alternatives: prefer vault_list_property_values for specific key values, and vault_search_by_property for key-value matching.

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?

The description adds significant behavioral details beyond the annotations (which only note readOnly and idempotent). It explains how array properties are unpacked, that counts may exceed note count, that unknown keys return empty array (not error), that values are stringified, and the sorting order. This fully informs the agent of the tool's 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 well-structured: starts with a clear purpose, includes an example, then 'When to use' paragraph, parameter details, and return format. Every sentence adds value; no waste. Front-loaded with key 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 three parameters, no output schema, and good annotations, the description covers all necessary aspects: usage context, parameter interactions, edge cases, return format, sorting, and data type handling. It is fully complete for the agent to use effectively.

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 meaningful context: key is case-sensitive and must match exactly, folder restricts subtree and interacts with key, limit applies after sorting and is suitable for high-cardinality properties. These details go beyond the schema's simple 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 clearly states the verb ('List distinct values'), the resource ('property key'), and the additional context ('with note counts'). It provides an example and distinguishes from siblings like vault_search_by_property and vault_list_property_keys by explicitly stating its use case: enumerating values before searching.

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 explicitly states when to use (before vault_search_by_property) and advises running vault_list_property_keys first. It covers parameter interactions (folder, key) and edge cases (unknown key, array properties). However, it does not provide an explicit list of when not to use it or compare it directly to other search 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?

Annotations already declare readOnlyHint and idempotentHint. The description adds critical behavioral details: only frontmatter tags are counted (not inline #tags), hierarchical tags are kept intact, count is unique notes, and empty vault returns empty array. No contradiction with annotations.

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

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

Description is concisely structured: core purpose first, then important counting rules, example, usage guidance, and return format. Every sentence adds value 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?

Despite no parameters and no output schema, the description fully explains behavior, edge cases (empty array), and return format (JSON array of { tag, count }). Combined with annotations, the agent has all necessary context for correct invocation.

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?

Tool has zero parameters, so the input schema is fully covered. The description adds no parameter information (unnecessary), which is appropriate. Baseline of 4 applies per guidelines.

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 ('List') and resource ('all tags in the vault'), specifies ordering and note counts, and differentiates from the sibling vault_search_by_tag by noting it is a discovery step versus a targeted 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 when-to-use ('Discovering what tags exist before searching by tag') and when-not-to-use ('Prefer vault_search_by_tag once you know which tag to query'), including a clear alternative 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context: it discloses that fenced code blocks and %% %% comment blocks are not indexed, that no follow-up reads are needed to locate a task, that no matches returns an empty result rather than an error, and that invalid date filters throw remediation text. This goes well beyond the annotation baseline and contains no contradictions.

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

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

The description is long, but the length is justified by 16 parameters and no output schema. It is front-loaded with purpose, then examples, then parameter and error sections, making it scannable. Some parameter text overlaps with the schema's own descriptions, but the examples and error/return details earn their 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 complex tool with 16 parameters, nested date objects, and no output schema, the description is exceptionally complete: it covers default values, sort semantics, error behavior, empty-result behavior, indexing exclusions, and the full return shape with which fields are conditional. An agent has everything needed to invoke it 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains that date filters only match tasks that actually have that date, that 'position' is the natural Kanban order, that 'not_done' excludes done and cancelled, and it provides five concrete usage examples showing parameter combinations. This meaningfully enriches the structured schema definitions.

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 precise verb and resource: 'List checkbox tasks across the whole vault with structured filters.' It clearly distinguishes itself from siblings by explicitly naming vault_read_note and vault_search as the alternatives for other use cases, so an agent can select it correctly without inspecting other tool schemas.

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 'When to use' section gives concrete scenarios ('what's overdue?', 'what's open per project?', 'what did I finish this week?') and explicitly says to prefer vault_read_note for reading a board lane verbatim and vault_search for full-text content queries. This is strong routing guidance with both inclusion and 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?

Annotations already indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds behavioral details beyond annotations: that the tool is tuned for recall over precision (expect marginal entries), that search_mode can be 'hybrid' or 'fts' with an any-term fallback to avoid empty results, that reranked indicates a relevance cut, and that truncated=true means least-relevant matches dropped (not a date range). No contradiction.

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

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

The description is multi-paragraph but each sentence adds necessary information. It front-loads the core purpose and usage, then details behavior, errors, and return format. While not terse, it avoids redundancy and every sentence appears justified for a tool with this 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?

Despite lacking an output schema, the description fully explains the return value: JSON with entries, total, truncated, search_mode, reranked. Each entry's fields (file, section, date, text) are described, including text containing raw markdown. Edge cases (empty results returning {entries:[], total:0}, unknown file returning empty) are covered. This is complete for a read-only, idempotent 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% with descriptions for all 3 parameters. The description adds significant value: for 'query' it explains natural language works best and contrasts content words vs meta framing with examples; for 'file' it clarifies omission means cross-file; for 'max_results' it explains truncation behavior. This goes well beyond the schema alone.

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 'recall' and the resource 'memory entries'. It specifies entry-granular hybrid retrieval across all About Me/ files and all time, and distinguishes from sibling tools like vault_get_memory (for known files/sections) and vault_search (for notes outside the memory layer).

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?

Explicit guidance is given: 'Answering "what does my memory say about X?" or "how has my view on Y evolved?"' as when to use, and 'prefer vault_get_memory to read a known file or section verbatim; prefer vault_search for notes outside the memory layer' as when-not and alternatives. Error behavior for empty results and unknown file is also documented.

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?

Even though destructiveHint=true already signals mutation, the description goes far beyond it: it explains link-rewriting semantics, the no-overwrite guarantee, protected paths, hidden path blocking, concurrency locking, and detailed failure recovery behavior (e.g., 'a failure never loses data'). It even discloses partial-failure states and how to recover, which is exactly the kind of beyond-annotation context an agent needs.

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 tightly organized into purposeful sections: intro, examples, when-to-use, errors, syntax notes, and return value. Every section earns its place, especially for a destructive operation with link rewriting and failure cases. The core purpose is front-loaded, with supporting detail following a logical order.

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 complexity of the operation—link graph rewriting, protected paths, failure recovery, and pruning—the description is complete. There is no output schema, but the description documents the return shape (moved_to, links_updated, updated_notes, pruned_empty_folders). It also catalogues the full error surface, so an agent can anticipate and respond to failures.

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, but the description genuinely adds value: it supplies concrete examples for pure rename, folder move, and prune behavior, and clarifies the prune_empty_folders semantics (walking up but never including vault root, only removing zero-entry folders). This exceeds the schema's own parameter descriptions without repeating them verbatim.

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: 'Move or rename a note and rewrite every link across the vault that points to it,' which immediately establishes both the action and its scope. It also references Obsidian's built-in rename, giving the agent an unambiguous mental model. This clearly distinguishes it from sibling read/write/delete tools.

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 'When to use' section explicitly states the intended scenario and names the alternative: 'Prefer this over vault_write_note + vault_delete_note, which would orphan every backlink.' It also tells the agent when to choose other tools ('To only change a note's body or properties, use vault_patch_note or vault_update_properties'). This is explicit routing guidance with no reliance on inference.

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?

Annotations already mark the tool as destructive, but the description adds substantial behavioral context: frontmatter preservation, possible YAML normalization, non-atomic write ordering, heading boundary semantics, hidden path blocking, concurrent write errors, and the risk of replace destroying child headings. It even describes what happens when a no-heading prepend accidentally nests existing 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 long, but the tool is genuinely complex with four operations, multiple edge cases, and an extensive error surface. It is well-structured with bolded section labels, a front-loaded overview, explicit examples, an organized error list, and a clear returns section, so an agent can quickly scan for relevant details.

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 every documented error, return format, operation-specific constraint, alternative-tool routing, and even an example call. Since there is no output schema, the explicit return message description is necessary and sufficient. Nothing required for correctly invoking the tool is missing.

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?

Although input schema coverage is 100%, the description goes well beyond the schema by explaining operation-specific behavior, heading matching semantics, heading_level disambiguation, include_children confirmation, table-row handling, and leading-callout editing. This adds real meaning to parameters like operation, heading, content, and include_children rather than just restating 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 opens with a specific verb phrase and resource: 'Surgical edits to a markdown note' and immediately enumerates the four operations: append, prepend, replace, or insert content by heading. It also distinguishes itself from siblings by explicitly naming vault_write_note, vault_replace_in_note, and vault_delete_span as alternatives.

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 an explicit 'When to use' section and states when to prefer vault_write_note and vault_replace_in_note instead. It also provides a step-by-step cross-section move workflow with read, patch, replace/delete, and retry guidance, making the selection and invocation conditions unambiguous.

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?

The description goes far beyond the annotations (which already declare idempotentHint=true, readOnlyHint=true). It details how images are downscaled/recompressed, how animated GIFs are handled, how PDFs are extracted (including heading hierarchy and code blocks), line-paging behavior, and the exact format of error messages. This is exceptionally exhaustive for a read-only 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 extremely long and contains a lot of detailed behavior, error explanations, and returns information that, while useful for behavioral completeness, could be shortened or moved to tool-specific documentation. The examples at the top are helpful, but the error list in particular is verbose. In its current form, it is not concise.

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 (100% schema description), clear annotations, no output schema, and a complex domain (multiple file types with different behaviors), the description provides exhaustive coverage: per-type return formats, paging details, error messages, search coverage, and relationships to sibling tools. It leaves no question unanswered about what the tool does or how it behaves.

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 restates some parameter semantics (e.g., raw behavior for canvas and PDF, start_line/limit paging) but does not significantly add beyond what the schema descriptions already provide. The examples in the description are valuable context but the parameter schema is already complete and well-documented.

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 is extremely precise: 'Read a non-markdown vault file in its most useful form per type.' It immediately distinguishes itself from vault_read_note (which handles .md files). The description also lists all supported types and their behavior, leaving no ambiguity about the tool's 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 explicitly states when to use this tool ('whenever a note references a file you need to actually see or read'), when not to use it ('For .md notes use vault_read_note — this tool rejects them'), and how to find files to read (vault_get_outgoing_links, vault_list_files). It also provides guidance on efficient usage ('To check a large file's size... request start_line: 1 with limit: 1').

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?

Annotations declare readOnlyHint, idempotentHint, and destructiveHint=false, confirming safe read behavior. The description adds rich behavioral context beyond annotations: default returns full raw content including properties, mutual exclusivity of modes, line ending normalization during paging, section boundary definitions, detailed error messages, and access restrictions (hidden paths blocked). No contradictions with annotations.

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

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

Well-structured with clear sections: examples, when-to-use, section boundaries, errors, and return value shape. Every sentence adds value—no filler. Essential details are front-loaded (main behavior then examples). The error list is comprehensive yet concise.

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 (7 parameters, 3 mutually exclusive modes, paging, multiple return formats) and absence of output schema, the description is exceptionally complete. It covers return shapes (raw markdown, JSON for properties/outline, window metadata), error scenarios, and boundary behavior—all necessary for correct agent usage without needing an output schema.

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%, and the description goes well beyond by providing practical usage patterns: outline returns a specific JSON structure with leading_callout and leading_content, paging adds window metadata, heading_level disambiguates when headings share text, and start_line with limit pages the rendition. The description adds context not present in schema descriptions, such as starting line 1 with limit 1 to get total line count.

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 it reads a markdown note by vault-relative path. It distinguishes itself from siblings like vault_search, vault_get_memory, vault_read_file, and vault_patch_note with explicit examples and when-to-use guidance. The verb 'read' combined with the resource 'markdown note' is specific and actionable.

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 when-to-use and when-not-to-use guidance, including preferring vault_search without a known path, vault_get_memory for 'About Me/' files, vault_patch_note for editing, and vault_get_backlinks/vault_get_outgoing_links for link exploration. Also gives detailed strategies for large notes (outline, heading, paging) and line count checking.

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?

Annotations already show readOnlyHint, idempotentHint, destructiveHint. The description adds context: explains mtime vs frontmatter behavior, notes without 'created' sort last, empty vault returns empty array, and that 'modified' includes sync touches. No contradictions.

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

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

The description is well-structured with purpose first, then examples, usage, parameter details, errors, returns. It's slightly long but every sentence adds value. Could be more concise but still effective.

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 (2 params, no output schema), the description covers purpose, usage, parameter behavior, edge cases (empty vault), and return format (listing fields). It is complete for an AI agent to use 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?

Schema coverage is 100%, but the description adds meaning: interaction between sort_by and limit, behavior when property missing, defaults, and that 'modified' includes sync touches. This adds significant value 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 the tool lists recently modified/created notes sorted by timestamp, and distinguishes itself from a date-range filter. It provides examples and differentiates from sibling tools like vault_search and vault_search_by_folder.

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 says when to use (catching up, finding recent work, orienting) and when not to (prefer vault_search for content, vault_search_by_folder for browsing). This is excellent 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?

Even though annotations already indicate a destructive, non-idempotent mutation, the description adds substantial behavioral context: YAML formatting may be normalized to block style, only the body is searched, replacement defaults to first occurrence only, there is no regex, Obsidian Flavored Markdown is interpreted with no escaping, and error cases are enumerated. This goes well beyond what annotations convey.

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 meticulously structured with sections for usage, parameters, errors, and syntax, and the core behavior and example are front-loaded. Every sentence carries operational or routing information; nothing is 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, so the description correctly explains the return value (confirmation with replacement count). It also covers failure modes, behavior with hidden paths, concurrency, and Obsidian syntax implications. An agent has everything needed to call and interpret this destructive 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 covers all four parameters with high-quality descriptions, so the bar is the extra meaning. The description adds value by explaining that old_text and new_text together determine edit versus deletion, advising contextual uniqueness for old_text, and framing replace_all_occurrences as a safety default versus deliberate bulk rename. This is more than baseline but somewhat duplicative of 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 opens with a specific verb and resource: 'Find and replace text in a markdown note's body.' It immediately bounds the scope ('Operates on the body only') and distinguishes the tool from sibling span-deletion/replacement tools, so an agent knows exactly what this tool is and is not.

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?

It has an explicit 'When to use' section that names targeted single-location edits and gives concrete alternatives with rationale: vault_delete_span for large multi-line deletions, vault_replace_span for anchor-based replacement, and vault_patch_note for relocating content. It also routes property edits to vault_update_properties or vault_write_note. This fully satisfies the when-to-use versus when-not-to-use requirement.

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?

The annotations only signal destructiveHint=true, but the description adds substantial behavioral context: whole-line selection, case-sensitive matching, properties preserved, YAML formatting may be normalized to block style, blank-line runs collapsed, end_anchor cannot run backward, and first_match applies independently to both anchors. It even describes the exact confirmation return message.

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 tightly structured with clear sections: opening behavior statement, examples, when-to-use, parameter semantics, error list, and Obsidian syntax caveats. Every sentence adds operational value; nothing is filler or tautological.

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 complex span-replacement tool with no output schema, the description is complete: it covers line-range semantics, anchor matching, error conditions, return message format, and Obsidian markdown escaping behavior. The tool can be invoked correctly without needing additional documentation.

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?

Even though schema coverage is 100%, the description meaningfully enriches the schema: start_anchor/end_anchor define a line range rather than a text range, the span never cuts mid-line, omitting end_anchor means single-line replacement, trailing newline in content adds a blank line, and first_match applies independently to each anchor. The examples demonstrate realistic parameter combinations.

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: 'Replace a contiguous block of whole lines in a note's body with new content, identified by short anchor substrings.' It clarifies the tool targets full lines rather than arbitrary text, distinguishes it from vault_delete_span and vault_replace_in_note, and provides concrete examples showing exact usage.

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 an explicit 'When to use' section: use this tool when replacing a block you've already read and reproducing the full text as old_text would be error-prone. It also names alternatives directly: 'Prefer vault_replace_in_note for small in-place text changes' and 'Prefer vault_delete_span when removing without replacement.'

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?

The description discloses rich behavioral details beyond the readOnly/idempotent annotations: transparent fallback to FTS5 while embeddings build, implicit AND with porter stemming, exact-phrase behavior, automatic sanitization of malformed query syntax, empty-result behavior, exclusive vs. inclusive date boundaries, and the meaning of search_mode and reranked flags. This exceeds what annotations alone convey.

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 well-structured with clear sections ('When to use,' 'Errors,' 'Returns'), bulleted filter specifications, and concise examples. Every section earns its place by clarifying complex behavior; there is no redundant filler or repetition of schema fields.

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 fully enumerates the return shape: results array fields (path, title, snippet, score, tags, folder, type, kind, extension, created, modified, bytes), total, search_mode, reranked, and optional leading_callout. It also covers error cases and fallback behavior, making the tool fully understandable without external documentation.

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?

Although schema coverage is 100%, the description adds substantial meaning: filters 'AND-combine with each other and the text query,' date bounds are explicitly exclusive/inclusive, properties support string/number/boolean, and multiple concrete examples show exactly how query and filters interact. This goes well beyond the schema's field 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 opens with a specific verb and resource: 'Hybrid search across all vault notes, ranked by combined keyword and semantic relevance using RRF.' This clearly distinguishes vault_search from sibling tools like vault_search_by_tag, vault_search_by_folder, and vault_search_by_property by positioning it as the content-based, hybrid discovery tool.

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 'When to use' section explicitly states this is 'The primary discovery tool for content-based queries' and names exact alternatives: 'Prefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder. Prefer vault_search_by_property for metadata-only queries. Prefer vault_recent_notes for time-based browsing.' This gives unambiguous guidance on when to use this tool vs. siblings.

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?

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds context beyond annotations: sorting by most recently modified, return format as JSON array with specific fields, error behavior (empty array for missing folder), and folder prefix matching. Minor gaps: sorting direction not specified, 'additional_properties' vague.

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?

Well-structured with sections for purpose, example, when-to-use, parameter details, errors, and return format. Front-loaded with purpose. Slightly verbose but each sentence adds value. Could be tightened without losing clarity.

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?

No output schema, so description must explain return values. It lists fields (path, title, tags, etc.) and sorting. Also covers error case (empty array). However, 'additional_properties' is vague and sorting direction is omitted. Still quite complete for a browsing 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 baseline is 3. The description adds meaning: folder is matched as prefix without trailing slash, recursive defaults to true, limit defaults to 20. It also provides an example call. This is additive and helpful.

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 browses notes in a folder with full metadata, distinguishing it from vault_list_notes which returns only paths. The verb 'browse' and resource 'notes in a folder' are specific and actionable.

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 guidance on when to use this tool (exploring folder contents) and when to prefer alternatives: vault_list_notes for paths, vault_search for text queries, and backlinks/outgoing links for connections. This helps the agent select the correct 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?

Annotations already declare read-only and idempotent. Description adds exact/case-sensitive matching, array contains logic, empty array on no match, and sorting by mtime. No contradictions.

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

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

Well-organized with overview, examples, usage guidance, parameter details, and return value description. No fluff; every sentence 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?

Despite no output schema, description fully explains return format, sorting, and edge cases (empty array, numeric strings). Covers all necessary context for agent invocation.

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% but description adds value: exact/case-sensitive behavior for key/value, array contains for arrays, folder as subtree filter, and examples. Exceeds 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?

Clearly states it finds notes by frontmatter property value, distinguishes from full-text search and tag search, and highlights metadata-only nature.

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 specifies when to use (when no text query), and lists alternatives: vault_search for text queries, vault_search_by_tag for tags, and related discovery 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?

Annotations already indicate read-only, idempotent, non-destructive. Description adds key behaviors: hierarchical prefix matching, empty array for unknown tags (not an error), return structure, sorted by modified date. No contradictions.

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

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

Well-structured with examples, usage guidelines, parameter details, error handling, and return format. Every sentence adds value; not verbose.

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?

No output schema, but description provides detailed return metadata (path, title, tags, etc.), sorting, and explanation of bytes and additional_properties. Covers error case (empty array). Sufficient for a two-parameter 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%, but description adds significant value: explains no '#' prefix, '/' separators, interaction between tag and exact, exact vs. prefix matching behavior, and that prefix matching is based on '/' separator, not string prefix.

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?

Clearly states 'Find notes with a specific tag.' Distinguishes from siblings vault_search (text ranking) and vault_list_tags (discover tags). Includes examples demonstrating usage.

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 states when to use ('exploring tag hierarchies') and when not to use ('prefer vault_search when text ranking needed', 'use vault_list_tags to discover tags'). Also explains default vs. exact matching.

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?

Annotations already set idempotentHint=true, and the description goes well beyond this by explaining the date prefixing, newest-first insertion, idempotency details, append-only convention, living policy, and near-duplicate section guard. It fully discloses behavioral traits without contradicting 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 comprehensive but somewhat lengthy. It front-loads key behavior (date prefix, idempotency, append-only), and the example, when-to-use, and error list are well-structured. A bit verbose in spots (e.g., the near-duplicate guard explanation could be tighter), but overall earned its space.

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 no output schema, the description documents the return value (confirmation message). It covers parameter semantics, error conditions with corrective guidance, and integrates context from sibling tools (vault_list_memory_files, vault_get_memory, vault_write_note). A complete and self-contained specification.

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 value by explaining the default date behavior, position semantics, and the nuance that the date prefix is automatically added. It also clarifies the section matching logic (case-insensitive). Loses a point for not detailing the options.date format more precisely than 'defaults to today' (the error section later covers date format, but the parameter description itself is terse).

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 appends a dated entry to a memory file section, which is a specific verb+resource combination. It distinguishes itself from siblings like vault_write_note and vault_get_memory, and the example makes the usage concrete.

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 explicitly says 'When to use: Recording a new preference, principle, opinion, or fact about the user' and advises calling vault_list_memory_files first. It also tells when NOT to use it ('Prefer vault_write_note for creating non-memory notes'), providing clear 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?

The annotations already indicate readOnlyHint=false, destructiveHint=true (modification), and idempotentHint=true. The description adds critical behavioral details: the return is a confirmation message (not the updated note), errors list includes 'not found', 'path traversal blocked', 'hidden path blocked', and 'concurrent write in progress' with recovery advice. It also warns that arrays are replaced entirely and that property type mismatches cause silent query failures. This goes well beyond the annotations.

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

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

The description is well-structured with clear sections: operation semantics, example, when-to-use (with alternatives), error handling, and Obsidian syntax. It is informative but slightly long; some error details could be condensed. However, every sentence adds value, and the front-loading of the core operation is effective.

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 2 parameters (both required, no enums), no output schema, and annotations providing some but not exhaustive behavioral cues, the description covers all essential aspects: operation semantics, usage with examples, error conditions with handling advice, and Obsidian-specific formatting rules. No critical gaps remain for an agent to invoke this 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?

Schema description coverage is 100%, so the schema already documents both parameters. The description adds an example showing exact syntax for properties (including null deletion and arrays), lists Obsidian-specific conventions (use arrays for multi-value fields, quote wikilinks, keep types consistent), and notes that properties property uses shallow merge. This provides meaningful context beyond the schema's property 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 clearly states the tool updates a note's frontmatter properties via shallow merge, explaining the exact semantics (new keys added, matching keys overwritten, null deletes, unmentioned keys preserved). It also specifies that the body is never modified, which distinguishes it from sibling tools like vault_replace_in_note or vault_write_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 explicitly says when to use this tool (changing tags, status, type, or any property without reading/rewriting the full note body) and also specifies alternatives: pref er vault_write_note when creating a new note or replacing the body, and read current properties first with vault_read_note for arrays (since they are replaced entirely). This provides clear guidance on tool selection.

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

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

Annotations already mark this as a destructive, non-idempotent write, and the description adds substantial behavioral context: single-write atomicity, explicit-null clearing semantics, Kanban lane auto-moves, sub-task restrictions, position defaults, and a full catalog of error conditions. None of this contradicts the annotations; it complements them richly.

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 well-structured and front-loaded with a summary and examples, followed by usage rules, parameter semantics, errors, and returns. It is long, but justified given 17 parameters and a complex mutation surface. It loses one point because the parameter block partly restates schema descriptions, adding some redundancy despite the valuable extra rules woven in.

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 17 parameters, no output schema, and a destructive mutation tool, the description is exceptionally complete: it covers prerequisites, identification strategies, per-field behavior, error handling, and the exact return payload. An agent has everything needed to select and invoke this tool correctly.

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

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

Even though schema coverage is 100%, the description adds meaning beyond the schema: exactly one of block_id or line must be provided, at least one mutation is required, omitted fields remain untouched, null clears fields, assign_block_id has uniqueness and character constraints, and add_subtasks appends without replacing existing checklist items. The examples further illustrate valid combinations and expected behavior.

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 scope: updating status, priority, description, dates, dependencies, block_id, checklist items, or heading placement in one call. It clearly names the operation's boundaries and distinguishes itself from vault_create_task, which is listed as a sibling. This is far from a tautology and gives an agent a precise mental model.

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?

An explicit 'When to use' block states that this tool is for any change to an existing task, directs the agent to vault_list_tasks first to obtain identification fields, and explicitly routes new-task creation to vault_create_task instead. This is unambiguous guidance with a named alternative.

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?

Annotations already mark destructiveHint: true, but description adds extensive context: full write behavior, property merge semantics, lack of partial editing, and detailed error conditions (note exists, hidden path, concurrent write, control characters). No contradiction with annotations.

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

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

The description is well-structured with clear sections (body, use cases, limitations, errors, Obsidian syntax). It is slightly verbose due to examples and detailed error list, but every paragraph earns its place. Could trim the examples slightly but still effective.

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 provides a confirmation message return. It covers all four parameters, error conditions, behavioral nuances, and integration with Obsidian syntax. For a write tool with destructive potential, it 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%, so baseline is 3. However, description adds significant value: clarifies body replaces entire content, properties merge with existing, and provides YAML-specific details (escape tags, quote wikilinks, consistent types). These go well beyond the schema's short 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 clearly states the tool creates a markdown note and distinguishes it from siblings by explicitly naming alternatives like vault_update_properties and vault_update_memory. The verb 'create' plus resource 'markdown note' is specific.

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 when-to-use guidance: creating a new note, only set overwrite when replacing. Lists specific alternatives for property-only edits and memory appends. Also warns about limitations for surgical edits.

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