Vault Cortex Obsidian MCP Server

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

Annotations only declare write/non-idempotent/non-destructive; the description adds real behavioral context: the task is always created as todo with created date set to today, format is auto-detected and should only be overridden on request, concurrent writes are rejected, and rewrites must preserve the properties block. It also documents the non-obvious parsing behavior where trailing emoji/Dataview fields get read back as metadata, surfaced via advisories.

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 four targeted examples, then when-to-use, then parameter rules, then errors, then return shape. The error catalog is long (over twenty bullets), but nearly all entries tell the agent how to recover; a few edge-case messages (properties block, ENAMETOOLONG) are marginal against a 17-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?

Seventeen parameters with no output schema would normally leave gaps, but the description supplies an explicit Returns section (path, line, block_id, heading, subtasks, changes, advisories) and explains how line acts as the follow-up handle when block_id is absent. Error remediation and Obsidian parsing caveats round out the coverage.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter constraints the schema cannot express: heading is required on Kanban boards unless a parent is given, parent_block_id/parent_line are mutually exclusive with each other and with heading, block_id is refused on Kanban sub-tasks, and position is ignored without a heading or under a parent. Some content (block_id regex, position enum semantics, priority enum) restates the schema, which keeps it from a 5.

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

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

The first sentence gives a specific verb and resource ("Create a correctly-formatted task") plus the scope of what gets written. It distinguishes itself from siblings by naming vault_update_task for status changes and checklist items, so an agent can choose without opening either 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?

There is an explicit "When to use" section that states the condition (creating a new task card on a board or in a note) and names the alternative (vault_update_task's add_subtasks for lightweight checklist items). It also points to vault_list_tasks for round-trip verification and vault_list_notes for path checking.

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

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

Beyond the destructive annotation, the description discloses append-only default behavior, the living-file exception, ambiguity around identical entries, safety-guard shrink protection, and a detailed error catalog. It clearly explains failure modes and the expected return value.

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 a clear purpose sentence and examples, followed by structured usage, parameter, error, and return sections. It is somewhat long due to the error catalog, but that detail is justified for a destructive operation with tricky matching.

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 four-parameter memory-deletion tool with no output schema, the description covers purpose, prerequisites, alternatives, matching rules, error behavior, and return format. An agent should have everything needed to invoke it correctly or 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 the baseline is 3, but the description adds non-obvious matching semantics: date and entry jointly select a bullet, identical copies make the match ambiguous, and section scoping means the same entry under another heading is not found. It also clarifies file naming through error messages.

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, resource, and scope: 'Delete a single dated entry from a memory file in About Me/'. It also explicitly distinguishes this operation from vault_update_memory, vault_delete_note, and vault_delete_span in context.

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 for removing entries that were wrong when written, warns not to delete merely to reflect a change, names vault_update_memory as the alternative, and carves out an entry-policy: living exception. It also tells the agent to call vault_get_memory first and to prefer vault_delete_note for entire notes.

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 goes well beyond: the caller cannot choose or see the trash outcome in advance, retention semantics (TRASH_RETENTION_DAYS 30 by default, never when set to none), the fact that backlinks break, protected-path refusal rules, and per-error recovery guidance. This is exactly the extra 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 the one-liner, examples, and when-to-use before the long behavior and error sections, and the section headers make it scannable. The error catalogue is unusually long for a two-parameter tool, and a few entries (config-read failures) could be compressed without losing 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?

No output schema exists, and the description supplies the return message format and the difference between "Deleted" and "Moved … to trash". Combined with the destructive-annotation baseline, permission/config failure modes, and protected-path rules, an agent has everything needed to call this 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning for prune_empty_folders: a folder holding any file (even a hidden .DS_Store) survives, and pruning is best-effort so an un-removable folder never fails the call. The path parameter gets less added value beyond the extension and hidden-path errors.

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 ("Delete a markdown note") and immediately clarifies the two possible outcomes. It distinguishes itself from siblings by name, routing memory-entry removal to vault_delete_memory, relocation to vault_move_note, and replacement to vault_write_note.

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

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

Explicit "When to use" plus three named alternative tools with the condition that selects each. Also gives two worked examples, one of which exercises the optional parameter, so the agent knows exactly which call shape to pick.

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

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

Annotations already mark this as destructive and non-idempotent, and the description adds substantial behavioral context: properties are preserved, CRLF becomes LF, blank-line normalization is described in detail, anchor ambiguity is explained, and error conditions are enumerated. Nothing contradicts the annotations.

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

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

The description is long but well-organized into examples, usage guidance, parameter notes, behavior, errors, and returns. The length is largely justified for a destructive editor with subtle whitespace and anchor semantics, though the error catalogue is somewhat expansive.

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 mutation tool with no output schema, the description covers the operation, alternatives, edge cases, behavioral side effects, error handling, and return format. An agent has enough information to invoke it correctly 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 parameter basics are already documented. The description still adds real meaning beyond the schema by explaining that end_anchor is searched at or after the start line, must be unique among those lines, that co-located anchors delete only one line, and how first_match resolves ambiguity.

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: deleting a contiguous block of whole lines from a note's body using anchor substrings. It clearly distinguishes the operation from vault_replace_in_note and vault_replace_span, and the examples make the intended granularity 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?

Explicitly says when to use it — removing a block already read where reproducing old_text would be error-prone — and names alternatives: vault_replace_in_note for small in-place edits and vault_replace_span for atomic replacement. It also includes the specific code-fence edge case where this tool should not be used.

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 a safe read-only, idempotent operation, and the description adds substantial behavioral context: exclusion defaults, how excluded folders affect results versus links, limit truncation ambiguity, empty-result meaning, and specific error conditions. There is no contradiction with the annotations.

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

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

The description is front-loaded with purpose, then examples, usage guidance, parameter caveats, errors, and return shape. Despite its length, every section carries non-obvious operational value and there is no filler.

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

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

For a two-parameter read tool with no output schema, the description fully explains return structure, optional fields, sorting, error behavior, and edge cases. An agent has everything needed to call it correctly and interpret the 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%, but the description adds meaning beyond the schema: exclude_folders replaces rather than extends defaults, [] means no exclusions, folder exclusion includes subfolders and is case-insensitive, and excluded notes still contribute incoming links. It also explains 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 gives a specific verb and resource ('Find notes with no incoming links') and defines orphan status precisely, including the self-link edge case. It clearly distinguishes this scan from the sibling vault_get_backlinks, which checks connectivity for one 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?

It explicitly states the use case (vault maintenance, surfacing notes to integrate into the graph), names the follow-up action with vault_patch_note, and tells the agent when to prefer vault_get_backlinks instead. The routing is unambiguous.

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

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

Annotations already mark this as read-only, idempotent, non-destructive, and closed-world, but the description adds substantial behavioral context: which link syntaxes are captured, that code-block links are ignored, that self-links appear, that heading anchors and aliases resolve to the base note, and that recently written links may not appear immediately. It also describes return shape 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 front-loaded with the core behavior, then usage guidance, return shape, and errors. Despite its length, every section earns its place by resolving a real operational question an agent would have when invoking the 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?

Although there is no output schema, the description fully specifies the return JSON shape, count behavior, empty-result semantics, freshness limitation, and relevant error cases. For a one-parameter read-only graph lookup, this is complete enough for correct invocation.

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

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

Schema description coverage is 100%, so the path parameter is already well documented with type, required status, extension requirement, examples, and case sensitivity. The description reinforces the required extension through its error section and examples, but it does not add much parameter meaning beyond the schema baseline.

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

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

The description states a specific verb and resource: find all notes and canvases linking to a given note or canvas. It distinguishes the tool from siblings by naming vault_get_outgoing_links and vault_find_orphans, and it clarifies exactly which link forms count.

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: assessing connectivity before editing/deleting, understanding references, or finding related notes via the graph. It also names the alternative for outgoing links and the alternative for finding orphan notes, so the agent can route correctly.

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

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

Annotations already cover the read-only/idempotent profile, but the description goes far beyond them: it explains the full config resolution order, documents each distinct error string and its remediation, and clarifies that a missing note returns exists=false rather than failing.

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 when-to-use, parameters, errors, and returns in clear labeled blocks. The error catalogue is long but each entry maps to a distinct failure mode with an action, so it earns its space; slightly verbose overall.

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

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

No output schema exists, yet the description fully specifies the return shape (path, content, exists) and even prescribes the follow-up action when the note is absent. Combined with the error coverage, 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 documents the YYYY-MM-DD format and today-default, so baseline is 3. The description adds genuine value by declaring that both past and future dates are valid, removing ambiguity the schema does not address.

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 daily note by date) and immediately explains the resolution chain for folder and filename format via env vars, .obsidian config, then defaults. This is clearly distinguishable from vault_read_note and vault_recent_notes.

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

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

