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

With no annotations the description carries the full burden, and it does real work: it discloses the bundle composition, that decision_tables include 'any status, cross-branch' items, and the key behavioral trait that the tool never summarizes and leaves narrative to the agent. It does not mention permissions or size/performance limits, keeping it short of a 5.

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

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

Two dense sentences, front-loaded with the action and scoped tightly to output composition, with zero filler. The inline doc reference ('report-bundle-v2.md') is compact, though it leans on an external file the agent may not have.

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 re-explained, yet the description still usefully characterizes the bundle contents. It is nearly complete for a read/assembly tool, with the only real gap being the undocumented depth and include_edge_types parameters.

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 gives root_id meaning ('root_id's part_of subtree') but says nothing about depth (default 4) or include_edge_types, leaving two of three parameters undocumented in both the schema and the 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 ('Collapse ... into a report bundle') and resource ('root_id's part_of subtree') and enumerates exactly what the bundle contains (nested sections, cross-links, decision_tables, per-section gaps). The explicit 'this never summarizes' clause disambiguates it from summarization-style siblings.

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

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

Usage is implied by the output shape (generate a report bundle from a subtree), and the 'agent writes the narrative' note clarifies the division of labor. But it never states when to pick this over siblings like briefing or overview, nor any prerequisites 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 behavioral burden; it does disclose the composite contents of the result, which is meaningfully behavioral. However, it omits any statement of read-only/cost/latency behavior and does not say whether the call is expensive or how results are sized, which matters for a multi-source aggregation.

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 payload contents, followed by the routing advice — little waste. The closing clause 'which grep cannot assemble' is marginally redundant with the preceding 'Prefer this over grepping'.

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 description covers the aggregation's scope and when to choose it. The one real gap is the undocumented k parameter, which is left entirely 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 description coverage is 0% and there are two parameters, yet the description only indirectly implies that 'query' is the topic ('scoped to the topic') and says nothing about 'k' (result count, default 5). With no schema descriptions and no compensating text, an agent cannot know what k controls.

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 concrete composite deliverable — hybrid search hits, their 1-hop neighborhood, open questions, and unjustified decisions scoped to a topic — which is far more specific than the bare name 'briefing'. It effectively distinguishes itself from the sibling primitives it bundles (search_nodes, neighbors, open_questions, decisions_without_rationale) by declaring it returns them together in one call.

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 'prefer this over grepping graph files for "what do we know about X"' directive plus the reason (grep cannot assemble nodes with neighborhood and gaps), which is clear usage guidance and an alternative. It stops short of naming the sibling tools it overlaps with (search_nodes, neighbors, open_questions), so routing among them 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 usefully define the exact normalization algorithm (Unicode NFC + casefold) and the minimum group size (>=2), which is genuine behavioral specification. However, it does not disclose that the operation is read-only, whether it scans the entire graph or a scoped region, or whether results are bounded, so an agent can't fully predict 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 compact clause with zero filler and no redundancy. It is front-loaded and easy to scan. It is arguably too terse to stand alone as documentation, but under the conciseness dimension there is no waste to trim.

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 the return shape need not be explained, and with zero parameters the schema burden is minimal. The criterion for a collision is stated exactly, which covers the core need. Still missing is the scope of the scan (whole graph versus a subset) and confirmation of read-only semantics, leaving modest gaps for a diagnostic tool in a crowded sibling set.

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

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

The tool takes zero parameters and the schema is fully described, so there is nothing for the description to clarify at the parameter level. Baseline of 4 applies for a parameterless tool; no additional param semantics are needed or missing.

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 precisely what the tool surfaces: groups of at least two node ids that are identical once normalized under Unicode NFC + casefold. That criterion is specific enough to distinguish it from sibling diagnostics like find_similar, orphans, or contradictions, which detect different conditions. It lacks an explicit verb, but the noun phrase unambiguously identifies the resource and the collision rule.

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, no statement of prerequisites, and no named alternative among the many diagnostic siblings (find_similar, orphans, contradictions, stale, dangling_edges). An agent must infer the use case purely from the criterion. The tool family membership implies a linting/reporting context, but that is only implied.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose one meaningful trait — dangling edges are excluded from the result set — but says nothing about deduplication, ordering, directionality of the pairs, or result size limits, which matter for a graph query.

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 a clarifying parenthetical, front-loading the return shape first. There is no filler, though the phrasing is terse enough that the implicit 'list/query' verb is left to inference.

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-argument read query with an output schema present, the description tells the agent what set is returned and how it differs from the nearest sibling. The return-value details are carried by the output schema, so little more is required.

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

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

