Vault Cortex Obsidian MCP Server

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

Beyond the annotations (readOnly=false, idempotent=false, destructive=false), it discloses that the task is created in todo status with a symbol pulled from the status registry, that ➕ today is auto-stamped, that metadata is written in the plugin-configured emoji/Dataview format, and that writes can fail with 'concurrent write in progress'. It also explains the advisory mechanism when a stored line parses back differently — behavior an agent could not infer from annotations alone.

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

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

Front-loaded correctly: purpose, examples, when-to-use, then parameters, errors, syntax caveats, returns. Every section is scannable, but the error catalog and the Obsidian-syntax paragraph make the text very long relative to the core instruction, and some error strings duplicate constraints already implied by the schema (block_id charset, single-line description).

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, yet the description fully documents the return object (path, line, description, block_id, heading, subtasks, changes, advisories) and explains when fields are omitted. For a 17-parameter mutation tool with no output schema, the description supplies everything needed to call it and interpret the response.

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 and vault-specific semantics the schema lacks: heading is required on kanban-plugin notes, parent_block_id/parent_line are mutually exclusive with each other and with heading, priority's 'no signifier' ranks between medium and low, and 'when done' recurrence bases the next occurrence on the completion day. These are genuine additions, though several details (position behavior, date omission) largely restate 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 correctly-formatted task in one call') and enumerates the fields written. It explicitly distinguishes itself from siblings: new tasks are its job, while 'starting work is vault_update_task's job' and lightweight checklist items belong to vault_update_task's add_subtasks. No schema-opening is required to route between the two tools.

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

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

Has a dedicated 'When to use' line plus four concrete call examples, and names the alternative use-path for lightweight checklist items. It also states preconditions and exclusions: heading required on Kanban boards, parent_block_id/parent_line mutually exclusive with heading, 'omit a date rather than guessing'. This is explicit when/when-not/alternative guidance.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description is consistent with that while adding far more: the append-only default policy, the `entry-policy: living` exception, the ambiguity failure mode, and the 'refusing memory write: would shrink content' safety guard. This is unusually rich disclosure of destructive-operation semantics.

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, example, when-to-use, parameters, and errors are cleanly headed and front-loaded, and the length is justified by a genuinely complex matching/error surface. The error list is exhaustive to the point of mild verbosity, but each entry maps to a distinct actionable recovery path.

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, non-idempotent tool with four required parameters and no output schema, the definition covers prerequisites, matching semantics, all failure modes with recovery steps, and the return value. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond it: date+entry together uniquely identify a bullet line, duplicate date+text pairs fail as ambiguous, and section scoping means an identical entry under a different heading will not match. Case-insensitive section matching is already covered by the schema, so it is not fully additive.

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

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

The description opens with a specific verb and resource ('Delete a single dated entry from a memory file in About Me/') and immediately scopes it against siblings by clarifying it removes one entry, not a note. The example makes the granularity concrete, so an agent can distinguish this from vault_delete_note without reading 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?

It gives explicit when-to-use ('removing an entry that was wrong when it was written'), explicit when-NOT-to-use ('do NOT delete to reflect a change: append via vault_update_memory instead'), and a named exception (files with `entry-policy: living`). It also routes to alternatives for adjacent cases (vault_delete_note for whole notes, vault_delete_span for duplicate/impossible-date lines).

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 destructiveHint annotation: it discloses that the outcome depends on the vault's trashOption setting, how Obsidian Sync bypasses that setting (with recovery windows), that the caller cannot pre-select or see the outcome, that backlinks break, and that protected paths are refused. This is unusually rich behavioral disclosure for a mutation tool. Minor deduction only because the very long error catalog is more error-reference than behavior.

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

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

Front-loads purpose, then usage, behavior, parameters, errors, returns — a sensible order. It is long, but most of the length is non-redundant behavioral/error detail. The error catalog is the one section that could be trimmed, keeping it just short of 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?

Given a two-parameter destructive tool with no output schema, the description covers outcome variability, protected paths, retention, failure modes, and the returned confirmation strings. 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. The description nonetheless adds real meaning for prune_empty_folders: it prunes each emptied parent up to but not including the vault root, is best-effort and never fails the call, and keeps folders containing even hidden files like .DS_Store.

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') with the scope of what happens to the file (trash vs permanent). It names the sibling operations it is not (vault_delete_memory, vault_move_note, vault_write_note), so an agent can route correctly without opening sibling schemas.

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

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

Has an explicit 'When to use' line plus three named alternatives with the exact condition that selects each (use vault_delete_memory for dated memory entries, vault_move_note to relocate, vault_write_note overwrite to replace). 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 declare destructiveHint=true and idempotentHint=false, but the description goes well past them: case-sensitive matching, properties preserved with YAML normalized to block style, body-only scope, the empty-line merge rule, forward-only end_anchor search, first_match semantics, and a full error catalogue including 'concurrent write in progress' and path-safety blocks. That is unusually rich disclosure for a destructive operation.

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

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

Front-loaded with the core mechanism, then examples, then routing guidance, then parameter and error detail — a logical order. It is long, and the parenthetical about empty-line counts at the end of the note is arguably over-specified for a description, but almost every sentence carries actionable information.

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

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

There is no output schema, and the description compensates by stating the return value (line count plus an 80-character preview) and enumerating the failure modes with a remediation for each. For a destructive, 4-parameter tool, 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 already 100%, yet the description adds semantics the schema does not: anchors define a line range rather than a text range and never cut mid-line, end_anchor is searched at or after the start line so the span cannot run backward, and first_match applies to each anchor independently. It also clarifies that a whitespace-only line counts as text, not as empty.

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 contiguous block of whole lines from a note's body') and immediately distinguishes its mechanism (anchor substrings instead of full block text) from the siblings that do similar work. An agent can tell it apart from vault_replace_in_note and 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?

