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

With no annotations, the description carries the full burden and does disclose meaningful behavior: the target folder, the dated-filename renaming, the added header, and the no-hard-delete guarantee. It omits what happens to backlinks/links, whether the note stays indexed, and permission requirements, so it is useful 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 front-loaded sentence that states the action and its most important trait (no hard deletion) with zero 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?

The output schema means return values need no explanation, and the core operation is described. However, with 0% parameter coverage and no annotations, the definition leaves path/vault semantics and link-handling behavior undocumented for an 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% across 3 parameters, so the description must compensate. It only hints at 'reason' (the header recording why); relative_path and vault are entirely unexplained, leaving the schema to speak for itself with no help.

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

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

States a specific verb and resource (move a note), the destination (99-Archive/), and the transformation (dated filename plus a why-header). An agent can distinguish it from siblings like delete_node. It stops short of naming a sibling explicitly, so it lands just below the top band.

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

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

The clause 'nothing in the vault is ever hard-deleted' implies this is the non-destructive alternative to a delete, but the description never explicitly says when to archive versus delete_node or other mutation siblings. Usage is implied rather than stated.

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

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

With no annotations, the description carries the full burden and does disclose the two most important traits: the operation is irreversible and it requires confirm=True. It stops short of covering auth/permissions, what happens to a null vault, or any confirmation of the response, so it is strong but not exhaustive.

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, no waste, and the destructive scope plus irreversibility are front-loaded ahead of the confirm gate. 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?

An output schema exists, so return values needn't be described, but the description leaves a meaningful gap for a destructive, unannotated tool: the semantics of a null/missing vault (default vault vs. none) are undefined, which directly affects whether the call does anything.

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 for both parameters. It explains 'confirm' (must be True) but says nothing about 'vault', which is nullable with default null — leaving the critical question of which vault gets wiped (default? all?) completely unresolved.

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

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

States a specific verb ('wipe') and scope ('every node and edge for a vault'), which cleanly distinguishes it from siblings like delete_node, delete_edge, and archive_note that operate on single entities. An agent can tell instantly that this is a full-graph destruction tool.

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

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

Usage is implied by the destructive scope, but no explicit when-to-use/when-not guidance or named alternatives (e.g. 'use delete_node for a single node') are given. An agent must infer that this is a last-resort, whole-vault operation.

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 it explicitly declares 'read-only', establishing the safety profile. An output schema exists, so return-value detail is not required here. It adds no auth, cost, or performance context, but for a read-only reporting tool the key behavioral trait is 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?

Two tight sentences: the first establishes what it produces, the second the cadence and trigger. Front-loaded and efficient, with only the internal 'Instructions.md Sec.7' reference adding mild opacity.

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 report with an output schema, the description covers what it does and when to run it, which is largely sufficient. The only gap is the undocumented vault parameter, a minor omission given its optionality.

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 optional 'vault' parameter has 0% schema description coverage, and the description never mentions it or its default-null behavior. For a low-coverage schema the description should compensate, but it provides no parameter meaning at all.

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

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

The description names a specific deliverable (a read-only consolidation report) and enumerates its contents: decayed notes, isolated graph nodes, and divergence issues. This distinguishes it from siblings like detect_divergence or graph_stats, which cover only subsets. The framing as 'The Instructions.md Sec.7 consolidation ritual' is a bit indirect but the purpose remains identifiable.

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

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

Gives explicit trigger conditions: 'Run this every ~10 sessions, or when asked to "consolida".' This is clear when-to-use guidance. It does not, however, name alternatives (e.g., when to prefer detect_divergence for a targeted check), so it stops short of full routing guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing beyond the operation itself. It does not say what happens if the edge does not exist, whether the operation is idempotent, whether it cascade-deletes adjacent structure, or whether special permissions are needed. For a destructive mutation with zero annotation coverage this is a substantial 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?

A single sentence with no waste that front-loads the verb and the resource. Nothing redundant is present.

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

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

The presence of an output schema means return values need not be explained, but as a destructive operation with no annotations the description should say more about failure modes and side effects. What exists is coherent but thin 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?

Schema description coverage is 0%, so the description must compensate, and it partially does by framing (src, dst, type) as the identifying key — semantics the bare string types do not convey. However, the fourth parameter 'vault' goes unmentioned, and there is no indication of expected formats (node IDs vs. names) for src/dst/type.

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

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