The tool takes zero parameters, so the baseline of 4 applies. The description correctly focuses on the return shape rather than inventing argument semantics.

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

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

The description states the exact resource returned: '{a, b} node pairs linked by a `contradicts` edge'. The verb is only implied (a read/list), but the resource is specific and the parenthetical explicitly distinguishes this tool from the dangling_edges sibling, so an agent can tell them apart without opening either schema.

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

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

It gives an explicit exclusion and points to the alternative: a dangling contradicts edge is 'surfaced by dangling_edges() instead, not here.' That is a clear when-not plus a named alternative, though it never states the positive when-to-use condition for querying contradictions.

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 the dst-existence precondition, the 'no dangling-edge creation' contract, the specific error (not_found), and the collision failure mode for part_of. It does not address duplicate-edge handling, self-loops, or permissions, so it stops short of exhaustive disclosure.

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

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

Front-loaded with the core action, followed by tightly packed failure-mode detail; every clause earns its place. The '(pin R2)' token is cryptic jargon that may not be meaningful to an agent, a minor blemish on an otherwise efficient structure.

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 important failure modes an agent must anticipate. Given the graph-domain complexity and the absence of annotations, it is nearly complete, missing only edge-type semantics beyond part_of and guidance relative to the batch sibling.

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

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

Schema description coverage is 0% for all three required params, so the description must compensate. It adds real meaning for dst (must already exist) and type (part_of collision semantics), but src is only implied through the part_of rule and the remaining enum values 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?

States a specific verb and resource ('Create a directed edge'), which is clear enough that an agent understands the operation immediately. However, it never differentiates itself from the sibling 'create_edges' (batch variant), so the singular-vs-batch choice is left to inference rather than stated.

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

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

Provides explicit condition-based guidance: dst must exist or not_found is raised, and for a collision on a differing part_of parent it names the concrete alternative workflow ('call delete_edge first to re-parent'). No exclusions are given for the batch sibling, so it falls just 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 exist, so the description carries the full burden, and it does so well: it discloses that validation runs across the whole batch (including part_of single-parent/cycle rules that consider sibling edges), that any hard error fails the entire call with the store's own message, and that no partial report is produced. These are precisely the behavioral traits an agent needs 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?

A single dense paragraph that is front-loaded with the atomicity guarantee, then error behavior, then sibling routing. Every sentence adds usable information; nothing is filler despite the 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?

For an atomic batch-mutation tool whose return shape is covered by an output schema, the description supplies the missing behavioral context: batch-wide validation, all-or-nothing failure, and the absence of partial reports. Nothing an agent needs to invoke it safely 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?

Top-level schema description coverage is 0%, and the description never explains the {src, dst, type} shape or ordering itself. It does add meaningful constraint semantics for the 'part_of' type value (single-parent and cycle rules evaluated against the rest of the batch), and the nested item object in the schema documents the edge shape, partially compensating 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 description states a specific verb and resource ('Create many edges in ONE atomic operation') and explicitly distinguishes itself from the sibling create_edge ('Prefer this over looping create_edge'). An agent can tell exactly what this tool does and how it differs from the single-edge tool without opening the schema.

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

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

It names the alternative (looping create_edge) and the condition that selects this tool ('when linking several edges from one dump'), even citing an organizing protocol section. This is explicit routing guidance of the highest kind.

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 usefully discloses the non-obvious trait that the node is created detached and needs a follow-up create_edge, but says nothing about permissions, duplicate/collision handling, or what identifier comes back to use as the edge source.

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

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

Two short sentences, zero filler, with the critical sequencing caveat front-loaded right after the purpose. 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 description covers the main gotcha (detached node requires create_edge). It remains thin on parameter meaning for a five-parameter create tool, but nothing needed to call 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 0% and the description names none of the five parameters, so the meaning of title, body, status, and properties is left entirely to inference. The enum does self-document the ten node types, but the description adds no semantic value over the structured fields.

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

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

States a specific verb and resource ('Create a new node') and immediately distinguishes itself from the edge-creating siblings by declaring what it does not do. An agent can tell it apart from create_edge/create_edges/merge_nodes without inspecting any schema.

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

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

