Vault Cortex Obsidian MCP Server

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

Annotations only provide the broad write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false). The description adds substantial behavior: tasks are always created as todo with created date set to today, format should only be overridden at the user's request, and it documents return fields, advisories, and a large set of failure modes.

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

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

The description is front-loaded with purpose, examples, and when-to-use guidance, then moves into parameters, errors, syntax, and return values. It is long, and the exhaustive error catalog is more than many agents will need, but the length is largely justified by the 17-parameter surface area.

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, but the description fully documents the JSON return shape, including path, line, description, block_id, heading, subtasks, changes, and advisories. Combined with the error catalog and Obsidian syntax note, an agent has enough context to invoke the tool correctly and interpret the result.

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 description coverage is already 100%, the description adds cross-parameter semantics that the schema does not cover: heading is required on Kanban boards unless a parent is given, parent_block_id and parent_line are mutually exclusive with heading, block_id is required except on Kanban sub-tasks where it is refused, and position is ignored without a heading or under a parent.

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

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

The description opens with a specific verb and resource: 'Create a correctly-formatted task in one call.' It immediately distinguishes this from sibling tools by naming vault_update_task and vault_list_tasks, and the examples make the exact scope 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?

It has an explicit 'When to use' section and routes lightweight checklist items to vault_update_task's add_subtasks param. It also explains when to use vault_update_task later for in_progress status, so both the positive and alternative paths are covered.

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 flag destructiveHint=true, but the description adds real behavioral detail beyond them: continuation lines under the entry are also removed, identical copies make the match ambiguous, and a guard refuses deletes that would shrink the file by more than half. It also enumerates the concrete error strings and their remedies, including path-name and permissions failures.

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?

Purpose and examples are front-loaded, then when-to-use, parameters, errors and return value in a predictable order. It is long — the ten-entry error catalogue is more than most agents need and repeats what runtime messages would say — but each section is scannable and the two examples clarify the ambiguous date+entry pairing.

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, but the description supplies a Returns line ('Deleted entry from About Me/<file>.md → ## <section>'). Combined with the usage policy, matching rules and error recovery, an agent has everything needed to invoke this correctly and to recover from failure.

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, and the description genuinely adds matching semantics the schema lacks: date+entry jointly select the bullet, entry matches only the bullet's first line, and section scopes the match so an identical entry under another heading is not found. It stops short of restating the naming/format rules for `file` and `date` in prose, but the schema covers those adequately.

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

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

States a specific verb and resource with scope: 'Delete a single dated entry from a memory file in About Me/.' The two worked examples show the exact call shape, and the description explicitly separates this from vault_update_memory, vault_delete_note and vault_delete_span, so an agent can pick it without opening the schema.

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

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

Gives explicit when-to-use ('removing an entry that was wrong when it was written'), explicit when-NOT ('memory files are append-only by default, so do NOT delete to reflect a change: append via vault_update_memory'), a named exception (files declaring `entry-policy: living`), a prerequisite (call vault_get_memory first) and the alternative for whole notes (vault_delete_note). Nothing is left to inference.

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

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

Although annotations declare destructiveHint=true and readOnlyHint=false, the description adds substantial behavior the annotations cannot convey: the vault's 'Deleted files' setting determines whether the note goes to trash or is permanently deleted, retention rules apply, links break, protected paths are refused, and pruning is best-effort. It also documents concrete error messages and recovery steps, which is unusually transparent for a destructive 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 long but well-structured, front-loading the core action before examples, usage guidance, behavior, parameters, errors, and returns. The extensive error catalogue is justified for a destructive filesystem operation, though the entry is verbose enough that an agent must scan rather than absorb it in one glance.

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 outcomes, trash behavior and retention, protected paths, link breakage, pruning semantics, path-format errors, configuration failures, and the confirmation message. With no output schema, it supplies the return-value detail needed, and it is complete enough for an agent to call the tool safely despite its destructive nature.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: prune_empty_folders keeps a folder that contains any file, even a hidden .DS_Store, and pruning failures never fail the call. The examples also reinforce the vault-relative path format and optional pruning 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: delete a markdown note, and explains the two possible outcomes (move to .trash/ or permanent removal). It explicitly distinguishes the tool from vault_delete_memory, vault_move_note, and vault_write_note, so an agent can identify its exact role among siblings.

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

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

The description states exactly when to use it (removing a note no longer needed) and names alternatives for adjacent tasks: vault_delete_memory for memory entries, vault_move_note for relocation, and vault_write_note with overwrite for replacement. It also advises using vault_get_backlinks before deletion when link breakage matters.

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 declare destructiveHint=true, but the description adds substantial behavioral context: properties are preserved, CRLF is normalized to LF, blank-line collapse rules are described in detail, same-line anchors delete one line, code-block fence ambiguity is explained, and concurrent-write retry behavior is included. This goes well beyond what the annotations provide.

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 appropriately sized for a destructive editing tool with nuanced anchor and line-break behavior. It is front-loaded with the core purpose, then structured into Examples, When to use, Parameters, Behavior, Errors, and Returns, with no obviously redundant section.

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 four parameters, destructive annotations, no output schema, and complex anchor semantics, the description is complete. It explains the return value, error recovery paths, edge cases, and behavioral guarantees an agent needs to invoke the tool correctly.

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

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

Schema coverage is 100%, but the description still adds meaning beyond the schema: end_anchor is searched at or after the start line and must be unique among those lines, same-line anchors delete only that line, first_match changes ambiguity handling, and the code-block fence caveat explains a non-obvious anchor constraint. These are useful semantics the schema alone does not provide.

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 and resource — deleting a contiguous block of whole lines from a note by anchor substrings — and explicitly distinguishes the tool from vault_replace_in_note and vault_replace_span. An agent can tell exactly what this tool does and how it differs from siblings without opening any schema.

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

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

It gives explicit when-to-use guidance ('Removing a block you have already read — a table row, callout, or run of list items') and names the alternatives: vault_replace_in_note for small in-place edits and vault_replace_span for block replacement. It also clarifies a when-not-to-use case ('this tool only deletes').

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 annotations, the description discloses indexing delay, exclusion semantics, truncation behavior, and specific error cases including SQLite/index integrity failures. This provides rich operational context for a read-only, idempotent 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 long but well-structured and front-loaded with purpose, examples, usage guidance, parameters, behavior, errors, and returns. The density is justified by the tool's nuanced exclusion and error behavior, with no obvious 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?