An explicit 'When to use' section names the scenario (a block already read, where reproducing old_text is error-prone) and names the alternatives: vault_replace_in_note for small in-place edits, vault_replace_span for block replacement. Both the positive case and the boundary 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds genuinely useful behavior beyond that: the daily-notes folder resolution order, that ORPHAN_EXCLUDE_FOLDERS replaces defaults, and — most importantly — that truncation is invisible because exactly 'limit' results may mean more exist.

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 definition and edge case, then cleanly sectioned into When to use / Parameters / Errors / Returns. Nearly every sentence earns its place, though the two inline Example calls are somewhat redundant given the parameter bullets, and the daily-notes resolution detail is dense for a two-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?

There is no output schema, and the description compensates fully with a Returns section enumerating the metadata fields (path, title, tags, folder, type, created, modified, bytes, etc.) and the sort order. It also documents the empty-array and 'too many excluded folders' cases, so nothing needed to call or interpret it is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes well past the schema: exclude_folders replaces rather than augments defaults (include defaults yourself, pass [] for none), each entry covers subfolders, matching ignores ASCII case, and limit applies after exclusions and most-recently-modified sorting. This is meaning the schema does not carry.

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 immediately defines the term 'orphans' as notes disconnected from the knowledge graph. It even resolves the edge case of self-links, so an agent knows exactly what this tool returns and how it differs from link-listing 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 states the use case ('Vault maintenance — surfacing notes to integrate into the graph'), names the follow-up action (link via vault_patch_note), and explicitly routes the agent elsewhere for the adjacent task ('Prefer vault_get_backlinks to check the connectivity of one specific note'). Both when-to-use and the alternative 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?

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

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

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

Though lengthy, the description is tightly organized with clear sections (summary, examples, when to use, parameters, returns, errors). Each sentence provides operational value, and the main purpose is stated upfront. No redundancy or unnecessary filler.

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

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

For a tool with no output schema, the description fully documents return structure (path, backlinks, count, item fields), link resolution rules, and error handling. It also covers both .md and .canvas inputs, making the description complete and self-sufficient.

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

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

Despite 100% schema coverage, the description adds meaning: emphasizes case-sensitivity, exact path format, file extensions, and provides explicit examples. The Errors section clarifies path rejection and non-indexed path behavior, enriching schema semantics.

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

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

The description clearly states the tool's function: finding all notes and files linking to a given note or canvas. It enumerates specific link types (wikilinks, markdown links, embeds, frontmatter, canvas references), which distinguishes it from any sibling tool.

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

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

Explicitly provides 'When to use' context, listing use cases like assessing connectivity before edits. It names alternative tools (vault_get_outgoing_links, vault_find_orphans) with clear differentiation, satisfying the when/alternatives criteria fully.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description goes well beyond them: it discloses the config resolution chain (env vars → .obsidian/daily-notes.json → defaults), the exists:false contract for not-yet-created notes, and two named error conditions with remediation. This is rich behavioral context the annotations cannot supply.

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

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

Front-loaded with purpose, then examples, when-to-use, parameters, errors, and returns — a clean, scannable structure where nearly every line carries information. It runs slightly long (the full env-var fallback chain and the exhaustive unsupported-token list) but that detail is load-bearing for error diagnosis, not filler.

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

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

With no output schema, the description fully specifies the return shape (path, content, exists) and even the follow-up action when exists is false. Config resolution, valid inputs, error conditions, and sibling handoffs are all covered, so 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% for the single date parameter, so the schema already carries format and default semantics (baseline 3). The description adds meaning beyond it: past and future dates are both valid, and a non-existent date yields exists:false rather than an error. That is genuine added semantics, though it stops short of anything like timezone nuance beyond the schema's server-timezone note.

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 (Read) and resource (daily note by date) and immediately scopes it with the vault's configured folder/format resolution. It explicitly distinguishes itself from siblings: vault_recent_notes is described as 'not date-filtered', and vault_patch_note is named for appending. An agent can route correctly without opening any other 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 covers both today's and arbitrary dates, and names two alternatives with the conditions that select them (vault_patch_note to append content, vault_recent_notes for date-adjacent vault activity). Exclusions and handoffs are explicit rather than inferred.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: the empty-string return when no memory files exist, the 'can be large' warning on the no-arg concatenation, frontmatter stripping, the markdown-vs-JSON output switch keyed on on_or_after, and a full enumerated error catalogue with remedies. This is genuinely rich disclosure.

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

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

Well front-loaded: the first sentence gives the core purpose, modes follow, then examples, then usage, errors, and returns. Nothing is wasted for a three-mode tool, but three near-duplicate examples plus a six-item error list make it longer than strictly necessary.

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

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

There is no output schema, so the description correctly carries the return contract itself, specifying raw markdown vs JSON { entries, total, on_or_after } and the entry shape, plus the empty-match case. Combined with the error catalogue and prerequisites, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so the per-parameter definitions are already documented. The description still adds meaning the schema does not: inter-parameter dependencies ('section requires a file', 'on_or_after requires a file'), how section scopes the result set, and how on_or_after changes the output type. It stops short of the full 5 because format details (ISO date shape, case-insensitivity) largely mirror 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 ('Read semantic memory from About Me/ files') and immediately distinguishes the three behavioral modes (file only, file+section, no args). It also names the siblings it is not (vault_read_note for non-memory notes, vault_list_memory_files for discovery), so an agent can route correctly 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' block (user preferences, principles, opinions, persistent context), an explicit prerequisite (call vault_list_memory_files first), a conditional trigger for on_or_after (reconciliation boundaries), and an explicit alternative rule ('Prefer vault_read_note for reading non-memory notes'). When/when-not/alternatives are all present.

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 behavior beyond them: code-block links are ignored, self-links are included, the note/canvas must be indexed (with watcher latency), and an unindexed path silently returns count 0 rather than an error. The broken-link and daily_note_forward_ref semantics, plus the note that bytes is on-disk size and not delivery cost, are genuinely non-obvious behavioral disclosures.

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 two examples and a clear When-to-use/Parameters/Returns/Errors structure, which is easy for an agent to scan. It is longer than strictly necessary — the daily-note and bytes explanations could be trimmed — but nearly every sentence carries actionable content.

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 return-value burden and does so fully: it enumerates path, outgoing_links, count, the per-link fields, and how exists/kind combine to mean note vs file vs broken. Error cases and the silent-empty-result edge case are also covered, leaving no gap 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 coverage is 100% and the schema already documents the path format and case-sensitivity, so the baseline is 3. The description modestly adds beyond the schema by stating the path is matched against the search index and that the target must already be indexed — a runtime precondition the schema cannot express.

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?

