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 covered. The description adds one behavioral trait beyond the annotations: that omitting topic yields a topic index. It discloses nothing about rate limits, output format, or failure modes.

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

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

Two short clauses, front-loaded with the tool's identity followed by the parameter instruction; no filler. It is arguably too terse for a help tool, but nothing in it is wasted.

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

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

With only one optional parameter and an output schema present, return-value detail is not required, and the annotations carry the safety profile. Still, the definition gives the agent no sense of what topics are available or what the manual covers, leaving discovery entirely to trial calls.

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 0% for the single parameter, so the description must carry the meaning. It does explain the optionality semantics — omitting topic returns the topic index, implying topic selects a specific entry — but it never says what valid topic values look like or how to discover them, so the compensation is partial.

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 names a specific resource (a usage manual / help documentation), which is clearly distinct from the vault-operation siblings like vault_read and vault_write. It stops short of stating an explicit verb or the scope of the manual, but an agent can identify it as the documentation tool without ambiguity.

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

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

Usage is only implied — the agent is expected to infer that this is the tool to call when it needs documentation. The clause 'omit topic for the topic index' does give one concrete invocation instruction, but there is no explicit when-to-use vs alternatives guidance beyond that.

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

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

Annotations already cover the read-only/idempotent safety profile, so the description earns credit for adding beyond them: it discloses that results include 'uncertainties and exact source versions' and that out-of-scope links are silently omitted—non-obvious behaviors an agent needs.

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

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

Three tight sentences with the core operation front-loaded, the key limitation second, and a pointer to help last. Nothing is redundant.

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?

An output schema exists, so return shape needn't be explained, and annotations cover safety. But for a 9-parameter tool with nested scopes and 0% schema coverage, the description leaves the limit parameters and their interaction with results unexplained, a real 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 description coverage is 0% across 9 parameters, including nested objects. The description maps the conceptual source/resolution scope and target dimensions, but the six max* limit parameters and the recursive flags are never explained, leaving most of the schema meaning undocumented.

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?

Specific verb ('Find references') plus resource ('file/heading/block') and the scoping model make the operation unambiguous. It does not explicitly contrast with siblings like search_query, but the 'references' framing distinguishes it well enough.

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 caveat 'Outside-scope incoming links remain unknown' implies when results are incomplete, and 'See help topic references' routes to more detail. However, it never states when to prefer this over search_query or other siblings, leaving usage largely 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, so the description earns credit for adding real behavior: truthy-value returns, overflow-errors-instead-of-truncation, and the scan-vs-filter distinction. The explicit 'never truncation' guarantee is exactly the kind of failure-mode disclosure an agent needs before setting caps.

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?

Four short sentences, each carrying a distinct fact (fields, return semantics, scan-vs-filter, overflow behavior), with the core purpose front-loaded. No filler and no repetition of schema 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?

With an output schema present, return values need not be described, and the scan/error semantics are well covered for a 7-parameter tool. The gap is the query DSL itself: no mention of which JsonLogic operators or field names are valid, which is the hardest part of invoking this tool correctly.

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

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

Schema coverage is 86%, so the baseline is 3; the description pushes above it by explaining that scope is the sole scan driver and that result caps are not truncation, which clarifies the intent behind maxResults and maxFiles. It still says nothing about the JsonLogic object shape required by the sole required 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 and resource ('Query Markdown') plus the mechanism and queryable fields (path, content, tags, frontmatter, stat), which lets an agent tell it apart from vault_list, tag_list and reference_query. The trailing 'No link graph' explicitly carves out the graph-query sibling.

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

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

Provides one important usage rule -- that only scope limits the scan while path/glob conditions merely filter results -- which shapes how an agent should build a query. However, it never names an alternative tool or states when to prefer vault_list/tag_list over this one; the 'No link graph' clause is the only implied exclusion.

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, so the bar is lower, yet the description adds real behavioral context: limits 'fail explicitly' (i.e., errors instead of silent truncation) and inline recognition 'may differ from Obsidian Desktop'. Those caveats are not derivable from the annotations or schema.

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

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

Three tight clauses, no filler, with the core purpose front-loaded before the two caveats. Nothing redundant is present.

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?

An output schema exists so return values needn't be described, annotations cover the safety profile, and the schema documents all five caps. The description covers the surprising edge cases; only the when-to-use gap keeps it from being fully complete.

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

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

Schema coverage is 100% and every cap parameter is self-documented in the schema, so the baseline of 3 applies. The description adds no syntax or default guidance beyond the schema's 'omit for 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 and resource: 'List tags and parent tags with per-file counts', and adds a concrete output detail ('names omit #'). It is clearly distinguishable from vault_list and search_query by resource, though it never explicitly contrasts itself with those siblings.

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

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

