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

Annotations already cover read-only/idempotent/no-destruction, but the description adds real behavioral context: strict properties.type matching (no fuzzy match), key matching against title or aliases, the guarantee that relation is always "wikilink" in v2.0.0, the Phase 4 widening plan, and the notable decision that superseded backlinks are NOT filtered. That last point is exactly the kind of non-obvious behavior 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?

Purpose is front-loaded, which is good, but the prose is dense with internal ticket references (D-03, D-04, GRA-04, CONTEXT D-04) that convey little to an invoking agent, and the embedded output-shape enumeration could be tighter. It is informative but not economically written.

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 appropriately fills that gap by enumerating anchor, linked_documents, and property_rollups fields. Combined with the behavioral caveats (unfiltered superseded backlinks, single edge source), an agent has enough to call and interpret it, though projection/heading_paths interplay is only lightly touched.

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

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

Schema description coverage is 100% and all six optional params carry their own descriptions, so the schema does the heavy lifting. The description restates the type/key semantics and outlines the property_rollups shape but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

The first sentence states a precise verb+resource: resolve {type, key} to an anchor document, walk backlinks, and build a dossier with named output sections. This clearly separates it from siblings like list_backlinks or get_document_bundle, which do not synthesize a structured multi-section dossier.

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 through the resolution/backlink-walking mechanics. It never says when to prefer this over list_backlinks, get_document_bundle, or expand, nor when a dossier is the wrong tool. The strict-match and alias rules hint at input expectations but do not guide tool selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and closed-world, so the safety profile is covered. The description usefully adds that this is specifically the *write* audit trail (create/update/delete events) and gives the default limit of 50, but says nothing about retention, ordering, or how far back the trail goes.

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 short, front-loaded sentences with no filler; the core purpose comes first and the filter/default details follow. Slightly terse for a six-parameter tool but structurally sound.

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 6-parameter, no-output-schema tool, the description covers the main query concept but leaves two parameters (including the required vault and the opaque is_memory_sink_write flag) and the timestamp semantics undocumented. Adequate to attempt a call, but the agent will likely need to guess on those fields.

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 full burden, and it only partially does so: it maps note_path, op, and time (since), and states the limit default. The required 'vault' parameter and 'is_memory_sink_write' are never mentioned, and 'since' is left ambiguous (epoch seconds vs ms) despite the numeric format.

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 ('Query') and resource ('write audit trail for a vault'), and the filter dimensions (note path, operation type, time) make the scope concrete. It does not, however, distinguish itself from lookalike siblings such as index_runs or recent_notes, so the agent must infer which log this reads.

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?

No when-to-use guidance, no alternatives named, and no exclusions. The mention of what it can be filtered by is a capability statement, not routing guidance, so the agent gets no signal on why it would pick this over recent_notes or index_runs.

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

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

Goes well beyond the readOnly/idempotent annotations by disclosing deterministic byte-identical assignment, the seeded RNG tag, cluster_id derivation, the 5000-node hard cap, exact error reasons, and that summaries are pure computations with no LLM enrichment.

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?

Dense but front-loaded, with the algorithm and determinism guarantees stated first and the path rules following. The parenthetical citation and library/plan references add minor noise but each sentence conveys operative detail.

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

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

For a complex tool with 6 params, 0% schema coverage, and no output schema, it fully describes the return shape ({cluster_id, size, members[], summary}) and all routing constraints. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 0%, so the description carries the burden; it explains the query/seed_doc_ids exclusivity, vault requirement, and force override. It does not explain query_top_k's role or the method const, leaving those only visible 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 operation (community detection over the typed-edge graph) with the exact algorithm (Louvain modularity) and libraries used. It distinguishes itself from siblings by naming search_hybrid and expand as components of its own query path rather than alternatives.

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

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

Explicitly defines the two mutually exclusive input paths (query vs seed_doc_ids), states that passing both returns an error, and specifies that vault is required on the query path when multiple vaults exist. It also states the force override condition for the 5000-node cap.

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, and the description earns credit by explaining the destruction: on target collision it auto-supersedes the prior brief via the D-12 supersede chain. It also discloses the wikilink footer enforcement and DeliveryAdapter write path. Missing only return/error shape nuance.

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

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

The core purpose is front-loaded in the first clause, which is good, but the paragraph is dense with opaque internal references (D-10, D-11, D-12, 'Phase 2 supersede chain') that consume space an external agent cannot decode. Every sentence is doing work, but the jargon lowers scannability.

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 7-parameter mutation tool with no output schema, the description covers the write target, the fallback ladder, link-footer enforcement, and collision semantics. It stops short of describing the return value or structured-error shape, but the behavioral picture is largely 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, but the description adds real meaning beyond the schema by situating prepared_text as the D-10 tier-3 fallback and max_tokens as a ladder hint, which clarifies how these two parameters interact at runtime.

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 ('Compile a brief from caller-supplied source documents') and names the sink destination. An agent can distinguish this from get_brief (retrieve) or assemble_dossier (compose a multi-bundle dossier) without opening either schema.

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

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

There is rich context about the internal LLM resolution ladder and collision handling, but no explicit statement of when to choose this over get_brief, assemble_dossier, or write_note. Usage is implied by the mechanics rather than routed against alternatives.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and non-idempotency. The description adds behavior beyond that: the write_enabled gate and the mandatory expected_hash concurrency guard, which tells the agent this is a guarded, non-blind delete. It could still say what happens on hash mismatch, but the added context is substantive.

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 sentences, action stated first, preconditions immediately after. No filler and nothing buried.

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 tool with no output schema, the key facts an agent needs — the write gate and the required hash — are present. Missing details are secondary: failure behavior on hash mismatch and confirmation that deletion is irreversible.

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 four parameters, so the description must carry the load. It explains why expected_hash exists (prevents blind deletes) but never defines vault, path, or client_id, and even references write_enabled, which is not a parameter in the schema at all. Compensation is only 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?

