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

With no annotations, the description fully carries behavioral disclosure. It details strict property type matching, key matching to title or aliases, v2.0.0 return format (wikilink relation), and that superseded backlinks are not filtered. It also mentions future Phase 4 changes.

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 a single dense paragraph but front-loads the core purpose. It includes version and future-phase details which, while informative, slightly reduce conciseness. Overall 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?

Given no output schema, the description thoroughly explains the return structure (anchor, linked_documents, property_rollups) and notes the wikilink relation in v2. It covers complex behavior comprehensively.

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 adds value beyond the schema by explaining matching rules (D-03, D-04) and default behavior for vaults. This context aids correct parameter usage.

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

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

The description clearly states the tool's purpose: resolving a {type, key} pair to an anchor document and walking backlinks into a structured dossier with specific fields (anchor, linked_documents, property_rollups). It includes strict matching rules and version details, distinguishing it from simple backlink tools like list_backlinks.

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 does not explicitly guide when to use this tool versus siblings such as list_backlinks or compile_brief. It implies usage for comprehensive dossier generation but lacks exclusions or alternative comparisons.

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 no annotations, the description must disclose behavior. It indicates a read operation ('Query') and a default limit, but omits details like ordering, pagination, error handling, or whether the call is safe. Adequate but minimal.

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, front-loaded with the core action, every word contributes. No fluff.

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 6 parameters, no output schema, and no annotations, the description is too brief. It lacks details on return values, pagination, filtering behavior, and the is_memory_sink_write parameter. Incomplete for reliable tool selection.

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 needs to explain parameters. It covers note_path, op, and limit (via default), but misses vault, since, and is_memory_sink_write. Partial but adds value 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 clearly states the verb 'Query' and the resource 'the write audit trail for a vault', specifying a distinct purpose among siblings with no overlap.

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 implicit usage hints through filterable fields (note path, operation type, time) and default limit, but lacks explicit when-to-use or when-not-to-use guidance versus 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?

With no annotations, the description fully discloses deterministic output, node cap, force override, mutual exclusion of parameters, vault requirement, and that no LLM enrichment is performed. This is comprehensive.

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 thorough but each sentence adds value. Slightly longer than necessary, but well-organized and front-loaded with key behavior. Could be structured into clearer sections for parameters.

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

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

Given no output schema, the description fully explains return value structure (cluster_id, size, members, summary fields) and the deterministic nature. It also addresses memory opacity inheritance from expand. The tool's role is complete.

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

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

Schema has 0% description coverage, but the description explains each parameter in detail: query path, seed_doc_ids path, vault, method (const), query_top_k (default/max), force (default). It adds operational semantics 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 clearly states it performs community detection via Louvain modularity, with deterministic behavior and specific cluster_id assignment. It distinguishes itself from siblings (like expand, search) by focusing on clustering.

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 explicitly explains when to use query vs seed_doc_ids, the mutually exclusive constraint, vault requirement in multi-vault setups, and force override for node cap. It does not explicitly name alternatives but provides clear usage context.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It reveals several key behaviors: LLM resolution via a defined ladder, automatic wikilink enforcement with a footer, writing through DeliveryAdapter, and auto-superseding on target collisions. This goes beyond a simple 'compile brief' statement and helps the agent anticipate internal processing.

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 concise at three sentences. The first sentence clearly states the core action, and subsequent sentences add critical behavioral details without redundancy. Every sentence is informative and earns its place.

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

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

Given the tool's complexity (7 parameters, no output schema), the description covers key behaviors like LLM resolution and supersede but fails to mention what the agent should expect as an output or return value. It also doesn't explain error conditions or when to use optional parameters like prepared_text or sink. With 100% parameter schema coverage, some gaps are mitigated, but overall completeness is adequate but not thorough.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add extra parameter-specific meaning beyond what the input schema already provides; it mentions source documents and LLM resolution but doesn't elaborate on individual parameters like vault, target, or purpose.

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

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

The description clearly states the tool's purpose: compiling a brief from caller-supplied source documents and writing it to a sink. It uses specific verbs ('compile', 'writes') and resource ('brief'), and includes unique behaviors like LLM resolution and wikilink enforcement that distinguish it from siblings like write_note or assemble_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?

The description does not explicitly state when to use this tool over alternatives like assemble_dossier or write_note. It describes internal mechanisms (LLM ladder, supersede) but lacks guidance on use cases or conditions. No exclusions or prerequisites are mentioned.

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 no annotations provided, the description carries the full transparency burden. It indicates that deletion requires a hash to prevent blind deletes, but fails to state that deletion is irreversible, what happens to associated links or indices, or any error conditions. For a destructive tool, this is insufficient.

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 uses only two sentences, with the primary action front-loaded. Every word serves a purpose: stating the action and key requirement. No redundancy or 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?