Explicit 'When to use' section names the exact alternative for each adjacent need: vault_patch_note for appending to a section, vault_recent_notes for general recent activity, and notes that recent_notes is not date-filtered. 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 declare readOnly/idempotent/non-destructive, so the description rightly spends its space on what annotations can't say: that the no-arg call 'can be large', that a missing setup returns an empty string, that ordering follows document order with newest-first convention, and a full enumerated error catalog with remediation for each. That is unusually rich behavioral disclosure for a read 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 with the core purpose, then modes, examples, usage, errors, and returns in a scannable order. It runs long and the trailing 'Returns:' paragraph partially repeats the return-format information already stated in the mode descriptions (frontmatter stripping, JSON shape), which is the main waste.

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

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

There is no output schema, so the description must carry the return contract — and it does, distinguishing raw markdown from the structured { entries, total, on_or_after } shape with per-entry fields and the empty-match case. Combined with the error catalog and discovery prerequisite, 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 100%, so individual parameter meanings are already documented; the description's added value is the cross-parameter contract — that section and on_or_after both require file, that omitting section reads all sections while keeping section attribution, and that on_or_after switches the return format to JSON. Worked examples reinforce the combinations. It stops short of a true 5 only because the per-parameter detail largely restates 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 opening sentence names the specific verb and resource (read semantic memory from About Me/ files) and immediately characterizes the data format (dated bullet entries under H2 headings). It then enumerates the three calling modes (no args, file, file+section, file+on_or_after) so an agent knows exactly what each shape yields, and it is clearly distinct from siblings like vault_read_note and vault_memory_recall.

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

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

An explicit 'When to use' block names the target content (preferences, principles, opinions, persistent context), prescribes a prerequisite call (vault_list_memory_files to discover valid file and section names), and gives a sibling exclusion ('Prefer vault_read_note for reading non-memory notes'). It also states when to reach for on_or_after versus a plain read.

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 read-only/idempotent/non-destructive profile, and the description layers on genuinely non-obvious behavior: links in code blocks ignored, self-links included, per-target deduplication, and the critical caveat that missing/dot-folder/just-created paths return an empty result rather than an error. It also flags index failures as SqliteError rather than call failure. Slightly below 5 only because the very specific broken-path normalization rules are dense enough to be borderline noise for most calls.

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 purpose and examples, then usage, then returns, then errors — a sensible ordering with no filler sentences. It is long, but with no output schema the return-shape detail is doing necessary work rather than padding.

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 documents the response (path, outgoing_links fields, count), the meaning of every field including the subtle daily_note_forward_ref and bytes-vs-delivery-cost caveat, and all three error/empty-result behaviors. An agent could call and interpret this correctly without any other 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, but the description adds real value: the error text for a missing extension tells the agent how to recover when the path lacks .md/.canvas, and two worked examples show the expected path shape for a note versus a canvas file.

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 files a given note or canvas links to') and enumerates exactly which link syntaxes count, including the canvas-file distinction. It is clearly separable from vault_get_backlinks by direction, and the two examples make the target object 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?