States a specific verb ('Remove') and resource ('one edge') plus the composite key that identifies it, which is more precise than the bare tool name. It does not explicitly contrast itself with siblings such as delete_node or upsert_edge, but 'edge' plus 'remove' is unambiguous against them.

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 rather than delete_node, upsert_edge, or clear_graph. The description only says what it does, leaving the agent to infer that this is the single-edge deletion path versus clear_graph or delete_node.

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 and does well: it discloses that the default is a soft delete that hides the node from reads while retaining the row, and that hard=True cascades to delete every touching edge irreversibly. It doesn't mention permissions/auth, rate limits, or whether downstream references break.

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 action and then the mode semantics. Every clause adds information; nothing is redundant or pad.

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

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

An output schema exists, so return values need not be explained, and the description focuses appropriately on mutation semantics. The main gap is the unexplained 'vault' parameter and lack of guidance relative to sibling tools like archive_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?

Schema coverage is 0%, so the description must compensate, and it does for the two meaningful parameters: 'hard' is explained via its default-vs-irreversible semantics, and soft-delete behavior is tied to the default. The 'vault' parameter is never addressed, which would matter for multi-vault scoping.

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

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

States a specific verb and resource ('Remove a node') and immediately distinguishes the two deletion modes. It does not name or contrast a sibling, so it stops short of the 5-level sibling differentiation.

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

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

Usage is implied through the soft/default vs hard distinction, giving the agent a sense of when hard deletion is warranted. However, there is no explicit guidance on when to prefer this over archive_note or clear_graph, nor any prerequisite or caution framing.

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 does declare read-only behavior and that nothing is deleted automatically, which is valuable safety context for a detect/audit tool, though it doesn't mention performance, vault scope behavior, or that an output schema exists.

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 clauses front-loading the detection target and immediately following with the safety profile. Zero waste, well 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?

Output schema exists so return values needn't be explained, and the safety profile is covered. The main gap is the vault parameter's semantics, which is left entirely unexplained given 0% schema coverage. Given the diagnostic nature and output schema presence, the description is largely complete but has that one hole.

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

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

Schema coverage is 0% and there is one parameter (vault, optional, nullable). The description doesn't explain what the vault parameter means or its default behavior (scoping to a single vault vs all). The baseline for 0-param is 4, but here there is one undocumented param that the description fails to compensate for.

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

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

States a specific verb (Find) and clear resource (nodes/notes pointing at paths that no longer exist, plus dangling edges), which is concrete and distinguishable from siblings like reindex_paths or sync_note_links. It's clear what the tool does, though it doesn't explicitly name the sibling it contrasts with.

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

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

Usage is implied by the diagnostic nature of the operation -- you'd use it to audit for broken references before reindexing or cleaning up. However, there is no explicit 'when to use this vs reindex_paths/sync_note_links' guidance or prerequisite statement, so the agent must infer the workflow 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?

No annotations are provided, so the description carries the full burden. 'Fetch' implies a read-only operation, but it does not disclose permission needs, error behavior when the id is missing, or the role of the vault parameter. It adds little beyond the name get_node.

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

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

A single, front-loaded sentence with no wasted words. It states the action, object, and lookup constraint efficiently.

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 and has an output schema, so return values need not be explained. However, with no annotations and 0% schema coverage, the description leaves the vault parameter and usage context unexplained, which is a meaningful gap.

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 there are two parameters. The description clarifies that 'id' is an exact match, but it never mentions the optional 'vault' parameter or its default, leaving a key parameter undocumented.

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

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

States a specific verb ('Fetch') and resource ('node') with a clear lookup mode ('by its exact id'). This separates it from list/search tools, but it does not name or compare any sibling alternative.

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 instead of search_nodes, neighbors, or read_note. The phrase 'by its exact id' implies the precondition of already knowing the id, but alternatives and exclusions are absent.

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

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

No annotations are supplied, so the description carries the full burden. 'Report' plus a reachability check implies a non-mutating diagnostic, and it discloses what is inspected, but it never states that nothing is modified, whether the probe can fail/timeout, or any permission requirement.

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 sentence with no filler, leading with what is reported and following with the reachability condition. Slightly dense but nothing is wasted.

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

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

One optional parameter, no annotations, and an output schema that already documents return values, so the description need not explain the response. What it covers is adequate; only the omission of any usage trigger holds it back.

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

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

Schema coverage is 0%, so the description must compensate, and it does: it establishes that the vault argument is optional ('requested (or default)') and that a fallback default vault is used when omitted — meaning the schema's bare string/null property and null default do not convey. It stops short of naming the parameter or its accepted 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 names a specific verb ('Report') and two concrete resources: configured vaults and the reachability of a vault's graph store. That is enough for an agent to distinguish it from data-oriented siblings like graph_stats or list_notes, though it never explicitly names which siblings are adjacent.

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

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