Explicitly routes the agent to the next step ('call create_edge next'), which is the primary sequencing decision for this tool. It gives clear context for use but no when-not guidance or coverage of alternatives like merge_nodes.

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, and it does disclose the selection criterion (edges whose endpoints fail to resolve), which is the core behavioral fact. It is silent on whether the call is read-only, whether results are ordered or paginated, and whether the edges are reported or repaired, leaving meaningful gaps for a diagnostic tool with zero annotation coverage.

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 clause that defines the predicate with no filler, which is well matched to a zero-argument query. It is a noun fragment rather than a full statement of action, but nothing in it 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?

With an output schema present, the description need not explain the return shape, and with no parameters there is nothing to document on the input side, so the definition of the predicate is the only essential content. It stops just short of complete by omitting any read-only assurance or guidance on the sibling diagnostics that overlap with it.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The sentence is spent entirely on defining the result set rather than on inputs, which is the right allocation here.

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 (edges) and the exact predicate that qualifies them: src and/or dst no longer resolving to a node. That is a concrete, unambiguous definition an agent can act on. It does not, however, distinguish itself from adjacent diagnostics in the sibling list such as orphans, contradictions, or stale, so the agent must guess how they partition the same problem space.

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, no stated alternatives, and no indication of when a dangling-edge check is appropriate versus orphans or contradictions. Usage is only implied by the tool name and the definition of the predicate.

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 disclosure burden. It does define the exact selection semantics (`justifies` edge direction = inbound, any status), which is the key behavior, but it never states that this is a read-only listing, nor anything about ordering, volume, or scope beyond the edge filter.

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 discriminating predicate is stated immediately. Nothing could be removed without losing meaning.

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 an output schema present, return values need no explanation, and with zero parameters there is no input surface to cover. What remains thin is the operational context (read-only nature, expected result volume, relationship to `orphans`), which keeps this short of a 5.

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

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

The tool takes zero parameters, so the schema has nothing to document and there is no parameter semantics for the description to supply. Baseline 4 applies.

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

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

The description names a concrete resource (decisions) and a precise filter predicate (no inbound `justifies` edge), which is far more specific than a tautology. It is not explicitly differentiated from the closest sibling, `orphans`, which is a broader no-connection query, so the agent must infer the distinction from the filter text alone.

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

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

There is no guidance on when to reach for this tool versus `orphans`, `open_questions`, or `contradictions`, all of which return filtered node sets. The predicate is stated but the triggering condition 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 provided, so the description carries the full behavioral burden, and it discloses nothing: not that removal is destructive/irreversible, what happens to the destination node if the edge was its only link, whether permissions are required, or whether the call is idempotent.

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?

It is one short sentence, but that brevity comes from under-specification rather than disciplined editing; there is no front-loaded scope or consequence information for an agent to act on.

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

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

For a destructive three-parameter mutation tool with no annotations and no parameter documentation, this is wholly inadequate. The existence of an output schema covers return values, but nothing covers the semantics of the inputs or the effects of the call.

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

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

Schema description coverage is 0% for three required parameters (src, dst, type), and the description adds nothing. In particular the meaning of 'type' (the nine edge relationship kinds) and the directionality of src vs dst are left entirely to inference from bare property 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?

"Remove an edge" restates the tool name almost verbatim (delete_edge), adding no scope, no target graph, and no differentiation from sibling mutators like delete_node, create_edge, or dangling_edges. It is a tautology rather than a stated purpose.

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

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

There is no when-to-use guidance, no mention of alternatives (e.g. delete_node, update_node, or whether edges should instead be superseded), and no prerequisites. The agent is given no basis for choosing this over sibling tools.

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

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

With no annotations, the description carries the full burden and does real work: it discloses that the file is removed but Git history is retained (soft/recoverable delete), and that inbound edges are intentionally left dangling rather than cascaded or silently dropped. It omits any auth/permission requirements, but the side-effect profile on the graph is unusually well communicated.

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 action and its reversibility guarantee, with the edge consequence secondary. No filler; only a minor stylistic flourish in the em-dash clause.

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 mutation's scope, recoverability, and graph side effects. For a one-parameter delete, that is nearly complete; only the meaning of the id parameter is left 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% for the single required parameter, and the description never mentions what "id" refers to or its format. The phrase "a node's file" weakly implies the id identifies the node, but it does not compensate for the total absence of parameter documentation.

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's file" plus the parenthetical that Git retains history. An agent immediately knows this deletes a node rather than an edge, but the description never names or contrasts with the sibling delete_edge or other node-mutating tools.

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

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