Explicit 'When to use' line lists three concrete scenarios (graph traversal, broken-link auditing, dependency checks before editing) and names the alternative: 'For incoming links ... use vault_get_backlinks.' Both the positive and negative selection conditions are given.

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

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

Annotations declare a non-destructive but non-idempotent write; the description goes well beyond that with CRLF→LF normalization, verbatim content preservation, trailing-newline semantics, path-safety blocking, concurrent-write behavior, and a full error catalog with remedies. Minor gap: it never says whether the write is atomic or what happens on partial failure, but the operational detail is unusually rich for a write tool.

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

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

Front-loaded with purpose, then examples, then when-to-use, parameters, errors, and returns — a sensible ordering. The error list is long, but each entry maps an error string to a remediation action, so it is dense rather than padded; a slightly tighter grouping of the path-safety errors would push this to a 5.

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 supplies the return format verbatim ('Inserted <N> line(s) <before|after> anchor in <path>') plus the line-count convention. Combined with examples, error-to-remedy mapping, and content-formatting rules, 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 100%, so baseline is 3, but the description earns a bump by explaining content semantics (blank lines preserved, trailing newline adds a blank line), the anchor/first_match interplay in the ambiguity error, and two worked examples that show realistic argument combinations. The control-character and Obsidian-syntax notes add meaning 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?

First sentence states a specific verb (insert), resource (note body), mechanism (whole lines relative to an anchor substring), and scope constraint (properties untouched). It is immediately distinguishable from vault_patch_note and vault_replace_span, both of which are named later.

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 scenarios (table rows, list items, landmark lines), and two named alternatives are routed away from: vault_patch_note for heading-targeted inserts and vault_replace_span for block replacement. When-not guidance is stated directly, not implied.

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

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

Annotations already declare readOnly/idempotent/non-destructive and closed-world, so safety is covered. The description adds genuinely useful behavior: exact-case folder matching, hidden dot-file exclusion, empty-listing-instead-of-error, and truncation via limit. That is meaningfully beyond the annotations, though the long 'Reading listed files' tail drifts into vault_read_file's behavior rather than this tool's.

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 is front-loaded and the sections (examples, when-to-use, behavior, errors, returns) are scannable. The final paragraph on how to read the listed files is useful but the longest and least about this tool, slightly inflating 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?

With no output schema, the description fully documents the return shape (files with path/extension/bytes, extension_counts, total, truncated), plus error cases and edge behaviors. An agent has everything needed to call it 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?

Schema coverage is 100%, so the baseline is 3, but the description adds working examples for each parameter combination and clarifies that omitting folder lists the whole vault and that extensions are matched case-insensitively by the tool. The case-sensitivity caveat on folder is a real semantic addition not present 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 and resource ('List non-markdown files in the vault or a folder — images, canvases, PDFs, data files') plus what is returned (byte sizes, per-extension counts). It explicitly separates itself from vault_list_notes and vault_search, so an agent can distinguish it 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?

Provides an explicit 'When to use' section naming the downstream action (read with vault_read_file) and the alternatives that cover markdown notes (vault_list_notes, vault_search_by_folder, vault_search) and linked files (vault_get_outgoing_links). The routing logic is unambiguous.

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

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

Annotations already declare read-only, idempotent, closed-world, so the description correctly spends its budget on behavior beyond that: sort order, subfolder/hidden-file exclusion, empty-folder behavior, and two concrete error strings with retry/escalation advice. It also discloses a non-obvious truth — that entry_policy is a convention the server does not enforce — which no structured field conveys.

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?

Strongly front-loaded: purpose, then example, then when-to-use, behavior, errors, returns — an agent can stop after two lines. Slight redundancy between the worked example and the 'Returns' block, which restates the same field list, costs it a point.

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

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

With no output schema, the description must carry the return shape, and it does so field by field ({ file, title, bytes, entry_policy, leading_callout, headings }) including the null convention and entry_count placement on H2s. Combined with the error appendix, nothing an agent needs to call or interpret 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?

Zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description instead devotes that space to the return shape, including that the `file` value is what other memory tools accept without the .md suffix — useful, but that is return-value information rather than parameter guidance.

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 ('lists About Me/ memory files') and immediately delimits scope with 'Does NOT return actual entries', which is exactly the distinction an agent needs versus vault_get_memory. It also names sibling tools it precedes, so it is distinguishable 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?

A dedicated 'When to use' section gives explicit ordering ('BEFORE calling vault_get_memory, vault_update_memory, or vault_delete_memory') and a mandatory call path ('Always call this first to get valid file and section names'). It also names the pruning case where entry_policy must be checked, covering the when-not implicitly.

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), yet the description adds sort order, hidden-file exclusion, symlink inclusion, empty-array-not-error semantics, and the exact error strings an agent may encounter plus recovery guidance. None of that is derivable from the annotations.

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

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

Front-loaded with the core contract, then examples, routing guidance, parameter notes, behavior, errors, and returns in a scannable hierarchy. Length is driven by genuinely non-obvious semantics (case sensitivity, glob scoping, error strings), and the mild restatement of the return type is harmless.

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 'Returns' line specifies the exact shape (JSON array of vault-relative path strings), and error conditions and their remediation are all covered. Nothing an agent needs 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?

Schema coverage is 100%, so the baseline is 3, but the description substantially enriches it: folder recurses into subfolders unless a glob is given, exact letter case matters on case-sensitive filesystems, and glob is matched against the path inside folder with '*' vs '**' depth semantics spelled out.

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 (list), resource (.md file paths in the vault), and explicit scope limits ('Returns paths only — not content or metadata'), which immediately separates it from content/metadata searching 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?