Usage is only implied: an agent can infer this is a health/configuration probe, but the description gives no explicit when-to-use trigger (e.g. before indexing or when operations fail) and names no alternatives or exclusions.

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 almost nothing. It does not state that the operation is read-only, whether it is scoped by vault, whether results are cached, or anything beyond the summary of the returned metrics.

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 terse fragment. It is short, but this reflects under-specification rather than deliberate conciseness — there is no front-loaded statement of purpose or scope to earn 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?

An output schema exists, so return values need not be explained, but for a tool with no annotations, no parameter documentation, and no usage guidance the description is too thin. An agent cannot tell when to reach for it or how the vault argument changes the result.

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

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

Schema description coverage is 0% and the single 'vault' parameter (optional, default null) is never mentioned in the description. With low coverage the description is expected to compensate, but it adds no meaning about what scoping the vault parameter 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 fragment 'Node/edge counts by kind and type' is specific about the resource (graph nodes/edges) and the shape of what it returns (counts grouped by kind and type). It distinguishes the tool as a read-only stats/aggregate tool, though it provides no verb and no explicit differentiation from siblings like get_status or neighbors.

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

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

There is no when-to-use guidance and no mention of alternatives. The agent is not told whether this should be preferred over get_status for inspecting graph health, nor under what conditions to call 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?

With no annotations, the description carries the full burden, yet it never states that the operation is read-only, how deep or expensive the traversal is, or whether a vault/permission scope is required. It does add real value by naming the semantic categories returned (needs vs. depends-on vs. exercises vs. DANGER), which goes beyond raw structure, but behavioral traits like cost and safety are unstated.

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

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

A single front-loaded sentence stating purpose first, then the payload categories. Every clause earns its place and there is no filler or repetition.

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

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

The presence of an output schema means return structure need not be explained, and the description usefully glosses the result labels. However, with 0% parameter coverage and no annotations, an agent still lacks the input-format details and cost/auth context needed to invoke this confidently, so it is only minimally complete.

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

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

Schema description coverage is 0%, so the description must compensate for the two undocumented parameters and it does not. It never clarifies what form `id` takes (node ID? path? note?), nor what `vault` selects or how the null default is resolved.

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

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

The description gives a specific function — impact analysis for a single node — and enumerates the distinct result categories (MUST_READ, MAY_CHANGE, MUST_TEST, documentation, DANGER), which makes it clearly separable from graph-walking siblings like neighbors or path_between. It stops short of naming those alternatives explicitly, so it is clear but not sibling-routing.

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

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

There is no when-to-use or when-not-to-use guidance, and no alternative tool is named. The reader must infer the use case (e.g. assessing blast radius before a change) purely from the list of returned categories, leaving no explicit context or exclusions.

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 disclosure burden. It usefully explains the semantics of the edges produced (files changing together without an import link), but omits whether it writes edges into the graph, whether it is idempotent, its cost on large histories, or any required permissions.

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

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

A single front-loaded sentence with a colon-delimited clarification; nothing is wasted. It is tight, though one extra clause on parameters could have been spent 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?

The output schema exists so return values needn't be described, but the tool evidently mutates graph state and the description says nothing about that effect, and it leaves all three parameters undocumented. Adequate for purpose, incomplete for correct invocation.

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

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

Schema coverage is 0%, so the description must compensate for three parameters and does not. In particular min_shared_commits (default 3) is a non-obvious threshold that is never explained, and vault versus repo scoping is left ambiguous.

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

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

States a specific verb ("Derive") and resource ("co_edit edges") and the source ("this repo's git history"), with a clarifying gloss on what co-edit means. It is distinguishable from siblings like index_repo, though it doesn't name any alternative explicitly.

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

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

No when-to-use, when-not-to-use, or prerequisite guidance. The description implies the operation only through its subject matter and never tells the agent when this is preferable to index_repo, reindex_paths, or detect_divergence.

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 it well: it discloses that the operation wipes and rewrites scanner-origin rows and explicitly states that manual/git-origin rows are preserved — the key destructive-scope fact. It does not mention permissions, runtime/long-running behavior, or whether it blocks, which is the remaining 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?

A single front-loaded sentence that delivers the destructive scope and the preservation guarantee with zero filler. 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?

An output schema exists, so return values need no explanation, and the destructive semantics are covered. However, for an unannotated mutation tool, the vault parameter is left completely undefined and no auth/prerequisite context is given, leaving a real gap.

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

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