There is no explicit guidance on when to delete versus merge_nodes, rename_node, or other alternatives. The Git-history note hints that deletion is recoverable, which indirectly supports the decision, but no when-to-use or when-not-to-use condition is 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 behavioral burden and does well: it discloses that an id input reuses a cached vector and that the query node is excluded from its own results, and that free text is embedded fresh. It doesn't state that the operation is read-only or describe result shape, though an output schema exists to cover the latter.

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

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

Three tight sentences: identity first, parameter semantics second, routing advice last. Every clause earns its place and there is no padding.

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

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

The output schema removes the need to describe return values, and the dual-mode input plus the self-exclusion behavior are covered. The only missing piece is how it relates to the search_nodes sibling, which an agent choosing between near-duplicate search and node search would 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 0%, so the description must compensate, and it does for the required parameter: text_or_id has two distinct modes (existing node id vs free text) with side effects spelled out for the id case. k is left entirely unexplained beyond its default of 5, which is the remaining 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 and scope: 'Vector-only near-duplicate search -- the dedup primitive.' The qualifier 'vector-only' implicitly contrasts with keyword-based siblings, so an agent grasps what it does. It never names the obvious sibling (search_nodes), so sibling differentiation is inferred rather than stated.

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

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

Gives a clear triggering scenario ('check is this already recorded') and explicitly steers away from an alternative method, grepping graph files, with a reason (paraphrase matching). It stops short of the 5 bar because it never mentions the sibling tool search_nodes, which is the most likely competing choice for the same intent.

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 the notable traversal behavior — neighbor_depth>0 pulls nodes within N hops regardless of edge type or direction, plus the node's direct edges — and "Fetch" implies a read. However, it says nothing about behavior when the id does not exist, whether traversal can be expensive or depth-bounded, or any error/permission semantics.

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

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

Two short sentences, with the core operation front-loaded and the conditional behavior following. Every clause contributes meaning; the depth explanation is 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?

An output schema exists, so return-value documentation is not required, and the neighbor_depth semantics are covered. Still, with zero annotation coverage and 0% schema descriptions, the definition leaves the id parameter and not-found/error behavior unaddressed, and it never bounds or warns about the cost of deep traversals.

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 neighbor_depth thoroughly (hop semantics, any edge type, any direction, plus direct edges), which is genuinely useful, but the required id parameter — its format and lookup semantics — is left entirely undocumented.

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

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

"Fetch a node" states a specific verb and resource, and the neighbor_depth clause clarifies the scope of the fetch. It stops short of explicitly distinguishing itself from siblings like neighbors or get_subgraph, whose behavior appears to overlap with the depth>0 case, so an agent must still infer the boundary.

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 neighbors, get_subgraph, or search_nodes, all of which plausibly return overlapping data. The description implies usage (fetching by id) but names no alternative and no exclusion condition.

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 one meaningful behavioral trait beyond the schema: traversal is direction-agnostic ('any direction'). However, it says nothing about read-only safety, result size/limits, or whether cycles are handled.

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 tightly-worded sentence with the core semantics front-loaded. Every word (connected, root_id, depth, hops, any direction) 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 not be described, which lightens the burden. Still, for a 3-parameter graph traversal tool with zero annotation coverage, omitting the `edge_types` filter and any usage/scope guidance leaves clear 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 description must compensate. It clarifies `depth` as measured in 'hops' and anchors `root_id` as the traversal origin, which adds real meaning. However, the `edge_types` filter parameter is entirely unmentioned 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?

The description states a specific operation: retrieve everything connected to root_id within `depth` hops. It is clearly a traversal/retrieval tool distinguishable from mutation siblings like create_edge or delete_node, though it doesn't explicitly differentiate itself from the `neighbors` sibling.

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, no prerequisites, and no mention of alternatives such as `neighbors` (likely the single-hop analogue). The agent must infer from the phrase 'within depth hops' that this is the multi-hop traversal option.

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 so well: it discloses edge repointing, outbound-edge dedup, that a part_of conflict degrades to a warning rather than a failure, that drop's file is deleted (destructive), and that bodies are not auto-merged. This is unusually rich behavioral disclosure 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?

Front-loaded with the core merge behavior, then caveats, in a compact multi-clause form with no filler. The telegraphic style and the unexplained internal reference 'pin R3' slightly reduce clarity, but every clause carries information.

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

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

