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

With annotations only providing readOnlyHint=false, idempotentHint=false, and destructiveHint=false, the description adds useful behavioral context: batch mode 'extract[s] lessons automatically via worker' suggests asynchronous/delegated processing, and lookup mode 'surface[s] top-ranked existing lessons' clarifies read behavior. This goes beyond the sparse annotations.

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

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

The description is compact and well-structured: a one-line summary followed by three bullet-like mode explanations. Every sentence earns its place, and the core purpose is front-loaded. No redundancy or filler exists.

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 11 parameters and three modes, the description provides sufficient high-level context to choose and invoke the tool correctly, especially with an output schema present. It explains the main parameter roles and mode selection. A possible improvement is explicitly stating mode-selection precedence (e.g., if find is set, lookup wins), but the schema defaults and parameter descriptions make this inferable.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful mode-based grouping: inline mode maps to title/context/problem/solution, batch mode to text, and lookup mode to find. It also reinforces that rank_by is ignored unless find is set. This is above baseline because it organizes parameters semantically rather than just repeating schema field 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 opens with 'Capture lessons: inline / batch write, or lookup by keyword,' which names a specific verb and resource. It then enumerates three distinct modes (inline, batch, lookup), making it clearly distinguishable from sibling vault_* tools that handle generic vault content.

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

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

The description gives clear guidance on when to use each mode: inline for title/context/problem/solution, batch for text extraction via worker, and lookup for keyword search. However, it does not explicitly compare this tool to alternatives like vault_write or vault_query, so some competitive routing is left to inference.

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

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