Schema description coverage is 0%, so the description must compensate. It implies the 'repo' argument ('one configured repo') but never clarifies the expected identifier form, and the 'vault' parameter is entirely unaddressed in both schema and description.

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

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

States a specific verb and resource ('Full (re)index of one configured repo') and scopes it precisely to scanner-origin nodes/edges. The scanner-vs-manual/git-origin split implicitly separates it from siblings like index_git_coedits and reindex_paths, though no sibling is named outright.

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

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

Usage is implied by the phrase 'one configured repo' — an agent can infer this is the full-repo rebuild versus a path-scoped reindex. But there is no explicit when-to-use/when-not statement and no alternative is named, so the agent must infer routing from the sibling list alone.

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 behavioral burden. Saying it returns "note paths" is a useful hint about output shape, but it omits ordering, recursion into subdirectories, pagination/limits, and permission requirements for a vault read.

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

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

A single front-loaded sentence with zero filler; the scoping clause is placed immediately after the core purpose. It is arguably terse rather than bloated, which is the right failure mode.

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

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

An output schema exists, so return values need not be described, and the tool has only two optional parameters. Still, with no annotations and 0% schema coverage, the description leaves open whether the listing recurses and how the vault argument defaults.

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

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

Schema coverage is 0%, so the description must compensate. It explains that subdir narrows the listing, but says nothing about the vault parameter (e.g., whether null means a default vault or all vaults) and does not state whether subdir is recursive.

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

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

States a specific verb ("List") and resource ("note paths") plus a scoping clause, so the agent knows exactly what comes back. It does not, however, distinguish itself from the closest sibling, search_vault, which is the key ambiguity an agent faces here.

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 parenthetical "(or under subdir)" implies a scoping use case but there is no explicit when-to-use guidance and no mention of alternatives like search_vault. Nothing tells the agent when to list versus search, or what prerequisites exist.

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, yet it only clarifies direction values. It says nothing about behavior on a missing id, vault scoping, or whether results are paginated or truncated.

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 with the core scope front-loaded and zero filler. It is efficient, though arguably terse to the point of under-specification.

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

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

An output schema exists so return values need not be described, but three of four parameters are undocumented and there is no routing guidance among the many graph siblings. For a graph-query tool in a dense sibling set, this leaves real 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?

Schema description coverage is 0%, so the schema documents no parameters. The description usefully enumerates the direction values ('out', 'in', 'both') that the schema omits, but leaves id, vault, and edge_types entirely unexplained.

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

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

States a specific resource and scope: 'one-hop neighbors of a node'. The 'one-hop' qualifier implicitly distinguishes it from transitive siblings like impact_of and path_between, though no sibling is named explicitly.

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

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

There is no when-to-use guidance and no mention of alternatives such as path_between or impact_of. The agent must infer from the name that this returns immediate adjacency only.

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, and it does disclose one meaningful trait: traversal goes 'either direction' (undirected). However, it says nothing about behavior on no-path-found, the max_hops cutoff, or cost, leaving significant gaps for a graph traversal 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?

A single, front-loaded sentence that states the operation first and the use case second, with no filler. Efficient and well-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?

The presence of an output schema relieves the description of explaining return values, and the directionality note helps. But with 4 undocumented parameters (0% coverage) and no annotations, the definition is thin for a traversal tool whose max_hops bound shapes results.

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

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

Schema description coverage is 0%, so the description would need to compensate, but it references only 'two nodes' generically. Key parameters like vault and especially max_hops (default 6, a critical traversal bound) are not explained at all.

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

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

The description names a specific operation (shortest connection between two nodes) and the resource (the graph), making the tool's output clear at a glance. It implicitly distinguishes itself from adjacency tools like neighbors and impact_of, though it never explicitly names a sibling it is not.

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 clause 'for "how are these two things related" questions' gives a concrete scenario that selects this tool over alternatives. There are no explicit exclusions or named alternatives, so it falls short of full when/when-not guidance.

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

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

No annotations, so description carries full burden. It discloses that the note is pre-filled with graph neighbors and written as status:'assumed' (skeleton, not verified), which is important behavioral context. It doesn't cover permissions or return value, though an output schema exists.

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?

Compact, front-loaded with the core action and destination, followed by behavioral caveat and usage note. No filler, but slightly dense with inline references.

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?

Output schema exists, so return values need not be explained. For a mutation tool without annotations, the description covers key behavior (auto-fill, assumed status) and usage restraint, but leaves parameter meanings vague and doesn't state permissions or side effects on the graph.

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

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