Starts with a specific verb+resource ('Find all notes and files a given note or canvas links to') and immediately differentiates the two input kinds (notes vs canvas files) with distinct link semantics. It also names the sibling it is not (vault_get_backlinks), so an agent can separate the two directions of the graph 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?

Provides an explicit 'When to use' clause covering three concrete scenarios (forward navigation, broken-link audit, dependency check before editing) and explicitly routes incoming-link queries to vault_get_backlinks. When-to-use and the alternative are both stated, leaving nothing to inference.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description discloses case-sensitive matching, the ambiguity-is-an-error rule unless first_match is set, that properties are preserved but YAML may normalize to block style on first edit, and that only the body is touched. It also enumerates nine specific error strings with remedies, which annotations cannot convey.

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

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

The content is long but well-organized and front-loaded: core behavior, two worked examples, when-to-use routing, parameter notes, then errors. The error catalogue is extensive but each entry earns its place by pairing a message with a fix. Slightly verbose overall, but no sentence is pure filler.

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

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

There is no output schema, but the description supplies the return contract verbatim ('Inserted <N> lines <before|after> anchor in <path>') and defines N. Combined with the error catalogue and Obsidian syntax caveats (#, [[, %%), an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the anchor locates a full line and the insert never splits one, content is inserted verbatim with internal blank lines preserved, and a trailing newline adds a blank line after the block. These are semantics the schema does not capture.

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 ('Insert content as whole lines before or after a specific line identified by a short anchor substring') and immediately scopes it ('Operates on the body only'). It explicitly distinguishes itself from vault_patch_note and vault_replace_span, so an agent can route correctly without opening any schema.

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

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

It provides an explicit 'When to use' section with concrete scenarios (table rows, list items, landmarks) and names two alternatives with the conditions that select them: vault_patch_note for heading-targeted inserts and vault_replace_span when replacing a block rather than inserting next to it. 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, yet the description adds substantially more: reads the filesystem rather than the index (explaining the case-sensitivity rule), empty-vs-error behavior for missing folders, three named error strings with their causes and remedies, and how 'bytes' relates to actual read cost (images shrunk, text over 100 KiB needing windowed reads).

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 three illustrations, then organized under 'When to use', 'Behavior', 'Errors', and 'Returns'. It is long for a listing tool and the Returns paragraph drifts into read-path advice, but nearly every sentence carries non-obvious 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, so the description fully documents the return shape (files/extension_counts/total/truncated, path sorting, '(none)' extension). Combined with error handling, case sensitivity, and sibling routing, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so per-parameter docs already exist and the baseline is 3. The description adds real meaning on top: it demonstrates each parameter with worked examples and supplies the case-sensitivity rule for 'folder' and the truncation semantics tied to 'limit' via the 'truncated' return field.

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') with an explicit scope qualifier ('non-markdown') that immediately separates it from note-oriented siblings. The examples make the resource and filter axes 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?

A dedicated 'When to use' block names the alternative tools (vault_read_file, vault_list_notes, vault_search_by_folder, vault_search, vault_get_outgoing_links) and the exact condition that selects each. It also states which file types other search surfaces index, so the boundary is not 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 (read-only, idempotent), and the description adds substantial context beyond them: hidden files are skipped, subfolders are not read, an empty folder returns an empty array instead of an error, entries are dated bullets, and entry_policy semantics are explained including that the server does not enforce either policy.

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?

Content is front-loaded (purpose, example, when-to-use, behavior, errors, returns) and every section carries information, but the embedded JSON example is long and the description as a whole is heavier than strictly necessary for a no-argument listing tool.

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

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

With no output schema, the description fully compensates by enumerating every returned field (file, title, bytes, entry_policy, leading_callout, headings) and its meaning, plus the error case and the entry-policy convention. An agent has everything needed to call and interpret it.

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

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

The tool takes zero parameters, which is the baseline-4 case. The description does enrich the semantics of the returned object fields, but those are output semantics rather than input parameter meaning, so it does not exceed the zero-parameter 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 ('lists About Me/ memory files') plus exactly what is and is not included ('heading outline, per-section entry counts, and leading callout... Does NOT return actual entries'). This cleanly separates it from vault_get_memory, vault_list_files, and vault_search, which the agent can distinguish without opening schemas.

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

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

Explicit 'When to use' section names the downstream tools (vault_get_memory, vault_update_memory, vault_delete_memory) and the sequencing rule ('Always call this first to get valid file and section names'). It also gives a distinct reason to call it, checking entry_policy before pruning.

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

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

Goes well past the annotations (readOnly/idempotent/non-destructive), disclosing sort order (uppercase before lowercase), hidden dot-file exclusion matching Obsidian, symlink inclusion, filesystem-vs-index sourcing, case sensitivity, and exact error semantics (empty array vs 'absolute path blocked'/'path traversal blocked'/'hidden path blocked'). This is rich context an agent cannot derive from any structured field.

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 tightly organized with headers (When to use / Parameters / Behavior / Errors / Returns), examples front-loaded after the first sentence, and no filler. Each section earns its space by covering a distinct decision an agent has to make.

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 2-param, no-output-schema read tool, the definition covers purpose, routing, parameter edge cases, ordering, hidden/symlink handling, and the full error taxonomy including remediation. Nothing needed to call it correctly is missing.

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

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

Even though schema coverage is 100%, the description adds real meaning: folder includes subfolders but 'Projects' does not match 'ProjectsOld/', exact letter case is required on case-sensitive filesystems, and glob semantics are spelled out ('* stays within one level, ** spans any depth', matched against the vault-relative path, case-sensitive). Far exceeds the terse 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?

Opens with a precise verb+resource+scope ('List .md file paths in the vault, optionally filtered by folder and/or glob pattern') and immediately bounds the output ('paths only — not content or metadata'). This distinguishes it cleanly from vault_search, vault_search_by_folder and vault_read_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' line plus two explicit routing rules: 'Prefer vault_search_by_folder when you need metadata... Prefer vault_search for content-based discovery. Use vault_read_note to read a note from the results.' Names both alternatives and the condition that selects each.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond that: only frontmatter counts (inline Dataview ignored), count includes null-valued notes, sample_values selection rules and tie-breaking, checkbox rendering as '1'/'0', and the empty-vault behavior. This genuinely enriches understanding rather than repeating 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 and example, then organized under When to use / Parameters / Behavior / Errors / Returns. Long but every section carries needed information, and the header structure makes it skimmable.

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

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

No output schema exists, but the description fully specifies the return shape (JSON array of {key, count, sample_values}, sorted by count desc then key) and error behavior. For a single-param read tool, nothing an agent needs 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% and the single param has a terse schema description, but the description adds real meaning: folder includes subfolders ('Projects' covers 'Projects/Archive' but not 'ProjectsOld/'), matching is ASCII-case-insensitive, and omitting folder scans the whole vault. This goes beyond the schema text, though it is a single parameter.

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

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

States a specific verb+resource ('Discover all property keys in the vault with note counts and sample values') and scopes it as metadata-schema inspection without reading notes. The example concretely anchors the shape. Clearly distinguishable from siblings like vault_list_tags and vault_list_property_values.

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 two named alternatives with the conditions that select them: vault_list_property_values for values of a specific key, vault_search_by_property for key-value matching. Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds substantial non-obvious behavior: array elements unpacked and counted individually, scalar/array handling, numeric-vs-text grouping quirks ('1' vs '1.0'), checkbox stored as 1/0, null skipping, and the silent-truncation caveat at limit. These are things an agent genuinely could not infer from annotations alone.

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 concrete example, then organized under clear headers (When to use, Parameters, Behavior, Errors, Returns). Every paragraph is dense functional content; nothing is filler or repeated from the schema or annotations.

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

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

For a read-only listing tool with no output schema, the description fully specifies the return shape, sort order (count descending then binary text order), and error behavior (unknown key or empty folder yields an empty array, not an error). An agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, yet the description adds real meaning beyond it: 'key' is case-sensitive and must match exactly, 'folder' includes subfolders with case-insensitive matching ('Projects' covers 'Projects/Archive' but not 'ProjectsOld/'), and 'limit' applies after count-descending sort with no truncation signal. This goes well past restating the schema.

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

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

States a specific verb and resource ('List distinct values for a specific property key with how often each occurs'), which unambiguously separates it from vault_list_property_keys (keys) and vault_search_by_property (notes). The inline example with the exact response shape removes any ambiguity about output.

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 ('Enumerating possible values ... before calling vault_search_by_property') and the prerequisite sequencing ('Call vault_list_property_keys first to discover valid key names'). The routing to siblings is stated, not inferred.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds substantial behavioral context beyond them: only frontmatter tags are indexed (inline #tags ignored), hierarchical tags are returned whole rather than split, count is unique notes not occurrences, and the # prefix is stripped. It also discloses the empty-vault behavior (empty array, not an error), which no annotation 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?

Front-loaded with the core behavior, then example, usage, errors, and returns, each under a clear label. Every sentence carries new information; even the example earns its place by showing the exact record shape. No filler or hedging.

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

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

With no output schema, the description carries the full burden of describing the return value, and it does so with both a concrete example and a prose summary ('JSON array of { tag, count }'). Error behavior for the empty case is covered, so an agent has everything needed to call and interpret this tool.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-param tool is 4. It does clarify the shape of each returned entry and the tag format, which is useful context but belongs to output semantics rather than parameter semantics.

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

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

States a specific verb and resource ('List all tags in the vault with note counts') plus the ordering ('count descending'), which is more than a bare restatement of the title. It also implicitly separates itself from siblings like vault_search_by_tag and vault_list_property_keys by scoping to tags only.

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

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

Explicitly names when to use it ('Discovering what tags exist before searching by tag. Good first step for vault orientation') and names the alternative with the condition that selects it ('Prefer vault_search_by_tag once you know which tag to query — it supports hierarchical prefix matching'). This is textbook when/when-not/alternative guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantial behavior beyond them: index lag ('a task written moments ago may still show its old state'), explicit exclusions (fenced code blocks, %% %% comments, NON_TASK statuses), and error semantics (malformed dates throw, no-match is not an error). This is exactly the context an agent needs to avoid misreading stale results.

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

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

Front-loaded with purpose, then examples, usage, behavior, parameters, errors, returns in clear sections — every section earns its place for a 16-parameter tool. It is long, and some example redundancy exists, but the structure makes it scannable rather than bloated.

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

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

No output schema exists, so the description carries the full return-shape burden, and it does so thoroughly (total/tasks, always-present vs conditional fields, subtask_progress semantics including the cancelled-child edge case and filter independence). For a complex 16-param read tool, nothing material 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 adds genuine meaning beyond it: 'virtual values expand in arrays' for status, the rule that 'a date filter only matches tasks that HAVE that date', and folder case-insensitivity with subfolder inclusion. These semantics are not obvious from the schema alone.

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

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

States a specific verb and resource (list checkbox tasks across the vault) and immediately scopes it against the Tasks-plugin data model, naming what metadata formats are indexed. It explicitly routes away from siblings: 'Prefer vault_read_note (heading mode)... Prefer vault_search for full-text queries'.

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 a dedicated 'When to use' block plus five concrete examples covering triage, Kanban lanes, project trees, and weekly done queries, and explicitly names alternatives (vault_read_note, vault_search) with the condition that selects each. 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 read-only/idempotent/non-destructive, but the description adds substantial behavioral context beyond them: recall-over-precision tuning (expect marginal entries), the any-term keyword fallback that rescues a would-be-empty result, that unknown files return empty rather than erroring, and the meaning of truncated/search_mode/reranked.

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 usage then errors then returns, so scanning is easy. It is long and the Returns paragraph is dense, but nearly every sentence carries non-redundant semantics; only marginal tightening is possible.

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

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

With no output schema, the description fully specifies the return shape ({entries, total, truncated, search_mode, reranked}), per-entry fields, sort order, and error semantics. Nothing an agent needs to interpret results 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 genuinely extends it: query phrasing guidance (content words rank better than meta framing), that file is applied before limit, and that limit drops least-relevant matches rather than a date range. The file parameter's case-sensitivity and default omission are covered by the schema.

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

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

States a specific verb (recall), resource (memory entries), retrieval mechanism (entry-granular hybrid keyword + semantic), and scope (ALL About Me/ files, ALL time). It explicitly distinguishes itself from vault_get_memory and vault_search, so an agent can route without opening schemas.

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

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

The 'When to use' block gives concrete trigger questions ('what does my memory say about X?') and names the two alternatives with the conditions that select them: vault_get_memory for a known file/section verbatim, vault_search for notes outside the memory layer. Exclusions 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 declare destructiveHint=true and idempotentHint=false, but the description adds far more: exactly which link forms are rewritten, the 'only rewrite when leaving it unchanged would break it' rule, write ordering (original deleted last), partial-failure recovery for both ordinary and case-only renames, lock scope, and pruning semantics. This is behavioral context an agent cannot get 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 behavior, then examples, when-to-use, parameters, errors, syntax, and returns — clearly sectioned and skimmable. It is long, but the length is justified by the number of distinct error/recovery paths; the four examples earn their place by disambiguating rename vs move vs prune.

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

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

Despite having no output schema, the description fully specifies the return payload (moved_to, links_updated, updated_notes, pruned_empty_folders), enumerates the failure modes and their recovery, and covers the preconditions (protected paths, path form). Nothing an agent needs to invoke or recover from this call is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the 'Parameters:' section meaningfully extends prune_empty_folders beyond the schema (per-parent behavior, hidden-file caveat, no-op on in-place rename or moves into source subfolders, best-effort failure tolerance). old_path/new_path behavior such as case-only renames and the .md requirement is also elaborated, though much of that duplicates 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 states a specific verb (move or rename), a specific resource (a note), and the distinctive side effect (rewriting every incoming and outgoing link across the vault). It explicitly distinguishes itself from siblings by naming vault_write_note + vault_delete_note, vault_patch_note, and vault_update_properties as the wrong tools for adjacent 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?

A dedicated 'When to use' line gives the triggering scenario (rename or relocate while keeping the link graph intact), and the description states both when-not (use vault_patch_note/vault_update_properties for body or property edits) and the anti-pattern (write+delete orphans backlinks). It also discloses the protected-path precondition that blocks the call.

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 non-idempotent, but the description goes far beyond them: frontmatter preservation and YAML normalization to block style, no separator insertion around content, the data-loss risk of replace on sections with child headings, the no-heading prepend nesting trap, section-boundary semantics, empty-heading non-targetability, and a full error catalogue with recovery actions.

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

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

Purpose and when-to-use are front-loaded and the body is cleanly partitioned into Operations, Limitation, Section boundaries, Errors, Obsidian syntax, and Returns. It is long, and the 13-entry error list plus the table-row and Obsidian-syntax asides push past what most calls need, but nearly every line carries actionable information.

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

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

For a destructive, non-idempotent mutation tool with no output schema, the description covers safety, failure modes, structural side effects, and the exact return string format. Nothing an agent needs to invoke it correctly or 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 adds real meaning beyond the enum: per-operation targeting rules (which ops require a heading), how heading matching behaves, how heading_level disambiguates, and what include_children actually authorizes. It stops short of documenting path/content syntax further because the schema already does that.

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

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

States a specific verb and resource ('Surgical edits to a markdown note') and enumerates the four operations up front. It explicitly distinguishes itself from siblings by naming vault_write_note, vault_replace_in_note, vault_create_task, and vault_update_task with the condition that selects each.

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' line plus four named alternatives with the scenario each covers (new notes, full rewrites, in-place typo fixes, task creation/completion). Edge cases such as 'to start a new section above the first heading use insert_before, not a no-heading prepend' make the routing 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 cover the safety profile (read-only, idempotent, non-destructive), and the description layers on rich behavior: server-side downscaling thresholds (49152 bytes / 1568px), animated GIF first-frame reduction, the 5-page raw PDF render limit, per-window text caps, and byte-exactness of unpaged reads. This is well beyond what structured fields 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?

Front-loaded with examples, then a per-type return table, paging rules, usage, errors, and returns — logically ordered and each section scannable. However it is unusually long for a read tool, and the exhaustive error catalogue (13 entries) is closer to reference documentation than agent-facing 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?

With no output schema, the description fully compensates by enumerating return shapes per type (image block + metadata line, alternating image/text page pairs, single text block with optional window metadata). Combined with paging, error, and size-cap coverage, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so baseline is 3; the description adds genuine meaning on top — how start_line/limit produce a metadata prefix with window and total, the 'continue with start_line: 101' hint, and the trick of start_line:1 with limit:1 to probe line count. It slightly understates raw's rejection for images in the paging context, but coverage is strong.

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 ('read a non-markdown vault file') and immediately positions itself as the read-side companion to vault_read_note, explicitly rejecting .md. The per-type return breakdown makes the scope unambiguous relative to siblings like vault_read_note and vault_list_files.

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 a dedicated 'When to use' section naming triggers (a note references a file you need to see), plus explicit alternatives: vault_get_outgoing_links to find linked files, vault_list_files to browse, vault_search for indexed content, vault_read_note for .md. It even states exclusions ('not images', 'this tool rejects them').

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 non-obvious behavior: mode mutual exclusivity, LF normalization on paged reads vs byte-identical unpaged reads, section-boundary rules, security blocks on absolute/traversal/hidden paths, and a full error catalog. This is well beyond what the annotations convey.

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

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

Front-loaded with purpose then examples, and nearly every sentence earns its place given seven interacting parameters. Slightly long: the Returns and Outline paragraphs restate shape details already present in the schema descriptions, and the six examples are more than strictly needed.

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

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

With no output schema, the description carries the full return-value burden and does so: raw markdown default, JSON for properties_only and outline, section markdown with heading line included, and the window-metadata prefix on paged reads. Error recovery paths are also covered, so nothing needed to call this correctly is missing.

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

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

Schema coverage is 100% (baseline 3), but the description adds semantics the schema cannot express: properties_only/outline/heading are mutually exclusive, heading_level only applies with heading and exists to disambiguate same-text headings, start_line/limit are invalid in JSON modes, and the 'start_line: 1, limit: 1' trick to obtain line counts.

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 (read a markdown note) scoped by vault-relative path, and immediately distinguishes itself from vault_read_file via the '.md' requirement and from vault_search via 'you know the exact path'. An agent can tell it apart from every sibling 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?

Explicit routing: vault_search when the path is unknown, vault_list_tasks for task status/order, vault_get_memory for About Me files, vault_patch_note to edit, vault_get_backlinks/vault_get_outgoing_links for link exploration. It also gives mode-selection guidance (outline first, then heading; properties_only when only properties are needed) and paging advice for oversized 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 mark this read-only and idempotent, and the description adds valuable behavior beyond that: 'created' sorts notes without the property last rather than excluding them, 'modified' catches sync touches and property changes, and an empty vault returns an empty array. These behavioral details will help an agent predict results accurately.

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 organized into clear sections: overview, examples, when to use, parameter interactions, errors, and return format. It is longer than a one-liner, but every sentence adds needed operational context, and the core purpose is front-loaded.

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

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

Despite having no output schema, the description fully documents the return shape: JSON array of note metadata with field names and nullability. It also covers empty-vault behavior and parameter edge cases, so an agent has enough information to call and interpret the tool correctly.

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

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

Although the input schema already covers parameter names and defaults, the description explains how sort_by and limit interact, including the pitfall that a small limit with sort_by 'created' may return only notes that have the property. This adds important meaning beyond the schema's minimal descriptions.

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

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

The description states a specific verb and resource: 'List recently modified or created notes, sorted by timestamp.' It also distinguishes itself from a date-range filter and shows examples, making the tool's purpose unambiguous and distinct from sibling search tools.

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

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

The description includes a dedicated 'When to use' section and explicitly names alternatives: 'Prefer vault_search for content-based discovery. Prefer vault_search_by_folder for browsing a specific folder.' This gives clear routing guidance and conditions for choosing this tool versus siblings.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds substantial context beyond them: properties are preserved, YAML may be normalized to block style, edits are body-only, replace_all defaults to first-match for safety, and a full error catalogue (concurrent writes, blocked paths, control characters) is enumerated.

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

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

Front-loaded with purpose, then examples, when-to-use, parameters, errors — a logical order. However, the paragraph explaining empty-line joining on deletion is dense and hard to parse, and could be tightened given how narrow the case is.

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, non-idempotent mutation tool with no output schema, the definition covers scope boundaries, side effects, safety defaults, error recovery paths, and the return value (confirmation with replacement count). Nothing an agent needs to call it safely 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 adds real meaning: old_text requires enough context for uniqueness and is not regex; new_text is Obsidian Flavored Markdown with no escaping, with tag/wikilink/comment caveats; and the long empty-line deletion semantics and replace_all rationale go well beyond the schema's one-line defaults.

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

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

States a specific verb+resource ('Find and replace text in a markdown note's body') and immediately scopes it (body only, not properties). It explicitly distinguishes itself from vault_replace_span, vault_delete_span, and vault_patch_note, so an agent can route without opening schemas.

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

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

Provides an explicit 'When to use' section with concrete scenarios (typos, renaming, deleting a short line) and names three alternatives with the precise conditions that select each (large multi-line block → vault_delete_span; anchor-based block replace → vault_replace_span; relocation between headings → vault_patch_note).

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 only declare destructiveHint/readOnlyHint/idempotentHint; the description goes far beyond by disclosing whole-line selection semantics, case sensitivity, property preservation, YAML normalization to block style, body-only scope, and concurrency behavior ('concurrent write in progress'). It even documents the full error surface and Obsidian syntax pitfalls, none of which structured fields 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?

Well front-loaded (purpose, examples, when-to-use, parameters, errors, returns) with clear section labels, and the length is largely justified by the operation's complexity. However, the empty-line joining rules are convoluted and slightly redundant with the Returns section, so it is not maximally tight.

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

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

For a destructive 5-parameter tool with no output schema, the description covers everything needed: return format with N/M semantics, the complete error catalog with remediation, and Obsidian syntax hazards. Nothing an agent needs to invoke 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), but the description adds genuinely new semantics: end_anchor is searched at or after the start line so spans cannot run backward, first_match applies to both anchors independently, and content empty-line behavior is spelled out in detail. This meaningfully exceeds the schema's own parameter text.

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 names a specific verb and resource ('Replace a contiguous block of whole lines in a note's body') and immediately states the distinguishing mechanism (anchor substrings rather than full text). It explicitly contrasts with vault_replace_in_note and vault_delete_span, so an agent can select it without opening sibling schemas.

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

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

A dedicated 'When to use' paragraph describes the exact scenario (a block already read, where reproducing old_text would be error-prone) and names two alternatives with their selecting conditions. It also gives practical anchor-selection guidance (short unique fragment of first line, last line for end_anchor).

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond them: transparent fallback to keyword-only while embeddings build, no-match returning an empty array rather than an error, auto-sanitization of malformed queries, and a thrown error with remediation text for bad date filters.

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 ranking are front-loaded, and the sectioned layout (filters, examples, when-to-use, errors, returns) aids scanning. However the description is unusually long and the Returns paragraph is dense, so it is thorough rather than tightly concise.

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

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

With no output schema present, the description compensates by documenting the full result shape, search_mode, reranked, and conditional fields like leading_callout. Error behavior, edge cases (notes lacking created), and sibling routing are all covered, so an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, but the description adds genuinely new semantics: folder matching includes subfolders and ignores case, properties compare by exact type with a checkbox 1/0 exception and any-element list matching, date bounds compare whole server-local days, unparseable created values never match, and query syntax (implicit AND, porter stemming, exact phrases, punctuated-term handling). Some filter text does restate the schema, which keeps this 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 opening sentence states a specific verb and resource ('Hybrid search across all vault notes') and names the ranking mechanism (RRF combining FTS5 with vector similarity). It disambiguates from siblings by naming four alternatives with the exact conditions that select each.

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 designates this as the primary discovery tool for content-based queries, then routes tag-only, folder-browsing, metadata-only, and time-based cases to vault_search_by_tag, vault_search_by_folder, vault_search_by_property, and vault_recent_notes respectively. No condition is left to inference.

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

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

Beyond the readOnly/idempotent annotations, it discloses index lag ('a few seconds'), that hidden dot-folders are never indexed, that truncation is not signaled ('exactly limit results may mean more exist'), result sort order, and that a nonexistent folder returns an empty array rather than an error. This is rich, non-obvious behavioral context.

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

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

Front-loaded with purpose, then a contrast, then when-to-use, parameters, behavior, errors, and returns — a clean scaffold. It is longer than strictly minimal, and the Returns field list is dense, but nearly every sentence carries information an agent needs.

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 covers the return shape (fields, sort order, nullable created, conditional leading_callout/additional_properties), error behavior, and freshness caveats. Nothing needed to call or interpret the tool is missing.

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

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

Schema coverage is already 100%, but the description adds real semantics: folder matches a whole folder not a prefix ('Projects' not 'ProjectsOld/'), case-insensitive ASCII matching, trailing slash ignored, and that limit applies after sorting with no truncation indicator. These are behaviors the schema cannot express.

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 (browse/search) and resource (notes in a folder) with scope, and explicitly contrasts with vault_list_notes which 'returns paths only.' An agent can distinguish it from siblings 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?

Provides explicit when-to-use guidance ('Exploring a folder's contents with full context') plus named alternatives: vault_list_notes for paths, vault_search for text queries, and the backlink/outgoing-link tools for graph traversal. 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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds substantial non-obvious behavior: exact/case-sensitive matching, numeric coercion rules, checkbox '1'/'0' encoding, subfolder inclusion, silent truncation when limit is hit, and that an unknown key returns an empty array rather than an error. This is well above what annotations provide.

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

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

Well front-loaded with purpose, examples, routing, then parameter detail. The numeric-matching paragraph is dense and covers edge cases beyond what most callers need, but the sectioning keeps it navigable.

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 (metadata fields, optional leading_callout/additional_properties, sort order) and the truncation caveat. Nothing an agent needs to call or interpret results correctly is missing.

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

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

Schema description coverage is 100%, so baseline is 3. The 'Parameters' block does add meaning beyond the schema (case-sensitivity, numeric/checkbox forms, folder covering subfolders, limit applied post-sort), but much of it restates or elaborates fields the schema already names.

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 scopes it as metadata-only with no text query. It clarifies the scalar-vs-array matching behavior, which is the key behavioral distinction from sibling search tools.

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

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

Explicit 'When to use' section, plus named alternatives with selection conditions: prefer vault_search with a text query, prefer vault_search_by_tag for hierarchical tag matching, and use vault_list_property_keys/values for discovery. 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 cover readOnly/idempotent/non-destructive, yet the description adds genuinely new behavior: an unknown tag or no match returns an empty array rather than an error and should not be used as an existence check, plus a result cap of 20 with no truncation signal so exactly 20 may mean more. That cap/truncation caveat is important and is not expressible in the annotations. Minor gap: no pagination/offset guidance for retrieving past the cap.

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-line purpose, then labeled blocks (Example, When to use, Parameters, Errors, Returns) that make scanning cheap. The Returns block is dense but earns its length because there is no output schema; the Parameters block repeats a little of what the schema already states.

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 full return contract (field list, promoted vs additional_properties keys, sort order, cap of 20), plus error semantics and the exact-vs-prefix interaction. Nothing an agent needs to call this correctly or interpret results is missing.

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

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

Schema coverage is 100%, but the description still adds meaning beyond it: the prefix match follows the '/' separator, so 'project' matches its children but NOT 'my-project' or 'projects', and exact=true excludes children entirely. Those boundary/negative examples are the exact failure modes an agent would hit and are absent 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?

Opens with a specific verb+resource ('Find notes with a specific tag') and immediately scopes the tool's distinct capability (hierarchical prefix matching on a tag, with an exact override). The 'When to use' block explicitly separates it from vault_search (text relevance) and vault_list_tags (tag discovery), so an agent can route without opening sibling schemas.

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

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

States the selection condition plainly ('Tag-only lookups ... with no text query'), names the alternative to prefer when text ranking is needed, and gives a prerequisite step ('Use vault_list_tags first to discover available tags'). Exclusions and alternatives are both 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 only declare idempotentHint/destructiveHint/readOnlyHint, but the description adds substantial behavioral context: automatic date prefixing, newest-first insertion, append-only policy with the entry-policy: living exception, auto-creation of missing files/sections, the near-duplicate heading guard, and the shrink-guard refusal behavior. This far exceeds what the annotations convey.

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

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

Front-loaded with the core action and behavior, then organized into example, when-to-use, parameters, syntax, errors, and returns. Every section earns its place, though the extensive error catalog makes it long; the density is justified by the tool's complexity but is near the upper bound of acceptable size.

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

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

Despite having no output schema, the description explicitly covers the return value ('Confirmation message... notes when an identical entry already existed'), plus edge cases (auto-creation, near-duplicate guard, shrink refusal). Nothing an agent needs to invoke this correctly or interpret failures 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, and the description modestly exceeds it by tying parameter constraints to concrete error conditions (single-line entry/section, bare YYYY-MM-DD date, bare file name with no dot or slash). It adds operational meaning beyond the schema field descriptions rather than merely restating them.

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 and resource: 'Append a dated entry to a section of a memory file in About Me/.' It explicitly differentiates from siblings by naming vault_write_note for non-memory notes and vault_list_memory_files for discovery, so an agent can route correctly 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?

Provides an explicit 'When to use' clause (recording a preference, principle, opinion, or fact about the user) plus a prerequisite workflow ('Call vault_list_memory_files first and reuse existing file and section names'). It also names the alternative for a different case ('Prefer vault_write_note for creating non-memory 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 declare the write/destructive/idempotent profile, and the description adds substantial non-redundant behavior: shallow-merge semantics, null-deletes-a-key, unmentioned keys preserved, body untouched, and a full error catalog including concurrency retry guidance. The null-delete behavior is exactly the kind of detail annotations cannot express, and it is consistent with destructiveHint=true.

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 merge contract, then example, when-to-use, errors, syntax notes, return value — a well-labeled structure where each block earns its place. It is on the longer side, and the Obsidian syntax paragraph is slightly tangential to tool selection, but nothing is 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?

No output schema exists, so the 'Returns: Confirmation message.' line covers the return contract, and the error list, merge semantics, and format caveats cover the rest of what an agent needs. For a 2-param nested-object mutation tool, this is complete.

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

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

Schema coverage is 100%, so the baseline is 3, and the description genuinely adds meaning on top: a concrete call example, the rule that arrays are replaced entirely rather than appended, and Obsidian type/quoting conventions for wikilinks and multi-value fields. Only the 'exact letter case' nuance of the path param is left to 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 ('Update a note's frontmatter properties via shallow merge') and immediately scopes the operation: body is never modified. This cleanly separates it from siblings like vault_write_note, vault_patch_note, and vault_replace_in_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' clause plus an explicit alternative ('Prefer vault_write_note when creating a new note, or replacing the body with overwrite: true') and a prerequisite step pointing at vault_read_note({ properties_only: true }). Both the when and the when-not are named.

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 idempotentHint=false, and the description substantiates both with concrete detail: Kanban lane moves, the delete-on-completion path that removes the line and children, the recurring spawn's loss of block_id/🆔/⛔, and the explicit caveat that completing by line is NOT idempotent for recurring tasks. It goes well beyond the annotation surface, covering concurrency ('concurrent write in progress'), auth/path blocking, and the advisories divergence mechanism.

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

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

The structure is strong — purpose, examples, usage, parameters, errors, syntax notes, and returns are clearly headed and front-loaded. However, the description is enormous relative to the task, and the exhaustive error catalog (24 entries) plus seven examples is heavier than an agent needs to select and invoke correctly, so it is complete rather than concise.

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

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

With no output schema, the 'Returns' section carries the full burden and documents every returned field including next_occurrence, changes, advisories, and on_completion_applied. Combined with the mutation/error/recurrence semantics, the definition is complete for a 19-parameter mutating 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; the description earns above that by documenting cross-parameter semantics the schema cannot express: exactly-one-of block_id/line, mutual exclusivity, the explicit-null clearing convention, position's interaction with heading moves (and its invalidity on sub-tasks), and how on_completion/recurrence govern the status='done' transition. Some field-level restatement overlaps the schema, keeping this 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 description opens with a specific verb+resource ('Update a task's status, priority, description, dates...') and enumerates the full set of mutable fields. It explicitly distinguishes itself from siblings: vault_list_tasks for identification and vault_create_task for creation. An agent can place this tool precisely 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?

The 'When to use' paragraph gives explicit conditions (completing, starting, re-prioritizing, editing, setting/clearing dates, moving headings, reordering) and names the alternatives to use first or instead (vault_list_tasks, vault_create_task). It also states the preconditions for a valid call — exactly one of block_id/line, at least one change, explicit null for clearing.

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

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

Annotations declare destructiveHint=true and idempotentHint=false, but the description goes well past them: it explains exactly what is destroyed (body replaces the entire note content), how properties merge on overwrite (new keys added, matching overwritten, null removes, unmentioned preserved), concurrency behavior, and an enumerated error catalogue including path-traversal and control-character failures. This is materially richer than the annotations alone.

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 the irreversible body-replacement warning before examples and error codes; each block (when-to-use, errors, syntax) earns its place. It is longer than strictly necessary — the error catalogue is exhaustive — but the information density remains high and scannable.

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, non-idempotent, 4-parameter write tool with a nested properties object and no output schema, the description covers data-loss risk, overwrite semantics, sibling routing, path rules, syntax pitfalls, and failure modes. Nothing an agent needs to call this safely is missing; the 'Returns: Confirmation message.' line closes the output gap.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond it: the merge semantics for properties (what null does to a key, what happens to unmentioned keys when overwriting without properties) and the overwrite gating rule. It also flags Obsidian-specific quirks (#, [[, %%) that affect body and property values, which the schema does not cover.

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 ('Create a markdown note') and immediately distinguishes itself from sibling write tools by contrast: vault_patch_note / vault_replace_in_note for partial edits and vault_update_properties for property-only edits. An agent can route correctly 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?

Contains an explicit 'When to use' section, a conditional rule for overwrite ('only when you intend to replace an existing note's body'), and names two preferred alternatives with the conditions that select them (property-only edits, appending dated memory entries). No exclusions are left implicit.

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