Given 4 parameters, no output schema, and 37 siblings, the description is too sparse. It lacks details on return values, error handling, post-deletion effects (e.g., index updates), and prerequisites beyond the hash. A delete operation warrants more complete context.

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 only adds meaning for 'expected_hash' by linking it to 'no blind deletes', but fails to explain 'vault', 'path', or 'client_id'. Parameters like 'client_id' are completely undocumented, leaving the agent without 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?

The description clearly states 'Delete a note' as the action, specifying verb and resource. Among siblings like write_note and update_frontmatter, it uniquely identifies the delete operation. The added requirement detail ('Requires write_enabled=true AND expected_hash') further clarifies the tool's purpose.

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 mentions prerequisites (write_enabled=true and expected_hash) but does not explicitly guide when to use this tool versus alternatives like write_note or vacuum_embeddings. The context is implied through the 'no blind deletes' safety note, but lacks direct comparison to 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?

No annotations are provided, so the description carries full burden. It discloses the tool is a pure function, lists the contents of the summary, and specifies error behavior for ambiguous vault. It does not mention error handling for nonexistent contracts, but coverage is good.

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 a single paragraph with clear structure: purpose first, then output details, then parameter guideline. Every sentence adds value with no redundancy.

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

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

With only two parameters, no output schema, and no annotations, the description covers purpose, detailed output, usage conditions, and error cases. It is sufficiently complete for a read-only description 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%, but the description adds meaningful context: 'name' is a registered contract (with reference to registration tool) and 'vault' usage rules. This goes beyond the schema fields.

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

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

The description clearly states it returns the input JSON Schema and an auto-generated markdown summary for a contract, emphasizing it is a pure function that does not execute the contract. This distinguishes it from sibling tools 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?

Provides explicit guidance on when to include or omit the 'vault' parameter based on single vs multi-vault setups, and describes the error case for ambiguous vault. However, it does not explicitly contrast with alternative tools (e.g., get_brief).

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 no annotations, the description carries full burden and provides extensive behavioral details: hop cap, default direction, filter capabilities, memory-namespace opacity, frontmatter-ref heuristics, superseded handling, error behavior, and dedup rules. This goes well beyond basic mechanism.

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

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

Every sentence provides unique, essential information. The description is dense but not verbose, front-loaded with the main purpose, and efficiently covers all critical aspects without 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?

Given the tool's complexity (6 parameters, no output schema), the description is remarkably complete. It explains the return format, provenance metadata, error handling, filtering, and edge cases, enabling an agent to use the tool effectively.

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% (all 6 parameters described), so baseline is 3. The description adds value by providing context such as version constraints on hops, behavior for unknown seed_doc_ids, and dedup strategy, which are not in the parameter descriptions.

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

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

The description clearly states it is a 'Typed-edge BFS retrieval' that returns the typed-edge neighborhood of seed documents. This gives a specific verb and resource, but it does not explicitly distinguish itself from sibling tools like list_forward_links or list_backlinks.

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 usage (for traversing typed edges with hop limit and filtering), but it does not provide explicit when-to-use or when-not-to-use guidance relative to alternatives. Agents must infer applicability from the feature 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?

No annotations are provided, so the description carries the burden. It discloses the output shape and mentions it is backed by read_note, implying a read operation. However, it does not discuss error conditions, authorization needs, or rate limits.

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

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

The description is two sentences, front-loading the key action and output. The term 'OB1-compatible fetch adapter' is jargon but not overly verbose.

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

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

Given no output schema and no annotations, the description provides a basic output shape but lacks details on error handling, behavior when id is invalid, and differentiation from closely related siblings like read_note.

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 schema has 0% description coverage for the single id parameter. The description adds meaning by explaining it is an 'opaque id (from `search`)', which clarifies the expected source and nature of the id.

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

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

The description clearly states it resolves an opaque id to a structured object, and mentions it is backed by read_note. However, it does not explicitly distinguish it from sibling tools like read_note, which might have similar functionality.

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 it should be used after search ('from `search`'), but provides no explicit guidance on when to use it versus alternatives, nor when not to use it.

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?

No annotations provided. Description implies a read-only operation but doesn't explicitly state non-destructiveness or other behavioral traits beyond listing.

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?

Single sentence, front-loaded with action and result, no unnecessary words.

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 listing tool with one parameter and no output schema, description covers core functionality; could mention return format but not essential.

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?

Single 'vault' parameter is self-explanatory; description adds no extra semantics despite 0% schema coverage. Minimal but adequate.

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?

Description clearly states the verb 'list' and resource 'broken wikilinks', distinguishing it from siblings like list_backlinks and list_forward_links.

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 guidance on when to use this tool vs alternatives. With many similar sibling tools, context for selection is missing.

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 no annotations, the description carries the full burden. It discloses the decision tree logic (staleness dominates, age independent, supersede chain), and explains null return conditions. This is transparent for a lookup tool, though it omits permission or error behaviors.

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

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