Schema coverage is 0% for 4 parameters, so the schema does not describe them. Description only implicitly names node (graph node) and body (prose, implied not verified). vault, extra_frontmatter, and body semantics are not explained, so it does not compensate for the coverage gap.

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

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

States a specific verb (materialize/promote) and resource (graph node -> curated note) with precise output location (20-Knowledge/codebase/{files,symbols,features}). Clearly distinguishable from write_note (writing prose) and upsert_node (graph mutation).

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 use: 'promote sparingly, per Instructions.md Sec.12: not every file earns a note.' Gives a usage posture but doesn't name a direct alternative or a when-not condition beyond scarcity.

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. 'Read' correctly conveys a non-mutating operation and it discloses what is returned (frontmatter + body), but it says nothing about behavior when a note is missing, vault resolution, or permissions.

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

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

A single front-loaded sentence with no filler; every word earns its place. It is efficient, though the extreme brevity contributes to the gaps scored elsewhere.

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

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

An output schema exists so return values need not be described, but two undocumented parameters, zero annotations, and no error/edge-case context leave the agent without enough to invoke this confidently beyond the trivial case.

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 mentions neither parameter. The meaning of 'vault' (default null, presumably default vault) and the expected format of 'relative_path' (relative to what?) are left entirely unexplained at the call site.

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

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

States a specific verb (read) and resource (one note) and even names what is returned (frontmatter and body). It does not explicitly contrast with siblings like list_notes, search_vault, or get_node, but 'one note' implicitly scopes it to single-note 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?

The word 'one' hints at single-note retrieval, but there is no explicit when-to-use guidance, no exclusions, and no alternative named (e.g., search_vault for locating a note, list_notes for enumeration). An agent must infer the routing.

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

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

No annotations exist, so the description carries the full burden. It usefully discloses that the operation is incremental and only touches the given paths, but says nothing about idempotency, how stale/removed paths are handled, auth requirements, or whether it is synchronous. Partial disclosure against a high bar.

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

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

A single front-loaded sentence that leads with the action and scope, then appends the usage trigger. No wasted words, though the '--' clause makes it slightly dense.

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

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

An output schema exists, so return values need not be explained. However, for a 3-parameter mutation with zero annotation coverage, the description leaves the vault parameter and the effect on deleted or renamed paths unaddressed, so it is adequate but incomplete.

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 clarifies that 'paths' are repo-relative ('relpaths') and that 'repo' scopes the operation, but the third parameter 'vault' is never mentioned, and no format or syntax details are provided for any parameter.

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

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

States a specific verb (reindex), a scoped resource (just these relpaths), and the modifier 'incremental' that distinguishes it from a full index_repo. An agent can tell it is a partial, path-targeted operation without opening the schema, though it never explicitly names the sibling it contrasts with.

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

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

Gives a clear trigger condition: 'call this after editing files so the graph does not drift from the code.' That is strong when-to-use guidance. It stops short of explicitly contrasting with index_repo or listing when-not-to-use (e.g. large-scale changes).

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 key trait that edges are preserved across the move, which is exactly the non-obvious behavior an agent needs. But it omits other behavioral facts: what happens if new_id already exists, whether old_id must exist, permission requirements, and the vault parameter's role.

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

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

A single front-loaded sentence with the core action first and the clarifying rationale in a parenthetical. Efficient and free of padding, though the example clause is somewhat dense.

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

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

An output schema exists, so return values need not be described. The description covers the essential purpose and edge-preservation semantics but leaves parameter meaning (especially vault) and error/edge cases unaddressed for a mutation tool with no annotations to lean on.

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 for all three parameters. 'Move a node to a new id' loosely maps to old_id/new_id, but neither parameter is named or explained, and the vault parameter is entirely undocumented in both schema and description.

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

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

States a specific verb+resource ('Move a node to a new id') and adds a distinguishing behavioral trait ('carrying every edge with it') that separates it from upsert_node or delete_node. It implicitly contrasts with index_repo's delete-then-create behavior. It does not explicitly name a sibling, so it falls just short of a 5.

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

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

The parenthetical gives one clear use case ('after a file move index_repo would otherwise treat as delete-then-create') which implies when the tool is needed. However, it offers no explicit when-not guidance and never names the sibling tools (upsert_node, delete_node) an agent would otherwise reach for, leaving the choice 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?