States a specific verb and resource ('Delete a note'), which is unambiguous and clearly distinct from siblings like write_note or update_frontmatter. It does not explicitly name a sibling alternative, so it falls short of the top tier.

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 preconditions for use: write_enabled=true and expected_hash required, with the constraint 'no blind deletes'. That is clear context and effectively an exclusion (you cannot delete without knowing the current hash), though it does not route the agent to any alternative tool.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuinely new behavior: it will not execute the contract, and it returns {ok:false, reason:'ambiguous_vault'} on ambiguous vaults, plus the exact contents of the generated summary.

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 the primary behavior, then packs the summary contents and vault rules into tight clauses. Dense with parentheticals but nearly every clause carries actionable information; no 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 description compensates by enumerating the return structure (Inputs/Sources/Sinks/Assembly/write_back/Output Shape) and the error shape. Combined with the annotations, 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%, so baseline is 3. The description goes beyond the schema's 'omit on single-vault setups' by defining the multi-vault requirement and the precise error result, adding real semantic value for the vault 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 ('Return the input JSON Schema + an auto-generated markdown summary for a contract') and immediately scopes it as a pure, non-executing function. This cleanly distinguishes it from execution-oriented siblings like instantiate_contract.

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

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

Gives explicit conditional usage for the vault parameter (omit on single-vault, pass on multi-vault) and describes the failure mode otherwise. It implies when to use this versus executing a contract ('does not execute'), but never names a sibling alternative outright, so it stops short of a 5.

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 safety (readOnly/idempotent/non-destructive), and the description goes well beyond: hard hop cap, default direction, dedup rule with tie-breaking, the memory-namespace opacity rule (ADR-004), supersede default behavior, and the non-throwing unknown-seed warning contract. This is rich, non-obvious behavioral 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?

Front-loaded with purpose, but the description is a dense wall of clauses and parenthetical rule IDs (ADR-004, Phase 2 D-03) that padding readability. Most sentences earn their place, but the packing is heavy for a single paragraph.

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?

Very complete for a complex graph-expansion tool with nested filter_properties and 7 params: hop cap, direction, dedup, supersede, warnings, and namespace rules are all covered. Lacking an output schema, the description still describes the packet shape, so only minor gaps remain.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema: it clarifies filter semantics ('strict equality, no operators'), explains when memory-sink docs are surfaced, and documents the default-false supersede rule and the unknown-seed warning handling.

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

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

States the specific retrieval algorithm (typed-edge BFS) and the exact resource (typed-edge neighborhood of seed documents), and describes the return shape (flat array of citation packets with via provenance). An agent can immediately distinguish this from siblings like list_backlinks, list_forward_links, or recall.

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

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

Implicitly this is the graph-expansion tool vs the search_* tools, but the description never names an alternative or states when to prefer expand over list_backlinks/list_forward_links/fetch. Usage is inferable from the algorithm name but not explicitly guided.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds that it is an 'OB1-compatible fetch adapter' backed by read_note, which hints at delegation, but says nothing about id validity, failure modes, or whether it re-indexes. Adequate but not rich.

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 short, front-loaded sentences with no filler: identity, input-to-output mapping, backing implementation. Tight and readable.

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 compensates by enumerating the returned fields, and the only parameter's meaning is explained. What remains missing is error behavior and relationship to sibling resolvers, a minor gap for a single-parameter adapter.

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 0% and the single param has no schema description, so the description must carry the burden. It does so well by defining the parameter as an 'opaque id (from `search`)', telling the agent both the type of value expected and its provenance.

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 ('Resolves') and resource ('opaque id') and gives the exact return shape {id, title, text, url, metadata}. 'Backed by read_note' and 'id (from search)' partially differentiate it from the many sibling retrieval tools, though the distinction is implied rather than spelled out.

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 phrase 'from `search`' implies this tool is used to resolve ids produced by search, which is useful routing context. However, there is no explicit when-to-use/when-not statement and no guidance on choosing fetch over read_note, expand, or get_document_bundle.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful context by defining what a 'broken' link is (a wikilink whose target note does not exist), but says nothing about output shape or scale.

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 with no waste, front-loading the verb and the resource scope.

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 simple read-only list tool with one parameter and no output schema, the definition is functional but thin: it omits any explanation of the vault parameter and gives no hint about what the returned broken-link list contains.

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

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

There is a single required parameter (vault) at 0% schema description coverage, and the description never explains it. It is presumably the vault to scan, but the description should have compensated for the schema's silence and does not.

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

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

States a specific verb (List) and a precisely scoped resource (wikilinks pointing to non-existent notes). This distinguishes it from related siblings like list_backlinks and list_forward_links by its filter on brokenness, though it doesn't explicitly name those alternatives.

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

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

Provides no when-to-use or when-not-to-use guidance. An agent must infer that this is a diagnostic tool distinct from list_backlinks/list_forward_links; nothing in the text tells it when to prefer this tool.

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

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

Annotations already cover the safe-read profile (readOnly, idempotent, non-destructive), yet the description adds real behavioral value: the null contract under stale/too_old plus !allow_stale, and the supersede-chain resolution. The 'D-13 decision tree' reference is internal jargon the agent cannot resolve, which caps this 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?

Three sentences, front-loaded with the core verb+resource, then the decision rule and the null contract. Dense and mostly waste-free, though the unexplained 'D-13 decision tree' label costs a little clarity.

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

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