The description is two sentences: first sentence states the core purpose, second sentence details the decision logic. It is concise but dense; the phrase 'D-13 decision tree' may be jargon but adds context. No wasted words.

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 lookup tool with no output schema, the description explains the key return behavior (null vs. brief) and the conditions. It covers the main aspects needed to use the tool effectively, though it does not describe the brief structure or error cases.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining how 'max_age_days' and 'allow_stale' interact, and referencing the 'target slug' concept. This enriches understanding of parameter behavior.

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

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

The description clearly states 'Look up a brief by target slug' which is a specific verb and resource. However, it does not explicitly differentiate from sibling tools like get_document_bundle or read_note, which share similar lookup semantics.

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 provides a decision tree (D-13) explaining when the tool returns null, implying usage for scenarios where staleness or age matters. It hints at when to recompile but does not explicitly state when to use this versus alternatives like compile_brief or supersede.

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 no annotations, the description fully discloses behavior: depth pinned to 1, broken links omitted, recent_edits limited to 10, error shape, and version constraints. This is comprehensive and transparent.

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 a single paragraph but well-structured, starting with the main purpose. It includes necessary details like version, error handling, and shape of fields. Slightly dense but earns its length.

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

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

Given no output schema, the description fully specifies return shapes (anchor, outline, backlinks, forward_links, recent_edits), error handling, constraints, and versioning. It is complete for a tool of this 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 descriptions cover parameters, but the description adds context: explains the depth constraint (zod-pinned to 1 for forward compatibility) and the optional nature of vaults. This adds value 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 clearly states 'Document-tree retrieval' and details the bundled output (anchor, outline, backlinks, forward_links, recent_edits). It distinguishes from sibling tools like get_outline, list_backlinks, list_forward_links by being a composite result.

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 context is implied but not explicit. No guidance on when to use this tool vs. alternatives, nor any exclusions. The description mentions error handling for unknown doc_id but not when to prefer this over single-purpose 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?

With no annotations, the description fully bears the burden of disclosure. It explains input format, output structure (OutlineNode fields), and error response format. It also hints at usage in citation packets, adding valuable context beyond a simple data return.

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 concise, with the main purpose in the first sentence followed by structured details about output fields. Every sentence adds value, and the format is easy to parse.

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

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

Given no output schema, the description adequately covers the return type (OutlineNode fields) and error case. It provides sufficient information for correct usage, including error handling and citation context.

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% with descriptions for both parameters. The description enriches understanding by explaining how parameters relate to the output (e.g., anchor, heading_path). This goes beyond the schema's minimal descriptions.

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

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

The description clearly states the tool returns a 'navigable section tree for a document,' specifying the verb and resource. It details the fields of OutlineNode and mentions error handling, making it distinct from sibling tools like search_sections.

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?

Description lacks explicit guidance on when to use this tool versus alternatives. It mentions error behavior for unknown doc_id but provides no context about trade-offs or preferred use cases relative 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?

With no annotations provided, the description should fully disclose behavioral aspects. It mentions 'recent' but does not define recency or ordering. It does not state whether the operation is read-only, if it requires specific permissions, or if it has any side effects.

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 a single sentence, which is concise, but it lacks essential details that would justify its brevity. It is not overly verbose, but it could be improved by adding parameter explanations or usage context.

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

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

Given the tool has two parameters and no output schema, the description is insufficiently complete. It does not explain the vault parameter, the meaning of 'recent', or the format of the return value. It leaves significant gaps for the agent to infer.

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 does not explain the parameters. 'vault' is required but not described, and 'limit' has a default and maximum but no explanation of its purpose or effect.

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

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

The description clearly states the verb 'List' and the resource 'recent index runs for a vault', and specifies the information returned ('what was scanned, when, how long, errors'). It distinguishes itself from sibling tools by focusing on indexing runs, which is a specific and distinct function.

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 provides no explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites, nor does it differentiate from sibling tools like 'start_shadow_index' or 'vault_stats'.

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

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

Discloses Zod validation with additionalProperties false, source/sink override chain, MemorySink-only constraint, assembly steps, write_back routing, and structured error envelope with 12 sealed reasons. With no annotations, the description carries full burden and delivers extensively.

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 with information, each sentence adds value. Front-loaded with main purpose. Slightly verbose but necessary given complexity; no fluff.

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

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

Covers input validation, overrides, execution flow, and error handling. Returns bundle structure explained. Lacks example of error envelope but sufficient for an execute tool without output schema.

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

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

Adds meaning beyond schema: explains validation behavior, override resolution chain, and vault conditions. Schema coverage is 100%, but description enriches understanding of each parameter's role and constraints.

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?

Clearly states 'Execute a registered contract end-to-end,' specifying the verb and resource. Distinguishes from siblings like describe_contract or register_contracts_as_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?

Provides context for vault parameter (omit in single-vault, required in multi-vault) but does not explicitly state when to use this tool over alternatives. Implied usage from the execution nature.

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?

No annotations are provided, so the description must carry the full burden. It mentions deprecation but does not disclose behavioral traits such as read-only nature, auth needs, rate limits, or what happens upon execution. Basic action is implied but not detailed.

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: first states purpose, second provides deprecation info and alternative. Front-loaded with key info, no unnecessary words.

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?