With no output schema, the description still fully explains the returned JSON array, field meanings, conditional fields, and sort order. Combined with usage guidance and error handling, it gives an agent everything needed to call and interpret 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?

Although schema coverage is 100%, the description adds substantial meaning: exclude_folders replaces defaults, requires re-listing defaults, applies folder-wide and case-insensitively, and affects results but not incoming links. It also clarifies that limit applies after exclusions and sorting and that truncation is not signaled.

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 and resource: finding notes with no incoming links from other notes or canvases. It also clarifies the edge case that a self-linking note still counts as an orphan, making the tool's 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?

It gives an explicit when-to-use scenario (vault maintenance) and names the alternative vault_get_backlinks for checking one note's connectivity. It also explains how to resolve an orphan via vault_patch_note, so the agent knows both selection and follow-up.

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, idempotent, non-destructive, but the description goes well beyond them: it discloses that links inside code blocks are ignored, that self-links appear in their own backlinks, that heading anchors and aliases resolve to the base note, and that recently written notes may not appear yet due to indexing latency. It also classifies errors into caller-caused versus index-failure categories, which annotations cannot express.

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?

Front-loaded with purpose and link-type coverage, then usage, parameters, returns, and errors in a scannable order. Slightly long, and the Returns section partly restates what could be inferred, but every section carries actionable information for a single-parameter tool.

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

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

Despite no output schema, the description documents the return shape (path, backlinks array of {path, title, bytes} sorted by title, count), the empty-result-vs-error distinction, indexing latency, and remediation via vault_search/vault_list_notes. An agent can call this correctly and interpret both success and failure without further information.

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 earns above baseline by clarifying that path is the target's own path, not a link's text, and explaining that link forms (bare [[Note]], relative ../Note.md, full path) all count toward the resolved note. It does not repeat the case-sensitivity/extension rule, which the schema already handles.

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

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

States a specific verb and resource ('Find all notes and canvases that link to a given note or canvas') and immediately enumerates the link forms it captures — wikilinks, markdown links, embeds, frontmatter properties, canvas cards. This is far more specific than the title and lets an agent distinguish it from outgoing-link and orphan-finding siblings without opening schemas.

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

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

Explicit 'When to use' section names concrete tasks (assessing connectivity before editing/deleting, graph exploration) and explicitly routes alternatives: vault_get_outgoing_links for outgoing links, vault_find_orphans for unlinked notes. When and when-not are both covered.

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/non-destructive, yet the description still adds real value: the three-level config resolution chain (env vars → .obsidian/daily-notes.json → defaults), the specific error strings and their fixes, and the non-existence behavior. The only gap is that rate/perf characteristics aren't mentioned, which is minor for a local read.

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

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

Front-loaded with purpose, then examples, when-to-use, params, errors, returns — a clean structure. The error enumeration is long but each entry names an actionable cause; slightly verbose for a one-parameter read tool.

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

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

No output schema exists, and the description fully specifies the return shape (path/content/exists) including the null-content case and the follow-up action (vault_write_note). Combined with the error catalog and config precedence, an agent has everything needed to call and handle results 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% and already states the YYYY-MM-DD format and the today-default, so the baseline is 3. The description adds meaning beyond the schema by clarifying the input format is always ISO regardless of the vault's configured filename format, and that past and future dates are both accepted.

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?

Opens with a specific verb+resource+scope: 'Read a daily note by date, using the vault's configured Daily Notes folder and filename date format.' This clearly separates it from the generic path-based vault_read_note sibling, and the examples make the unit of work 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?

Explicit 'When to use' section plus two named alternatives with their selection conditions: use vault_patch_note with the returned path to append, and vault_recent_notes for recent activity because it 'has no date filter.' An agent has no ambiguity about routing.

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 cover safety (readOnly, idempotent, non-destructive, closed-world), yet the description still adds real behavior: output shape flips from raw markdown to JSON when on_or_after is present, the properties block is stripped, empty results return an empty string, and the no-arg call "can be large." The error catalog documents constraint failures and what each message means, which the annotations do not.

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?

Behavior is front-loaded and the examples are genuinely useful, but there is redundancy: the section-scoping behavior is stated in the header line and then restated in prose ("Add section to scope to one H2 section; omit it to read every H2 section's entries..."). The long error list is valuable but pushes the description toward the upper end of useful length.

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 must carry return values — and it does, describing both the markdown and JSON return shapes down to the entry fields ({ file, section, date, text }) and the empty-match case. Combined with the error catalog and prerequisite, an agent has everything needed to call 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?

Although the schema covers 100% of parameters, the description supplies semantics the schema cannot express: section requires file, on_or_after requires file, entries come back in document order, and omitting section reads every H2 section with attribution preserved. Four concrete call examples map parameter combinations to results.

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 opening sentence gives a specific verb and resource ("Read semantic memory from About Me/ files") and immediately specifies the data model (dated bullet entries under H2 headings). The three scoping modes (file, file+section, no args) are enumerated so the agent can distinguish this from vault_read_note and vault_memory_recall without opening the schema.

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

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

It contains an explicit "When to use" clause covering preferences/principles/opinions, plus a prerequisite (call vault_list_memory_files first to discover names). It also routes to alternatives by condition: vault_read_note for non-memory notes, vault_memory_recall for topic search across files.

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 substantial context beyond annotations: code-block links are ignored, self-links are included, duplicate targets are listed once, canvas links follow file nodes only, and broken-link paths have defined normalization. It also explains empty results for nonexistent/dot-prefixed paths, daily-note forward-reference behavior, and the bytes caveat about read_file downscaling.

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?

Despite its length, it is organized and front-loaded: purpose, link types, examples, when-to-use, parameter caveat, returns, and errors. The extra detail is justified by the absence of an output schema and by the non-obvious link and broken-path semantics.

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

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

With no output schema and complex return semantics, the description fully explains the JSON shape, field meanings, broken-link behavior, daily-note flag, error messages, and non-error empty-result cases. An agent has enough information to call it and interpret the result without guessing.

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

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