For a retrieval tool with no output schema, the description covers the null contract and chain-following, which are the essential behaviors. It leaves gaps on what a brief actually contains and how the supersede chain is traversed, and leans on an unexplained internal decision-tree reference.

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 goes further by explaining how allow_stale and max_age_days interact with staleness to produce null versus an annotated brief. That interaction is not spelled out in the schema and is the key calling decision.

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 ('Look up a brief by target slug') and adds scope detail (supersede chain to the terminal brief) that separates it from a plain note fetch. It does not name its closest sibling (compile_brief) explicitly, so the differentiation is implied rather than stated.

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 null-return clause tells the agent when this tool will not yield a brief and that the caller must recompile, which is an actionable routing cue. It stops short of naming the alternative tool (compile_brief) or stating exclusions, so it is clear context rather than explicit alternatives.

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

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

Annotations already cover read-only/idempotent/non-destructive, and the description still adds substantial behavioral detail: the unknown-doc_id error shape, that broken links are omitted, that recent_edits is capped at 10 and keyed by the CURRENT anchor path (pre-rename history hidden), and that depth is zod-pinned for forward compatibility. This is context 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?

Purpose is front-loaded and the bundle shape is given before the caveats, so an agent can skim the first sentence for routing. It is dense but earns most of its length; minor redundancy appears in the repeated depth:1/'same shape' statements.

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 substitutes by specifying the exact return structure, field shapes, error contract, and known limitations. For an 8-parameter tool this is sufficiently 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?

Schema description coverage is 88%, so the schema already documents params thoroughly. The description largely restates schema content (depth:1, max_chars budget) rather than adding new meaning; the only incremental semantics are the depth-literal versioning caveat and the ≤10 recent_edits bound, which is modest additive value at this coverage level.

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

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

States a specific verb+resource ('Document-tree retrieval', returns a bundle for a single document) and then enumerates the exact bundle components (anchor, outline, backlinks, forward_links, recent_edits). It also distinguishes itself from siblings by noting the outline 'same shape as get_outline.root' and that it consolidates what list_backlinks/list_forward_links/audit_log expose separately.

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 rather than stated: the enumeration of collected artifacts signals that this tool replaces several narrow sibling calls for one document. However, there is no explicit 'use this instead of X when Y' guidance, and no when-not conditions beyond the depth:1 versioning 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 already cover safety (readOnly, idempotent, non-destructive, closed-world), so the description's added value is behavioral detail it does supply: the exact failure mode 'Unknown doc_id returns {error:'doc_not_found', doc_id}'. It doesn't cover pagination or ordering of the tree, so it's not 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?

Three sentences, front-loaded with the core purpose, then return fields, then the error case — every sentence earns its place. The field enumeration is dense but justified since there is no output schema.

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

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

With no output schema, the description carries the return-shape burden and does so: it lists every OutlineNode field and their citation-role. Combined with annotations covering the safety profile and an explicit error contract, 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 both `doc_id` and the optional `vaults` filter are already documented in the schema, and the description adds no parameter-level syntax or format guidance (e.g., when the vault filter matters). The mention of `chunk_ids` describes return data, not inputs, so the baseline 3 applies.

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: 'Return the navigable section tree for a document,' which is distinguishable from siblings like search_sections, get_document_bundle, or read_note. It does not explicitly name an alternative or contrast with them, so it stops short of a 5.

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 rather than stated: 'Consume `anchor` + `heading_path` as the section-level half of the citation packet' hints at a downstream citation workflow, but there is no explicit when-to-use, when-not-to-use, or named alternative among the many search/bundle siblings.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered structurally. The description adds value by disclosing the payload contents (scan scope, timestamps, duration, errors), but says nothing about result volume, ordering, or that the list is capped.

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 front-loaded sentence that names the action first and then the returned fields. No filler words; every clause carries information.

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

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

No output schema exists, and the description usefully previews the returned fields, which is the right move. However, for a tool with two undocumented parameters and no guidance on result limits or ordering, an agent still lacks enough to invoke it confidently beyond the simplest call.

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 parameter burden. It implies vault scoping via 'for a vault' but never explains the 'limit' parameter (default 20, max 200) or what the vault string should be, leaving both partially or wholly 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?

States a specific verb and resource ('List recent index runs') with the scope qualifier 'for a vault', and enumerates the content returned (what was scanned, when, duration, errors). It does not compare itself against siblings like audit_log or vault_stats, which is the only thing keeping it from a 5.

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?

No indication of when to reach for this tool versus audit_log, vault_stats, or start_shadow_index, and no stated prerequisites. Usage is only implied by the semantics of listing index runs.

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 cover safety flags (readOnly=false, openWorld=true, idempotent=false, destructive=false); the description adds substantial non-obvious behavior: Zod validation against the contract schema, the D-A4b override resolution chain, MemorySink-only sinks enforced by the MEM-05 invariant, write_back routed through DeliveryAdapter.write(), and a structured InstantiateError envelope with 12 sealed reasons.

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

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

The core action is front-loaded in the first sentence, but the rest is one dense run-on paragraph laden with internal references (D-A4b, D-A4c, MEM-05, ADR-006 §Decision 7) that an agent without domain context must parse. Much of it earns its place, but the jargon and length dilute scannability.

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

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