Lacks parameter explanations and behavioral details (e.g., read-only vs write, return format). For a simple tool with no output schema and no annotations, the description should be more comprehensive.

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 does not explain the parameters 'vault' and 'path'. No additional meaning is conveyed beyond the raw schema fields.

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

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

The description clearly states the tool's purpose: 'Find all notes that link TO a given note.' It is specific and distinguishes from siblings by focusing on backlinks. The deprecation notice adds context without muddling the purpose.

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

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

Explicitly states when to prefer an alternative ('prefer MCP Resource...') and that the tool remains callable until v3.0.0. Provides clear guidance on when not to use it.

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?

No annotations are provided, so the description must carry the burden of behavioral disclosure. It only states the basic function without detailing output format, error handling, or default behavior of the include_broken parameter (defaults to true in schema). The description is minimal and leaves critical behavioral traits 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?

The description is extremely concise with two sentences. It front-loades the purpose and adds a secondary option. Every word earns its place with no redundancy or extraneous 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?

Given the tool has 3 parameters, no output schema, and no annotations, and exists among many similar sibling tools, the description is too brief. It fails to explain the vault parameter, output format, or how broken links are represented. An agent would lack important details to use the tool correctly without further context.

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%, but the description hints at two parameters: 'FROM a given note' implies path, and 'Optionally include broken links' hints at include_broken. However, the vault parameter is not explained, and include_broken's default is not indicated. The description adds some meaning but does not fully compensate for the lack of schema descriptions.

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

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

The description clearly states it lists forward wikilinks from a note, distinguishing it from sibling tools like list_backlinks (which lists backlinks) and find_broken_links (which finds broken links). The verb 'list' and resource 'wikilinks FROM a given note' are specific and 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?

The description implies usage for viewing outgoing links from a note and optionally filtering broken links, but it does not explicitly compare with siblings or state when to use alternatives. No when-not-to or context for exclusion is provided.

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 no annotations, the description fully discloses behavior: lists models with dim, active flag, and chunk counts. It also transparently states deprecation status, that it remains callable through v2.x, and scheduled removal in v3.0.0. No contradictions.

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

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

The description is three sentences, each earning its place: purpose/fields, usage context, deprecation info. Front-loaded with key action and output. 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 list tool, the description covers return values (dim, active flag, chunk count), usage context, deprecation, and alternative. No output schema exists, so the description adequately describes what the agent can expect. Complete for the tool's 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?

The only parameter 'vault' has 0% schema description coverage. The description mentions 'for a vault' but does not elaborate on the parameter's format, allowed values, or semantics. It adds minimal value beyond the schema, only implying the vault identifier context. Baseline of 3 for low coverage with limited compensation.

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

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

The description clearly states 'List all embedding models registered for a vault, with dim, active flag, and how many chunks have been embedded under each.' It specifies the verb (list), resource (embedding models), scope (for a vault), and output fields. It distinguishes from siblings by mentioning its use before start_shadow_index/switch_active_model.

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 explicitly states when to use the tool: 'Use before start_shadow_index / switch_active_model.' It also provides an alternative for the deprecated function: 'prefer MCP Resource `vault-memory://models/{vault}`.' This gives clear context and 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?

With no annotations, the description fully bears the burden of disclosure. It reveals the tool lists vaults with status, and states deprecation status and future removal. However, it does not explicitly mention whether the operation is read-only or safe, or if any authentication 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 sentences: the first sentence states purpose and output, the second adds deprecation context. Every word earns its place, and the description is front-loaded with the core functionality.

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

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

Given no parameters and no output schema, the description adequately explains what the tool returns (vaults with status including note count and last indexed run). Deprecation information adds useful lifecycle context. Could mention scope (e.g., all vaults accessible to the user) but is sufficient.

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

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

The tool has zero parameters and schema coverage is 100%, so no parameter documentation is needed. The description does not add parameter info, but the baseline score for a no-parameter tool is 4.

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

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

The description clearly states the tool lists vaults with status details (note count, last indexed run), distinguishing it from sibling list tools by specifying the resource 'vaults' and the output fields. The action verb 'List' is specific and 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?

Explicitly marks the tool as DEPRECATED and directs agents to use the MCP Resource 'vault-memory://vaults' instead. It also clarifies the tool remains callable through v2.x and removal is scheduled for v3.0.0, providing clear when-to-use and when-not-to-use 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?

With no annotations, the description must disclose behavior. It mentions supported predicates and AND logic, which are behavioral traits. However, it does not state whether the tool is read-only (safe), any side effects, performance implications, or the format of the result. This is minimal but not misleading.

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

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

The description is two sentences, efficiently covering purpose and key usage details without fluff. It is front-loaded with the main action and adds necessary details. No wasted words.

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

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