A dedicated 'When to use' line names the positive case (browsing by filename, matching path patterns) and explicitly routes to three alternatives: vault_search_by_folder for metadata, vault_search for content, vault_read_note for reading. That is when/when-not/alternatives in full.

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), but the description goes well beyond with frontmatter-only scope (inline Dataview fields excluded), precise count semantics (null-valued notes included), sample_values computation rules (3 most frequent, array elements counted separately, booleans rendered "1"/"0", nulls skipped), and sort order. Error behavior is disclosed too: empty vault/folder returns [] rather than throwing, and SqliteError is attributed to the index rather than the call.

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 purpose, then cleanly sectioned into examples, when-to-use, parameters, behavior, errors, and returns. Two worked examples are arguably one more than strictly needed, but each sentence carries concrete 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?

With one optional parameter and no output schema, the description supplies the return shape inline (JSON array of {key, count, sample_values}), the sort order, and the empty-result case. Nothing an agent needs to call it correctly or 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 baseline would be 3, but the description adds real boundary semantics the schema lacks: folder includes subfolders, matching is ASCII-case-insensitive, and "Projects" covers "Projects/Archive" but not "ProjectsOld/". Omitting the parameter to scan the whole vault is also spelled out.

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") and immediately adds scope details (note counts and sample values) that separate it from a mere key enumeration. It also names the two nearest siblings (vault_list_property_values, vault_search_by_property) and states what each is for, so an agent can distinguish them 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?

An explicit "When to use" section frames it as the discovery step before property search and as a companion to vault_list_tags. Two explicit "Prefer X when…" statements give the exact condition that switches the agent to a sibling tool.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior, but the description adds substantial context: scalar vs array counting, grouping of same displayed strings, checkbox encoding, null skipping, truncation signals, and error behavior. No contradictions.

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

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

Front-loads purpose and examples, then uses labeled sections for when-to-use, parameters, behavior, errors, and returns. The length is justified by the nuanced counting and truncation semantics and the absence of an output schema; no filler sentences.

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 the return shape and sort order, edge cases, error behavior, and parameter interactions. With no output schema, the description still gives an agent everything needed to call and interpret 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?

Even with 100% schema coverage, the description adds meaning beyond the brief schema descriptions for all three parameters. It explains key case-sensitivity and exact-match requirements, folder inclusion of subfolders with ASCII case-insensitive matching, and limit application after count sorting with no truncation indicator.

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: list distinct values for a property key with occurrence counts. It clearly distinguishes this from vault_list_property_keys (which lists keys) and vault_search_by_property (which searches notes by property).

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

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

Explicitly states when to use it: enumerate values before calling vault_search_by_property, and call vault_list_property_keys first to discover valid key names. It also explains how vault_search_by_property interprets values, reinforcing the alternative.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial semantics the agent could not infer: count means unique notes not occurrences, case-variant spellings are merged, hierarchical tags are not split, inline #tags are excluded, and the '#' prefix is stripped. It also discloses failure modes (empty array is not an error; SqliteError means the index failed) rather than the call.

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 behavior and ordering, then an example, then when-to-use, then errors and returns. Section labels make it scannable, and each sentence supplies a distinct fact (case folding, hierarchy, unique-note counting) rather than restating the previous one.

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

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

No output schema exists, yet the description fully specifies the return payload via example plus a Returns line, and it covers the error surface. For a zero-parameter discovery tool this leaves nothing an agent needs unanswered.

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

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

There are zero parameters, so the schema carries nothing to explain and the baseline is 4. The description nonetheless documents the output item shape ({ tag, count }, tag without '#'), which is genuinely useful since no output schema exists.

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) plus the ordering rule, and the closing 'When to use' section explicitly distinguishes it from vault_search_by_tag. An agent can separate this discovery tool from tag-query tools without reading 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?

Gives an explicit usage condition ('Discovering what tags exist before searching by tag. Good first step for vault orientation') and names the sibling to switch to with the exact condition that triggers the switch ('Prefer vault_search_by_tag once you know which tag'). Both when-to-use and when-to-use-something-else are stated.

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

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

Beyond the read-only/idempotent annotations, the description discloses indexing exclusions (fenced code blocks, comment blocks, NON_TASK statuses), freshness latency after writes, detailed error conditions, and return behavior. These are meaningful operational traits that annotations alone do not cover.

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 definition is front-loaded with purpose, examples, usage guidance, and alternatives, which suits a 16-parameter tool. It is long but mostly structured and purposeful, though the examples and Returns section could be trimmed slightly without losing essential guidance.

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, 16 parameters, and lack of an output schema, the description is complete: it explains scope, indexing behavior, filtering semantics, alternatives, errors, and the full return shape including subtask_progress. An agent has enough information to call it correctly and interpret 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 schema already documents each parameter and enum. The description still adds useful semantics beyond the schema, such as date filters only matching tasks that actually have that date, folder subfolder/case behavior, status array expansion, and how top_level_only interacts with checklist items.

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

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

The description opens with a specific verb and resource: list checkbox tasks across the vault with structured filters, and frames it as the Tasks-plugin data model over MCP. It clearly distinguishes this from sibling tools by naming vault_read_note and vault_search as alternatives for different needs.

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, multiple concrete examples for common queries, and clear alternatives: prefer vault_read_note for verbatim Markdown or post-write state, and vault_search for full-text content searches. This leaves little ambiguity about when to choose this tool.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantive behavior beyond them: recall-over-precision bias with marginal entries expected, the relaxed any-term fallback for meta-framed queries, truncation semantics tied to limit, and pre-limit file filtering. Error behavior ('empty results, not an error'), unknown-file failure mode, and index-error disambiguation are all disclosed.

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 scope, then structured into examples, usage, errors, and returns — every block is scannable. The Returns section is dense and somewhat lengthy, but with no output schema it is carrying necessary weight, so the length is largely earned.

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?