No annotations exist, so the description carries the full burden, but it does disclose real behavioral detail: results are organized into MUST_READ, DANGER, MAY_CHANGE and MUST_TEST sections and read-only intent. It omits any statement about permissions, cost, or mutation (none expected), which is acceptable given the retrieval nature. Value is added, but the output semantics come largely from the output schema.

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

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

Two dense, front-loaded sentences that waste no words and put the core purpose first, followed by result-interpretation guidance. The dense jargon (FTS5, PageRank, MUST_READ) is compact but not cryptic in 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?

For a four-parameter tool with an output schema, describing return values is unnecessary, and the description does outline the semantic sections of the result. It is still incomplete on parameters and on how the result should drive subsequent actions beyond 'consider a change done', which is vague.

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

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

Schema description coverage is 0% across all four parameters (query, top_k, vault, seed_k) and the description explains none of them. 'Natural-language description of a task' weakly implies the query's form, and 'FTS5-seeded, PageRank-expanded' hints at the seed_k/top_k tradeoff, but no parameter is actually defined, leaving the schema to carry undocumented fields.

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

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

States a specific purpose: graph-expanded context retrieval seeded by full-text search for a natural-language task, and frames itself as 'the main entry point'. The FTS5/PageRank mechanism distinguishes it conceptually from siblings like search_vault and search_nodes, though it never names or contrasts those alternatives 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?

'The main entry point' implies this is the default starting tool for a task, which is genuine usage guidance. However, it gives no explicit when-not conditions and does not mention sibling retrieval tools (search_vault, search_nodes, neighbors) that an agent might confuse it with.

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. It usefully discloses the non-obvious trait that a valid node-id query short-circuits to the exact node first, but says nothing about result ordering/ranking, permissions, or interaction with the limit default.

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

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

Two tight sentences with the core behavior front-loaded and no filler. It is efficient, though arguably too terse given the undocumented 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?

An output schema exists so return values need no explanation, but with 0% schema coverage, no annotations, and no sibling differentiation, the definition leaves an agent guessing about `limit`/`vault` semantics and when to prefer this over search_vault.

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 for all three parameters. It clarifies that `query` is matched as full text across several fields, but gives no meaning at all for `limit` or `vault` (a nullable string targeting a vault), leaving real gaps.

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

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

States a specific verb ('Full-text search') and enumerates the searched fields (node id/label/path/curated-note body), so the agent knows exactly what is matched. It does not explicitly distinguish itself from siblings like search_vault or retrieve_context, keeping it short of a 5.

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

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

There is no guidance on when to use this versus the many sibling search tools (search_vault, retrieve_context, get_node). The note about exact-id matching is a behavioral trait, not a when-to-use rule, and no exclusions or prerequisites are given.

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 reveals matching semantics (substring) and return shape (snippets), but says nothing about safety, pagination across the limit, scope defaults when vault is null, or whether it touches the graph. This is thin for a no-annotation 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?

A single tight sentence that front-loads the operation and appends the return shape. Nothing is wasted.

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

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

An output schema exists, so return value details aren't required. But with 0% parameter coverage and no annotations, the description should clarify scoping and limit behavior; it leaves key invocation details to inference.

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

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

Schema description coverage is 0% across three parameters. The description mentions id/body as search surface but doesn't explain query syntax, what limit controls, or what vault=null means (default scope). The agent gets no compensating meaning for the undocumented parameters.

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

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