Given the complexity of the 'where' parameter (nested objects, multiple predicate types), the lack of an output schema, and no annotations, the description is insufficient. It does not explain the return value, constraints on frontmatter field names, or provide examples. The tool has 3 parameters but only partial description of one.

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 should compensate. It mentions predicates (relating to 'where') but does not describe the 'vault' or 'limit' parameters. The vault parameter's purpose is implied but not explicit, and limit's meaning is clear from schema but not reinforced.

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

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

The description clearly states the action ('Filter notes by their YAML frontmatter') and specifies supported predicates and combination logic. This distinguishes it from sibling tools like read_note or search, but it doesn't clarify the output format (e.g., returns note paths or IDs).

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 how to use the predicates and that multiple keys are AND-combined, which gives usage hints. However, it does not explicitly state when to use this tool versus alternatives (e.g., search tools for full-text search, read_note for reading content). No exclusions or alternatives are mentioned.

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 no annotations, the description carries full burden. It implies a non-destructive read operation but does not disclose error behavior, permissions needed, or side effects like logging. Basic transparency but incomplete.

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, concise sentence that immediately conveys the action and resource. No wasted words, front-loaded with the verb.

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

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

Given the complexity (2 parameters, no output schema), the description omits usage guidelines, parameter details, return value format, and differentiation from many similar read tools. It feels incomplete for effective use.

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 description must compensate. It mentions 'vault-relative path' but does not explain what 'vault' and 'path' mean in detail, format, or allowed values. Adds minimal semantics beyond the schema's type strings.

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

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

The description clearly states the verb 'Read', the resource 'full content + frontmatter of a note', and the identifier 'by its vault-relative path'. It effectively distinguishes from siblings like write_note 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?

No guidance provided on when to use this tool versus the 36 sibling tools (e.g., get_brief, recall). The description lacks any when-to-use or when-not-to-use instructions.

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?

No annotations exist, so the description carries the full burden. It discloses the return shape (8 fields), default hiding of superseded documents, filtering parameters, and ranking by recency. However, it omits details like rate limits, authentication requirements, or error handling.

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

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

Two sentences: the first covers purpose, filtering, and ranking; the second covers return format and default behavior. It is efficiently front-loaded with no wasted words.

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

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

For a tool with 7 parameters and no output schema, the description explains the return shape and default behavior. It lacks pagination details beyond the limit parameter and does not mention error handling or empty result behavior.

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 value by explaining ranking by recency (observed_at DESC) and the return shape (citation packets), which are not in the schema. This helps the agent understand the output structure.

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

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

The description clearly specifies the verb 'retrieve', the resource 'memory documents from MemorySinks', and details filtering and ranking. It distinguishes from sibling search tools by emphasizing MemorySinks and citation packets.

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 usage for retrieving memory documents but does not explicitly state when to use this tool versus alternatives like search_hybrid or search_text. No when-not-to-use guidance is provided.

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?

No annotations provided, so description carries full burden. It discloses the tool is a simple SQL query, deprecation status, and removal timeline. Lacks details on error handling or rate limits, but sufficient for a read-only list operation.

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

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

The description is three sentences, efficient and front-loaded with the core action. Every sentence adds useful information without redundancy.

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

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

The description covers purpose, usage context, and deprecation, but fails to document parameters (vault, limit, since) which are essential for correct invocation given zero schema descriptions. Output schema is absent, but not required for a list operation.

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

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

Schema description coverage is 0%, yet the description does not explain any of the three parameters (vault, limit, since). The description adds no value beyond the schema for parameter understanding.

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

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

The description clearly states the tool lists recently modified notes with a specific sorting (mtime DESC). It distinguishes from other note tools by focusing on recency, and the deprecation notice provides additional clarity.

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 gives a use case ('agent self-orientation'), contrasts with vector search, and provides a clear alternative (MCP Resource) along with a deprecation schedule.

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?

No annotations are provided, so the description must carry full behavioral disclosure. It mentions that writes route through DeliveryAdapter.write() and pass through a centralized provenance validator. It also describes the auto-filling of provenance properties and caller-last merge for properties. However, it does not disclose idempotency, error handling, or whether the operation is synchronous or asynchronous. Some internal details are provided, but gaps remain.

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 consists of two sentences. The first sentence clearly states the purpose. The second sentence provides important technical details about auto-fill and merging, but is dense and may be confusing. It is concise but could be better structured (e.g., bullet points for clarity). It remains functional without being overly verbose.

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

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