The description never says when to reach for tag_list versus search_query or vault_list, nor does it state any prerequisites. Usage is only implied by the word 'List'.

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

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

Goes well beyond the annotations: it discloses create-on-miss behavior, mandatory optimistic concurrency on existing files, the LF normalization side effect, binary/NUL rejection, and the absence of automatic retry. These are exactly the mutation traits an agent needs and annotations alone don't 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?

Three compact sentences with the primary action and create-on-miss behavior front-loaded, then constraints. No filler; each clause carries a distinct operational fact.

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?

An output schema exists so return values needn't be described, and the mutation semantics are well covered. The remaining gap is the missing pointer to where ifMatchGuard/versionGuard values come from (presumably vault_read) and what failure looks like when the precondition fails.

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 0%, so the description must carry the load. It clarifies the conditional requirement on ifMatch/ifMatchGuard ('copy versionGuard'), but leaves the sha256 format of ifMatch, the 64MiB content cap, and where a guard token is obtained unexplained.

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 ('Append UTF-8 text') and adds a key scope fact — missing files are created. The append semantics are self-evidently distinct from siblings like vault_write, vault_patch, and vault_replace_text, though no sibling is named.

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

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

Gives real conditions ('Existing files require ifMatch or ifMatchGuard') but frames them as parameter requirements rather than when-to-use-this-vs-alternatives guidance. An agent still must infer that vault_write is the overwrite path and vault_patch the edit path.

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 substantive context they don't convey: deletion lands in .trash and is recoverable, permanent=true is irreversible, and there is no automatic retry or fallback to permanent deletion. Permissions/auth requirements are still unstated, keeping it below 5.

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

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

Two dense sentences with the recoverability default front-loaded and the irreversible case immediately following — no filler. Slight penalty for telegraphic phrasing ('ifMatch or ifMatchGuard (copy versionGuard)') that reads as notes rather than explanation.

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?

An output schema exists so return values need no explanation, and the description covers the key danger profile for a destructive mutation plus the no-retry caveat. Missing pieces are path resolution semantics and any permission requirements, which matter for a delete operation.

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 0%, so the description must carry parameter meaning. It explains permanent and gestures at ifMatch/ifMatchGuard as source checks, but the phrase 'copy versionGuard' is cryptic and the two conditional parameters are never clearly distinguished (full sha256 digest vs 16-hex guard), and 'path' is left entirely implicit.

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 file') plus the immediate destination semantics ('recoverable Vault .trash'), and clarifies the permanent-mode variant. No sibling tool in the list performs deletion, so the agent can distinguish it without inspecting 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?

Gives clear conditional guidance: default behavior is recoverable, set permanent=true only when irreversibility is acceptable, and use ifMatch/ifMatchGuard to guard against concurrent modification. It does not explicitly name alternatives (e.g., vault_move as a non-destructive option), so it stops short of full when-not 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 read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful detail about what the map contains and that its keys are intended to be reused unchanged, but it does not explain truncation behavior, limits, or what happens when maxBytes/maxHeadings are hit.

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

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

The description is two compact sentences with no filler, and the primary purpose is front-loaded before the key-reuse instruction.

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

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

The output schema covers return values, and annotations cover safety, but the 0%-described parameters are a significant gap for a tool whose maxBytes and maxHeadings settings affect what the map contains. The description does not compensate for that missing parameter semantics.

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 0%, with three parameters (path, maxBytes, maxHeadings) and no descriptions in the schema. The description does not mention any parameter, so an agent gets no guidance on what the limits mean or how they affect the returned map.

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 ('Get') and lists concrete returned artifacts: heading paths, block IDs, property names, version, and versionGuard. This clearly distinguishes it from a plain document read, though it does not explicitly name sibling tools or contrast itself with vault_read/vault_list.

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 implies the tool is used before targeted reads/patches by saying to copy returned keys unchanged. However, it does not name the alternative tools or state when not to use this map, leaving the routing decision partially implicit.

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 closed-world, so the safety profile is covered. The description adds real behavior beyond that: trailing '/' on directory names, omission of protected/symlink entries, and a failure mode where overflow errors rather than truncates. That error-over-truncation guarantee is exactly the kind of context an agent needs and could not 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?

A single tight sentence pair: the core action and root-addressing rule come first, then the behavioral caveats. No filler, no repetition of the schema, and the most decision-relevant constraint (root path) is front-loaded.

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

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

With an output schema present, return-shape explanation is unnecessary, and the annotations carry the safety profile. The description adds the filtering rules and the error-not-truncation contract, which is most of what an agent needs; only the maxEntries semantics remain undocumented in prose.

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 0%, so the description has to carry both parameters. It explains path well (omitting it or passing "" selects root), and 'overflow errors, never truncation' indirectly implies maxEntries caps results and errors when exceeded, but maxEntries is never named or bounded in prose. Partial compensation for a coverage gap, hence a mid score.

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

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

