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

With no annotations, the description carries the full behavioral burden, and it discharges most of it by disclosing the substantive contents of the response — tested status, project count, recorded disagreements, change blast radius, and acknowledged unknowns. It does not explicitly state that this is a pure read operation or note any cost/format constraints, but nothing is contradicted.

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 what the tool returns and ending with the usage condition. The first sentence is a dense list but every item earns its place by signaling a distinct return dimension.

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

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

No output schema exists, so the description must convey return content — and it does, enumerating the components of the epistemic state. For a single-item lookup this is nearly sufficient; only response format or aggregation behavior is left unspecified.

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

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

There is a single parameter with 100% schema description coverage ('note path, basename, or distinctive substring'), so the schema fully documents it. The description adds no further lookup-syntax guidance, making the baseline 3 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 names a specific resource (one rule or note) and enumerates the dimensions of its 'epistemic state' — grounding, testing, disagreements, blast radius, unknowns. That is far more informative than a generic getter, though it never distinguishes itself from siblings like vault_impact (blast radius) or vault_get (generic retrieval).

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 two explicit triggers: 'Use before relying on a rule, and before changing one.' That is clear context for invocation. It stops short of naming an alternative or an exclusion (e.g., when vault_impact or vault_gaps is the better choice), so it sits just below the top band.

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 usefully discloses the data source (the notes' own callouts) and implicitly frames this as a read operation, but says nothing about pagination, limit behavior, ordering, or what the results look like.

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

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

Two tight sentences, front-loaded with the resource definition and followed by the actionable directive. Every clause earns its place 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?

Purpose and timing are well covered, but with no annotations, no output schema, and 0% parameter coverage, the definition leaves the calling mechanics (what `query`/`limit` do, what comes back) unexplained for an agent trying to invoke it correctly.

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

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

Schema description coverage is 0% and the description explains neither `limit` nor `query`. An agent cannot tell whether `query` filters the gaps, searches the notes, or something else, and there is no hint about default or bounds for `limit`.

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 and distinctive resource: gaps the vault admits it doesn't know, sourced from [!todo] and [!question] callouts. This clearly separates it from generic siblings like vault_search or vault_get. It lacks a crisp verb, but the scope and data source are 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?

It gives an explicit when-to-use condition: 'Read this BEFORE proposing a new direction', plus the rationale that the corpus may already record or have closed the gap. No named alternatives or when-not guidance, so it stops short of a 5.

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

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

No annotations are provided, so the description carries the full burden. It says what is returned but not that this is a read-only retrieval, what happens for a missing/ambiguous note, or whether the identifier is a path, title, or ID. For a tool with zero annotation coverage, this is thin.

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

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

Two short fragments, zero waste, with the primary outcome front-loaded before the usage hint. It borders on under-specification rather than verbosity, but the structure is sound.

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

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

The simple shape (one required param, no output schema, no annotations) is partly covered: return content ('full markdown') is stated. However, identifier format and failure behavior for a missing note are unaddressed, which an agent needs to call it correctly.

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

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

The single 'note' parameter has 0% schema description coverage, and the description only restates that it targets 'one note'. It never clarifies the identifier format (name vs. path vs. slug) or whether it is case-sensitive, leaving the only parameter effectively undocumented.

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

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

States a specific resource and scope: 'Full markdown of one note.' The word 'Full' implicitly contrasts with vault_skeleton (outline) and vault_search (matching), so an agent can roughly separate it from siblings, though no sibling is named. Not a tautology.

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

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

'Use after pack/search to drill in' gives an explicit ordering/context: call this to expand a note surfaced by those tools. It names alternatives and a triggering condition, but offers no when-not guidance or mention of what to use if the note isn't found.

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 load and does so well: it discloses the transitive-by-default behavior, quantifies how badly depth-1 understates impact (median 3.9x, up to 9.5x), and explains what each semantics mode follows ('Governed by' vs 'Read first'). It omits return format and cost/performance, but the behavioral core is genuinely disclosed.

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

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

Front-loaded with a clear one-line purpose, then rationale and mode semantics. It is dense and jargony ('Governed by', 'framework note', the multiplier statistics), but each sentence carries information rather than 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 3-param analytical tool with no output schema and no annotations, the description supplies the semantics of both meaningful parameters and the default behavior, enough to call it correctly. It does not describe the shape of the returned set, which an agent might want.

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

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

Schema coverage is only 33% (note is undocumented; semantics has enum values but no description), so the description must compensate. It adds substantial meaning for semantics, distinguishing 'falsified' from 'needs_reread' by edge type and framing the resulting question, and clarifies deep implicitly via the transitive-vs-depth-1 contrast.

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 phrase 'blast radius of changing a note' states a specific resource and operation, and the transitive-vs-depth-1 discussion pins down exactly what is computed. It stops short of contrasting itself with graph-adjacent siblings like vault_neighbors or vault_load_bearing, so an agent must infer the difference.

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?

'Run before editing any framework note' is explicit when-to-use guidance scoped to a class of notes. It does not name an alternative tool or state exclusions (e.g., when depth-1 or neighbors is preferable), so it falls short of full routing guidance.

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

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

With no annotations, the description carries the full burden. It usefully discloses the character of the result (bimodal: a few notes at 30-50% falsification, most at none) and the semantics of the ranking, which is real behavioral value. It says nothing about truncation via limit, cost, or what the returned records look like.

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

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

Three short sentences, front-loaded with what the tool returns. The middle sentence is domain flavor but it does convey the actual distribution an agent will see, so it earns most of its space.

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

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

No annotations, no output schema, and two undocumented parameters with zero schema coverage. The description covers the ranking concept but not what a call actually returns or how limit/semantics shape it, leaving the agent under-informed for a tool with this much structured ambiguity.

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 neither parameter is explained. The description only implies the default "falsified" semantics; the "needs_reread" enum value and the limit/pagination behavior are left entirely undocumented, so it fails to compensate for the coverage gap.

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

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

The first sentence states a specific operation: rank every note by how much of the vault a change to it would falsify. That is a clear verb+resource, well beyond a tautology. It does not, however, differentiate itself from the sibling vault_impact, which sounds like it could compute a similar thing.

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

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

"Use this to decide where to be careful" gives an intended purpose, but there is no when-not guidance, no prerequisites, and no routing against the ten sibling tools (notably vault_impact). Usage is implied rather than specified.

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 supplied, so the description carries the full behavioral burden. It does disclose genuinely useful semantics — that the eight buckets have unequal strength and what each family means — but omits default behavior when 'buckets' is omitted, error handling for unknown notes, and any read-only assurance.

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 what the tool returns, then the payoff sentence on bucket hierarchy. Dense but not padded; the only weakness is the clipped noun-phrase opening.

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 two-parameter read tool with no annotations and no output schema, the description covers the conceptual output structure well but leaves the default bucket set, per-neighbour return shape, and note identifier expectations unspecified.

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

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

Schema coverage is only 50% and there are no enums, so the description must compensate. It names six of the eight valid bucket values (Governed by, Read first, Source, Evidence, Applied in, See also) and explains their relationships, which the schema's bare 'comma-separated subset' does not; it stops short of listing all eight or the exact token format.

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

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

The description names the resource ('neighbours of a note') and the qualifier 'typed', so an agent can tell it returns graph-related notes rather than note content (vault_get) or a search result set. It lacks a verb and makes no explicit sibling contrast, but the scope is unambiguous.

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

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

There is no statement of when to call this versus vault_get, vault_impact, or vault_gaps. The bucket commentary describes how to interpret output, not when the tool is the right choice, so usage is only faintly implied by the resource name.

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 and does substantial work: it discloses a token budget, that results are ranked and provenance-annotated, and what each result is annotated with (why matched, grounded-by, constraints, applicability). It stops short of stating it is strictly read-only, what happens when nothing matches, or any result-size guarantees beyond the budget framing.

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

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

Three sentences, front-loaded with what the tool is, then what it returns, then when to use it. Dense but every clause carries information; minor jargon ("provenance-annotated", "what constrains it") costs a little clarity without bloat.

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

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

With no annotations and no output schema, the description is the sole carrier of behavior and it adequately explains the return shape and the raison d'être (cheaper than reading whole notes). Gaps remain around the undocumented k and full_body parameters and any failure/empty-result behavior, but nothing essential to calling it correctly is absent.

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

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

Schema description coverage is only 40%, so the description needs to compensate and only partly does: "Budgeted" maps to budget_tokens and "grounded" maps to grounded_only, but k and full_body are never addressed in prose. Baseline 3 is appropriate given the schema's partial coverage and the description's partial fill of the gap.

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

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

The description names a specific resource (a budgeted, provenance-annotated context pack for a task or question) and states what it returns: ranked notes annotated with match reasons, grounding, constraints, and applicability. It implicitly separates itself from siblings like vault_search and vault_get by framing itself as the cheaper first-pass reader, though it never names those siblings directly.

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

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

"Use this first for any question about how to do something in this vault" gives clear when-to-use guidance and positions the tool ahead of alternatives ("Cheaper and more trustworthy than reading whole notes"). What is missing is an explicit when-not / routing rule naming the sibling tools (vault_search, vault_get, vault_load_bearing) for cases this tool does not cover.

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 of behavioral disclosure. It mentions output features (match explanation, provenance) but does not state that the operation is read-only, whether it has side effects, or any permission requirements, leaving important behavior unspecified.

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 wasted words. It is appropriately concise, though its brevity contributes to gaps in other dimensions rather than being a structural flaw.

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 five parameters, low schema coverage, no annotations, and no output schema, the description is incomplete. It omits parameter explanations, usage context, and sufficient return detail to fully guide correct invocation.

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

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

Schema description coverage is only 20%, and the description does not explain any of the five parameters. It does not clarify what k, layer, status, or grounded_only do, nor does it add meaning beyond the parameter 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 states a specific resource (notes) and the operation (ranked retrieval for a query), plus output features (match explanation, provenance). It is clear enough to distinguish from most siblings, but it does not explicitly differentiate from vault_get or vault_neighbors, keeping it at 4 rather than 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?

There is no guidance on when to use this tool versus alternatives like vault_get or vault_neighbors. The description only says what it returns, not the context or conditions under which it should be chosen.

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, so the description carries the full burden. It discloses token cost (~29k, 18% of corpus) and behavioral scope (no bodies) — genuinely useful context for planning whether to hold it in context. It doesn't disclose auth or freshness/caching 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?

Two sentences, front-loaded with the scope and followed by the usage rationale. Every clause earns its place — token count and corpus percentage are concretely useful.

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 zero params, no annotations, and no output schema, the description does a good job of framing scope and cost tradeoffs. Could be stronger by stating what the agent is expected to do with the skeleton next (e.g., pair with vault_get for bodies).

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?

Zero parameters, so the baseline is 4. The description correctly implies the parameterless nature by framing it as a whole-vault view.

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

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

States a specific resource ('every rule and every typed relation in the vault') with scope exclusions ('with no bodies'). Without named siblings, it doesn't explicitly distinguish itself from vault_load_bearing or vault_gaps, but the scope wording implies a complete-but-shallow view.

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 guidance: 'Small enough to hold for a whole session, which is usually better than repeated searching.' This steers the agent to prefer skeleton over vault_search for session-wide holds. It doesn't name which sibling to use when bodies ARE needed, which is a minor gap.

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 behavioral burden but discloses nothing beyond the return metrics. It does not state that the operation is read-only, nor does it mention any permissions, side effects, 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 a single, front-loaded sentence with no wasted words. It efficiently communicates the key return categories.

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 no-parameter, read-only stats tool, the description lists the returned metrics but omits details about format (e.g., counts vs percentages) and does not clarify domain-specific terms like 'layer' and 'provenance'. It is adequate but leaves notable gaps.

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

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

The tool takes no parameters, so there is nothing to document in the description. The baseline score for zero parameters is 4, and the description adds no misleading parameter 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 metrics returned: index size, layer and provenance distribution, and freshness. It distinguishes from siblings by being a read-only stats report rather than a search or retrieval action. However, it lacks a specific verb like 'retrieve' or 'get', so it stops just short of 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?

There is no explicit guidance on when to use this tool versus alternatives. The implied usage is to obtain vault statistics, but the description gives no context about prerequisites or conditions that select it over siblings.

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