Schema coverage is 100%, so the schema already documents the path parameter thoroughly. The description still adds useful semantics: the examples show note and canvas usage, and it warns that a note or canvas created or moved in the last few seconds may not be found yet.

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 and resource: "Find all notes and files a given note or canvas links to." It explicitly distinguishes notes from canvas files and later routes incoming-link queries to vault_get_backlinks, so an agent can identify the tool's scope immediately.

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 gives explicit "When to use" cases: forward graph navigation, auditing broken links in one note/canvas, and checking dependencies before editing. It also names the alternative vault_get_backlinks for incoming links and fallback discovery tools when an unexpected empty result occurs.

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 non-read-only, non-destructive, non-idempotent, but the description adds real behavioral context beyond them: atomicity ('A failed save leaves the note unchanged'), line-ending normalization (CRLF to LF), property-block preservation, and a full error taxonomy including concurrent-write and paths. Minor gap: no explicit statement about the ambiguity/repeat-call risk implied by idempotentHint=false.

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?

Front-loaded with the core action, then examples, when-to-use, errors, syntax notes, and returns in a scannable structure. The error list is long because the tool genuinely has many failure modes, but the two worked examples restate points made elsewhere, keeping it just short of maximally tight.

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?

Thorough for a non-idempotent mutation tool with no output schema: return value format is described precisely, every documented error has a remediation, and Obsidian Markdown pitfalls (#, [[, %%) are flagged. What's missing is only peripheral (e.g., whether the note is created if absent is covered indirectly by 'note not found').

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 of 3 applies, and the description goes beyond it with verbatim-insertion semantics ('blank lines inside it are kept, and a trailing newline adds a blank line after the inserted block') and the first_match remedy for ambiguous anchors. Not a 5 because the anchor's case-sensitivity and uniqueness expectations are carried mainly by 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?

States a specific verb and resource ('insert content as whole lines into a note's body') plus the targeting mechanism (anchor substring, before/after). It immediately distinguishes itself from sibling insert tools by naming vault_patch_note and vault_replace_span as the 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?

Has an explicit 'When to use' section with concrete scenarios (table rows, list items, landmark lines) and then routes away from itself: 'Prefer vault_patch_note for heading-targeted inserts' and 'Prefer vault_replace_span when replacing a block rather than inserting next to it.' Conditions for choosing each alternative are spelled out.

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/non-destructive, and the description adds real behavior beyond them: exact-case folder matching on case-sensitive filesystems, permanent invisibility of dot-prefixed files and .obsidian/, empty-listing-not-error semantics, the three distinct error classes with remediation, and truncation via `truncated`. That is disclosure of what can silently return fewer results than expected — precisely the risk an agent needs to know about for a listing 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?

Front-loaded one-liner followed by labeled sections (Example / When to use / Behavior / Errors / Returns / Readable types), so an agent can skim to what it needs. It runs long — the three worked examples and the multi-line error table are more than strictly necessary — but nearly every line carries operational information rather than filler.

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

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

There is no output schema, and the description compensates by fully spelling out the return shape ({ path, extension, bytes }, extension_counts, total, truncated) and the sort order. Combined with error handling and the readable-type list that gates the natural next call to vault_read_file, nothing an agent needs to invoke this correctly 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%, so the baseline is 3; the description still adds value by stating the case-sensitivity rule for `folder` ("use the folder's exact letter case") and illustrating real invocations with `extensions` and `limit`. It does not re-explain `limit` truncation semantics in the parameter discussion, but the Returns section covers it, so the gap is minor.

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?

Opens with a specific verb+resource and an explicit scope qualifier: "List non-markdown files in the vault or a folder — images, canvases, PDFs, data files", plus what is returned (byte sizes, extension counts). The markdown/non-markdown boundary is exactly the line that differentiates it from the note-oriented siblings, so an agent can route correctly from the first sentence alone.

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?

A dedicated "When to use" clause names the downstream step (read with vault_read_file) and explicitly excludes three siblings with the reason: vault_list_notes and vault_search_by_folder are markdown-only, vault_search indexes only canvas/PDF/text. It even routes the link-following case to vault_get_outgoing_links, so both when-to-use and when-not-to-use are covered.

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 cover the safety profile (readOnly/idempotent/non-destructive), and the description adds substantial context beyond them: sorted by file name, subfolders not read, dotfiles skipped, empty folder returns [] rather than erroring, and the two failure strings with remediation steps. It also explains the entry_policy semantics and that the server does not enforce them — non-obvious behavior an agent needs before pruning.

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?

Front-loaded and sectioned (When to use / Behavior / Errors / Returns), so an agent can scan it quickly. Slightly over-long: the opening summary is restated almost verbatim in the Returns section, and the `Example: vault_list_memory_files()` line adds nothing for a zero-argument call.

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 carries the full burden of documenting the return shape, and it does so field by field ({ file, title, bytes, entry_policy, leading_callout, headings }) including the nested heading shape and entry_count placement. Error conditions and the empty-folder edge case are both covered, so nothing an agent needs to call and interpret this correctly 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?

Zero parameters, so the baseline is 4; the description correctly spends its budget elsewhere rather than inventing parameter detail. It does clarify the identity semantics of the returned `file` value (name without .md, the same value other memory tools accept), which is useful downstream context even though this tool takes no input.

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?

Opens with a specific verb+resource ("lists About Me/ memory files with each file's heading outline, per-section entry counts, and leading callout") and immediately negates the most likely misread: "Does NOT return actual entries." This clearly separates it from vault_list_files (generic file listing), vault_get_memory (returns entries), and vault_memory_recall (topic 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?

Explicitly stages usage: discover files/sections BEFORE vault_get_memory, vault_update_memory, or vault_delete_memory, and names the routing alternative — vault_memory_recall for finding entries by topic. Exclusions and prerequisites are both stated, leaving nothing to 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 declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description still adds real behavioral detail beyond them: sorted output order, hidden paths never listed, symlinks included, no result cap, and empty array rather than error on misses. However, the annotation baseline is already strong, and several of these disclosures overlap with what idempotent/readOnly imply, so this lands at a solid 3 rather than higher.

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?

Front-loaded with purpose, then examples, then when-to-use, then parameters, then behavior and errors — a clear hierarchy. It runs long for a two-parameter read tool, and the filesystem error section (ENAMETOOLONG, EACCES) is heavier than this tool's decision surface requires, but nearly every sentence carries 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?

No output schema exists, and the description compensates by specifying the return shape (JSON array of vault-relative paths), the absence of a result cap, sort order, and the empty-array-on-no-match contract. An agent can call this correctly and interpret the result without further information.

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%, yet the description adds semantics the schema does not carry: folder without a glob recurses into subfolders but does not prefix-match siblings ("Projects" covers "Projects/Archive" but not "ProjectsOld/"), folder matching is case-sensitive, and glob resolves against the folder-relative path with * single-level and ** arbitrary depth. This is genuinely additive over the schema's one-line parameter descriptions.

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

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

States a specific verb and resource ("List .md file paths in the vault") and immediately bounds scope with "Returns paths only — not content or metadata." This distinguishes it from vault_search_by_folder and vault_search, which handle metadata and content respectively.

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?

"When to use" names the browsing-by-filename case, then explicitly routes to alternatives with conditions: vault_search_by_folder for metadata, vault_search for content discovery, vault_read_note to read a result. Selection is fully determined without 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 declare readOnly/idempotent/non-destructive, yet the description goes well beyond them: it explains that only frontmatter properties count and inline Dataview fields are excluded, defines what count includes (null-valued notes), explains how sample_values are computed (3 most frequent displayed strings, array elements counted separately, booleans as '1'/'0'), and documents empty-result and SqliteError 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?

Front-loaded and cleanly sectioned into Examples / When to use / Parameters / Behavior / Errors / Returns, so it scans well. It is on the long side, with two examples and a Returns line that partly restates the earlier example, but nearly every line carries load-bearing 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 single-parameter read tool with no output schema, it supplies everything needed: output shape and sort order, scoping rules, exclusion of inline fields, counting semantics, and both silent (empty array) and error ('[SqliteError]: …') failure modes with the advice that the index, not the call, failed.

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 would be 3, but the description adds genuinely non-obvious semantics the schema does not: folder includes subfolders ('Projects' covers 'Projects/Archive' but not 'ProjectsOld/'), matching ignores ASCII case, and omitting the parameter scans the entire vault.

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

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

States a specific verb+resource ('Discover all property keys in the vault') with the key differentiator from note-reading siblings spelled out: 'without reading individual notes.' It also shows the exact return shape and scoping example, so an agent immediately knows this is a metadata-level inventory call rather than a content read.

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 'When to use' clause, plus a direct pairing with vault_list_tags for orientation, and two named alternatives with the exact conditions that select them (vault_list_property_values for full value lists, vault_search_by_property for key-value matching). Nothing is left to inference.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive operation, and the description adds substantial behavioral detail. It explains array element counting, grouping of equal displayed strings, checkbox coercion, null skipping, limit ordering, lack of truncation signaling, and error 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 long but well structured with examples, usage guidance, parameter notes, behavior, errors, and returns. The extra length is justified by subtle counting, grouping, and sorting semantics that an agent could easily get wrong.

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 read-only listing tool with no output schema, the description covers everything needed: return shape, sort order, truncation behavior, empty results, and index-error handling. There are no significant omissions for correct invocation or interpretation.

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 semantics beyond the schema. It specifies that key matching is case-sensitive and exact, that folder includes subfolders but excludes similarly prefixed names, and that limit is applied after count-descending sorting.

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 and resource: listing distinct values for a property key, including occurrence counts. It clearly distinguishes this from sibling tools by naming vault_search_by_property and vault_list_property_keys as related operations.

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

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

It explicitly says when to use the tool: enumerating possible values before calling vault_search_by_property. It also gives the prerequisite action to call vault_list_property_keys first to discover valid key names.

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 cover the safety profile (readOnly, idempotent, non-destructive), so this is bonus context: frontmatter-only counting (inline #tags excluded), case-insensitive tag unification with most-common spelling shown, no hierarchical splitting, count = unique notes. It also discloses error behavior (empty array is not an error; SqliteError means index failure) — exactly the kind of operational detail annotations cannot express.

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?

Front-loaded with purpose, then example, then usage, then errors — a clean progression with no filler. Minor deductions: the 'Returns' line partly restates the example, and the SqliteError bullet's guidance ('the message says what to do') is vague enough to add little.

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 zero-param read tool with no output schema, the description covers everything an agent needs: aggregation rules, ordering, casing behavior, output shape, edge case, and a sibling alternative for the folder/limit 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?

Zero parameters, so there is no input semantics to explain and the baseline is 4. The description instead invests in output semantics ('tag omits the # prefix'), which is useful given there is no output 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?

States a specific verb and resource ('List all tags in the vault with note counts') plus exact ordering semantics, and immediately distinguishes itself from tag-searching and property-value siblings. An agent knows precisely what this returns without opening any schema.

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

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

Explicit 'When to use' section frames it as a discovery step, then names the alternative route: 'Prefer vault_search_by_tag once you know which tag', and points to vault_list_property_values for folder-scoped or limited counts. Both the when and the when-not are covered with named 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 declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: indexing exclusions (fenced code blocks, %% %% comments, NON_TASK statuses), the staleness caveat that a just-written task may show old state, and a per-message error catalog with recovery guidance. It also states that no matches returns { total: 0, tasks: [] } rather than an error, which prevents false failure handling.

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?

Front-loaded with purpose, then examples, usage, behavior, parameters, errors, returns — a scannable structure where each block has a distinct job. It is long and somewhat repetitive (the examples restate points made in the prose, and the Returns inventory is dense), but almost every line carries information an agent would otherwise have to discover by trial.

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 16-parameter, nested-object, no-output-schema tool, the description supplies what the structured fields cannot: return shape with per-field presence rules, subtask_progress semantics and its independence from query filters, indexing exclusions, and a named error catalog. Nothing an agent needs to call it correctly or interpret the response appears to be 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%, so baseline is 3; the description still earns credit by adding semantics the schema omits — status array expansion (["not_done","done"] matches todo+in_progress+done), the rule that date filters only match tasks that actually have that date, folder boundary and case-insensitivity behavior, and sort tie-breaking (undated tasks last, no-priority tasks between medium and low). It leaves limit, top_level_only, heading, tag, and priority purely to the schema, so it is additive rather than complete.

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?

Opens with a specific verb+resource+scope ("List checkbox tasks across the whole vault") and immediately names the data model it indexes (Tasks-plugin emoji signifiers and Dataview inline fields). It explicitly distinguishes itself from vault_read_note and vault_search, so an agent can pick the right tool without opening schemas.

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

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

Contains a dedicated "When to use" block covering board reading with sort_by: "position" and vault-wide triage, plus two explicit "Prefer X only when…" alternatives (vault_read_note heading mode for verbatim Markdown, vault_search for full-text). Four worked examples map concrete intent (overdue triage, Kanban lanes, project tree, completed this week) onto parameter shapes.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantially more: index lag of a few seconds, recall-over-precision tuning with marginal entries expected, threshold degradation to any-term keyword matching, and a documented error taxonomy where empty results are not errors. It also explains search_mode and reranked flags, which an agent needs to interpret the response.

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?

Front-loaded with the core statement and cleanly sectioned by Examples / When to use / Behavior / Errors / Returns, so an agent can scan to the relevant part. It is long, however, and the return shape is introduced twice — 'Returns the relevant dated entries, up to limit, sorted oldest-first' up top and again in the Returns block — so some trimming is available.

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

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

There is no output schema, and the description fully compensates: it enumerates the JSON keys (entries, total, truncated, search_mode, reranked), the shape of each entry, and how file/section feed into vault_get_memory or vault_delete_memory. For a 3-parameter read tool with annotations already carrying safety, nothing an agent needs to call or interpret it correctly 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%, so the baseline is 3, but the description goes beyond it: it advises content-word query phrasing ('testing philosophy', 'sustainable pacing') as ranking best and explains the meta-framed query fallback, and it clarifies that the file filter is applied before limit, which materially changes what limit means. Slight gap: limit's interaction with the 9007199254740991 maximum is not discussed, and query construction guidance stays at the example level.

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

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

States a specific verb and resource ('Recall memory entries about a topic'), plus the retrieval mechanism (entry-granular hybrid keyword + semantic) and scope (ALL About Me/ files, ALL time). An agent can immediately distinguish this from vault_get_memory (verbatim read of a known file) and vault_search (notes outside the memory layer) without opening any schema.

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

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

Explicit 'When to use' block names the two triggering question shapes ('what does my memory say about X?' and 'how has my view on Y evolved?') and routes to both alternatives with the conditions that select them: vault_get_memory for a known file/section verbatim, vault_search for non-memory notes. Nothing is left to inference.

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

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

Annotations already flag destructiveHint=true and non-idempotence, but the description adds substantial context the annotations cannot: exactly which link forms are rewritten, when links are left alone, preservation of embed/heading/alias syntax, no-overwrite behavior, case-only rename support, partial-failure states, and best-effort pruning. This is far beyond the annotation baseline.

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 core purpose and alternatives are front-loaded, and examples are clearly separated. The exhaustive error catalog is valuable for recovery but makes the description long; every item earns its place, yet the overall density is heavy enough that it is not maximally 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 complex, destructive move tool with three parameters and no output schema, the description covers return values, all relevant error states, protected-path constraints, link-rewrite behavior, and partial-failure semantics. Nothing an agent needs in order to invoke or recover from this 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?

Schema coverage is 100%, so the parameters are already documented. The description still adds useful semantics beyond the schema: prune_empty_folders keeps any folder containing even a hidden file, in-place moves and moves into subfolders prune nothing, pruning is best-effort, and path case/extension rules are reinforced with examples. The extra value is real but not indispensable given 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 states a specific verb and resource — moving or renaming a note while rewriting all links across the vault — and explicitly names the sibling alternatives it replaces (vault_write_note + vault_delete_note, vault_patch_note, vault_update_properties). An agent can distinguish this from every other note-mutating sibling without opening the schema.

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

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

It provides explicit when-to-use guidance, names the alternatives for body/property edits, explains why not to use delete+write, and documents protected paths that cannot be moved. The examples and error guidance further clarify selection conditions.

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 flag destructiveHint=true and idempotentHint=false, but the description goes far beyond them: it discloses LF normalization of CRLF, that content is written verbatim with no separator, section-boundary rules including child-heading inheritance, and a warning that replace destroys child headings unless include_children is set. It also enumerates concurrency behavior ("concurrent write in progress"), path-safety blocks, and the exact return confirmation format.

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?

Placeholder.

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 six-parameter mutation tool with no output schema, the description covers purpose, routing, operation semantics, boundary edge cases, a full error taxonomy with remedies, and the return message shape — including the special nested-prepend confirmation. An agent has everything needed to call it correctly and to recover from 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 baseline would be 3, but the description adds substantial semantics the schema does not carry: per-operation behavior for append/prepend/replace/insert_before, when heading may be omitted, heading_level as the disambiguator for duplicate headings, and include_children as a destructive-write confirmation gate. The table-row and callout guidance further constrains how content must be formed.

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

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

States a specific verb and resource ("Surgical edits to a markdown note") and immediately enumerates the four supported operations, so the agent knows exactly what capability this exposes. The "When to use" block explicitly contrasts it with vault_write_note, vault_replace_in_note, vault_insert_at_anchor, vault_replace_span, vault_delete_span, and vault_update_properties, making it distinguishable from every overlapping sibling.

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?

"Modifying part of an existing note without overwriting the entire body" gives the positive selection criterion, and each of the ten "Prefer X for Y" lines names the alternative and the condition that routes to it. Exclusions are explicit (creating notes, full rewrites, in-place text fixes, property edits, task operations), leaving nothing to 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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description goes far beyond them: it documents the 49152-byte image budget and 1568-pixel downscale threshold, the 100 KiB text cap, the 5-page limit on PDF raw rendering, the 50 MiB file cap, the first-frame reduction for animated GIFs, the byte-exact vs. paged newline difference, and a full error catalogue with recovery actions. This is the load-bearing content 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?

Well front-loaded and sectioned (examples, when-to-use, return shapes per type, raw semantics, paging, errors, returns), so an agent can scan to the needed part. However, the roughly two-dozen-error catalogue is disproportionately long for a read tool and includes entries whose recovery is obvious (EACCES, ENAMETOOLONG); it could be compressed to the errors that change agent behavior.

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 4-param read tool with no output schema and a highly variable return type, the description supplies exactly what is missing: what each content block looks like per file type, how paging manifests in the output, and how each failure mode should be retried. Nothing an agent needs to invoke it correctly or recover from failure is absent.

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 still adds real meaning: raw is explained as a canvas-JSON vs. outline switch and a PDF-images vs. extracted-text switch (and that it is a no-op for text formats), and start_line/limit are described as a line window with a concrete continuation metadata line format, plus the tip of requesting start_line: 1 with limit: 1 to learn total line count. It also states which combinations error out (paging on images, raw on images).

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

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

States a specific verb and resource ("Read a non-markdown vault file") and explicitly positions itself as the read-side companion to vault_read_note, defining the boundary at .md. The per-type examples make the scope concrete and distinguishable from every sibling in one sentence.

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?

A dedicated "When to use" block names the alternatives and the conditions that select them: vault_read_note for .md, vault_get_outgoing_links for discovering linked files, vault_list_files for browsing, and an explicit note that vault_search indexes some but not all of these types. Exclusions are stated, not inferred.

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?

Goes well past the readOnly/idempotent annotations: it discloses that the tool sets no response cap, that unpaged full reads return exact bytes while heading/paged reads normalize to LF, that sections extend to the next same-or-higher heading, and how window metadata is prepended. It also documents a full error catalog with remediation for each, which is exactly the burden a description should carry when there is no output schema.

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

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

Well front-loaded: purpose, then examples, then when-to-use, errors, returns, outline semantics — easy to scan. However, it is very long, with five examples and a ~12-entry error catalog; a few entries (e.g. generic filesystem error codes, ENAMETOOLONG) are marginal and push it past what most calls need.

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 specifies return shapes for all four modes (raw markdown, properties JSON, outline object, section markdown) plus the window-metadata preamble and byte/line-ending differences. All seven parameters are covered via schema plus description, so an agent has everything needed to call this correctly on the first attempt.

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 already 100%, so the baseline is 3; the description earns more by explaining relationships the schema cannot express — outline/heading/properties_only are mutually exclusive, heading_level only disambiguates same-text headings, and start_line/limit apply only to full or heading reads. The line-count trick (start_line: 1, limit: 1) adds genuine operational meaning beyond the field descriptions, though some detail is duplicated rather than new.

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?

Opens with a specific verb+resource ('Read a markdown note by its vault-relative path') and immediately enumerates the four content modes. It explicitly distinguishes itself from vault_search (unknown path), vault_get_memory (About Me files), and vault_list_tasks (task status) without the agent needing to open sibling 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?

Contains an explicit 'When to use' section with the positive condition (you know the exact path) plus named alternatives for each divergent case: vault_search, vault_list_tasks, vault_get_memory, vault_patch_note, vault_get_backlinks, vault_get_outgoing_links. It also prescribes an escalation path for large notes (outline → heading → start_line/limit) rather than leaving it to 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 declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered by structured data. The description still adds real value beyond that: index lag of a few seconds, the fact that "modified" tracks sync touches and property writes, null created values sorting last, and how [SqliteError]/[IndexIntegrityError] messages should be read as index failures rather than call failures.

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?

Front-loaded with the key distinction, which is good, but the block is long for a two-parameter tool and repeats the same sort_by/limit tradeoff across the Parameters section and the example lines. The two example calls largely duplicate what the schema defaults already convey.

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 carries the return-value burden and does so thoroughly: it enumerates the metadata fields, calls out that created is null for missing/non-ISO frontmatter, defines bytes as on-disk size, and explains when leading_callout and additional_properties are present. Empty-vault and error cases are also covered, so nothing needed for a correct call 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%, so both parameters are already documented, giving a baseline of 3. The description does go further by explaining the interaction between sort_by and limit (undated notes sorting last can be pushed out by a small limit), but it restates the enum semantics rather than adding syntax or format detail the schema lacks.

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

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

States a specific verb and resource ("List recently modified or created notes, sorted by timestamp") and immediately delimits scope with "a time-ordered window into the vault, not a date-range filter." That contrast alone separates it from vault_search with its created/modified range filters, so an agent can pick it without opening a schema.

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" list names the concrete situations (catching up, finding recent work, orienting after a break), and two named alternatives are offered with the condition that selects them: vault_search for content queries, vault_search_by_folder for folder browsing. Both when and when-not are covered.

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 destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered structurally; the description nonetheless adds substantial value beyond them — CRLF-to-LF normalization, properties left verbatim, the blank-line collapse rules, control-character rejection, and the 'concurrent write in progress' retry path. It loses points only because several of these blocks (the deletion blank-line algebra) are dense to the point of being hard to act on in one read.

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

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

Purpose, examples, when-to-use, parameters, errors, and return value are cleanly sectioned and front-loaded, and the three examples map to the three distinct modes (replace, delete, replace-all). It is on the long side for a four-parameter tool, and the multi-level blank-line rules are the one passage that could be tightened.

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 correctly states the return string ('Replaced <N> occurrence(s) in <path>') and enumerates the error surface including path-safety and encoding failures. Nothing an agent needs in order to call this correctly is missing; the only residual gap is that the note-mutating semantics for the 'properties block' error are described but not resolvable without a follow-up read.

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

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

Schema coverage is 100%, so the baseline is 3; the description does go further by advising that old_text include surrounding context for uniqueness, spelling out that new_text="" deletes, and warning to include the trailing line break when removing a table row or list item. Those are real additions beyond the schema, but the largest chunk of the parameter section is the blank-line normalization rules, which are output-shape behavior rather than parameter meaning.

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?

Opens with a specific verb+resource: 'Find and replace exact text in a markdown note's body,' and immediately delimits scope by saying properties are untouched and pointing at vault_update_properties/vault_write_note for them. An agent can distinguish this from vault_replace_span and vault_patch_note without opening any schema.

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

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

An explicit 'When to use' sentence names concrete cases (typos, value updates, term renames, short-line deletion) and routes three alternative scenarios to specific siblings: vault_delete_span for large block deletion, vault_replace_span for anchor-based replacement, and vault_patch_note with an add-before-delete rationale for relocations. This is exactly the when/when-not/alternative structure the top score requires.

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 destructiveHint=true and readOnlyHint=false, so the description goes beyond that with real behavior: properties are preserved, CRLF is normalized to LF, content line breaks merge with adjacent empty lines and can split tables, empty/whitespace-only lines are treated distinctly, and concurrent writes are rejected with retry guidance.

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?

Front-loaded with the purpose, then examples, then guidance, then parameters and errors – well structured with headers. It is long, and the exhaustive error catalog is heavier than most calls need, but nearly every line carries actionable 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?

Covers purpose, alternatives, tricky parameter interactions, Obsidian Markdown escaping gotchas (#, [[, %%), the full error surface with recovery steps, and the exact return string. Nothing material is missing for a destructive 5-parameter mutation tool with no 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 coverage is 100%, so the baseline is 3; the schema already documents path, start_anchor, end_anchor, first_match and content. The description does add genuine edge-case meaning (end_anchor searched at or after the start line, same-line collapse, first_match ending at the opening fence), which would push it slightly above the baseline but not to a full 5 since most parameter semantics are already in 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?

States a specific verb (replace), resource (a contiguous block of whole lines in a note's body) and the distinctive mechanism (anchor substrings instead of old_text). This clearly separates it from vault_replace_in_note and vault_patch_note without needing to open their 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?

Has an explicit 'When to use' section, plus named alternatives with the conditions that select them: vault_replace_in_note for small in-place edits and vault_delete_span for removals. It also routes the code-block-fence case to vault_replace_in_note instead.

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?

Although annotations already establish that this is a safe, read-only, idempotent operation, the description adds substantial behavioral context: hybrid ranking, query parsing rules, filter AND-combination, date-bound timezone behavior, index lag, and error handling. It also distinguishes empty results from errors and explains how malformed syntax is handled.

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

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

The description is well structured and front-loads the core purpose, filters, examples, and alternatives. It is unusually long, with detailed error strings and return-field notes, but most of the content is useful for correct invocation; the length is justified though not maximally 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, 100% schema coverage, annotations, and lack of an output schema, the description is complete enough for an agent to call it correctly. It covers query syntax, filter semantics, alternatives, edge cases, error behavior, and the shape of returned results.

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 would be 3, but the description adds meaningful semantics beyond the schema. It clarifies stemming, exact-phrase quoting, punctuated-term behavior, folder case/subfolder rules, tag case/prefix matching, property type comparison including the boolean/1 exception, and calendar-day date-bound 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 states a specific verb and resource — hybrid search across vault notes and file content — and explains the ranking model. It explicitly distinguishes this as the primary content-based discovery tool versus tag-only, folder-browsing, property-only, and time-based sibling 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?

It gives explicit when-to-use guidance and names alternatives for tag-only, folder browsing, metadata-only, and recent-note queries. The examples also show how text queries combine with filters in common scenarios.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavioral context: index lag of a few seconds after file changes, hidden dot-folders never appearing, and the fact that truncation is silent with no offset. Error handling is spelled out per class (empty folder returns [], index errors are not call failures).

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?

Front-loaded with purpose, then examples, routing, parameters, behavior, errors, and returns in scannable blocks; the inline gloss on the second example ("the folder's own notes, 10 most recent") is well spent. It is on the long side for a three-parameter read tool and the Returns field list is dense prose that could be trimmed slightly.

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 carries the return value itself, documenting every field including sort order, null-vs-empty conventions (related [], type/created null), and conditional keys (leading_callout, additional_properties). Edge cases, silent truncation, and error semantics are all covered, so nothing needed to call this correctly 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?

Despite 100% schema coverage, the description materially extends the schema: folder is a whole-folder match rather than a text prefix ("Projects" does not match "ProjectsOld/"), matching is ASCII-case-insensitive, and a trailing slash is ignored. It also clarifies that limit applies after sorting and that there is no offset or truncation signal — none of which the schema states.

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?

Opens with a specific verb + resource + scope ("Browse notes in a folder with full metadata"), which distinguishes it from path-only listing and text search. The description explicitly names the sibling alternatives (vault_list_notes, vault_search, vault_get_backlinks) so an agent can route without opening schemas.

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

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

"When to use: Exploring a folder's contents with full context for vault orientation" is followed by two explicit alternative-routing rules (path-only → vault_list_notes, text query → vault_search). Link exploration is also redirected to vault_get_backlinks/vault_get_outgoing_links, leaving no ambiguity about when this tool is the wrong choice.

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?

Goes well beyond the readOnly/idempotent annotations: discloses index lag ('a note written moments ago may not match yet'), that truncation is invisible ('nothing in the response signals truncation'), the exact sort order and its mtime caveat, and the error taxonomy (empty array vs SqliteError vs IndexIntegrityError). This is precisely the context annotations cannot carry.

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?

Front-loaded with purpose and examples, then clean labelled sections (When to use, Parameters, Behavior, Errors, Returns) that make the length scannable. It is long, but nearly every line carries non-obvious information; only the returns-field enumeration could be tightened.

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, so the description carries the return contract — it documents the array shape, sort order, fallback values for title/related/type/created, and when optional fields appear. Combined with error and lag disclosure, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds substantial semantics the schema lacks: case-sensitive exact matching with no globbing, the numeric-coercion rules for finite YAML numbers, checkbox '1'/'0' matching as text only, list element full-equality ('blog' vs 'my-blog'), and folder including subfolders but excluding 'ProjectsOld/'.

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?

Opens with a specific verb+resource+scope: 'Find notes where a frontmatter property matches a value', with two concrete invocation examples. It is immediately distinguishable from vault_search and vault_search_by_tag by the explicit routing sentences that follow.

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 'When to use' section states the condition (metadata lookup without a text query) and names three alternatives with the conditions that select them: vault_search for text+property, vault_search_by_tag for tags, vault_list_property_keys/values for discovery. Nothing is left to inference.

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

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

Beyond the read-only/idempotent annotations, it discloses case-insensitivity, that inline tags in bodies are not searched, nested-tag matching rules with concrete examples, that limit is applied after sorting with no truncation signal in the response, and that results can lag file changes by seconds. Error semantics (empty array vs. real errors, trailing-slash gotcha, SqliteError/IndexIntegrityError meaning) are unusually complete.

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?

Front-loaded with the core rule and examples, then cleanly sectioned into usage, parameters, behavior, errors, and returns. Slightly long in the Returns enumeration, but with no output schema that detail is load-bearing rather than 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?

No output schema exists, and the description fully specifies the return shape (fields, sorting, defaults, ISO timestamps, optional leading_callout/additional_properties). Combined with lag behavior and error taxonomy, an agent has everything needed to call and interpret 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 coverage is 100%, so the baseline is 3; the description earns above that by explaining that with exact=false a tag matches all nested descendants at any depth, that 'project' won't match 'projects' or 'my-project', and that limit is applied after sorting. It does not restate the tag format details already in the schema, which is appropriate.

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

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

States a specific verb+resource ('Find notes by frontmatter tag') and immediately narrows scope by excluding inline #tags. It is clearly distinguishable from siblings such as vault_search (text relevance), vault_search_by_property, and vault_list_tags, which it explicitly references.

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 an explicit 'When to use' section ('tag-only lookups ... no text query'), names vault_list_tags as the discovery step, and routes text-based queries to vault_search. When-to-use and alternatives are both covered.

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 flag idempotentHint=true, but the description earns its keep beyond them: it explains the exact no-op condition (same date + text in same section), the append-only default with a 'newest wins' resolution for changed preferences, the living-file exception, and automatic file/section creation. It also documents failure modes (permissions, path collisions, near-duplicate section headings, properties-block hazard) that no structured field could carry.

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 front-loaded: purpose, two worked examples, when-to-use, then parameters and returns. The error catalogue is long and largely restates error strings the agent will see at call time, which is the only thing holding this back from 5; every other section 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?

No output schema exists, yet the description states the exact return strings, including the duplicate no-op return and the new-file placeholder scope callout. Combined with error handling, the date/position interaction, and the living-file policy, an agent needs nothing else to call this 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; the description adds an important interaction not in the schema — that options.date only sets the bullet's date while placement follows options.position — and shows it in a backdated-entry example. The remaining emphasis on single-line/escaping constraints duplicates what the schema and the Obsidian note already say, so it falls short of 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?

Opens with a specific verb and resource: "Append a dated entry to a section of a memory file in About Me/." It names the scope (memory files under About Me/), the unit of write (a dated entry, in a named section), and the idempotency rule, which separates it from the generic note-writing siblings vault_write_note and vault_patch_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?

There is an explicit "When to use" (recording a preference, principle, opinion, or fact about the user), a prerequisite (call vault_list_memory_files first and reuse existing file/section names) and an exclusions section routing non-memory notes to vault_write_note. The `entry-policy: living` paragraph also names vault_delete_memory as the correct sibling for pruning.

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 destructiveHint=true and idempotentHint=true, but the description goes well beyond them: it says exactly what is destroyed under each mode (null deletes a key; replace wipes the whole block where null writes an empty property and {} removes it), that the note body is preserved, that arrays are replaced not appended, and that concurrent writes require re-read-and-retry. The enumerated error strings map directly to recovery actions.

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?

Front-loaded correctly — merge/replace semantics come before examples, usage, and errors, and every section is actionable. The error catalogue is long (eight entries) and could be compressed for an agent that will simply read the returned message, which keeps it short of a 5 despite zero filler elsewhere.

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, and the description compensates by stating the two return strings. Path constraints (.md extension, vault-relative, no hidden segments) and the Obsidian type-consistency warning cover the remaining failure modes for a destructive, nested-object mutation tool. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, which sets a baseline of 3, but the description adds semantics the schema cannot convey: null as a delete sentinel, {} as a block remover, the replace flag's whole-set behaviour, and array replacement rather than append. These are non-obvious semantics for what is effectively an untyped object parameter (additionalProperties: {}), so the added value is substantial.

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

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

States a specific verb and resource (update a note's frontmatter properties) and immediately distinguishes the two operating modes (shallow merge vs. replace). It also names the sibling it is not used for (vault_write_note for creating notes or replacing bodies), so an agent can pick it out of a 30-tool sibling list without opening a schema.

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" line (changing tags, status, type, or any property without rewriting the body) plus a "Prefer vault_write_note when…" exclusion and a recommended read-first step (vault_read_note with properties_only: true) for the repair case. Alternative selection is fully specified rather than inferred.

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 destructiveHint=true and idempotentHint=false, but the description goes far beyond by explaining what gets destroyed (🏁 delete removes the task line and children), that Kanban 'done' cascades to nested cards, that recurring completions spawn a sibling and that completing by line is NOT idempotent, and that concurrent writes are rejected. It never contradicts the destructive/non-idempotent annotations and reinforces them with concrete mechanisms.

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?

It is front-loaded and well-sectioned (capability, examples, when-to-use, parameters, errors, returns), and the examples are genuinely instructive. However, the ~25-entry error catalogue with per-error repair instructions, plus the Obsidian syntax and full return-value walkthrough, pushes the text well past what most agents need at selection time.

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 19-parameter destructive mutation tool with no output schema, the description covers identification, mutation preconditions, side effects, error recovery, and a full enumeration of the returned JSON fields. Nothing an agent needs in order to call it correctly, or to interpret the result, 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% so the baseline would be 3, but the description adds semantics the schema does not carry: exactly one of block_id or line, that clearing requires explicit null and omission leaves a field untouched, the interaction between recurrence and status 'done', how on_completion overrides the stored 🏁 value, and how position differs from a plain 'bottom' append. This is genuine meaning beyond the 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 opening sentence gives a specific verb (update) and resource (an existing task) plus the exhaustive list of writable fields, and the 'When to use' section explicitly separates it from vault_create_task and vault_list_tasks. An agent can distinguish it from every sibling without reading the schema.

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 states 'Any change to an existing task', directs the agent to vault_list_tasks first for identification fields, names vault_create_task for creation, and names vault_create_task with parent_block_id for full sub-tasks. It also gives explicit exclusions ('cannot move a sub-task to a heading'), which is stronger than typical.

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 destructiveHint=true, and the description substantiates exactly what is destroyed ('the old body's text is lost unless the new body includes it') and how properties survive a body overwrite via merge/unmentioned-key-preservation rules. It also discloses non-obvious behavior an agent would otherwise learn only by failing: concurrent-write errors requiring retry, hidden/absolute path blocking, and properties-block repair failures.

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?

Core mutation semantics are front-loaded before examples, guidance, and errors, which is the right ordering. The error catalogue is unusually long (nine entries) and, while each line is terse and actionable, it stretches the definition beyond what most callers need for selection; a slightly trimmed list would earn full marks.

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 write tool with no output schema, the description still states the return value ('Wrote <path>'), covers the overwrite/merge contract, path rules, Obsidian markdown pitfalls, and failure recovery. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, but the description adds semantics the schema does not carry: overwrite merges properties rather than replacing them, null values remove keys, omitting properties preserves existing values on overwrite yet drops null keys on creation, and property type consistency matters for later queries. That is real added meaning for the nested properties object, not restatement.

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

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

States the precise verb and resource ('Create a markdown note') and immediately defines the overwrite variant as replacing an existing note's body. It explicitly distinguishes itself from four named siblings (vault_patch_note, vault_replace_in_note, vault_update_properties, vault_update_memory), so an agent can route correctly without opening schemas.

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

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

Provides an explicit 'When to use' block plus three 'Prefer X' alternatives each paired with the condition that selects them (partial edits, property-only edits, dated memory entries). No inference required.

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