Given 7 parameters (5 required), a nested object, no output schema, and no annotations, the description covers purpose, auto-fill logic, routing, and provenance validation. However, it lacks information about return values (e.g., does it return the created observation or just a success status?) and does not mention persistence guarantees. Completeness is adequate but not thorough.

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 schema covers all 7 parameters with descriptions, achieving 100% coverage (baseline 3). The description adds significant value by explaining that provenance properties (source, confidence, evidence, status, observed_at, type, superseded_by) are auto-filled from arguments, and that the `properties` parameter is an escape hatch with caller-last merge (D-02 rule). This clarifies the behavior beyond what the schema alone 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 clearly states the action: 'Record a new memory observation under the labeled MemorySink for a vault.' It specifies the resource (memory observation) and the location (labeled MemorySink, vault). This distinguishes it from sibling tools like write_note (which writes a note) and recall (which retrieves memories).

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 how to use the properties escape hatch and that provenance properties are auto-filled, but it does not provide explicit guidance on when to use this tool versus alternatives (e.g., write_note). No exclusions or context for when not to use it are given. Usage is implied but not clearly delineated.

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 no annotations, the description fully explains behavior: scanning registry, updating tool list, returning a diff. It mentions 'explicit-control escape valve' which implies manual intervention. However, it does not disclose potential side effects like tool duplication or overhead.

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 a single sentence that immediately states the core purpose and behavior. It is front-loaded and contains no unnecessary words.

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

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

Despite having no output schema, the description specifies the return value (per-vault diff). It covers purpose, usage, parameter behavior, and side effects (config gate override). Given the simplicity of the tool, the description is fully adequate.

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

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

Schema coverage is 100%, and the parameter description in the schema is clear. The tool description adds no extra semantics beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool registers/unregisters contracts as dynamic MCP tools, including the vm_<name> naming pattern. It distinguishes itself as an 'escape valve' for explicit control, which differentiates it from sibling tools that handle other operations.

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

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

The description mentions 'Always callable' and explains when to use it ('regardless of the [contracts.auto_register_tools] config gate'). It also clarifies the optional vault parameter. However, it does not explicitly state when not to use it or suggest 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?

No annotations are provided, so the description carries full burden. It discloses the search algorithm (hybrid semantic+BM25+RRF) and the output format structure. However, it does not mention safety traits, side effects, or authorization requirements, leaving gaps.

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 three sentences long, front-loads the purpose, and each sentence adds value without redundancy.

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

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

Given the presence of many sibling search tools and no output schema or annotations, the description lacks details on pagination, error handling, return format completeness, and usage context. It is insufficient for an agent to confidently use the tool.

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

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

Schema coverage is 0%, meaning no parameter descriptions in JSON schema. The description does not explain the meaning of 'query' or 'limit' beyond the schema defaults, failing to compensate for the missing schema descriptions.

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

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

The description clearly states it is an OB1-compatible search adapter returning a flat list with specific fields (id, title, url, snippet) for connector ecosystems. It distinguishes itself from search_hybrid by noting that tool provides richer output.

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

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

The description mentions an alternative tool (search_hybrid) but does not provide guidance on when to use this tool versus other sibling search tools like search_text, search_semantic, or search_sections. There is no explicit when-to-use or when-not-to-use advice.

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 no annotations provided, the description discloses key behavioral traits beyond the schema: it explains the RRF fusion method, and details that expand runs after recency/authority rescore and preserves ranking. This gives useful insight into the tool's internal processing, though it doesn't cover return format or error behavior.

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

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

The description is concise, front-loaded with the core purpose, and every sentence contributes value. The first sentence defines the tool in one line, and the second adds an optional behavior with a clear code example and caveat, 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?

The tool is complex (13 params, nested objects) with no output schema and no annotation support. The description covers the core mechanism and one optional feature, but leaves most parameters undocumented, making it difficult for an agent to fully utilize the tool without additional 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?

The schema has zero description coverage for 13 parameters. The description only explains the expand parameter in detail and implicitly references the query. All other parameters (rrf_k, top_k, rerank, half_life_days, recency_weight, authority_weight, etc.) remain completely unexplained, failing to compensate for the schema's lack of semantic information.

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

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

The description clearly states the tool performs a hybrid search combining semantic and BM25 results via Reciprocal Rank Fusion, naming the specific resource and behavior. It distinguishes itself from sibling tools like search_text and search_semantic by calling it the 'best general-purpose query.'

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 provides clear context for when to use this tool ('Best general-purpose query') and gives a specific usage tip for the expand parameter. It does not explicitly name alternatives or exclusion criteria, but the guidance is practical and distinct.

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?

No annotations, but description fully discloses the hybrid pipeline, promotion, dedup, scoring, tie-breaking, and citation packet fields, offering thorough behavioral transparency.

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?

Descriptions is verbose with algorithmic detail; front-loaded purpose but contains excess implementation details that could be streamlined.

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?

Lacks output schema, but description covers return format. Missing error handling, permissions, rate limits, and parameter descriptions for completeness.

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 0%; description only explains 'limit' indirectly (limit×5) but leaves other 5 parameters (query, vaults, recency_weight, authority_weight, include_superseded) undescribed.

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?

Description clearly states 'section-level retrieval' and contrasts with chunk window context, distinguishing it from sibling search tools.

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

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

Ends with 'Use when you want WHOLE-SECTION context, not a chunk window', providing implicit guidance vs. chunk-based siblings, but lacks explicit when-not-to-use or alternative names.

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

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