No output schema exists, and the description compensates by describing the return bundle {steps, write_back} and the failure envelope. It also covers the vault ambiguity error, though it does not enumerate the 12 InstantiateError reasons, leaving a small gap for a complex mutation 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 schema already documents all five parameters — baseline 3. The description adds only marginal value beyond the schema (typo rejection via additionalProperties:false, sink override constraints, and the vault ambiguity rule, the latter of which is arguably behavioral 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?

Opens with a specific verb+resource: 'Execute a registered contract end-to-end.' An agent can distinguish this from describe_contract and register_contracts_as_tools without opening schemas, since this is the execution/run tool rather than a metadata or registration 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?

Gives one concrete usage rule (omit `vault` on single-vault setups; required otherwise, returns `ambiguous_vault`), which is real guidance. But it never states when to use this tool versus siblings like describe_contract or compile_brief, so the run-vs-inspect choice is only implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuine value the annotations cannot: deprecation status, the callable window, and the scheduled removal version. It does not describe the return shape, but for a deprecated read tool that gap is minor.

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 sentences, zero filler, and the core purpose is front-loaded ahead of the deprecation notice. Every sentence earns its place.

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

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

For a small deprecated read tool with annotations covering safety and no output schema, the description is serviceable. The notable gap is that the two required parameters remain unexplained anywhere, leaving an agent to guess at vault/path 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 coverage is 0% for two required parameters (vault, path), so the description must carry the burden and does not: 'a given note' never clarifies which parameter identifies the note, nor what vault/path formats are expected (relative path? absolute? docId?). Nothing here helps an agent fill the required fields.

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

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

States a specific verb and resource with directional scope made explicit ('notes that link TO a given note'), which cleanly separates it from the sibling list_forward_links. An agent can select it without opening the schema.

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

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

Explicitly routes the agent away from the tool: 'DEPRECATED since v2.0.0 — prefer MCP Resource vault-memory://backlinks/{vault}/{+docId}', and gives the lifecycle window (callable through v2.x, removal in v3.0.0). This is exactly the when/when-not/alternative guidance the dimension asks for.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that it lists forward links and can optionally include broken links, which is useful context, but it doesn't disclose return format, pagination, or any behavioral nuances beyond what annotations and schema imply.

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 sentences with no waste, front-loading the core action and then the optional parameter. Perfectly sized for a simple list 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?

For a simple read-only list tool with no output schema, the description covers the basic purpose and option. However, it lacks details about the return format (e.g., what a wikilink looks like) and does not compensate for the complete absence of parameter descriptions in the schema, leaving some ambiguity for an agent.

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

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

Schema description coverage is 0%, so the description must compensate. It implies that 'path' and 'vault' identify the note and vault, and that 'include_broken' toggles broken links, covering all parameters at a high level. However, it doesn't clarify the distinction between vault and path, nor does it note the default value (true) for include_broken, leaving gaps.

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 ('List') and resource ('wikilinks FROM a given note'), clearly distinguishing it from backlink tools by direction. However, it does not explicitly name sibling tools or contrast alternatives, so it falls short of a 5.

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 by the phrase 'FROM a given note' and the optional broken links, but there is no explicit guidance on when to use this tool versus alternatives like list_backlinks or find_broken_links. The description provides context but not decision criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint false, and openWorldHint false. The description adds meaningful context beyond annotations: the returned fields (dim, active, embedded chunk counts) and the deprecation lifecycle through v2.x with removal in v3.0.0. It does not cover edge cases such as an unknown vault, but the added lifecycle and output detail are substantial.

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

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

The description is front-loaded with the tool's purpose and return fields, followed by usage guidance and deprecation details. Every sentence earns its place; there is no filler or repetition.

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 simple read-only list tool with no output schema, the description usefully summarizes return fields and clearly communicates deprecation and an alternative resource. The main remaining gap is the undocumented vault parameter, but overall the definition is largely 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 description coverage is 0%, and the only parameter (vault) is not explained in the schema. The description says the models are registered 'for a vault' but does not specify the expected vault identifier format or behavior for an invalid/missing vault, so it fails to compensate for the schema gap.

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

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

The description states a specific verb and resource: listing embedding models registered for a vault, including the fields dim, active flag, and embedded chunk counts. It also names related sibling tools (start_shadow_index, switch_active_model), making it easy to distinguish from other list/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?

It explicitly says to use the tool before start_shadow_index / switch_active_model, and it clearly states that the tool is deprecated in favor of the MCP Resource vault-memory://models/{vault} for agent discovery. This gives both when-to-use and when-to-prefer-an-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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description adds the deprecation lifecycle and migration path, which is genuinely useful non-schema context. It stops short of describing pagination or exact status shape, so not 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?

Two sentences, zero waste; the concrete capability is front-loaded and the deprecation notice follows. Every clause earns its place.

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

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

For a zero-parameter read tool with an empty schema and no output schema, the description supplies the returned fields, the safety-relevant status, and the deprecation replacement. 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?

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify beyond noting there are no inputs.

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

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

States a specific verb (List) and resource (configured vaults) and enumerates the returned status fields (note count, last indexed run). An agent can distinguish it from siblings like vault_stats or index_runs 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?

Explicitly states when NOT to use it – prefer the MCP Resource `vault-memory://vaults` for agent discovery – and gives the lifecycle window (callable through v2.x, removed in v3.0.0). This is precise when/when-not/alternative routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds the AND-combination behavior of multiple keys, which is genuinely useful, but says nothing about limits, result ordering, or behavior on unknown keys.

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, each earning its place: purpose first, then predicate support, then combination semantics. Nothing 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?

For a nested-object query tool with no output schema and 0% schema coverage, the description covers the core filtering semantics but omits anything about the shape of results, how `limit` behaves, or what an empty/malformed `where` does. It is minimally sufficient rather than 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 description coverage is 0%, so the description must carry parameter meaning. It does explain the predicate operators ($in, $exists, $contains) and equality, plus the AND semantics of the complex `where` object, which is the hardest parameter. However, `vault` and `limit` (with its default and cap) receive no explanation at all.

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: 'Filter notes by their YAML frontmatter'. It is distinguishable from the search_* siblings in concept, but it never explicitly contrasts itself with search_text/search_semantic, so the division of labor is left implicit.

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 when-to-use guidance and no mention of alternatives, despite several plausible substitutes (search_text, search_semantic, search_hybrid, list_vaults) in the sibling set. The agent must infer that frontmatter-based filtering is the right choice.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful return-content context ('full content + frontmatter'), but does not describe error behavior, pagination, or what happens with missing notes.

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 front-loaded sentence with no wasted words. It states the action, returned data, and input format directly.

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 simple two-parameter read tool, the description states what is returned and the path semantics, and annotations cover safety. However, the vault parameter remains undefined in both schema and description, and there is no output schema to clarify return shape.

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 clarifies that path is vault-relative, but says nothing about the required vault parameter. One of two parameters is explained, leaving a significant gap.

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 the full content plus frontmatter of a note. It clearly identifies the input as a vault-relative path. It does not, however, distinguish itself from sibling read/search tools such as fetch or search_text.

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?

No explicit guidance on when to use this tool versus alternatives like fetch, get_brief, recall, or the search_* tools. The vault-relative path requirement implies usage, but alternatives and exclusions are absent.

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 safe read-only, idempotent, non-destructive behavior. The description adds useful behavioral context beyond annotations: it names the exact citation-packet fields returned, states that results are ranked by observed_at DESC, and notes that superseded documents are hidden by default.

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 tightly structured and front-loaded: the retrieval purpose comes first, followed by the return shape and default behavior. Every sentence adds useful information, and the parenthetical parameter grouping and field list are efficient rather than wasteful.

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

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

For a 9-parameter retrieval tool with no output schema, the description does important work by documenting the return packet shape and superseded-document default. It remains incomplete around as_of semantics and explicit sibling routing, but the core invocation and return context are adequately covered.

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 78%, so the schema does most of the parameter documentation. The description reinforces the provenance-filtering parameters min_confidence, types, and max_age_days, but it does not add meaningful semantics for sink, vaults, as_of, or include_superseded beyond what the schema already provides.

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

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

The description gives a specific verb and resource: retrieve memory documents from labeled MemorySinks. It also clarifies the retrieval mode through provenance filtering and recency ranking, but it does not explicitly distinguish this tool from sibling search tools such as search_hybrid or search_semantic.

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 explains what recall does, including filters and default hiding of superseded documents, but it gives no explicit when-to-use guidance or guidance on when another sibling tool should be preferred. It lacks the kind of routing advice that would help an agent choose between recall, search_hybrid, or search_semantic.

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), so the description only needs to add context. It does: SQL-backed rather than vector retrieval, ordered by mtime, and the full deprecation lifecycle (callable through v2.x, removal in v3.0.0). It does not mention result limit behavior or return shape, 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?