Three parameters with 100% schema coverage, no output schema — and the description compensates by documenting the return shape (entries/total/truncated/search_mode/reranked) field by field, including how file and section feed into vault_get_memory. Nothing an agent needs to call or interpret results correctly 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%, so the baseline would be 3, but the description adds real meaning: content-word query phrasing ('testing philosophy') ranks best versus meta-framed queries, and crucially that the file filter is applied before limit so limit keeps the most relevant matches from that file. That interaction is not derivable from 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 ('Recall memory entries about a topic') with the retrieval mechanism ('entry-granular hybrid keyword + semantic') and scope ('across ALL About Me/ files and ALL time'). An agent can distinguish this from vault_search and vault_get_memory 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?

The 'When to use' block names the exact question shapes this serves ('what does my memory say about X?') and explicitly routes to alternatives: vault_get_memory for known files/sections, vault_search for notes outside the memory layer. It also states the file-parameter default ('omit for cross-file recall — the default and usual 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?

The annotations already declare destructiveHint=true and idempotentHint=false, but the description adds substantial context beyond them: it explains exactly which link forms are rewritten, how relative links are fixed, when links are intentionally left alone, and what never-overwrite behavior means. It also documents partial-failure states and recovery steps, so an agent understands the operational risk and expected behavior.

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

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

The description is front-loaded and clearly sectioned into purpose, examples, when-to-use, parameters, errors, syntax, and returns, so an agent can scan it efficiently. It is longer than typical, with an exhaustive error enumeration, but most of that content is actionable and earns its place.

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

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

For a complex mutation that rewrites links and can partially fail, the description covers prerequisites, protected paths, parameter behavior, error recovery, and return values. Since no output schema exists, the explicit Returns section is especially important and is fully populated.

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

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

Schema description coverage is 100%, so the schema already documents old_path, new_path, and prune_empty_folders thoroughly; a baseline of 3 would be defensible. The description adds useful meaning beyond the schema, especially for prune_empty_folders — explaining hidden-file retention, in-place rename behavior, and best-effort pruning — and supplies concrete path examples.

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 — moving or renaming a note — and immediately states the distinctive behavior: rewriting every link across the vault. It distinguishes itself from siblings by naming vault_write_note + vault_delete_note, vault_patch_note, and vault_update_properties as alternatives for different tasks.

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, states which alternatives to prefer and why, and names the protected paths that cannot be moved. It also clarifies when to use other tools for body or property edits, leaving little ambiguity about tool selection.

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

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

Annotations already mark this as destructive and non-idempotent, and the description adds substantial context: section-boundary semantics, newline handling, the include_children guard, a no-heading prepend limitation, control-character errors, and concurrent-write retry guidance. It also explains return values and does not contradict the annotations.

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

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

The description is front-loaded with purpose and usage, then organized into operations, limitations, errors, syntax notes, and returns. It is long, but most of the length is justified by a destructive six-parameter tool with many named failure modes; the extensive error catalog is useful rather than pure padding.

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 explains the confirmation return format and special no-heading prepend return sentence. Combined with annotations and full schema coverage, it gives enough operational detail to call the tool correctly across normal and edge cases.

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

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

Although schema coverage is 100%, the description adds operation-specific meaning well beyond the schema: append behavior around blank lines and tables, prepend callout behavior, replace requiring a heading, insert_before placement, heading_level disambiguation, and include_children confirmation. This is strong compensation even where the schema already documents fields.

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 names the specific resource (markdown note) and verb set (append, prepend, replace, insert by heading), and immediately distinguishes surgical edits from whole-note writes. An agent can identify the tool 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 gives an explicit 'When to use' rule and then routes the agent away from this tool toward vault_write_note, vault_replace_in_note, vault_insert_at_anchor, vault_replace_span, vault_delete_span, vault_update_properties, and task tools under clear conditions. Alternative selection is fully specified.

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 read-only/idempotent/non-destructive, and the description still adds substantial behavior beyond them: server-side downscaling thresholds (49152 bytes, 1568px), first-frame GIF reduction, the 5-page ceiling on raw PDF rendering, the 100 KiB per-window text cap, byte-exact vs. paged line endings, and the 50 MiB file cap. It is also honest about limits paging cannot overcome (one very long line overflowing the window).

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 worked examples are front-loaded and every section maps to a real agent decision, but the exhaustive error catalog (roughly eighteen distinct messages) dominates the back half, and the decisive 'When to use' block sits after the long type/behavior tables. The content earns its place, but it could be tightened and reordered so the routing guidance appears earlier.

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 four-parameter read tool with no output schema, the description covers return shapes per file type (image block plus metadata text, alternating page/image pairs, single text block), size and line caps, paging recovery, and per-error remediation. Nothing an agent needs to invoke this correctly or recover from failure is missing.

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

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

Although schema coverage is 100%, the description goes materially beyond the schema: it explains what raw:true actually changes for canvas (exact JSON vs. outline) and PDF (rendered pages vs. extracted text) and that it is a no-op for text formats, and it defines the paging contract for start_line/limit including the emitted window-metadata line and the continue-with hint.

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 names a specific verb (read) and resource (non-markdown vault file) and explicitly positions itself as the read-side companion to vault_read_note, so the boundary against the closest sibling is unmistakable. The per-type table then enumerates exactly which extensions are in scope.

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

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

A dedicated 'When to use' section states the trigger (a note references a file you need to see or read) and names the alternatives with their selection conditions: vault_get_outgoing_links to discover linked files, vault_list_files to browse folders, vault_read_note for .md, and the caveat that vault_search does not index images. It also gives a concrete pre-check recipe (start_line: 1 with limit: 1) for large 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, and the description does not contradict them. Beyond annotations, it discloses token-budget motivation for modes, mutual exclusivity of properties_only/outline/heading, section boundary semantics, paging metadata behavior, line-ending differences, and how YAML property errors affect available modes. These are meaningful behavioral details an agent needs.

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

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

The description is front-loaded with purpose and mode overview, then examples, then usage and errors, so it is structurally sound. It is long, and the five examples plus full error catalog are close to excessive, but nearly all content earns its place for a seven-parameter tool with multiple modes.

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 carries the burden of explaining return values, and it does so thoroughly: raw markdown, JSON properties, outline object, heading section markdown, paging metadata, and line-ending behavior. It also documents error conditions sufficiently for an agent to recover or choose another tool.

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

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

Schema coverage is 100%, so the baseline is already high, but the description adds substantial semantics: it states that properties_only, outline, and heading are mutually exclusive, that heading_level only disambiguates heading matches, and that start_line/limit only apply to text renditions. The examples concretely map parameters to expected call shapes.

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

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

The first sentence states a specific verb and resource: read a markdown note by vault-relative path. It immediately distinguishes the default full-content behavior from optional modes for properties, outline, and single sections, so an agent can tell exactly what the tool does.

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

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

The description gives explicit when-to-use guidance, including large-note workflow (outline then heading), paging oversized sections, and checking line counts. It names concrete alternatives for adjacent needs: vault_search for unknown paths, vault_list_tasks for board status, vault_get_memory for About Me files, vault_patch_note for editing, and backlink/outgoing-link tools.

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

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

Annotations already cover safety (readOnly/idempotent/non-destructive), but the description adds real behavior: 'modified' uses filesystem mtime so sync touches register as recent, 'created' relies on frontmatter and undated notes sort last (so a small limit can silently exclude them), plus explicit error semantics (empty vault returns [], index errors are not call failures). This is context an agent cannot get from annotations or 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?

Front-loaded with the scope statement, then examples, when-to-use, parameter notes, errors, and returns — each block earns its place. Even the long-looking Returns enumeration is justified because there is no output schema.

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

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

With no output schema, the description documents the returned fields (path, title, tags, folder, created, modified, bytes, leading_callout, additional_properties) and their conditional-presence/null rules, and covers error cases. 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% (baseline 3), yet the description still adds meaning beyond the enum descriptions: it explains the interaction between sort_by and limit and the failure mode where undated notes fall outside a small limit under 'created'. That is genuine decision-relevant semantics, 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 a specific verb+resource ('List recently modified or created notes') and immediately scopes it ('a time-ordered window into the vault, not a date-range filter'), which pre-empts confusion with the date-filtering siblings. An agent can distinguish it from vault_search and vault_list_notes 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 plus two named alternatives with the exact condition that selects each ('Prefer vault_search for content-based discovery, including a text query limited to a date range... Prefer vault_search_by_folder for browsing a specific folder'). No inference required.

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 destructive=true / idempotent=false, and the description goes well beyond them: CRLF normalized to LF, property block preserved as written, detailed blank-line compaction semantics for deletions, atomicity reasoning for cross-section moves, and an enumerated error taxonomy including concurrent-write and control-character cases. No contradiction with annotations.

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

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

Front-loaded with purpose, worked examples, and usage routing before reference material — good ordering with no filler sentences. The blank-line deletion rule is a single ~90-word run-on sentence that could be broken into bullets for parseability, which is the only structural weakness.

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 supplies the exact return string ('Replaced <N> occurrence(s) in <path>'), the full error catalogue with remediation hints, and Obsidian syntax pitfalls (#word, [[, %%). Nothing an agent needs in order to invoke or recover 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% (baseline 3), but the description adds real meaning for every parameter: uniqueness strategy for old_text (include surrounding context), exact-match deletion semantics for new_text including line-ending effects, and intent guidance ('deliberate bulk renames') for replace_all_occurrences.

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 and replace exact text in a markdown note's body.' Immediately bounds the scope by stating properties are untouched and pointing to vault_update_properties / vault_write_note for that concern, which separates it cleanly from the other write-family 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?

Explicit 'When to use' list (typos, value updates, term renames, short-line deletion) followed by named alternatives with the condition that selects each: vault_delete_span for large blocks, vault_replace_span for anchor-based block replacement, vault_patch_note for relocating content. It even explains why add-before-delete is safer (failure duplicates rather than loses content).

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 well past them: properties are preserved, CRLF is normalized to LF, ambiguity is an error unless first_match is set, and the code-block-fence case is explicitly a no-go. The error catalog (concurrent write, control characters, properties-block edge case) is genuinely additive. It stops short of 5 only because the escapes to vault_replace_in_note for the fence case are described but not summarized as a general failure-mode list.

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 a one-sentence definition, then examples, then routing, then edge cases — a sound order. The content-line-break paragraph is dense and repetitive ("keeps the gaps as they were", "widen a gap but never narrow it", "joins both sides into one gap") and could be tightened without losing meaning.

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 mutation with no output schema, the description covers the safety profile, anchor resolution rules, content-merging semantics, Obsidian syntax gotchas, the exact return string with N/M line counts, and a remediation for every documented error. An agent could call this correctly and recover from failure without opening any other tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema cannot: end_anchor is searched at or after the start line and must be unique among those lines, and if both anchors land on the same line only that line is replaced. The long passage on how content's leading/trailing line breaks merge with surrounding empty lines (and how a trailing newline splits a table) is exactly the non-obvious behavior an agent would otherwise get wrong.

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 precise verb+resource+mechanism: replace a contiguous block of whole lines, addressed by short anchor substrings rather than the block's literal text. The two worked examples make the granularity (one table row, one callout block) unmistakable and separate it from vault_replace_in_note at a glance.

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' clause (blocks already read, where reproducing old_text exactly is error-prone) plus two named alternatives with the condition that selects each: vault_replace_in_note for small in-place edits, vault_delete_span for removal without replacement. 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial behavior beyond them: query-syntax mangling (AND/OR/NOT dropped, never throws), no-match returns empty not error, search_mode/reranked semantics, and offset-aware day bounds. This is the kind of context 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?

Long but front-loaded and sectioned (purpose, filters, examples, when-to-use, errors, returns). Given the complexity of nested filters and hybrid search semantics, every block carries information an agent needs; there is no filler prose.

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

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

No output schema exists, yet the description fully enumerates the return shape (results fields, total, search_mode, reranked, kind/extension, omitted created). It also documents error cases and edge behaviors, so an agent has everything needed to call and interpret 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% (baseline 3), but the description adds real meaning: filters AND-combine, folder includes subfolders but not prefix-siblings, tags are case-insensitive, properties compare by exact type with true/false coercing to 1/0 and list-any-element matching, and created/modified bounds are whole-day in server timezone. This meaningfully exceeds the schema 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 ('Hybrid search across vault notes and file content') and immediately distinguishes the mechanism (keyword + semantic relevance). The 'When to use' section explicitly names the four sibling search tools it is not, 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?

Explicit 'When to use' guidance plus a full routing table: prefer vault_search_by_tag for tag-only, vault_search_by_folder for browsing, vault_search_by_property for metadata-only, vault_recent_notes for time browsing. It leaves nothing to inference about which search entry point to pick.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is established structurally. The description nonetheless adds genuinely non-obvious behavior: index lag of a few seconds, hidden dot-folders never appearing, no truncation signal in the response, and empty-folder vs index-error differentiation. The only notable omission is pagination — there is a limit but no offset, which is left implicit rather than stated. Against an already-annotated read tool, this is solid added context rather than exceptional.

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-line purpose, then call examples, then when-to-use, parameters, behavior, errors and returns in labeled blocks. Dense but every sentence carries an operational fact; no filler or restatement of the name.

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 three-parameter read tool with no output schema, the description closes all the gaps an agent needs: sorted return shape and field list, eventual-consistency caveat, hidden-folder exclusion, empty-result vs error disambiguation, and the truncation ambiguity. Nothing material is left to inference.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema cannot express: folder matching is whole-folder not text-prefix ("Projects" excludes "ProjectsOld/"), case-insensitive with trailing slash ignored, and limit is applied after sorting so it caps the newest N rather than paginating. Those are exactly the semantics that cause incorrect calls if misread.

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 ("Browse notes in a folder with full metadata") and immediately distinguishes itself from siblings that list paths only or search by text. An agent can tell from the first line that this is a folder-scoped read returning rich metadata, not a query-based 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 names the alternatives and the conditions that select them: vault_list_notes for paths only, vault_search for text queries, backlink/outgoing-link tools for connectivity. It also names the positive case (folder exploration for vault orientation), so 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 cover the read-only/idempotent/non-destructive profile, and the description adds genuinely non-obvious behavior: silent truncation ("nothing in the response signals truncation"), empty array instead of error for bad keys, index-failure error shapes, and mtime-based sort quirks with recently-synced notes. That is real disclosure beyond the structured fields.

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, examples, then when-to-use, parameters, errors, returns — a clean scan order. It is dense and a few edge cases ("1e-999" matches 0, integers past 2^53 comparing equal) are more niche than an agent needs, but nothing is misordered or truly wasted.

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 contract itself: field list, sort order, and the conditional appearance of leading_callout and additional_properties. Combined with the error section, an agent has everything needed to call and interpret 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 already 100%, but the description goes well beyond it: exact case-sensitive key/value matching, numeric coercion rules ("04" and "4.0" match number 4 but not text "4"), checkbox as "1"/"0" only, full-element array matching, folder subfolder inclusion and case-insensitivity, and that limit keeps most recently modified 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?

States a specific verb and resource ("Find notes where a frontmatter property matches a value") and immediately distinguishes itself from vault_search and vault_search_by_tag. The two inline examples make the call shape concrete at a glance.

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 ("finding notes by metadata when you don't have a text query") plus named alternatives with the conditions that select them: vault_search when a text query exists, vault_search_by_tag for tag prefixes. It also routes discovery through vault_list_property_keys/values, so an agent never has to guess a key.

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 hierarchy matching semantics, case insensitivity, omission of inline tags, truncation ambiguity via limit, index lag after file changes, and error behavior. These are meaningful behavioral traits that annotations alone do not 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 front-loaded with purpose and matching rules, then uses clear sections for usage, parameters, behavior, errors, and returns. It is fairly long, but most content is valuable for correct invocation; the return-field enumeration is thorough rather than wasteful.

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 describes the return structure, sorting, timestamps, and optional note fields. It also covers error cases, index lag, truncation caveats, and tag matching edge cases, so an agent has enough context to call and interpret 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%, so the baseline is 3, but the description adds real semantics beyond the schema: exact controls subtree matching, limit applies after sorting and has no truncation indicator, and malformed tag values have specific error behavior. The added detail is useful, though some overlaps with schema descriptions prevent a top score.

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

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

The description states a specific verb and resource: find notes by frontmatter tag, ignoring case, and explicitly excludes inline #tags. It distinguishes tag-only lookup from text search and tag discovery, making the tool's role clear relative to 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?

It explicitly says when to use tag-only lookups, when to use vault_list_tags first, and when to prefer vault_search for text relevance. It also explains nested-tag matching and the exact flag, leaving little ambiguity about tool choice or mode.

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 far beyond the annotations: explains idempotency semantics (duplicate = no-op, safe retry), the append-only default with newest-wins behavior, the living-file exception surfaced by vault_list_memory_files, auto-creation of missing files/sections, and the placeholder scope callout. It also enumerates concrete error cases and the exact return strings, which the annotations do not cover.

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 is front-loaded, then examples, usage, parameters, syntax, errors, and returns in a scannable order; two worked examples clarify default vs. override behavior efficiently. The error catalog is long, but each entry maps to a distinct actionable failure mode, so little is wasted.

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 mutating, nested-parameter tool with no output schema, the description covers side effects (file/section creation, placeholder callout), duplicate handling, return strings, and the full failure surface. An agent has everything needed to call it correctly and recover from errors.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real disambiguation: 'options.date only sets the bullet's date; placement follows options.position, never the date' resolves a non-obvious ambiguity, and the Obsidian Markdown escaping note (tags, wikilinks) tells the agent how to shape the entry value. Not a 5 because file/section naming rules largely restate schema descriptions and the error section rather than describing parameters directly.

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 precise verb + resource: 'Append a dated entry to a section of a memory file in About Me/'. This is clearly distinguishable from siblings like vault_write_note, vault_get_memory, vault_delete_memory, and vault_replace_in_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?

Has an explicit 'When to use' section (recording a preference, principle, opinion, or fact), a stated prerequisite ('Call vault_list_memory_files first and reuse existing file and section names'), and a named alternative with its condition ('Prefer vault_write_note for creating non-memory notes'). It also documents the append-vs-prune policy and the `entry-policy: living` exception.

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 annotations (destructiveHint=true, idempotentHint=true) by spelling out merge vs replace semantics, that null deletes in merge but writes an empty property in replace, that {} removes a property under replace, that the body is preserved, and that a merge refuses invalid YAML/lists/tags. It also catalogues concurrency and path-guard errors with recovery steps.

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-segmented with labeled Example / When to use / Errors / Returns blocks, and the core semantics are front-loaded. The eight-bullet error catalogue is a little heavy for a definition, but each entry carries actionable recovery guidance 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?

For a destructive mutation with a nested object parameter and no output schema, the description supplies examples, error conditions, return strings, merge/replace edge cases, Obsidian syntax cautions, and sibling routing. An agent could invoke it correctly on the first try.

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 baseline is 3, but the description adds real meaning the schema lacks: how null and {} are interpreted inside `properties`, that arrays are replaced rather than appended, and how `replace: true` changes the interpretation of both parameters. It stops short of documenting the `propertyNames`/nesting constraints, so not a full 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+resource: "Update a note's frontmatter properties." It immediately scopes the operation to frontmatter (not the body) and later names the sibling it is not, vault_write_note, so an agent can distinguish it 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?

A dedicated "When to use" section states the scenario (changing tags/status/type without rewriting the body), names alternatives and when to prefer them (vault_write_note for creating or replacing the body), and prescribes a read-first workflow with vault_read_note({ properties_only: true }). Exclusions and prerequisites are explicit.

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

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

Annotations already flag destructive=true, idempotentHint=false and openWorld=false, but the description goes far beyond: it discloses Kanban auto-move semantics, that completing by line is not idempotent for recurring tasks (spawn occupies the old line), nested-line behavior, concurrency errors, and the delete-on-completion path. This is exactly the mutation risk context an agent needs.

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

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

Well front-loaded — purpose sentence, then examples, then usage, parameters, errors, syntax, returns. The very long error catalog and seven examples push it past what's needed for tool selection, though each item is actionable once invoked. Not wasteful, but heavier than the selection decision requires.

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 compensates fully: it documents the return object field-by-field (path, line, block_id, subtasks, next_occurrence, changes, advisories, on_completion_applied), the side effects, and the failure modes. 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%, yet the description still adds cross-parameter rules the schema cannot express: exactly one of block_id/line, 'at least one change' required, explicit null to clear vs. omission to leave untouched, on_completion overriding a stored delete, and position's interaction with heading/done-lane moves. This is genuine value beyond the structured fields.

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 plus an enumerated set of updatable fields, and explicitly contrasts itself with vault_create_task for the create case. An agent can distinguish it from every sibling (vault_create_task, vault_list_tasks, vault_replace_span) 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?

States 'When to use: Any change to an existing task', names the prerequisite lookup (vault_list_tasks for path + block_id/line), and routes creation to vault_create_task. Seven worked examples cover the ambiguous cases (recurrence, heading move, clearing a date, assign_block_id).

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 flag destructiveHint=true, and the description substantiates exactly what is destroyed: body replaces the entire note content and existing content is lost unless re-included. It also discloses the non-obvious property merge rules (null removes keys, unmentioned keys preserved, new note drops null keys), concurrency behavior, and a detailed error catalogue — context the annotations cannot convey.

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

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

Core mutation semantics and the alternatives are correctly front-loaded before the error list, and both examples are compact and illustrative. The error catalogue is long and a few entries carry little weight ("ENAMETOOLONG/EACCES — the message says what to do" essentially says nothing), which costs a point on density.

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 4-param write tool with no output schema, the description covers the return string ("Wrote <path>"), every foreseeable failure with a recovery action, and the merge model for nested properties. Nothing an agent needs to call this correctly and recover from errors 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 meaningfully exceeds the schema for `properties`, which is documented only as "Properties to merge" — the null-removal, overwrite, and preservation semantics are supplied here. It also adds Obsidian-specific encoding rules (escape \#, quote wikilinks, keep property types consistent) that the schema omits, though `path` guidance largely restates 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?

Opens with a specific verb+resource ("Create a markdown note") and immediately bounds the scope with overwrite semantics. It explicitly separates itself from siblings vault_patch_note, vault_replace_in_note, vault_update_properties, and vault_update_memory, so an agent can route correctly without opening other 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 a dedicated "When to use" line plus explicit alternatives with the selecting condition ("Prefer vault_update_properties for property-only edits", "Prefer vault_update_memory for appending dated entries"). It also states the exact condition for setting overwrite: true, 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.