The description gives a specific verb+resource ('List a Vault directory') and immediately pins down the scope ('omit path or use "" for root'), which is enough for an agent to distinguish it from vault_read, vault_get_document_map, and search_query without opening a schema. It stops short of naming a sibling alternative explicitly, so it falls just below the top mark.

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 tells the agent how to address the root directory ('omit path or use ""'), which is useful invocation guidance, but it never states when to choose vault_list over search_query or tag_list, nor any exclusions or prerequisites. Usage is implied by the name rather than argued.

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?

Despite annotations already flagging destructiveHint=true, the description adds substantial non-redundant behavior: parent auto-creation, trailing-slash filename retention, the overwrite flag requirement, the fact that ifMatch/ifMatchGuard validate the source only, and the absence of retry or cross-filesystem fallback. These are exactly the operational caveats an agent needs before a destructive move.

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

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

The definition is tightly packed with semicolon-delimited clauses and leads with the core action, so no sentence is filler. The telegraphic style is dense but each clause conveys distinct operational 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?

With annotations covering the destructive/non-idempotent safety profile and an output schema handling return values, the description fills the important behavioral gaps (parents, overwrite, precondition scope, no fallback). It is nearly complete, missing only explicit guidance on failure behavior when overwrite is not permitted.

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 0%, so the description carries the burden and does so well: it explains destination trailing-slash semantics, allowOverwrite's role, and that ifMatch vs ifMatchGuard are source-only precondition checks (with a note that ifMatchGuard mirrors copy's versionGuard). Only 'path' is left unelaborated, which is reasonable given its obviousness.

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 ('Move a file') and immediately scopes it ('no link/history updates'), which distinguishes it from copy-style or link-maintaining operations among the siblings. It stops short of naming a sibling outright, but the scope statement makes the tool's identity unambiguous.

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

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

Usage is implied through conditional rules ('Overwrite requires allowOverwrite') rather than explicit when-to-use versus alternatives. It never states when an agent should pick vault_move over vault_write or vault_delete, so the agent must infer selection from the sibling names.

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

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

The annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=false. The description adds useful context that a version precondition (ifMatch/ifMatchGuard) must be copied from a read/map and that no automatic retry occurs, but omits conflict/error behavior and permission requirements.

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

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

It is short, but structured as a dense run-on of cryptic clauses like 'Copy map keys unchanged' and 'markerAndContent prepend/append' that are not interpretable without additional context. The core verb/resource is front-loaded, but the rest is hard to parse.

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

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

For a complex mutation tool with 14 parameters, nested objects, and very low schema coverage, the description does not explain most parameter semantics, prerequisites for obtaining the version guard, or error/conflict behavior. An output schema exists, so return values needn't be covered, but the input-side gaps are large.

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 only 14% across 14 parameters, so the description must compensate, but it only touches ifMatch, ifMatchGuard, within, and some scope semantics. Most parameters (path, target, targetType, operation, value, content, destination, createTargetIfMissing, allowSubtreeReplacement, rejectIfContentPreexists) get no explanatory help.

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?

It states a verb ('Patch') and resource types (heading/block/property), but 'property' does not match the schema's targetType enum (heading/block/frontmatter), and the phrasing is cryptic. It does not clearly distinguish itself from siblings such as vault_replace_text, vault_append, or vault_write.

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

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

There is no explicit guidance on when to use this tool versus vault_replace_text or vault_write. Only oblique hints exist ('from a read/map', 'No automatic retry') without a clear decision rule.

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 and non-destructive behavior, so the description only needs to add beyond that. "No link graph" is a useful disclosure about what is not returned, and "targeted heading levels are relative" clarifies resolution semantics, but the mention of "version and versionGuard" is confusing since no such parameters exist in the schema, and nothing is said about maxBytes truncation 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?

Very short and front-loaded, which is good, but the phrase "with version and versionGuard" consumes limited space on parameters that don't exist in the schema, creating noise in an otherwise tight definition. The remaining clauses each carry real 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?

An output schema exists, so return-value explanation is rightly absent. However, for a 5-parameter read tool the description does not address maxBytes/truncation, the content-vs-marker scope behavior, or clarify the phantom version parameter, leaving gaps an agent must guess at.

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 only 40%, but the schema itself already documents scope ("Requires a target; defaults to content") and target formats. The description adds the useful note that heading levels are relative and points to vault_get_document_map for building target paths, yet leaves maxBytes and the interaction between target/targetType and scope largely unexplained, and references a version parameter that isn't in the schema.

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

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