No annotations are provided, so the description carries the full burden. It mentions the search method (cosine similarity) and default scope, but lacks details on performance, rate limits, or whether the vaults parameter overrides or filters.

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

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

Two sentences, front-loaded with the core purpose. No extraneous words. 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?

With 4 parameters, no output schema, and no annotations, the description is insufficient. It doesn't describe return format, ranking, or parameter behaviors beyond vault defaulting.

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. Only the 'vaults' parameter gets some context (default all vaults). No explanation for 'query', 'top_k', or 'exclude_paths'.

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

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

The description clearly states the tool performs semantic search using embedding cosine similarity, and it searches all vaults by default. This is specific and distinguishes it from sibling tools like 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?

The description implies use for semantic search but does not explicitly state when to use this tool versus alternatives like search_text or search_hybrid. No explicit when-not-to-use 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?

No annotations are provided, and the description does not disclose any behavioral traits such as side effects, authentication requirements, or read-only status. For a search tool, it is assumed read-only but not stated.

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 a single, front-loaded sentence that conveys core purpose and differentiating context. It is concise, though could benefit from a bit more structure without becoming verbose.

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

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

Given four parameters and no output schema, the description is incomplete. It omits parameter formats, return type details, and any conditions or limitations, making it insufficient for an agent to invoke 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?

The description does not explain any of the four parameters (query, vaults, top_k, exclude_paths). With 0% schema description coverage, the description fails to add meaning beyond the schema field names.

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

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

The description clearly states it is a full-text BM25 search via SQLite FTS5, and specifies it is best for exact-word and phrase matches, effectively distinguishing it from sibling search tools like search_semantic or search_hybrid.

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 implicitly guides usage by stating 'Best for exact-word and phrase matches,' implying it is not suited for semantic or fuzzy searches. However, it lacks explicit when-not-to-use or alternative recommendations.

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?

Without annotations, the description discloses key behaviors: idempotent/resumable, no disruption to active model or search. Does not detail monitoring or resource impact, but sufficient for an agent to understand safety.

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, each adding value: main action, reassurance, and follow-up. No redundant information, front-loaded with the core verb and resource.

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?

Describes key behaviors and follow-up, but lacks parameter details and output expectations. Given no output schema and sibling tools like index_runs, some gaps remain for a complete 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?

Schema coverage is 0% and description does not explain parameters (vault, model, batch_size). Names are somewhat intuitive, but no additional context is given, leaving ambiguity about format or allowed values.

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

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

The description clearly states the tool's purpose: to backfill embeddings for a shadow model over all chunks in a vault. It specifies 'shadow' and mentions 'active model is untouched', distinguishing it from other 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?

Provides clear context: active model remains unaffected, search works during run, and a follow-up action (switch_active_model) is suggested. Does not explicitly exclude alternatives but implicitly distinguishes via use case.

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 discloses the return structure ({existing, suggestions, conflicts}), the sorting of suggestions by confidence, and the meaning of conflicts. While no annotations are provided, the description provides sufficient behavioral insight for a suggestion tool without claiming any destructive actions.

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

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

The description is concise, using only a few sentences to convey the tool's purpose, modes, return values, and sorting. It is front-loaded with the primary function and structured logically.

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

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

Given the absence of annotations and output schema, the description provides a good understanding of input modes and output structure. It could mention potential error states or the implicit read-only nature, but it is largely complete for an agent to use 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?

With 0% schema description coverage, the description compensates by explaining that 'path' is for an existing note, while 'content', 'folder_hint', and 'title' are for a draft. It clarifies that at least one of path/content is required. The 'vault' parameter is not explained, but it is a common container 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 clearly states the tool's purpose: suggesting frontmatter fields for a note, using specific heuristics. It distinguishes itself from sibling tools like 'query_frontmatter' and 'update_frontmatter' by focusing on suggestion rather than querying or updating.

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 explicitly outlines two input modes (existing note vs. draft) and the required parameters for each. It states that at least one of path or content is required, providing clear usage context. However, it does not mention when to avoid this tool or suggest alternatives among 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?

No annotations exist, so the description carries full burden. It discloses atomic OCC update, status field changes, and forward-only behavior. It does not cover authentication, rate limits, or idempotency, but the key behavioral traits are well covered.

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 informative sentences, front-loaded with main purpose. No wasted words; each sentence adds critical context.

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

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

The description lacks any mention of return values, which is a gap given no output schema. It explains the mutation but not what the agent should expect as a response. Otherwise, it is complete within its scope.

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

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

Schema coverage is 100%, but the description adds meaning by explaining the effect: 'atomic single OCC update on the OLD doc; sets status="superseded", superseded_by, and superseded_reason.' This links parameters to the update behavior, adding value beyond 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 clearly states the verb 'mark superseded' and the resource 'existing memory document'. It distinguishes from siblings by noting the forward-only nature and that back-links are derived later, making it distinct from linking tools.

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

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

The description provides context: 'Forward-only — the replacement doc is NOT touched' and mentions back-links are derived at query time, implying when to use this. However, it does not explicitly state when not to use it or name 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?