An output schema exists, so return values need not be described. Combined with a full account of the mutation's side effects and the recommended follow-up workflow, an agent has enough to call it correctly. Minor gaps remain: permissions/preconditions, atomicity, and the opaque 'pin R3' reference.

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

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

Schema description coverage is 0%, so the description must define the parameters, and it effectively does: keep_id is the survivor that receives edges and the file, drop_id is the node consumed and deleted. The roles are unambiguous, though the ID string format and edge cases (e.g., keep_id equal to drop_id) are not addressed.

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 operation (dedup/merge of one node into another) and enumerates its concrete effects: repointing drop's inbound edges to keep, migrating outbound edges, and deleting drop's file. It also distinguishes itself from update_node by noting the body is NOT auto-merged, so an agent can tell these apart without opening schemas.

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 conditional guidance: inspect dropped_body_preview and call update_node(keep_id, ..., mode='append') first if unique content from drop should survive. This names an alternative tool and the condition that selects it. It stops short of stating exclusions (e.g., when not to merge, preconditions like same-type nodes), so it is not a full when/when-not rubric.

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, yet it only restates the core query. It does not disclose whether the source node is included, how dangling edges are treated, deduplication behavior, or result 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?

A single front-loaded sentence with no filler; the scope and filters come first and 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 values need not be explained, and the tool is a simple read. Still, with no annotations and no filter semantics, the definition leaves gaps an agent would want filled before invoking.

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, but it only name-drops 'type/direction' without explaining enum values, the 'both' default, or the null default for edge_types. The meaning of 'touching' (incident in either direction) is implied but never clarified.

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 ('edges') and scope ('single-hop') anchored to the `id` node, so an agent can distinguish it from broader traversals like get_subgraph. It does not explicitly name that sibling, but 'single-hop' implies the distinction.

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 or when-not-to-use guidance. The agent must infer from 'single-hop' that multi-hop needs get_subgraph, and nothing indicates when to prefer this over dangling_edges or contradictions.

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 discloses almost nothing: it does not state that this is a safe read-only query, whether results are paginated or ordered, or how many nodes may be returned. The only behavioral information conveyed is the result-set filter.

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, which is the right size for a parameterless query. It is arguably terse to the point of under-specification, but no sentence 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 values need not be described, and the zero-parameter schema is fully covered. What is missing is behavioral framing (read-only, ordering, volume) that no annotation supplies, which for a listing tool leaves a modest but 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?

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description's mention of status='open' correctly signals that this filtering is built in rather than caller-controlled.

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

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

Names a specific resource (question nodes) and a filter condition (status='open'), which is enough to distinguish it from siblings like orphans, contradictions, and stale. However, it is a bare noun phrase with no verb, so the agent must infer that it is a read/query operation rather than, say, a mutation, and no sibling is named as the 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 when-to-use guidance, no prerequisite context, and no mention of alternatives such as search_nodes or get_node for related lookups. The filter condition implies the tool's purpose but the agent gets no routing help.

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 does disclose the actual detection rule plus an important false-positive exclusion (root-level concepts lacking a part_of parent are not flagged). It does not discuss ordering, limits, or how results are shaped, but the output schema covers the return format.

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 defines the result set, with a parenthetical that pre-empts the most likely misreading. Every clause earns its place.

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

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

For a zero-parameter diagnostic with an output schema, the description supplies everything needed to invoke and interpret it: the filter rule and the carve-out. Only the relationship to sibling diagnostics is left implicit.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly spends no words on parameter semantics.

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

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

The description states precisely what the tool returns: nodes with zero edges in any direction or type. That is a clear, specific discriminator among the diagnostic siblings (dangling_edges, contradictions, stale), though it never names an alternative so the agent must infer the boundary itself.

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 by the diagnostic family context (an audit tool for finding isolated nodes). There is no explicit 'use this when' guidance and no mention of when a sibling such as dangling_edges would be the better choice.

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

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

With no annotations, the description carries the full burden, and it discloses useful behavioral traits: it is 'cheap' and 'shallow', returns tallies rather than raw records, and is read-only in nature (a 'map'/'returns'). It does not explicitly state absence of side effects or any access constraints, but the read-only character is strongly implied by the 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?