States a specific verb and resource ("Read a Vault text file or target") and adds a scope exclusion ("No link graph"). The word "text" implicitly separates it from vault_read_binary, but the contrast is never made explicit.

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

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

Gives an actionable routing hint: "Discover targets via vault_get_document_map," which tells the agent how to obtain the target value this tool requires. It lacks an explicit when-not statement (e.g. when to prefer vault_read_binary or search_query), so it stops short of full alternative coverage.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false. The description adds useful behavior beyond annotations: the 4 MiB limit for bytes mode, the preview-or-link behavior of auto mode, and the PDF exclusion.

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 short, front-loaded, and every sentence carries operational value: supported file type, mode behavior, size limit, and PDF exclusion. There is no wasted text.

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

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

The output schema exists, so return values need not be explained, and annotations cover safety traits. However, with zero schema parameter descriptions, the missing link mode and unexplained path parameter leave the definition only partially complete 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?

With 0% schema description coverage, the description must fully explain the parameters. It describes auto and bytes modes, but omits the link enum value entirely, and it does not explain the required path parameter. This leaves a significant gap in mode selection 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 states a specific verb and resource: read images and non-PDF attachments. It clearly excludes PDFs, but it does not explicitly distinguish this tool from sibling vault_read for text files. The purpose is still clear and actionable.

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

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

The description gives clear context for when to use this tool versus native file handling, especially by stating that PDFs are unsupported in every mode. It also explains the auto and bytes modes, though it does not explicitly route text reads to vault_read.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false; the description adds real context beyond them: the match must be unique and case-sensitive, empty newText deletes the match, and there is no automatic retry on conflict. It does not say what error surfaces when the match is missing or non-unique, which is the remaining gap for a destructive tool.

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

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

Four short sentences, zero filler, with the core operation and its uniqueness constraint front-loaded before the workflow notes. Every sentence adds a distinct fact 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?

An output schema exists so return values need not be described, and the description covers the match semantics, guard parameters, delete-by-empty-newText, and retry behavior. The only meaningful omission is failure-mode detail for a non-unique or absent match on a destructive edit.

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?

With 0% schema description coverage, the description carries the burden and largely succeeds: oldText must be an exact literal from vault_read, newText may be empty to delete, and both ifMatch and ifMatchGuard are explained as version-carrying guards. Only 'path' is left unstated, which is self-evident.

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

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

States a specific verb and resource with the exact matching semantics: 'Replace one unique, case-sensitive literal match in an existing UTF-8 file.' The uniqueness and case-sensitivity constraints implicitly separate it from vault_patch, vault_write and vault_append, so an agent can pick it without opening a schema.

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

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

Gives the required workflow upfront: copy exact oldText from a whole-file vault_read, and carry version into ifMatch or versionGuard into ifMatchGuard. 'No automatic retry' tells the caller it must handle failure. It stops short of naming when to use vault_patch or vault_append instead, so no explicit exclusion is 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 destructiveHint and idempotentHint, but the description adds genuinely new behavioral facts: parent directories are created automatically, binary/NUL content is refused, and there is no automatic retry after a failure, which matters for an agent retry strategy. The overwrite-guard requirement on existing files is also disclosed. It stops short of stating permission/auth requirements or what happens on a failed guard mismatch, keeping it short of a 5.

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?

Extremely front-loaded: capability first, then preconditions, then side effects and failure behavior. Every clause carries information, with no filler. The telegraphic style ('copy versionGuard', 'Binary/NUL refused') trades some readability for density, which keeps it slightly below a perfect score.

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?

Since an output schema exists, return values need not be described, and the annotations carry the safety profile. Given those, the description covers the key gaps an agent needs: parents auto-created, overwrite guard requirement, content-type limits, and no retry. Residual ambiguity about how to obtain versionGuard and about path format is minor but present.

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 0%, so the description must carry the load. It explains the otherwise opaque ifMatch/ifMatchGuard parameters in terms of purpose (required to overwrite existing files) and even hints at the source ('copy versionGuard'), which is real added value. But path and content semantics, and the accepted sha256 format versus 16-hex guard format, are left entirely to the schema's regex patterns.

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 pair and resource: 'Create or replace UTF-8 text', which implicitly separates it from sibling tools like vault_append and vault_patch that modify rather than replace full content. It never names those siblings explicitly, so a reader must infer the boundary from the verbs.

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 precondition 'Existing files require ifMatch or ifMatchGuard' gives clear context for overwrites, which implies when this tool succeeds versus fails. However, there is no explicit guidance on when to choose vault_write over vault_append, vault_patch, or vault_replace_text, so the selection logic is inferred from the description rather than stated.

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