States a specific verb (substring search) and resource scope (every note's id/body), and describes the result shape (short snippet per hit). It doesn't distinguish itself from the very similar sibling search_nodes, leaving the agent to guess which search target applies.

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

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

There is no guidance on when to use this tool versus search_nodes, retrieve_context, or list_notes. The description gives no conditions, exclusions, or alternatives despite a crowded sibling namespace.

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 does disclose useful partial-update semantics ('without touching anything else'), which tells the agent no other fields are modified. However it says nothing about permissions, behavior when the node id doesn't exist, or validation of invalid status values.

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

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

A single front-loaded sentence with no filler; every clause (status values, optional confidence, scope limit) carries information.

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

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

An output schema exists, so return values need not be described, and the status value set is covered. But for an unannotated mutation tool the description omits permission requirements and error behavior for a missing/invalid node, and confidence remains an unconstrained string with no documented domain.

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 there are no enums in the schema, so the description compensates partially by listing the valid status values and noting confidence is optional. It adds nothing for `id` or `vault`, and doesn't specify valid confidence values, leaving two of four parameters undocumented anywhere.

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

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

Specific verb+resource ('Update a node's status') with the allowed status values enumerated and a scope constraint ('without touching anything else') that implicitly separates it from upsert_node. It stops short of naming an alternative sibling explicitly, so it lands just under 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 says what it does but gives no when-to-use guidance versus upsert_node, update_note_frontmatter, or promotion tools. Usage is only inferable from the scope phrase 'without touching anything else'.

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 does disclose the key safety trait -- 'additive only, never removes a link you added by hand' -- which tells the agent the operation is non-destructive to hand-authored content. However, it says nothing about idempotency on repeat runs, whether existing wikilinks are deduplicated, or whether indexing state is required.

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, the operational scope front-loaded and the safety guarantee second. 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?

An output schema exists, so return values need no explanation, and the description covers what is written and the additive guarantee. It leaves open what counts as a 'curated note', whether the vault parameter is required or defaults to the active vault, and what state the graph must be in beforehand.

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 and the single parameter 'vault' is never mentioned in the description, so the agent gets no guidance on what the vault identifier is or that it defaults to null. Unlike the zero-parameter baseline, this one undocumented parameter must be compensated for in prose and is not.

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

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

Specific verb (add) plus resource (wikilinks in curated notes) and a precise trigger condition (graph neighbors that also have a note), with the qualifying edge types enumerated. It does not distinguish itself from siblings like write_note or update_note_frontmatter, which also mutate note content, so it stops short of a 5.

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

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

The description implies when the tool fires (after graph neighbors exist and have their own notes), which is useful context. But it gives no explicit when-not, no prerequisites (e.g. must the vault be indexed first?), and names no alternative such as write_note for manual linking.

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 disclose useful side effects: body untouched, `created` preserved, `updated` bumped automatically. However it omits error behavior (e.g. what happens if the note/path doesn't exist) and any permission or creation semantics for a mutation 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?

Two tight sentences, zero waste, with the core merge behavior and side effects 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?

An output schema exists, so return values need no explanation, and the description covers the primary merge semantics. But for a mutation tool with no annotations and a fully undocumented `vault` param, the missing error/edge-case behavior leaves it only 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 0% across 3 parameters. The description explains `updates` (merged into frontmatter) and implies `relative_path` identifies the note, but the `vault` parameter is entirely undocumented, leaving a real gap the description should have compensated for.

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

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

States a specific verb+resource: merging `updates` into a note's existing frontmatter. The clause 'leaving the body untouched' implicitly distinguishes it from write_note and upsert_node, though no sibling is named 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?

No explicit when-to-use guidance or alternatives are given. An agent must infer that this is the tool for frontmatter-only edits versus write_note for full-body writes; the routing is left unstated.

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 present the description carries the full burden, and it delivers genuinely useful behavior: upsert (create-or-update) semantics, weight/origin defaulting from the edge type via graph.weights, and the non-obvious invariant that origin='manual' survives a reindex. It omits permissions, conflict resolution, and error behavior, but covers more than the schema does.

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 front-loaded sentences with no filler; the purpose leads and the operational caveat follows. The graph.weights cross-reference is slightly dense but 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?

Output schema covers return values and the description handles purpose and defaulting, but for an 8-parameter mutation tool with 0% schema coverage and no annotations, the definition leaves most parameters and the write's side effects/authorization unexplained.

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% across 8 parameters, yet the description only explains weight and origin (their defaulting behavior). Six parameters (src, dst, type, vault, source, confidence) receive no semantic elaboration anywhere, so the description does not compensate for the coverage gap.

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

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

States a specific verb+resource ('Create or update one edge') and the 'one edge' scope implicitly distinguishes it from the bulk upsert_edges sibling. It does not name the sibling explicitly, but the capability 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?

It offers conditional guidance for the origin parameter ('pass origin=manual when in doubt'), but gives no tool-level when-to-use guidance such as when to pick this over upsert_edges or a note-sync path. Usage is implied rather than stated.

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

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

No annotations are provided, so the description carries the full burden. It conveys upsert (create-or-update) semantics, but says nothing about permissions, atomicity/partial-failure behavior, or what happens to existing edges not in the batch. For an unannotated batch mutation this is a significant 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?

A single front-loaded sentence with no filler; the core action ('create or update several edges at once') leads. Slightly dense with the parenthetical jargon but efficient overall.

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

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

An output schema exists, so return values need not be described, but for an unannotated batch-write tool the description omits scope (vault), failure/atomicity behavior, and any when-not-to-use guidance. It is not complete enough to call this confidently.

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 reported as 0%, so the description must compensate. It names the required (src, dst, type) shape and notes optional extras like weight/origin, which helps for the edges array, but the second parameter 'vault' is never mentioned and defaults/confidence are left entirely to the schema.

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

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

The description states a specific verb ('create or update') and resource ('edges'), and the phrase 'several edges at once' distinguishes it from the singular sibling upsert_edge. The reference to the '(src, dst, type) shape from starter_edges' adds concrete structure, though 'starter_edges' is unglossed internal jargon.

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?

Batching ('several edges at once') implicitly signals when to prefer this over the singular upsert_edge, but the description never states that alternative or any condition/exclusion explicitly. Usage 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?

With no annotations, the description carries the full behavioral burden. It does disclose one genuinely useful trait: code-node writes here can be clobbered by a subsequent reindex. But it says nothing about how defaults (origin=manual, status=verified, confidence=high) behave, what happens on id collision beyond 'update', or whether the operation is reversible.

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

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

Three sentences, front-loaded with the core action and then the routing constraint. Every clause works; no filler. Minor awkwardness only in the parenthetical id-prefix lists.

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

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

An output schema exists, so return values need not be described, and the overwrite hazard is covered. However, for a 12-parameter mutation tool with no annotations, the description leaves the majority of parameters and the write semantics undocumented.

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

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

Schema description coverage is 0% across 12 parameters, so the description must compensate and largely doesn't. It adds meaning only for the id parameter via the prefix conventions; kind, path, repo, vault, lineno, origin, status, summary, note_path, and confidence are left entirely unexplained, including their non-obvious defaults.

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

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

The first sentence gives a specific verb+resource: create or update one graph node. It goes further by naming the identifier conventions it owns (feature:, ext:, note:) and explicitly contrasting with code nodes (file:/fn:) which are the domain of index_repo. It stops short of clarifying the relationship to the plural sibling upsert_nodes.

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 clear routing guidance: use this for curated nodes or manual corrections, and let index_repo own code nodes. The rationale (a later reindex would overwrite your write) makes the choice concrete. It doesn't address when to batch via upsert_nodes vs calling this once.

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. It discloses that this is a create-or-update (mutating) operation and shows the (id, kind, label) shape, but it does not explain upsert merge semantics (which existing fields are overwritten vs preserved), permissions, or batch atomicity/failure 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?

A single front-loaded sentence with the verb first and no filler; the parenthetical adds useful field detail efficiently. It is appropriately terse, though arguably too thin for the nested schema it governs.

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

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

An output schema exists, so return values need not be explained, and the description covers the batch create/update intent. However, for a nested-array mutation tool with no annotations and 0% schema coverage, the description leaves key gaps: the 'vault' parameter, upsert merge semantics, and several optional node fields go unaddressed.

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 names the core shape fields (id, kind, label) and some optional extras (repo/path/status/confidence), but omits others (lineno, origin, summary, note_path) and never mentions the top-level 'vault' parameter at all.

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

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

States a specific verb (create or update) plus resource (nodes) and adds batch scope ('several nodes at once'), which effectively distinguishes it from the singular upsert_node sibling. It does not explicitly name the sibling, but the 'several...at once' phrasing makes the batch role clear.

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

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

Usage is only implied: 'several nodes at once' hints that this is the bulk alternative to upsert_node, but no explicit when-to-use, when-not, or named alternative is given. An agent must infer the batch-vs-single distinction from the plural.

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, and it does disclose two meaningful traits: contract enforcement driven by vault profile and refusal of secret-looking content unless allow_secrets=True. However, it omits critical mutation semantics for a write tool – whether an existing note is overwritten or merged, and what happens when the contract check fails.

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 with the core action front-loaded and the guardrail immediately after. The parenthetical contract-field list is dense but each clause carries information; 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?

An output schema exists, so return values need not be explained. But for a mutation tool with no annotations, zero schema coverage on 5 params and a nested frontmatter object, the description leaves path semantics and overwrite behavior unstated – adequate, not complete.

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

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

Schema description coverage is 0% across 5 parameters, including a free-form nested frontmatter object. The description explains allow_secrets and lists contract fields (id, type, area, status, confidence, source) but says nothing about relative_path, vault, or body, so it only partially compensates for the schema gap.

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

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

The description opens with a specific verb pair and resource: 'Create or update a note.' It does not name or differentiate itself from close siblings such as update_note_frontmatter or upsert_node, so an agent still has to infer which of the several note/node writers is correct.

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

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

It states conditional behavior (contract enforced only when the vault profile requires it) but gives no when-to-use guidance and never mentions alternatives like update_note_frontmatter or upsert_node. Nothing tells the agent which sibling to prefer for a frontmatter-only edit versus a full note write.

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