The annotations are neutral (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description carries the burden of behavior disclosure. It reveals genuinely non-obvious traits: the ≤50 line direct-return threshold, automatic delegation of large files, and the fallback to raw content when workers are unavailable. It stops short of stating side effects (whether summaries persist back to the vault) or cost/latency implications of delegation.

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 with zero filler. The one-line purpose statement is front-loaded, and the conditional flow is compressed into a tight, scannable second sentence. Every clause earns its place.

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

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

For a 10-parameter dual-mode tool with an output schema, the description captures the core decision logic (mode selection, size threshold, fallback) while the schema documents parameters and return values. The main gaps are the relationship between the two modes and whether summarization has persistent side effects, but the rich schema compensates for most of what the description omits.

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 exceptionally rich per-parameter descriptions (model-value rejection semantics, timeout ceiling behavior with HIVE-384 reference, structured-mode rationale). Per the rubric, high coverage sets a baseline of 3. The tool description adds connective flow logic (project triggers file reading; size threshold drives delegation) but no parameter-level detail beyond what the schema already provides.

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

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

The description opens with a specific verb-resource pair: "Offload work to a cheaper model or summarize vault files." This clearly distinguishes it from the vault_* siblings and worker_status. However, "offload work" is slightly vague about what the work actually is, and the dual-purpose framing splits focus, so it just misses the top score.

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 mode selection implicitly: "When project is provided, reads a vault file" and the small/large file branching. It does not explicitly name alternatives or say when to prefer this tool over vault_ask or other siblings — an agent could not tell from this alone whether to pick delegate_task or vault_ask for a summarization request.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true and the description's 'loads/returns/assembles' language is fully consistent with them, so there is no contradiction. The description adds real behavioral value beyond the annotations: the empty-project vs. project-set branches, the aggregation of four data sources, and the discoverability convention shared with vault_health() and worker_status(). It does not cover failure behavior for an invalid project slug, but that is minor for a safe, read-only call.

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

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

Four short sentences with the purpose front-loaded, followed by the two parameter-dependent branches and a cost comparison. Every sentence earns its place — including 'replaces 3-4 manual calls,' which conveys value, and the sibling mention, which conveys response-shape parity — 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?

For a single-optional-parameter, read-only, idempotent tool with an output schema, the description covers when to call it, what each branch returns, and how it relates to alternatives. The only gaps are minor: no statement of behavior on an unknown project slug and no note on data freshness/caching for the aggregated git and lesson data.

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% — the schema already explains the `project` slug format, the empty-string meaning, and even notes there is no `days` argument. The description's 'without a project / with a project' phrasing mirrors the schema rather than adding new semantic content, so it lands at the high-coverage baseline of 3.

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

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

The description opens with a concrete directive — 'Call at the start of every new session to load project context' — then details the two behavioral branches (project list vs. assembled briefing of tasks, lessons, git activity, health). It distinguishes itself from the vault_* and worker_status siblings by explicitly naming vault_health() and worker_status() and by describing aggregation semantics no sibling offers.

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

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

It gives an explicit trigger condition ('start of every new session') and frames the tool as replacing '3-4 manual calls,' which tells the agent when the aggregated call is preferable. It names vault_health() and worker_status() for the discovery-parity case, but it never states an explicit when-not-to-use condition — e.g., what to call when only one slice of context (git activity alone) is needed.

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

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

Beyond the readOnly and idempotent annotations, the description discloses meaningful behavior: it returns a how-to-enable message when not configured, never errors, and changes behavior when HIVE_SYNTH_MODEL is set. This gives the agent accurate expectations for unconfigured environments.

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

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

The description is front-loaded with the core purpose and then efficiently covers fallback behavior, configuration prerequisites, and the sibling alternative. Every sentence serves a distinct purpose 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 output schema exists and the tool has optional synthesis behavior, the description fully covers prerequisites, degraded mode, configuration, and when to use a sibling tool. An agent has everything needed to decide whether and how to call it.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by emphasizing use of the `question` parameter over `query` or `prompt`, which helps agents avoid common naming mistakes.

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 uses a specific verb ('Ask') and resource ('vault') with a concrete output ('source-cited synthesized answer' or 'relevant vault sections'). It clearly distinguishes itself from sibling vault_search by framing this as natural-language / semantic retrieval versus keyword / regex lookup.

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 states exactly when to use the tool (natural-language questions, semantic retrieval/RAG) and explicitly says to use vault_search instead for keyword/regex lookups. It also covers the disabled-by-default state, prerequisites, and configuration needed for synthesis.

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

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

Annotations only say readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the description carries most of the behavioral burden. It discloses the no-op case ('clean-tree notice when there is nothing to commit'), the commit-wide scope, and the possible return states. It does not detail failure causes or permission requirements, but the behavior is well covered for a simple commit tool.

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

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

The description is compact and front-loaded. The first sentence states the action, the second gives the companion context, and the third describes return behavior. Every sentence earns its place with 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 one-parameter tool with an output schema, the description is complete: it explains what the tool does, when to use it instead of per-write commits, its whole-tree scope, and its return values. Nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100%: the schema already explains the message default value and explicitly notes this is the only parameter, with no project argument. The main description adds no further parameter-level meaning beyond referring to the commit message, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource: 'Stage everything in the vault and create one commit.' It clearly differentiates itself from siblings by positioning it as the batched flush counterpart to vault_write(commit=False) and vault_patch(commit=False), and it states the output (commit SHA or clean-tree notice).

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

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

It explicitly names the companion sibling tools and the exact condition for using this tool: callers that opt out of per-write commits should batch writes and then 'flush with a single vault_commit call.' The schema also reinforces scope by stating there is no project argument and the commit spans the whole vault working tree.

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

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

Annotations declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, which is odd for a delete tool. The description compensates by explicitly stating the operation is destructive, recoverable via git, commits by default, rejects directories, and errors on non-existent paths unless idempotency_key is set. It also discloses the commit=False rejection behavior. This adds substantial behavioral context beyond the annotations, though the annotation contradiction is notable.

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 well-structured with a clear opening sentence, then a compact paragraph covering behavior and edge cases. It is dense but not bloated; every sentence adds value. The only minor issue is the heavy use of ADR references and parentheticals, which could be slightly streamlined, but overall it is efficient and front-loaded.

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

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

Given the tool's complexity (destructive operation, commit behavior, idempotency, edge cases) and the presence of an output schema, the description covers all essential behavioral aspects: what gets deleted, what happens to the commit, how errors are handled, and how retries behave. The output schema handles return values, so nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds meaningful context beyond the schema: it explains the commit parameter's relationship to vault_write and ADR-018, and clarifies the idempotency_key's retry semantics. This goes beyond baseline schema coverage, earning a 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 opens with a specific verb and resource: 'Delete a single file from the vault', and immediately flags the destructive nature and recoverability via git. It distinguishes itself from siblings by noting it handles files only and rejects directories, and by contrasting with vault_write's deferred mode. This is unambiguous and clearly scoped.

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 this tool (delete a single file), what it does not do (directories rejected, no deferred mode), and how it differs from vault_write. It also explains the idempotency_key behavior for retries, giving an agent clear conditions for when a non-existent path is acceptable. This is strong 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?

Annotations already signal readOnlyHint and idempotentHint, and the description adds beyond that: the guaranteed server identity block, the all-projects default, and the parameter-gated behavior for drift detection and analytics. There is no contradiction with annotations.

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

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

The description is compact and front-loaded: the one-line purpose is followed by the guaranteed output block and then a clean list of conditional behaviors. Every sentence carries necessary information without 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 the fully documented schema, the presence of an output schema, and read-only/idempotent annotations, the description covers what the tool returns, how parameters change the response, and what the default behavior is. Nothing essential is missing for safe, correct invocation.

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

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

Schema coverage is 100%, so each parameter is already documented with defaults and meaning in the input schema. The description reinforces the conditional relationships between parameters and behavior, but does not add substantial meaning beyond the schema, so the baseline of 3 applies.

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

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

The description begins with a specific verb and resource: 'Return vault health metrics, validation, and optional usage analytics.' It clearly distinguishes this tool from content-oriented siblings like vault_list, vault_query, and vault_ask by focusing on health, drift detection, and runtime/usage metadata.

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 spells out the main behavioral modes: no parameters means a health summary for all projects, checks trigger drift detection, and include_usage/include_runtime append specific blocks. It does not explicitly name alternative tools, but the conditional usage is clear enough for an agent to know when this tool applies.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds the core behavior of listing projects/files but does not disclose additional details like sorting, pagination, or the effect of the pattern parameter (though the schema covers it). It is consistent with annotations and adds some context, but not rich behavioral depth beyond the annotations.

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

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

Two sentences with zero fluff. The core action is front-loaded, followed by two clear usage examples. Every sentence earns its place, making it efficient and 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?

The tool is simple (list projects/files) and has an output schema, so the return format is defined. Annotations cover side effects, and the description covers the primary invocation modes. It doesn't mention the subpath alias or pattern parameter, but those are fully documented in the schema. Overall, nothing critical is missing for a read-only list tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description implicitly explains the project parameter (with/without project) and path usage via the two invocation modes, but it does not add syntax or format details beyond what the schema already provides. It adds marginal value by clarifying the default behavior, but not enough to exceed the baseline.

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

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

The description clearly states the tool lists vault projects or files within a project, with a specific verb and resource. It distinguishes between the two modes (no args vs. with a project). However, it does not explicitly differentiate from sibling tools like vault_search or vault_query, which might also list/filter content, so it's not a 5.

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

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

The description explains how to invoke the tool with or without a project, which is internal usage. It provides no guidance on when to choose this tool over alternatives such as vault_search (for content search) or vault_query (for structured queries). The absence of any reference to siblings leaves the agent to infer the appropriate tool, which is a significant gap given the overlapping toolset.

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

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

With annotations only carrying false boolean hints, the description adds substantial behavioral detail: 3-pass cascading match, sequential patch application, all-or-nothing validation, and the auto-commit side effect. The commit parameter description further clarifies the default queue-for-reconciler path, so there is no misleading gap.

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

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

Four short paragraphs, each earning its place: summary, mode selection, validation constraint, and matching algorithm. It front-loads the core purpose and avoids restating schema definitions or adding filler.

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

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

For a 9-parameter tool with an output schema, the description covers all invocation-critical behavior: mode selection, uniqueness constraint, atomic failure, matching semantics, and commit behavior (with a pointer to the durability contract). An agent has enough to select and invoke the tool correctly.

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

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

Schema coverage is 100%, and the description goes beyond per-field docs by explaining how find/replace relate to patches, that patches apply in sequence, that each find must be unique, and that modes cannot be mixed. This adds real cross-parameter meaning rather than repeating 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 opens with 'Surgical find-and-replace in a vault file with auto git commit,' which names a specific operation, resource, and side effect. This clearly differentiates it from the sibling vault_write/vault_delete tools by emphasizing targeted in-place edits, and the mode details reinforce 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?

It gives explicit usage rules: single mode via find/replace, multi mode via patches, 'Do not mix both modes,' and the validation requirement that each find must appear exactly once. It lacks explicit when-not guidance naming alternatives (e.g., vault_write for whole-file overwrites), so it doesn't earn a 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, which cover the safety profile of this read-only operation. The description adds no behavioral detail beyond 'read content' — nothing about truncation, metadata prepending, or section-versus-path behavior — though those are documented in the schema. There is no contradiction between the description and the annotations.

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

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

The description is a single, front-loaded sentence with no filler, and the 'instead of direct filesystem access' clause adds meaningful guidance. It is concise and scannable. However, it is minimal enough that it misses a natural opportunity to point to alternative vault tools.

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 rich input schema, output schema, and read-only annotations, an agent can determine how to invoke the tool correctly without extra description. The description alone, though, does not situate vault_query among the twelve sibling tools, particularly vault_ask and vault_search, so selection context is incomplete. The overall package is adequate for invocation but not fully complete for optimal tool choice.

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

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

Schema description coverage is 100%, and each parameter already has a detailed description covering path, project, section, max_lines, identifier, and include_metadata. The tool description itself contributes nothing about parameters. Baseline 3 is appropriate because the schema carries the full semantic burden.

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

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

The description identifies a specific action ('Read content') and resource ('vault project'), so the core function is clear. It does not, however, differentiate vault_query from siblings like vault_list, vault_search, or vault_ask, all of which also involve retrieving information from the vault. It avoids tautology and is more informative than the title alone.

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

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

The phrase 'use instead of direct filesystem access' gives a useful policy context: when an agent would otherwise read files directly, it should use this tool instead. It does not say when to prefer vault_query over vault_list, vault_search, or vault_ask, nor does it provide any exclusions. This is a clear but incomplete usage signal.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds mode-specific behavior (e.g., rank_by != 'bm25' limits to lessons-only) but does not disclose other behavioral traits like performance, pagination details, or the interaction of aliases. Given the annotations, this is adequate but not rich.

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

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

The description is concise, front-loaded with the core purpose, and uses a compact bullet-like structure to list modes. Every line adds value, and there is no fluff. It could be slightly more structured, but it is efficient and readable.

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

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

Given the presence of an output schema and 100% schema coverage, the description does not need to explain return values or every parameter. It covers the primary modes and their key parameters, which is sufficient for an agent to understand how to invoke the tool correctly for common use cases. It does not mention all filters (tag, status, type), but those are self-explanatory in the 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?

With 100% schema coverage, the baseline is 3. The description adds meaningful semantics by explaining the effects of ranked, since_days, and rank_by parameters, including that rank_by != 'bm25' restricts to lessons-only and ranks by usage. This goes beyond the schema's property descriptions and clarifies intended 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 'Search the vault' and enumerates three distinct modes (flat, ranked, recent) plus a rank_by variant, giving a specific verb and resource with mode distinctions. However, it does not explicitly differentiate from sibling tools like vault_query, so it doesn't fully separate itself from alternatives.

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

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

The description provides usage guidance for its own modes (when to use ranked, recent, rank_by) but never mentions when to use this tool versus other vault-related tools like vault_query or vault_list. There is no explicit 'use this for X, use that for Y' guidance, so the tool-level selection context 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?

The description adds meaningful behavioral context beyond the annotations: auto-generated frontmatter, mode-specific requirements, and operation inference. However, it does not disclose the deferred-commit behavior (only present in the schema) or explicitly note that 'replace' overwrites existing section content. No contradiction with the annotations was found.

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

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

The description is front-loaded with the core purpose and then uses a compact bulleted mode list that maps cleanly to parameters. Every sentence earns its place; there is no filler or redundant restatement of the schema.

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

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

Given 8 parameters and a rich output schema, the description covers the key mode-selection logic well. However, it omits the important deferred-commit/durability behavior and does not contrast the tool with siblings like vault_patch, which would help an agent choose the correct tool at a glance. The schema fills many gaps, but the description itself is not fully complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying that section is behaviorally required for append/replace and path for create, even though these are not schema-level required fields, and by explaining the operation inference rule. This exceeds 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 states a specific verb and resource ('Write to the vault') and enumerates the three operation modes (append, replace, create), making the core purpose clear. It does not explicitly distinguish itself from siblings like vault_patch, so it misses the top-tier differentiator required for a 5.

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

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

The description gives clear when-to-use context within the tool: append/replace requires a section, create requires a path, and operation is inferred when path is set with no section. It does not state when to prefer an alternative sibling tool, but the internal mode guidance is strong and unambiguous.

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

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

Annotations already declare read-only and idempotent, and the description adds material behavioral context: reachability is probed, not inferred; configuration and reachability are reported separately; and dollar-budget fields were removed as misleading. This tells an agent not to treat 'configured' as 'answering' and explains why no budget gauge appears. No contradiction with annotations.

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

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

The opening sentence is crisp and front-loaded. However, most of the text is a historical rationale about HIVE-384 and the old dollar budget; it supports understanding but is longer than needed for a one-parameter status tool.

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

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

For a read-only, idempotent tool with one optional parameter and an output schema, the description is sufficient: it states what is shown, clarifies the key semantic guarantee of probed reachability, and the schema covers parameter details and return shape. An agent has what it needs 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 single parameter include_models is fully documented in the input schema (100% coverage), including its default and effect of avoiding a network call when false. The description itself adds no parameter-specific meaning, so the schema carries the burden. Baseline 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 first sentence names a specific verb ('Show') and resource ('worker health') and enumerates the four aspects reported: configuration, reachability, model, and usage. The 'worker' framing clearly separates it from the vault_* siblings, including vault_health, so there is no ambiguity about what it targets.

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 makes the intended use context clear — checking worker health/status — but never states when to prefer this tool over an alternative or when not to use it. There is no explicit exclusion or sibling routing, and guidance is implied rather than explicit.

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