Four short sentences, front-loaded with the core purpose and routing/deprecation guidance, with the deprecation note placed before the removal schedule. Minimal waste, though 'No vector search, just SQL' is slightly peripheral.

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?

Deprecation and migration path are thoroughly covered, which is the most important context here. However, with no output schema and 0% parameter coverage, the ambiguity around 'since' and 'vault' semantics leaves an agent unable to call the tool precisely without experimentation.

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 all 3 parameters, so the description carries the full burden and it does not compensate. 'since' is undocumented (timestamp? seconds vs milliseconds? inclusive?) and 'vault' scope is never explained; only the mtime DESC hint loosely gestures at the ordering. Most of the parameter meaning is left to guesswork.

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

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

States a specific verb and resource ('List recently modified notes') plus the ordering (mtime DESC), and explicitly disclaims a sibling capability ('No vector search, just SQL'), which separates it from search_semantic/search_hybrid. An agent can identify what this returns without opening the schema.

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

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

Gives the exact motivating question ('what has the user been working on lately?') and names the preferred alternative (the vault-memory://recent/{vault} resource) along with the deprecation timeline. When-to-use and when-to-prefer-something-else 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 already declare this is a non-read-only, non-idempotent, non-destructive write. The description goes beyond that by disclosing that provenance fields are auto-filled from arguments, that `properties` overrides sugar defaults under a caller-last merge (D-02), and that the write routes through DeliveryAdapter.write() and a centralized provenance validator. That is genuine behavioral context an agent cannot get from the annotations, though the internal component names add little for invocation.

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 sentences, front-loaded with purpose, then mechanics, then the override rule. The 'D-02' ticket reference and 'DeliveryAdapter.write()' class name are internal jargon that does not help an agent decide or invoke, but the text is otherwise tight and waste-free.

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 seven-parameter mutation tool with no output schema, the definition covers the write path and provenance handling but omits what a successful call returns (a handle? an id?) and says nothing about failure modes such as contract or validator rejection. Annotations cover the safety profile, so the gap is moderate rather than severe.

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 all seven parameters are already documented in the schema, which sets the baseline at 3. The description's note on the `properties` escape hatch and merge order largely restates the schema's own wording, adding no new per-parameter syntax or format guidance.

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

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

States a specific verb and resource: recording a new memory observation under a labeled MemorySink for a vault. It is distinguishable from read-oriented siblings like recall or search, but it never differentiates itself from the other write-side tools (write_note, supersede, update_frontmatter), so an agent must still guess which mutation path applies.

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 explains mechanics but never states when to use this tool versus siblings such as write_note or supersede, nor any preconditions (e.g. that the vault must be registered, or that provenance fields are derived rather than supplied). Usage must be inferred entirely from the name and the required-parameter 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?

Annotations declare the safety profile (not read-only, open-world, not idempotent, not destructive), and the description adds real context beyond that: it mutates the dynamic tool list, bypasses a config gate, and returns a per-vault diff. It does not explain reversibility or what happens to existing dynamically registered tools that are still valid, which would have rounded it out.

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 tool's role and effect, and the return value and scoping rule follow in order. It is dense and mostly earns its sentences, though identifiers like '(D-A1)' and the config-key bracket are noise for an agent selecting a 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 compensates by specifying the return shape (per-vault diff of {registered, unregistered}). Combined with the scope rule and the config-gate bypass, an agent has everything needed to call 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?

Only one parameter and schema description coverage is 100%, so the schema already documents `vault`. The description restates the omission semantics ('omit vault to apply to every configured vault'), which duplicates the schema's own description rather than adding new meaning. Baseline 3 applies.

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 specific verbs and resources: scans the per-vault contract registry and updates the dynamic MCP tool list, naming both effects (registers new contracts as vm_<name>, unregisters removed). This clearly distinguishes it from siblings like describe_contract and instantiate_contract, which operate on individual contracts rather than the tool registry.

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 when this is needed (the explicit-control escape valve that works regardless of the [contracts.auto_register_tools] gate, and is always callable) and the vault-scoping option. It does not name an alternative tool or state when *not* to call it, so it stops just short of a full when/when-not guide.

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?

With annotations already covering read-only, idempotent, and non-destructive behavior, the description adds valuable context beyond them: the exact return shape (flat list of fields) and the underlying hybrid search backend (semantic+BM25+RRF). It doesn't cover auth needs or rate limits, but those are less critical given the annotations.

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

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

The description is four compact sentences with no filler. It front-loads the tool's identity and return format, then adds backend and alternative details. The opening 'OB1-compatible' is somewhat jargon-heavy, but overall it is efficient.

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 search tool with no output schema, the description usefully documents the return fields and backend. However, it omits any parameter guidance and fails to distinguish this generic search from many sibling search tools beyond search_hybrid, leaving an agent with incomplete routing information.

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

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

Schema description coverage is 0% for the two parameters (query, limit). The description does not mention either parameter or their semantics, so it fails to compensate for the lack of schema-level documentation. The agent must infer from parameter names alone.

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

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

The description identifies the tool as an OB1-compatible search adapter that returns a flat list of {id, title, url, snippet} for connector ecosystems. It distinguishes itself from search_hybrid by output richness, but does not explain how it differs from other search siblings like search_semantic or search_text.

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 a clear usage context ('for connector ecosystems') and explicitly names the alternative for richer output ('use search_hybrid'). However, it provides no when-not guidance or distinction from other search tools in the sibling 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real behavioral detail: RRF fusion, that expansions preserve ranking and run after recency/authority rescore. However, it leaves the behavior of ~11 tuning knobs (rerank, recency_weight, authority_weight, half_life_days, include_superseded, frontmatter filters) undisclosed.

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 dense, front-loaded sentences with zero filler: mechanism first, positioning second, the one parameter worth elaborating last. Every clause earns its place.

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

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

With 13 parameters, a nested `expand` object, 0% schema description coverage, and no output schema, the description is far too thin to let an agent configure the tool confidently. It documents the optional expansion path well but omits any hint about scoring, filtering, or supersession parameters that materially change results.

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

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

Schema description coverage is 0% across 13 parameters, so the description must carry the parameter burden and it only explains one: `expand` (hops 1–2, expansions[] per hit, ordering). The other twelve parameters — rrf_k, top_k, rerank, half_life_days, recency_weight, authority_weight, frontmatter_boosts/filter, include_superseded, vaults, exclude_paths — get no semantic explanation at all.

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 ('Hybrid search') and names the exact mechanism (semantic/embedding + BM25 fused via RRF), which immediately distinguishes it from the sibling search_semantic and search_text tools. The claim 'Best general-purpose query' further positions it relative to alternatives.

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

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

'Best general-purpose query' gives clear positive guidance on when to reach for this tool over the specialized siblings. It lacks an explicit when-not or a named alternative for narrow cases (e.g. when to use search_text instead), so it stops short of full routing 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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial behavior: the inflated top_k, chunk-to-section promotion, MAX scoring, tie-break rule, dedupe key, and the 8-field citation packet. Much of the algorithm detail is more implementation than behavioral guidance, but the output shape and scoring semantics are genuinely useful.

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, but the bulk is a single dense sentence enumerating pipeline internals (RRF, promotion, dedupe keys, tie-break) that an agent rarely needs to invoke the tool. Sizeable trimming would lose little.

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

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

For an 11-parameter tool with no output schema and low schema description coverage, the description does cover the return shape (citation packet) but leaves most parameters undocumented. It is adequate for a knowledgeable caller but incomplete given the complexity.

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 36%, so the description must carry the load, but it only clarifies `limit` (via the top_k = limit × 5 note) and lightly touches scoring. It never explains max_chars, projection, heading_paths, recency_weight, authority_weight, include_superseded, include_observations, as_of, or vaults.

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 ("Section-level retrieval") and explains the retrieval pipeline plus its distinguishing scope (whole-section context). It contrasts implicitly with chunk-window tools rather than naming a sibling like search_hybrid, so differentiation is strong but not fully 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?

"Use when you want WHOLE-SECTION context, not a chunk window" gives a clear selection condition against chunk-based retrieval. It stops short of naming the alternative tools (search_hybrid / search_semantic) or stating when NOT to use this one.

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 covered. The description adds the useful scoping default ('searches all vaults by default'), but says nothing about ranking, limits, or performance characteristics.

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, front-loaded sentences with no filler. Efficient, though minimal content means it is not doing much work.

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 and no parameter documentation; for a 4-parameter search tool with rich siblings, the definition leaves too much unspecified about scoping, ranking, and result limits.

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 all four parameters. The description only hints at the vaults parameter's default behavior ('all vaults by default') and says nothing about query, top_k, or exclude_paths, leaving the agent to infer semantics from names alone.

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

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

The description names a specific verb+resource (semantic search) and explains the mechanism (embedding cosine similarity), which distinguishes it from the sibling search_text and search_hybrid tools. It is clear, though it doesn't explicitly name 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?

It gives no when-to-use or when-not guidance relative to search_text, search_hybrid, or recall. The only contextual cue is the implicit 'semantic' framing, which the agent must infer.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds only implementation flavor (BM25 via FTS5); it says nothing about result ordering, scoring, or behavior with empty/no matches beyond 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?

Two short sentences, no waste, with the core purpose and the differentiator front-loaded. Nothing could be trimmed without losing signal.

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

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

For a four-parameter search tool with no output schema and zero schema descriptions, the two-sentence description leaves top_k, vaults, and exclude_paths entirely unexplained. An agent cannot know how to scope the search or how many results it will get.

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% and the description explains none of the four parameters. 'Query' is inferable from 'full-text search', but top_k, vaults, and exclude_paths are completely undocumented in both the schema and the description, so the tool fails to compensate for the coverage gap.

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 (full-text search) plus the underlying mechanism (SQLite FTS5), and 'exact-word and phrase matches' implicitly distinguishes it from the semantic/hybrid siblings. It stops short of naming those alternatives outright, so sibling differentiation is only implied.

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?

'Best for exact-word and phrase matches' gives a usage signal that helps an agent pick between this and search_semantic/search_hybrid. However, it never names those alternatives or states when NOT to use it, leaving the routing decision 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?

The description explicitly claims 'Idempotent (resumable)', but the annotations declare idempotentHint=false — a direct contradiction on the same behavioral property, which could cause an agent to assume repeated invocations are no-ops. Although the description valuably notes the active model is untouched and search stays live, the explicit conflict with structured metadata forces a 1.

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 short sentences, each carrying a distinct fact (what it does, safety during run, resumability, next step). The core action is front-loaded and there is no filler.

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

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

For a three-parameter mutation tool with no output schema and 0% schema description coverage, the description omits all parameter semantics and does not describe progress reporting or error behavior. It covers the operational narrative well but leaves too much undocumented for an agent to invoke it reliably.

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 all three parameters (vault, model, batch_size). The description only indirectly implies what 'model' means (the shadow model) and says nothing about vault scoping or batch_size limits, so it fails to compensate for the documentation gap.

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 — backfilling embeddings for a secondary/shadow model across every chunk in the vault — and explicitly differentiates the shadow model from the active one. An agent can immediately tell this apart from sibling tools like switch_active_model or vacuum_embeddings.

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 sequencing guidance: run this, then run switch_active_model once complete to promote the shadow. It also clarifies the run is safe to do concurrently with search. It stops short of stating when NOT to use it or what to do on failure, so it is strong but not exhaustive.

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 safety profile is covered. The description adds genuine behavioral context beyond that: the return shape ({existing, suggestions, conflicts}), confidence-DESC sorting, and the meaning of the conflicts list.

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

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

Front-loaded with the purpose, then modes, then return contract. Dense and every sentence adds information, though the parenthetical clauses make it slightly packed versus a fully scannable form.

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

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

With no output schema and no schema descriptions, the description supplies the return shape and the input-mode contract, which is most of what an agent needs. The undocumented required 'vault' parameter is the remaining hole.

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, and it does for path, content, folder_hint, and title by grouping them into named input modes. The 'vault' parameter (the only required one) is never explained, leaving one gap.

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 ('Suggest frontmatter fields for a note') and enumerates the three evidence sources (folder-conventions, wikilink-neighborhood, content heuristics), which cleanly separates it from query_frontmatter and update_frontmatter.

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 concrete selection criteria between two input modes (existing note via {path} vs. draft via {content, folder_hint, title}) plus the 'at least one of path/content required' rule. It does not, however, say when to prefer this over siblings like query_frontmatter or update_frontmatter.

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, it discloses important behavior: the replacement document is not touched, back-links are derived at query time, and the operation is an atomic single OCC update on the old document that sets status, superseded_by, and superseded_reason. This is rich operational context for a destructive update.

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 dense and front-loaded, with no wasted sentences. It immediately names the operation and follows with the most important constraints and effects.

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

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

For a three-parameter destructive mutation with full schema coverage and safety annotations, the description supplies the necessary behavioral context: forward-only semantics, OCC atomicity, and the fields updated on the old document.

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 all three parameters are already documented. The description adds only a light mapping by noting that the operation writes superseded_by and superseded_reason, but it does not add syntax or format details beyond the schema.

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

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

The description states a specific verb and resource: "Mark an existing memory document as superseded by a replacement document." It is clear what the tool does, but it does not explicitly distinguish itself from similar document-mutation siblings such as update_frontmatter or delete_note.

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

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

The description implies the usage context (retiring an old document in favor of a replacement) and clarifies the forward-only direction, but it offers no explicit when-to-use guidance or alternatives to sibling tools.

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

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

Annotations already declare it is a write (readOnlyHint=false), non-idempotent, and non-destructive, so the safety profile is covered. The description adds real value beyond that: it discloses atomicity and the exact failure contract (ok:false / reason:'incomplete' when a chunk lacks a shadow embedding). It omits what happens to the previously active model and whether auth is needed.

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 tight sentences, zero waste, with the core action front-loaded and the failure semantics immediately after. Every clause earns its place.

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

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

For a mutation tool with no output schema and 0% parameter coverage, the description covers the success effect and failure mode reasonably but leaves the vault parameter and the post-switch state of the prior active model undocumented.

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 burden. It clarifies that model_name must be a *registered* model with shadow embeddings, but says nothing about 'vault' and adds no format, naming, or value detail for either 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 ('promote a registered model to active') with the added qualifier 'atomically', so the effect is unambiguous. It does not explicitly differentiate itself from siblings like list_models or start_shadow_index, but the action is distinct enough to select on.

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 mention of a required 'shadow embedding for the target model' hints at a precondition (shadow index must exist) but never states when to call this versus alternatives or what state must hold. No explicit when/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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the body is preserved byte-exact, scoping the blast radius to frontmatter, and it documents the merge DSL operations. It does not mention idempotency (annotation says false) or required permissions.

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 tightly packed sentences: purpose front-loaded, then the DSL reference. Every clause earns its place with zero filler, and the higher-value scoping statement precedes the operator table.

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

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

For a destructive mutation with a nested merge object and no output schema, the description covers the core (what changes, what is preserved, merge semantics). However, it omits expected_hash concurrency behavior, the client_id/vault roles, and any note about the return, 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 description coverage is 0% across 5 parameters, so the description must compensate. It thoroughly documents the 'merge' parameter's DSL value semantics (scalar=set, $unset, $push, $pull), which is the most complex nested field, but leaves path, vault, client_id, and expected_hash entirely 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?

States a specific verb and resource ('Modify a note's frontmatter only') plus a scope constraint that separates it from write_note, which would rewrite body and frontmatter. It does not name the sibling tools it is distinct from, but the 'frontmatter only' framing makes the purpose 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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named (e.g. write_note, suggest_frontmatter). The 'frontmatter only' phrase is the sole implicit signal that this is for partial edits, matching the no-guidance severity seen in comparable update tools.

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

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

The description asserts the operation is 'Safe and idempotent,' but the annotations declare idempotentHint=false and destructiveHint=true. The idempotency claim directly contradicts the structured metadata, and calling a row-deleting operation 'safe' undercuts the destructiveHint. This is an annotation contradiction.

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

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

Three short, front-loaded sentences: the action first, then safety/scope, then the migration use case. Every sentence carries information and nothing is repeated from structured fields.

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

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

For a destructive, non-idempotent cleanup tool with no output schema, the description explains what is removed and why, which is the core need. But it leaves the sole required parameter undocumented and its safety framing conflicts with the annotations, so an agent lacks a trustworthy behavioral picture.

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 only parameter, 'vault', has 0% schema description coverage and is never mentioned in the description. The agent is told what vacuuming does but not which vault to target or what form that identifier takes, so the description does not compensate for the schema gap.

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?

Names a specific verb (drop) and resource (orphaned embedding rows) with the exact condition that qualifies them (chunk_id no longer present in the chunks table). An agent can distinguish this cleanup operation from sibling search/read/write tools without opening the schema.

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

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

Gives a clear triggering context: run it after migrations from pre-v0.7.0 schemas where chunk deletion did not cascade. It does not, however, state when NOT to run it or name an alternative cleanup path, so it stops short of full routing 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 readOnlyHint, idempotentHint, openWorldHint=false and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: the deprecation lifecycle (v2.x callable, removal in v3.0.0) and the all-vaults default, which an agent cannot infer from the schema or 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?

Three tight sentences: capability first, scope/usage second, deprecation last. Every clause carries information (return contents, default scope, migration target, timeline) with no filler.

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

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

With no output schema, the description must carry return-value semantics, and it does so by listing the metrics returned. Combined with the deprecation notice and usage routing, an agent has everything needed to decide whether to call this or switch to the resource.

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% and the single `vault` parameter is undocumented in the schema. The description compensates by explaining its omission semantics ("Omit `vault` to get all configured vaults"), which is real meaning beyond the structured field, though it never states the accepted identifier format for the 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?

The description enumerates exactly what the tool returns (note/word counts, top tags, frontmatter keys, embedding model, last index run) and frames it as agent self-orientation, which is far more specific than a restatement of the name. It lacks an explicit verb, and overlap with siblings like list_models/index_runs/list_vaults is only implicitly resolved by the enumerated contents, so it stops short of a 5.

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 when to use the tool (agent self-orientation/discovery), how to widen scope ("Omit `vault` to get all configured vaults"), and routes the agent to a named alternative (the `vault-memory://stats/{vault}` MCP Resource), including the migration timeline. Nothing about tool selection 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 destructiveHint=true and idempotentHint=false, so the safety profile is known; the description adds what annotations cannot, namely atomicity and the write_enabled=true permission gate. It stops short of 5 because it does not say what happens to existing frontmatter or content on overwrite.

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 short sentences, front-loaded with the action and scope, with each remaining sentence carrying a distinct rule (permission gate, safe-overwrite pattern, create case). No filler.

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

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

For a destructive write tool with no output schema, it covers the critical operational facts: permission requirement, atomicity, and hash-based concurrency safety, while annotations cover the destructive/idempotency profile. The gap is the undocumented frontmatter and client_id parameters and their effect on overwrite.

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 6 parameters, so the description must compensate. It adds real meaning for expected_hash (read the note, pass its hash) and implies content/path/vault usage, but leaves frontmatter and client_id completely 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 and resource ('Atomically create or overwrite a note'), which clearly separates it from read_note, delete_note and update_frontmatter. It does not explicitly name a sibling or a boundary case, so it stops short of the top band.

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

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

Gives an explicit prerequisite (write_enabled=true) and a precise when/when-not rule for the risky mode: use expected_hash for overwrites by reading first, omit it only when creating a new note. An agent can pick the correct call pattern without inference.

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