Purpose is front-loaded, followed by the grep comparison and the session-start guidance. The first sentence is dense with a long parenthetical enumeration, but every clause carries information; no filler sentences.

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 re-explained, and there are no parameters to cover. The description supplies the missing pieces an agent needs: what shape comes back, why it beats grep, and when to invoke it.

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

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

The tool takes zero parameters, so there is nothing to document beyond the empty schema. Baseline for a parameterless tool is 4.

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

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

The description names a specific resource (the project's spine structure) and enumerates exactly what it returns: spine roots, part_of children as branches, per-subtree tallies, whole-graph totals, and top open questions. It is clearly distinguishable from siblings like open_questions or briefing because it returns the aggregated shape in one call.

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

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

It gives explicit when-to-use ('at the start of a session, before anything else'), a named alternative it supersedes ('prefer this over grepping graph files'), and the reason the alternative is insufficient. The graph://project/overview resource is offered as an equivalent path, leaving nothing 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 burden. It usefully discloses that the index is *derived* (regenerable from graph/nodes/*.md) and that it writes into index/, but says nothing about whether the operation is safe to run while the service is live, how long it takes, or whether concurrent access/locking matters. Adequate but incomplete for an unstipulated mutating 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?

Two sentences, zero filler. The purpose is front-loaded, followed immediately by the actionable triggering conditions.

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 a 0-param tool makes schema burden minimal. The description covers what is rebuilt, from what source, and when to run it, leaving only operational concerns (duration, live-run safety) 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?

The tool takes zero parameters, so there is no parameter semantics to document; the baseline for a 0-param tool is 4. The description correctly does not invent parameter detail.

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?

"Rebuild the derived index from graph/nodes/*.md" names a specific verb (rebuild), the resource (derived index), and its source. None of the siblings (create_node, search_nodes, briefing, etc.) perform index maintenance, so the agent can distinguish this tool immediately.

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 concrete triggering conditions: after a manual git pull/merge, or to recover from a deleted/corrupted index/. That is clear when-to-use guidance. It stops short of a 5 because it names no alternatives or explicit when-not conditions.

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 so well on the key asymmetry: it states exactly what is mutated (inbound frontmatter wikilinks), what is NOT (inline [[wikilinks]] in prose), and where the gap is surfaced (body_references_not_updated). It does not address collision handling, irreversibility, or required permissions, which keeps it short of a 5.

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

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

The core action and its cascade are front-loaded, the exception follows immediately, and the parenthetical explanation of why inline links are missed earns its space. No filler sentences.

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-format details are not needed, and the description covers the behavioral landmine an agent would otherwise hit. Remaining gaps are collision/failure behavior and permissions, which are minor for a two-parameter rename.

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 implies id identifies the target node and new_title is the replacement, and the phrase 'rewriting ... to the new id' usefully reveals that the id is derived from the title. But it never explicitly maps either name, and the id/title wording is muddy.

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 ('Rename a node') plus the non-obvious side effect that inbound frontmatter wikilinks are rewritten. However, a sibling named update_node exists and the description never says how rename_node differs from it, so sibling differentiation is absent.

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: reach for this when the node's name/id must change rather than its other properties, and the body-link caveat hints at when results may surprise you. But there is no explicit when-to-use/when-not statement and no pointer to update_node as the alternative for non-rename edits.

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 add real behavioral context: the hybrid FTS+vector mechanism, RRF fusion, and the fact that type/status filtering happens per-branch before fusion (so filtered results never consume a rank slot). It omits any note on result limits, pagination, or auth, but the algorithmic behavior is unusually well 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?

Three sentences, mechanically front-loaded with the search model before the usage directive. The parenthetical about fusion rank slots is verbose but earns its place by explaining the filtering semantics.

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. For a hybrid-retrieval tool the description covers mechanism, filtering behavior, and usage adequately; only 'k'/result-count behavior and the free-form status domain are left to the schema.

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

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

Schema coverage is 0% for 4 parameters, so the description must compensate. It explains how types/status filtering interacts with fusion, covering two of the four params, but never mentions 'k' or the status value domain, leaving half the parameters undocumented.

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

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

States a specific verb and mechanism ('Hybrid FTS+vector search, fused by Reciprocal Rank Fusion') and what it returns ('typed nodes'). It distinguishes itself from external grep but does not differentiate from close MCP siblings like find_similar or get_node, so an agent still has to infer the boundary.

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?

'Prefer this over grepping graph files for ANY lookup' gives a clear when-to-use directive, but the alternative named is not an MCP sibling, and there is no guidance on when to choose find_similar, get_node, or get_subgraph instead. Usage is implied rather than fully scoped.

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 disclosure burden and partially meets it: it explains that push triggers a network operation and that the default is off specifically to avoid a surprise network call. That rationale adds value beyond the schema's bare default:false. It stops short of disclosing whether the operation is reversible, what happens with an empty staging area, or any auth requirements.

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

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

A single, front-loaded sentence with no filler; the key action comes first and the push caveat second. Only the parenthetical pathspec clause adds noise without corresponding schema support.

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 is low-complexity with only two parameters. Still, the description leaves the commit-message parameter undefined and asserts a pathspec concept that the schema does not support, so an agent cannot fully reconstruct intended usage from the definition alone.

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 does explain the push flag's default behavior and rationale, but 'message' is never described even implicitly beyond its name. Half the parameters remain semantically 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?

The description states a concrete action set (stage + commit, optional push) under the verb 'snapshot', which is more specific than a restatement of the name. However, it claims pathspec scoping through 'git add (pathspec-scoped)' while the input schema contains no pathspec parameter, which muddies rather than clarifies what the tool actually operates on. The 'git add + commit' framing does distinguish it from the graph-node siblings, but the pathspec mismatch creates ambiguity.

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

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

There is no explicit when-to-use guidance or comparison to alternatives; the only contextual hint is the conditional nature of push. An agent is left to infer that this is the tool for persisting changes to a repo. No prerequisites, no statement of when not to use it.

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

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

With no annotations, the description carries the full burden, and it does disclose non-obvious defaulting behavior (omitted types/statuses fall back to the non-terminal set; explicit [] matches nothing). However, it never confirms the read-only, non-mutating nature of the operation, nor any limits on result size. Useful behavioral detail, but incomplete coverage for an unannotated 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 sentences, front-loaded with the core predicate, then the parameter caveat. The parenthetical '(None)' is slightly awkward notation but costs little. Nothing extraneous; the density is appropriate for a small filtering tool.

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

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

An output schema exists, so the return shape needn't be described. Against three parameters at 0% schema coverage, the description handles the defaulting semantics but leaves the statuses value space and the timestamp format undocumented, which is a noticeable gap for a tool whose whole purpose is a precise filter. Adequate but 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 coverage is 0%, so the description must compensate, and it does partially: it explains the None-vs-empty-array distinction for types/statuses, which is a real trap an agent could fall into. It does not, however, enumerate the valid statuses values (the schema leaves them as untyped strings) or state the expected format of before_iso, leaving two gaps the schema does not fill.

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 the resource and the filter predicate precisely: 'Nodes untouched since before_iso', which pins down exactly what this tool returns. It is a noun phrase rather than a verb phrase, but the semantics are unambiguous and distinguishable from siblings like orphans or dangling_edges, which use different predicates. No explicit sibling cross-reference, so not a 5.

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

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

There is no statement of when to reach for this tool versus orphans, decisions_without_rationale, or open_questions, all of which are sibling analysis tools that could plausibly overlap. The only guidance offered concerns parameter defaulting behavior, not tool selection. An agent gets no routing help from the text.

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 does well: it discloses that properties MERGES rather than replaces, that remove_properties is applied after the merge and wins on key collision, and that removing an absent key is a no-op. It omits any statement about permissions, reversibility, or the effect of the `mode` field (append vs replace), which is a behavioral trait, not just a parameter.

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

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

Front-loads the core action, then the exclusions, then the merge semantics. Efficient overall, though the trailing '-- pin R5' reference is unexplained noise and the nested parenthetical about merge ordering is 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 no explanation. For a mutation tool with no annotations, the description covers the highest-risk behavior (merge vs replace, removal precedence). The main gap is the unexplained `mode` interaction with `body`, which affects what actually gets written.

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 6 parameters, so the description must compensate. It explains properties and remove_properties semantics and precedence well, but leaves `id`, `body`, `mode` (the append/replace enum), and `status` entirely unexplained. Partial compensation only.

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 ('Update a node's') and enumerates the mutable fields (body/status/properties). It explicitly distinguishes itself from rename_node, create_edge, and delete_edge, so an agent can tell it apart from its siblings without opening any schema.

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

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

Explicitly states what it cannot do (title, edges) and routes the agent to the correct alternative for each excluded case (rename_node / create_edge / delete_edge). This is genuine when/when-not guidance with named alternatives.

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