With no annotations, the description carries full burden. It discloses atomicity and a specific failure mode (chunks missing shadow embedding). However, it does not detail success behavior or side effects.

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?

One sentence covering purpose and a key failure condition. No fluff, front-loaded with action.

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 tool with two params and no output schema, the description covers core behavior and a failure condition but omits success returns, prerequisites, and other potential errors.

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

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

Schema coverage is 0%, so description must compensate. It implies 'model_name' is the target model to promote but does not explain 'vault' or provide per-parameter details beyond context.

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

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

The description clearly states it atomically promotes a registered model to active, which is a specific verb and resource. It distinguishes from siblings like 'list_models' by focusing on the promotion action.

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 lacks explicit when-to-use or when-not-to-use guidance. It only mentions a failure condition, but no comparison with alternative tools like 'list_models' or 'register_contracts_as_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?

With no annotations, the description carries full burden. It discloses that the tool preserves the note body and uses a merge DSL for operations (set, unset, push, pull). However, it lacks details on side effects, atomicity, or permission requirements.

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

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

Two sentences front-load the purpose and then explain DSL. However, 'bytegenau' appears to be a typo (likely 'exactly') which may confuse. Otherwise, concise and structured.

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 5 parameters (3 required) and no output schema or annotations, the description is too sparse. It omits behavior of vault, path, expected_hash, client_id, and return value. Critical for an agent to use 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 description must compensate. It explains the merge DSL in detail but fails to clarify vault, path, expected_hash, and client_id parameters. Only merge gains semantics; others remain opaque.

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

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

The description clearly states 'Modify a note's frontmatter only', specifying the exact verb (modify) and resource (frontmatter). It also distinguishes from siblings like write_note that modify entire notes.

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

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

The description implicitly limits usage to frontmatter modifications but provides no explicit guidance on when to use this tool versus alternatives like write_note or query_frontmatter. No when-not-to-use or exclusion criteria are mentioned.

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 clearly states the tool is safe and idempotent, and specifies what it does (drops orphaned rows) and what it does not affect (live data). With no annotations provided, the description carries the burden well, though it omits details about return values or edge cases.

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

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

The description is concise with two sentences: the first states the core purpose, the second adds safety and context. Every sentence adds value and is front-loaded with the key action.

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

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

Given the tool's simplicity (one parameter, no output schema), the description fully covers what an agent needs: purpose, safety, and typical usage scenario. It is complete for the task at hand.

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 input schema has one required parameter 'vault' with 0% description coverage. The tool description does not explain what 'vault' represents or how to use it, leaving the agent without guidance on this crucial 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 clearly states the action ('Drop orphaned embedding rows') and the specific condition ('whose chunk_id no longer exists in the chunks table'). It distinguishes this tool from siblings by mentioning safety and idempotence, and the context of post-migration cleanup.

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 explicitly mentions the use case ('after migrations from pre-v0.7.0 schemas') and assures safety ('does not touch live data'). While it does not name alternative tools, the context makes it clear this is for maintenance, not regular operations.

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?

Full disclosure: describes output contents, deprecation status, and that it remains callable until v3.0.0. No annotations provided, so description carries full burden—no behavioral surprises.

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 plus deprecation notice, all essential. No wasted words, front-loaded with purpose.

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

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

For a tool with one optional param and no output schema, description is fully sufficient: covers usage, output, deprecation, and parameter semantics.

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

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

Input schema has 0% description coverage, but description explains the 'vault' parameter: omit for all vaults, specify for a single vault. This adds essential meaning.

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

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

Description clearly states verb ('overview') and resource ('vault'), and lists specific data points (note/word counts, top tags, etc.). It distinguishes from siblings like list_vaults and index_runs by focusing on statistical overview.

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 mentions deprecation and recommends an alternative MCP resource. Also explains behavior when 'vault' is omitted, giving clear usage 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?

Without annotations, the description carries the burden of behavioral disclosure. It mentions atomicity, write_enabled requirement, and safe overwrite mechanism via expected_hash. However, it does not describe error conditions, return values, or side effects, but the core behavior is clear.

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 concise—two sentences—with no extraneous information. It front-loads the tool's purpose and key usage notes, making it easy to scan.

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

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

Given six parameters (three required), no output schema, and no annotations, the description provides essential behavioral context (atomicity, expected_hash) but omits details for four parameters and return value, leaving the tool partially underspecified.

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. Only expected_hash is explained; vault, path, content, frontmatter, and client_id are not described, leaving significant gaps for correct parameter usage.

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

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

The description clearly states the tool's function: 'Atomically create or overwrite a note.' It uses a specific verb and resource, and distinguishes itself from sibling tools like delete_note and read_note.

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

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

The description provides explicit when-to-use guidance: requires write_enabled=true, use expected_hash for safe overwrites, omit expected_hash only for new notes. This distinguishes from alternatives and sets prerequisites.

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