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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation profile is known. The description adds genuine value by disclosing the line-ending insertion behavior, but says nothing about the stale-write protection (expected_sha256), error handling, or whether existing content is preserved — relevant for a destructive write 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 crisp sentences plus a concrete example. Purpose is front-loaded and the line-ending behavior follows immediately. The example earns its place by demonstrating the exact parameter shape, though it is slightly more verbose than strictly necessary.

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 write tool with no output schema and a partly-documented schema, the description covers the core behavior and line-ending nuance but omits error/return semantics, the role of expected_sha256 staleness, and how it differs from create_file/prepend_file. Adequate but with 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?

Coverage is 50%: agent_preset and expected_sha256 are documented in the schema, while path and content carry no schema description. The description's example partially compensates by showing how path and content are used, but the ambiguity of agent_preset's interaction with append behavior is unaddressed. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Append content to an existing file') that is clearly distinguishable from siblings like prepend_file, create_file, and replace_text. It doesn't explicitly name those siblings, so routing relies on the agent inferring the difference, keeping it just below 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 phrase 'to an existing file' implicitly signals this is not for creating files, but there is no explicit when-to-use guidance, no when-not-to-use, and no reference to alternatives such as prepend_file or create_file. The 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?

Annotations already declare readOnlyHint=false and destructiveHint=true, so safety is covered; the description adds real behavior beyond that: fail-closed (no anchor-less model merge), marker-line stripping, and the requirement of exactly one anchor. It does not describe the return shape or the stale-error path beyond what the schema already carries.

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 content is repeated almost verbatim across the paragraph ('Morph-class freeform fragment with required placement... no model merge without anchors'), so several sentences do not earn their place. The first sentence is well front-loaded, but the duplication makes the whole entry noticeably bloated.

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

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

For a 9-parameter mutation tool with no output schema, the description covers the critical behaviors: anchor requirement, marker stripping, fail-closed semantics, and an example. It could say more about success/failure outcomes, but annotations plus the schema fill most remaining 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 100% and the schema itself already states 'Exactly one of after, before, or old must be set', so the description mostly reinforces what is documented. The inline example adds marginal value by showing fragment/path/after in use, but it does not add syntax or semantics the schema lacks.

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 concrete verb+resource ('freeform fragment apply') and scope (strips Morph-style markers, inserts/replaces at a required anchor). It names an alternative ('use replace/ast for precise edits'), so an agent can partly distinguish it from siblings. The purpose is clear but the doubled phrasing and internal ticket references (#2018) add friction rather than sharpen it.

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 for lazy-snippet agent output when anchors are known; use replace/ast for precise edits' gives an explicit when-to-use condition and an alternative tool. It does not state an explicit when-not to use beyond the fail-closed constraint, but the selection guidance is concrete rather than 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?

Well beyond the destructiveHint=true annotation, it discloses that multi-match SEARCH/REPLACE is ambiguous and results in no write, that empty-hunk /dev/null unlinks, that stale minus lines leave the file untouched, that allow_conflicts writes conflict markers, and warns never to commit conflict-marker files. 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-loads the core action and each clause carries real information, so virtually nothing is wasted. However it is delivered as a single dense run-on paragraph full of semicolons and jargon, which costs some readability for a complex 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?

Covers formats, default write behavior, edge cases (stale context, empty-hunk unlink, conflict markers), and recovery advice, which is substantial for a destructive tool with no output schema. Return values/result reporting are not described, and 'strict' is unexplained, leaving minor 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?

With only 50% schema description coverage, the description compensates by explaining the diff formats in depth, apply's default and preview semantics, replace_all's uniqueness rule, on_stale=merge, and allow_conflicts=true. Only the 'strict' parameter (rollback on lifecycle failure) is left to the schema, so it nearly closes 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 precise verb ('Apply') and enumerates the resource/input forms it accepts: unified diff, Codex *** Begin Patch, and Aider SEARCH/REPLACE. This is specific and unambiguous, but it never names or contrasts with siblings such as apply_fragment, replace_text, or batch_replace, so sibling differentiation is left implicit.

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

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

Provides clear in-tool routing: apply=true writes vs apply=false is check-only, on_stale=merge for three-way merges, replace_all for multi-match, and explicitly recommends file.delete for path-only unlink. There is no high-level statement of when to pick this tool over the sibling patch/replace tools, which keeps it 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?

Annotations already declare destructiveHint=true and openWorldHint=false, so the safety profile is covered; the description adds genuinely new context by specifying that the deletion swallows leading doc comments and attributes and that blank lines collapse to one. It still omits irreversibility/undo availability and what happens when the symbol is absent.

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 first and second sentences say the same thing almost verbatim ('Delete... including leading doc comments and attributes, and collapse surrounding blank lines' / 'Deletes the full symbol span (docs and attributes included) and collapses surrounding blank lines'), wasting a full sentence. The example is useful and the core action is front-loaded, but a quarter of the text is redundant.

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, no-output-schema mutation whose annotations already flag destructiveness, the description covers the action, the destruction footprint, and a usage example. Gaps are minor: absence/error behavior and whether the deletion is reversible are left unstated.

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

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

Schema description coverage is 100%, so lang, expected_sha256, and agent_preset are already documented; the description only reinforces path and symbol via an example. That is the baseline 3 when the schema carries the load, with the example adding marginal value.

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 (delete) and precise resource (a whole symbol span), with scope qualifiers — leading doc comments, attributes, and surrounding blank-line collapsing — that functionally separate it from ast_rename and ast_replace_symbol. It never names a sibling explicitly, so it falls short of full 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?

No guidance on when to choose this over ast_replace_symbol, ast_rename, or delete_file, and no prerequisites stated. The example shows a bare invocation but not the conditions under which deletion is appropriate, and nothing mentions the stale/expected_sha256 workflow.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the supported-language list and the reverse-lookup behavior, but says nothing about output shape or performance characteristics, so it clears the (lower) annotated bar without excelling.

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 plus a minimal example, with the core purpose front-loaded and the reverse hint placed before the example. Nothing is padded, though the language list is somewhat enumerative.

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, three-parameter tool the description is largely adequate, but with no output schema it still omits any indication of the return format (flat list vs. grouped by file) and does not disambiguate from the adjacent ast_imports tool.

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

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

Schema coverage is 100%, so the schema already documents path, lang, and reverse. The description's mention of reverse=true and the path example merely restate schema content, adding no format or semantic detail beyond it. Baseline 3 applies when the schema does the heavy lifting.

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 (Extract) and resource (import/dependency statements from source files) and enumerates the supported languages, so the scope is concrete. However, it never distinguishes itself from the sibling ast_imports tool, which appears to cover overlapping ground, leaving the agent to guess which to pick.

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

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

The description explains the reverse=true mode ('find what imports a file'), which is useful conditional guidance, and supplies a call example. But there is no explicit when-to-use versus ast_imports or ast_refs, so the routing guidance 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's added value is the output semantics: symbol-level (added/removed/modified) rather than line-level, and comparison against git refs. It does not disclose error behavior for non-git directories or non-source files, but that is a modest gap against a safe-read annotation profile.

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 front-loaded sentences: purpose, scope contrast, then mechanics and an example. No filler, and the most decision-relevant fact (structural, not line-level) comes second.

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

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

With no output schema, the description carries the return-value burden and names the diff categories returned. It leaves unstated what happens with unsupported languages or non-versioned files, but is otherwise sufficient for a 4-parameter read tool.

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

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

Schema description coverage is 100%, so defaults for from/to and the language hint are already documented structurally, establishing the baseline of 3. The description's example reinforces path and from usage but adds no meaning beyond what the schema provides.

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

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

States a specific verb+resource ('structural diff between two versions of a file') and immediately narrows scope by contrasting with the line-level alternative. An agent can distinguish it from ast_read or doc_diff 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?

Explains that comparison happens against git refs and provides a concrete invocation example with path and from, which effectively shows how to use it. It stops short of naming when-not-to-use conditions or pointing to a sibling for line-level diffs.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this mutates files. The description adds that modules with unwrap=true get un-indented content, which is useful behavioral context. However, it doesn't explain what gets destroyed (e.g., the source file's original block is replaced by 'replacement' text), the overwrite semantics (covered by the 'force' parameter schema), or the required preconditions for update_imports beyond what the schema already says.

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

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

The description is two sentences and an example: the first states the purpose, the second highlights a specific behavioral detail (unwrap), and the example shows parameter usage. It's front-loaded and free of waste, though the example could be seen as slightly verbose.

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

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

For a destructive tool with 11 parameters, no output schema, and 100% schema coverage, the description provides the core purpose and a usage example. It omits important behavioral context like the result of extraction (what happens to the original location), dependency implications (e.g., update_imports behavior), and error conditions. Adequate but with 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 100%, so the schema already documents all 11 parameters thoroughly. The description adds an example that illustrates how some parameters work together, but doesn't provide additional semantic meaning beyond what the schema provides. Baseline 3 is correct when schema does the heavy lifting.

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: extract a symbol (module, function, struct) to a separate file. This is clearly distinct from siblings like ast_move or ast_split, which handle different refactoring operations. However, it doesn't explicitly contrast itself with the closest alternatives, 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 offers no guidance on when to use this tool versus alternatives like ast_move or move_file. The example provides a concrete usage scenario but doesn't articulate when or when not to choose this 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?

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation profile is covered. The description usefully adds that the module is created if missing or appended to, but does not warn that symbols are removed from their original location (the destructive effect) nor mention auth or reversibility.

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 plus a compact JSON example, with the core behavior front-loaded. Efficient, though the example could be trimmed and no guidance sentences follow it.

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 annotations carrying safety, 100% schema coverage, and no output schema, the description covers the essentials of what and how. It falls short on when-to-use versus the many AST siblings, leaving the selection decision to the agent.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters including the position and lang fields the description ignores. The embedded example adds practical syntax for path/module/symbols/preamble but nothing beyond what the schema already conveys.

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 (group) and resource (symbols into a named module), and the phrase 'within a file' implicitly separates it from ast_extract_to_file and ast_move. Sibling differentiation exists but is not spelled out by name.

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 never says when to choose this tool over ast_wrap, ast_move, or ast_extract_to_file, nor any prerequisites or exclusions. Only the create-vs-append behavior is given, which is behavioral rather than 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description usefully clarifies that traversal is transitive (direct AND indirect dependents), which is real behavioral information, but says nothing about return shape, result size limits, or handling of cycles. Adequate but thin against the lowered 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?

Three short sentences, front-loaded with the core purpose before the mechanism and example. The example is somewhat redundant given a fully described schema, but it is compact and does not bloat the text.

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 traversal tool with no output schema, the description conveys what it computes (affected symbols) but not what the response looks like or how results are bounded. The essential inputs are covered by the schema, so nothing critical is missing, but a few gaps remain.

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

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

Schema description coverage is 100%, so path, symbol, and depth are already documented, and the description's example merely restates those same three fields. Baseline 3 is appropriate; the description adds no format or semantics beyond the schema.

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

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

States a specific verb (transitive impact analysis) and resource (symbols affected by a change), plus the mechanism (traces the reference graph for direct and indirect dependents). It does not, however, distinguish itself from close siblings like ast_deps or ast_refs, which likely also traverse the reference graph.

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 through the worked example rather than stated: an agent can infer this is for 'what breaks if I change X' questions. There is no explicit when-to-use/when-not, no mention of when to prefer ast_deps or ast_refs instead, and no prerequisites noted.

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

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

Annotations declare destructiveHint=true, and the description adds real context beyond them: add is idempotent (skips existing), and an empty mutation argument set degrades to a safe read — a nuance the readOnlyHint=false annotation alone would hide. It does not say whether formatting/ordering is preserved or how removal failures are reported.

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 plus one short example; the operation set and the read-mode rule are front-loaded, and nothing is redundant with the schema.

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

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

For a five-parameter mutation tool with no output schema, it covers modes, idempotency, and read behavior. It leaves unstated what a successful mutation returns and how a not-found removal is handled, which is a minor 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?

Schema coverage is 100%, so baseline is 3, but the description adds semantics the schema lacks: the interaction rule that omitting add/remove/dedupe selects read mode, and the idempotency contract of add. The inline example also demonstrates the argument shape concretely.

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 (import/use statements) and enumerates the exact operations: add, remove, deduplicate, plus a read mode. This is clearly distinguishable from generic siblings like ast_insert or ast_replace, which do not target imports specifically.

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 an explicit mode-selection rule: 'With no mutation args, lists existing imports,' and flags that add is idempotent. It does not name which sibling to prefer for non-import edits, so the routing guidance is clear but not exhaustive.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation profile is covered. The description adds a genuinely non-structured behavioral trait — indentation is auto-detected — which tells the agent the tool reformats rather than inserting raw text.

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 plus a compact worked example, with the structural-positioning capability front-loaded ahead of the illustration. Nothing is padded.

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

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

For a mutation tool with no output schema and full annotation coverage, the description conveys positioning modes and indentation behavior adequately. It stops short of describing failure handling (e.g. target symbol not found) or whether surrounding code is reformatted.

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

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

Schema coverage is 100%, so all seven parameters are already documented with descriptions and mutual-exclusion notes; the baseline is 3. The description's example illustrates the after+content combination but adds no syntax or format detail beyond the schema.

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

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

Names a specific verb (insert) and resource (code) plus the structural positions it supports (inside module/impl/struct, before/after a named symbol). That clearly separates it from flat-file siblings like append_file or prepend_file, though it never names a sibling 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?

The mode list implies when each targeting option applies, and the schema notes mutual exclusivity, but the description gives no explicit when-to-use/when-not guidance versus alternatives such as ast_replace_symbol or apply_patch.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that 20 languages are supported and what symbol kinds exist, but says nothing about output shape, result size on large directories, or pagination behavior.

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

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

Two compact sentences with the core capability front-loaded, followed by concrete examples. No filler, though the trailing example block is somewhat redundant with the schema descriptions.

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 listing tool with full schema coverage and no output schema, the definition covers purpose, scope, language support, and example invocations. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so all three parameters (path, kind, lang) are already documented in the schema, including the comma-separated kind list. The description's examples reinforce usage but add no syntax or format detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'List symbol definitions (functions, classes, structs, enums, methods, etc.) in a file or directory.' This clearly separates it from list_files (files, not symbols) and ast_search (search vs enumeration). It does not explicitly name a sibling alternative, 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 scope ('in a file or directory') implies when to reach for it, and the two inline examples show typical invocations. However, there is no explicit guidance on when to prefer ast_list over ast_search, ast_map, or ast_read, nor any stated prerequisites.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description usefully adds the ranking algorithm and the token-budget-aware nature of output, but never describes the shape of the returned map or how ranking/boost/focus actually affect results.

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, purpose front-loaded and the example placed last. Nothing wasteful, though the example occupies space that could have carried guidance on the optional boost/focus 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?

For a read-only tool with no output schema, the description covers what it does and its mechanism, but leaves open what the 'map' actually looks like in the response and how ranking/boost interact. Adequate but with a visible gap for an agent that must interpret the output.

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

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

Schema coverage is 100%, so all four parameters are already documented in the schema, setting the baseline at 3. The inline example of path + max_tokens adds a little concrete usage guidance, but boost and focus receive no extra explanation in 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 ('Generate') plus resource ('ranked repository map') and even the mechanism ('PageRank over the symbol reference graph'), so the agent knows exactly what it produces. However it does not name or contrast any sibling (e.g. ast_deps, ast_impact, ast_refs) that an agent might confuse it 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?

'Shows the most important symbols' hints at intent, but there is no explicit when-to-use, when-not-to-use, or alternative routing among the many ast_* siblings. The agent is left to infer whether this replaces ast_impact or ast_search.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, covering the safety profile. The description adds that the target is created if needed and that the source is mutated, which is useful. It omits auth/permission needs, collision/overwrite behavior when the target already contains the symbol, and the fact that update_imports requires new_module_path/old_module_path.

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

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

Two sentences plus a compact JSON example, front-loaded with the core action. Efficient, though the example chooses a lesser-used parameter rather than the required trio.

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 9-parameter mutation with no output schema, the description is workable but thin: no return semantics, no mention of conflict/overwrite outcomes, no indication that update_imports has coupled required params. Annotations carry the safety signal, keeping this at minimum viable.

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

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

Schema description coverage is 100%, so the schema already documents all 9 parameters, including position enum-likes and the module-path dependency. The description only illustrates target_prepend, adding marginal value. Baseline 3 applies.

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

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

States a specific verb (Move) and resource (symbols between files), and clarifies the two-part effect (removes from source, inserts into target). It doesn't explicitly distinguish itself from siblings like ast_extract_to_file, ast_insert, or move_file, but the symbol-level scope is 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?

No when-to-use guidance, no conditions selecting this over ast_extract_to_file / ast_insert / move_file, and no prerequisites called out. The example implies typical usage but does not state exclusions or alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description usefully adds that resolution is AST-based and exact rather than textual, but it does not say what happens when the symbol is not found, whether partial matches are returned, or how 'context' interacts with symbol boundaries.

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

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

Two sentences plus a compact inline example, front-loaded with the core action and mechanism. Every element earns its place and nothing is padded.

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 tool with fully documented parameters and no output schema, the description covers purpose and resolution mechanism adequately. The one residual gap is return-shape ambiguity (exact definition only vs. surrounding lines), which matters slightly more because no output schema exists to clarify it.

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

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

Schema coverage is 100%, so all four parameters (lang, path, symbol, context) are already documented in the schema, and the baseline is 3. The description's example reinforces the path/symbol pairing and the symbol syntax ('run'), but adds nothing about lang hints or context line 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 a specific verb (Read), a precise resource (a specific symbol's source code), the input (by name from a file) and the mechanism (AST parsing to find the exact definition). This clearly distinguishes it from whole-file readers like read_file and from search-style siblings such as ast_search.

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 'by name' framing and demonstrated by the inline example, but there is no explicit when-to-use/when-not guidance and no named alternative (e.g. read_file for whole files, ast_search when the symbol name is unknown). An agent must infer the selection criteria.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, covering the safety profile. The description adds the useful behavioral note that definitions are distinguished from references, but doesn't disclose result format or whether recursive search occurs, leaving it at baseline-plus.

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

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

Two sentences plus an example, front-loaded with the core purpose. Efficient, though the JSON example is somewhat verbose relative to the payload it conveys.

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 reference-finding tool with full schema coverage and annotations, the description is nearly complete. It could note how definitions are marked in output, but no output schema exists so that gap is minor.

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

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

Schema description coverage is 100%, so the schema fully documents all four parameters. The example confirms symbol/path usage but adds no semantics beyond the schema's own descriptions. Baseline 3 applies.

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

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

States a specific verb+resource ('Find all references to a symbol') and explicitly distinguishes from definitions ('Distinguishes definitions from references'), which differentiates it from siblings like ast_search or ast_impact.

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

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

The description implies usage (finding symbol references) but offers no explicit when/when-not guidance or named alternatives among the many ast_* siblings. The inline example clarifies invocation but not tool selection.

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

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

Annotations already flag this as destructive and non-read-only. The description adds genuinely non-obvious behavior beyond that: it is AST-aware and explicitly skips strings and comments, and it operates 'across files.' It still omits reversibility/undo and confirmation of in-place file writes, 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?

One front-loaded sentence with the key constraint (skips strings/comments) followed by a compact example. No filler; every element is functional.

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 4-param mutation tool with no output schema and full schema coverage, the definition is nearly sufficient: it conveys scope and semantic behavior. The remaining gap is that it never states that files are modified on disk or how to verify/undo the change.

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

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

Schema coverage is 100%, and the schema even documents the from/to aliases, so the baseline is 3. The example maps path/old/new to a concrete call, but adds no semantics (e.g., lang, alias behavior) beyond what the schema already provides.

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

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

States a specific verb and resource ('Rename identifiers across files') and adds the differentiator 'AST-aware... skips strings and comments.' However, it never contrasts itself with close siblings like ast_replace, ast_replace_symbol, or replace_text, which is exactly the confusion an agent would have 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 description implies the basic use case (rename an identifier) but gives no when-to-use/when-not guidance and names no alternatives. With sibling tools such as ast_replace, ast_replace_symbol, and replace_text, the agent is left to guess which renaming tool to select.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation profile is covered structurally. The description adds the notion of scoping (file vs. nested scope) but says nothing about what gets rewritten, whether comments/formatting are preserved, or whether the operation is reversible — useful additions the annotations do not supply.

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 in the first sentence, followed by two compact examples that carry real information. No filler text, though the examples are somewhat dense inline.

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 mutation tool with no output schema, the description covers what and how but omits safety-relevant context such as reversibility, permission needs, or whether unrelated file content is preserved. Adequate but with clear gaps for a write operation.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The examples reinforce the shape of 'order' (a keyword like 'alphabetical' vs. an array of names) and the interaction with 'inside', but add no semantics beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (reorder), resource (symbols within a file or scope), and the ordering criteria (name, kind, or custom order). It is clear on its own, but it never names a sibling like ast_move or ast_group, so the agent must infer the boundary between reordering and moving/grouping from other tools.

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

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

The two examples illustrate the mechanics of calling the tool, but nothing states when to choose ast_reorder over ast_move, ast_split, or ast_group, nor any prerequisites such as a clean/parseable file. There is no when-to-use or when-not guidance at all.

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

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

Annotations already declare destructiveHint=true / readOnlyHint=false, so the safety profile is known, but the description adds real value by bounding the blast radius: 'only changes code inside the named symbol, leaving everything else untouched.' It still omits failure behavior (e.g., symbol not found, no match) and regex semantics, which keeps it from 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?

Front-loaded with the purpose, then the scoping guarantee and a compilable example. The second sentence slightly restates the first ('only within symbol's body' vs. 'only changes code inside the named symbol'), so it is efficient but not perfectly tight.

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 6-param destructive tool with no output schema, the description covers scope and usage form well and annotations carry the safety profile. It leaves gaps around error/no-match behavior and how the regex flag interacts with symbol scoping.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including aliases. The example usefully shows path/symbol/old/new used together, but the description adds no extra semantics (e.g., regex + symbol interaction) beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb (replace) with a precise scope (text only within a named symbol's body, via AST scoping) that distinguishes it from generic siblings like replace_text and from ast_replace_symbol. The example makes the operation concrete and actionable.

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 to use it (scoped, symbol-local replacement vs. whole-file replacement), but never names an alternative tool or states a when-not condition. An agent must infer that replace_text is the unscoped counterpart rather than being told.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so safety is covered. The description adds real value beyond that: it discloses that the replaced span includes leading doc comments and attributes (i.e. those will be destroyed) and that replacement source is re-indented to the symbol column. It still omits failure behavior when the symbol is absent.

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 and the example earns its place, but the second sentence ('Replaces the full symbol span (docs and attributes included)') is near-verbatim repetition of the first, wasting a quarter of the text.

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 6-parameter mutation tool with no output schema, the description covers the core span semantics but says nothing about failure modes (missing symbol, stale hash) or what a successful response contains. Adequate as a minimum, 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 100%, so the baseline is 3; the schema already documents path, symbol, content, lang, agent_preset and expected_sha256. The description adds only that the replaced span is the whole symbol, which partly restates the schema's own top-level description, and the example demonstrates required-parameter usage without adding format rules.

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 ('Replace a whole symbol span') and qualifies the scope as including leading doc comments and attributes, which separates it from a plain text replace. It does not explicitly name the sibling it differs from (e.g. ast_replace or ast_rewrite_signature), so the differentiation is left to inference.

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 alternative-selection guidance is given. The embedded example shows how to call it but not when to prefer it over ast_replace, ast_rewrite_signature, or apply_patch.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=false, so the safety profile is covered. The description adds only 'multi-language via tree-sitter' and an example; it never says whether the function body is preserved, whether the edit is atomic/undoable, or how conflicting matches are handled, which is thin for a destructive mutation.

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 in the first clause, the two input modes follow, and the JSON example earns its place by showing required keys and formatting. Three sentences with little waste, though the example duplicates schema content.

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 7-parameter tool with no output schema, the description covers the input shape but omits failure/ambiguity behavior, body-preservation guarantees, and how structured fields interact with new_signature. Adequate but with clear gaps an agent would hit in practice.

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

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

Schema description coverage is 100%, so every parameter is already documented, and the baseline is 3. The description reiterates the field names and shows a concrete example, but adds no precedence rule between the structured fields and new_signature, nor semantics the schema lacks.

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 (rewrite a function signature) and names the exact structured fields involved, so the operation is unambiguous. It does not, however, differentiate itself from close siblings like ast_rename or ast_replace_symbol, which an agent must choose between.

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

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

The description implicitly tells the agent it may either supply structured fields or a full new_signature string, which is real mode-selection guidance. It offers no when-to-use vs. alternatives (ast_rename, ast_replace_symbol), no prerequisite conditions, and no note on what happens if the named function is absent or ambiguous.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful behavioral context: literal tokens match exactly, $$$MULTI not implemented. However, it doesn't explain result format, pagination, or performance characteristics. The implementation limitation ($$$MULTI) is genuinely useful added context beyond annotations.

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

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

Front-loads the core purpose in the first sentence, then explains pattern mode and gives an example. Slightly dense but no wasted sentences; each element (pattern mode, literal matching, $$$MULTI limitation, example) serves a purpose.

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

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

For a 5-parameter search tool with no output schema, the description covers the query syntax well and provides an example. However, it omits result format, behavior when no matches found, and lang hint requirements (though schema covers lang). Adequate but with clear gaps for output interpretation.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds an example showing query and path usage, and clarifies pattern mode requirements (valid source after substitution). This adds marginal value over the schema descriptions, so baseline 3 is appropriate.

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

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

States a specific verb+resource: 'Structural search using AST queries'. Distinguishes from sibling search_files (text search) and ast_validate by being the search function. An agent can tell this is the AST-based structural search 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?

Implies usage through example and explanation of pattern mode, but never explicitly says when to use this versus ast_validate, ast_map, or search_files. The example demonstrates invocation but not selection rationale.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation risk is covered structurally. The description adds genuinely useful context beyond that: 'Atomic: all targets succeed or all roll back,' which tells the agent the operation is transactional and safe to retry on failure — a real behavioral trait not derivable from annotations.

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

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

Front-loaded purpose sentence, then the atomicity guarantee, then a dense JSON example. No filler text; the example is long but carries parameter-interaction information that would otherwise be prose. Structure is appropriate for a 7-parameter mutation tool.

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

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

For a destructive multi-file mutation with no output schema, the description covers the essential risk (atomic rollback) and demonstrates a realistic invocation. It does not describe what the agent receives on success/failure or the effect of unlisted symbols, though require_exhaustive is documented in the schema.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents every parameter. The worked example goes further by showing how the parameters interlock — distributing named symbols across targets, keeping 'main' in source, and using source_suffix for a 'mod types;' declaration — which clarifies the relationship between keep_in_source, targets, and source_suffix that the flat schema does not convey.

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 with mechanism: 'Split a file into multiple target files by distributing symbols.' The 'multiple target files' framing implicitly separates it from single-target siblings like ast_extract_to_file or ast_move, but no sibling is named explicitly, so the differentiation is inferential 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?

The description and its worked example imply when this tool applies (a large file whose symbols should be distributed into modules), but there is no explicit when-to-use versus ast_extract_to_file/ast_move guidance, no prerequisites, and no statement of when to prefer a different sibling.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context beyond that: the return shape ("parse errors with line numbers") and language coverage (20 languages), which matters since there is no 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?

Four short sentences, front-loaded with the purpose and followed by the return value, language scope, and a concrete call example. No filler, though the example is somewhat redundant with the schema.

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

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

For a read-only, two-parameter tool whose annotations carry the safety profile, the description covers purpose, return content, and language scope. The main open question is directory handling (does a directory path recurse, and does it stop at first error?), which neither the description nor schema clarifies.

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

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

Schema description coverage is 100%, so both parameters are already documented (path as file or directory, lang as a language hint). The description's example illustrates the path format but adds no semantics the schema lacks. Baseline 3 is appropriate.

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

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

States a specific verb+resource ("Validate syntax of source files") and adds scope detail (20 languages, parse errors with line numbers). It does not name any sibling to differentiate from, though the validate/lint niche is reasonably distinct from the mutation-heavy ast_* family.

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 alternative guidance is given. The description never mentions related tools like md_lint, tidy_check, or fix_whitespace, so the agent must infer that this is the pre-edit syntax check.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, so the mutation risk is already conveyed. The description adds the 'structural block' concept and mutual exclusivity detail, which is useful. But for a destructive, non-idempotent mutation, it doesn't disclose whether the operation is reversible (e.g., via undo), whether it preserves formatting, or any file-modification side effects. This is a moderate 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?

Three sentences, front-loaded with the core operation, then selection mode, then a concrete example. No obfuscation. Slightly more verbose than a minimal description but every element serves clarity.

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 mutation with no output schema and 100% schema coverage, the description covers purpose and mechanics adequately. However, it omits critical context for a destructive tool: whether wrapping is reversible, what happens to existing comments/formatting, and any error conditions (e.g., overlapping wrappers). The annotations flag destruction but don't compensate for these omissions.

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

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

Schema coverage is 100%, so both required and optional parameters are fully documented in the schema. The description reinforces the two selection modes (symbols vs lines) and provides an example, which adds marginal value. Baseline 3 is appropriate when the schema does the heavy lifting.

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: 'Wrap existing code in a structural block (module, impl, cfg, etc.).' This clearly differentiates from siblings like ast_insert (insert new code), ast_group, and ast_rewrite_signature. However, it doesn't explicitly name a sibling it's distinguished from, so a 4 rather than 5.

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

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

The description gives implied usage through the example and mentions specifying symbols by name or line range, but offers no explicit when-to-use/when-not-to-use guidance or named alternatives (e.g., vs ast_group or ast_insert). It relies on 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?

Annotations only say this is a destructive, non-read-only write; the description adds the substantive traits an agent needs: engine staging is atomic for applied writes (all succeed or none change), misses are soft by default, absent `old` refuses by default, and the JSON report shape (match_mode, match_score, matched_text, match_count, refused[]). That is real disclosure beyond the annotation layer.

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 purpose and the atomicity guarantee, then behavior, then example — good ordering with no filler sentences. The inline issue references (#1758, #1674, #1668, #1687) are clutter that costs tokens without helping the agent.

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 15-parameter destructive tool with no output schema, the description covers the essentials: atomicity semantics, default failure policy, opt-in flags, alias precedence, and the shape of the returned JSON including the refused[] miss channel. An agent has enough to call it correctly without opening 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 description coverage is 100%, so the baseline is 3, and most description content (files vs file alias, fuzzy, allow_absent_old, require_change) restates what the schema already documents. The one genuine addition is the worked example showing a minimal valid call, which alone does not lift it above baseline.

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

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

Opens with a specific verb + resource + scope: 'Replace the same text across multiple files in one call,' which immediately separates it from single-file replace_text and from patch-style siblings. It never names the alternative tool explicitly, so the distinction is inferred from 'multiple files' 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 concrete conditional guidance for the important switches: soft-miss default with require_change=true to fail the whole batch, and refuse-by-default when exact `old` is absent unless allow_absent_old=true. It does not, however, tell the agent when to pick batch_replace over replace_text or apply_patch, so tool selection is left implicit.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation profile is known. The description adds meaningful context beyond that: transactional 'all files succeed or none change' atomicity, which is important for an agent deciding whether partial failure is possible. It does not describe error reporting or how failures surface, but the atomicity disclosure is a real contribution.

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 operation, followed by atomicity guarantees, then parameter guidance and an example. Four sentences with little waste, though the alias sentence repeats what the schema already states, slightly diluting density.

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

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

For a mutation tool with no output schema, the definition covers the operation, atomicity, and argument forms, which is most of what an agent needs. It stops short of describing success/failure reporting, the only notable gap given there is no output schema to carry that.

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

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

Schema coverage is 100% and the schema already documents the files/file alias relationship and precedence ('files wins'). The description restates the canonical-vs-alias distinction and adds a concrete example, but this largely duplicates structured data, so baseline 3 is appropriate.

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

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

States a specific verb and resource (fix whitespace in multiple files) and names the exact transformations performed: trims trailing spaces and ensures final newline. This distinguishes it from the sibling fix_whitespace (single file) and tidy_check (check-only) even without opening their 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?

The phrase 'multiple files in one call' implies the batch context, but it never explicitly tells the agent when to prefer this over fix_whitespace, tidy_check, or batch_replace, nor does it state exclusions. Usage must be inferred from the implied batch semantics.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered and the bar is lower. The description adds genuinely new context — the existing-file failure mode and the force override — which the annotations do not convey.

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 key behavioral caveat, then a compact usage example. Every element earns its place with 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?

For a 5-param destructive write tool with no output schema, the description covers the core create/force behavior and gives an example. It omits any mention of expected_sha256 stale handling or agent_preset interaction, though those are documented in the schema.

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

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

Schema coverage is 40% (low), so the description should compensate. It explains force semantics and demonstrates path/content values via the example, but path/content semantics are never described in prose, and agent_preset/expected_sha256 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 opens with a specific verb+resource ("Create a new file with specified content"). The word "new" implicitly distinguishes it from append_file/prepend_file siblings, so an agent can route correctly without opening a 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?

"Fails if the file exists unless force=true" gives a conditional on the force flag, which is borderline behavioral rather than usage guidance. It never names alternatives (append_file, prepend_file, apply_fragment) or says when to prefer this tool, so guidance 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so safety is covered structurally. The description adds genuinely useful error semantics (default not_found on a missing path; if_exists soft-skips with a success and no write), which the agent cannot infer from the schema alone. It stops short of covering rollback or the concurrency implications of the SHA 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?

The lead sentence is appropriately front-loaded, but the middle content is redundant: the if_exists=true soft-skip instruction is stated twice in near-identical wording. The example is compact and helpful, but the duplicated sentence is wasted space.

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

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

With destructive annotations and a fully documented schema, the description only needs to supply the missing-file behavior, which it does. That plus the example is sufficient for an agent to call the tool correctly, though the leftover duplication and silence on expected_sha256/stale behavior keep it from being fully polished.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including if_exists. The description restates the if_exists behavior rather than adding syntax or format meaning, so it does not exceed the schema baseline.

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

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

The opening 'Delete a file' states a specific verb and resource, making the action unambiguous among siblings like move_file and create_file. It does not, however, explicitly differentiate itself from any alternative tool; the clarity comes from the nature of 'delete' rather than comparative framing.

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

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

The description explains the default missing-path failure and offers if_exists=true as a soft-skip, which is a conditional usage nuance. It never states when to prefer this tool over siblings or any preconditions for the destructive delete, leaving usage 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?

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=false, so the safety profile is covered. The description adds essentially nothing beyond that: it does not say what happens if the selector path is not an array, whether the file is created when absent, that writes are destructive/irreversible, or how expected_sha256 staleness is surfaced.

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

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

One terse sentence plus one inline example, front-loaded with the core action. Nothing is wasted and the example compactly demonstrates parameter shape.

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 array mutation the description is thin, but annotations carry the safety signal and the schema fully documents all five parameters including stale-write protection. Missing is any note on edge-case behavior (non-array selector, absent file) that an agent would want before a destructive write.

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

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

Schema description coverage is 100%, so path, value, selector, agent_preset, and expected_sha256 are all documented in the schema. The description's example reinforces the three required params but adds no format or constraint detail beyond what the schema already provides, which is the baseline 3.

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

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

The description gives a precise verb+resource: append a value to an array at a selector path. This is clearly distinguishable from sibling mutations like doc_prepend, doc_set, doc_merge, and doc_delete. It stops short of naming a sibling to contrast against, but the operation itself is specific.

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 a concrete example showing the three required parameters in use, but no statement of when to reach for doc_append versus doc_prepend, doc_set, or doc_update, and no exclusions or prerequisites. The agent is left to infer usage purely from the verb.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful behavior not in the annotations: the success payload carries changed/removed counts, deleting a missing key is idempotent (removed=0, exit 0/ok), which prevents an agent from mistaking a no-op for a failure.

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 in the first sentence and the total length is appropriate for a mutation tool. The middle sentence about 'CLI --json and MCP/tx' is tersely worded and slightly cryptic, but not wasteful.

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 mutation with no output schema, the description covers the important return semantics (changed/removed, idempotent no-op) and the schema covers the concurrency guard via expected_sha256. It omits any note on permission requirements or revertibility (undo_list/undo_restore exist as siblings), which is the only 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 100%, so path, selector, expected_sha256, and agent_preset are all documented in the schema; baseline is 3. The description only echoes path/selector via the example and adds no syntax detail (e.g. how to escape dots in a key name) beyond what the schema already provides.

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

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

States a specific verb (delete), the exact resource (a value at a selector path), and the supported file formats (JSON, YAML, TOML). The 'selector path' framing implicitly separates it from the predicate-based sibling doc_delete_where and from whole-file siblings such as delete_file.

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 shows a concrete invocation example, so usage is implied, but it never states when to reach for this tool over doc_delete_where, delete_file, or ast_delete_symbol, and gives no exclusions or preconditions. An agent must infer the selection from sibling names 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the base safety profile is covered. The description adds genuinely new behavior: changed/removed result counts, 0 when nothing matches, and exit 0 / ok idempotency — useful for a mutating tool with no output schema. It does not cover permissions or the stale/expected_sha256 failure path beyond the 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?

Front-loaded with the action and predicate mechanism, then progressively adds per-case syntax and an example with no filler sentences. Some parsing cost comes from the compressed '(CLI) or the predicate field (plans)' parenthetical and stacked clauses, 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?

With 5 parameters, no output schema, and mutation semantics, the description supplies the return-field summary (changed/removed) and idempotency guarantee that would otherwise be missing. Remaining gaps — ordering of deletions, error surface other than stale, and the agent_preset interaction — are minor 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 already 100%, so baseline is 3, but the description goes beyond the schema by spelling out multiple predicate dialects (=x, _=x, value=x, field=value), nested-path predicates, and a full worked JSON example mapping predicate/path/selector. That is real added semantic value for the most error-prone 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 and resource with mechanism: delete array elements matching a key=value predicate, and explicitly contrasts with doc.update's inside-the-path filtering. An agent can distinguish this from the large sibling set (doc_delete, doc_update, ast_delete_symbol) without opening a 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?

Gives concrete selection guidance per case (scalar arrays use .=x/_=x/value=x; object arrays use role=admin; nested paths use settings.theme=dark) and names doc.update as the alternative with the differentiator. It stops short of a full when-not-this-tool rule, but the routing information is clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered by structured data. The description usefully adds the supported input formats, but says nothing about output shape (unified diff vs. structured summary), depth of comparison, or behavior on missing/unparsable files, which matters given there is no 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 short sentences, front-loaded with the core action followed by a concrete example. Nothing is padded, though the inline JSON example is slightly inelegant inside prose.

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 diff tool with no output schema and no annotations on comparison semantics, the description should say what the differences output looks like and how errors are surfaced. Format support is covered, but return-shape disclosure 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 100% and both parameters are documented as file paths relative to the working directory, so the schema does the heavy lifting. The description's example duplicates that meaning and adds only the file-format scope, which is a marginal gain.

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 ('Compare two structured files ... and show differences') and scopes the supported formats to JSON, YAML, or TOML, which implicitly separates it from sibling ast_diff. It never names an alternative sibling explicitly, so the 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?

There is no when-to-use guidance, no exclusions, and no pointer to alternatives such as ast_diff for source-code comparisons. The included example illustrates argument shape rather than usage context.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds the useful conditional-write rule, but says nothing about the expected_sha256 stale handling, error behavior, or the agent_preset replace mode that the schema mentions, so the added behavioral value is modest.

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 conditional rule and immediately followed by a compact, high-signal example. No filler and nothing redundant.

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 five-parameter mutation tool with fully-covered schema and existing annotations, the description covers the essential contract (conditional set). It omits any mention of the stale-hash guard or the agent_preset behavior, but those are documented in the schema, so the gap is minor.

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

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

Schema description coverage is 100%, so all five parameters are already documented, including path, picker, value and the stale/preset flags. The inline example adds a concrete illustration of the selector/path/value shape but no semantics beyond the schema, so baseline 3 applies.

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

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

The description states a specific operation with condition: set a value only if the selector path does not already exist. That conditional-write semantics is clear enough to distinguish it from an unconditional sibling like doc_set, 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?

It communicates the key usage condition (only write when the key is absent), which implies when to prefer this over doc_set, but it never names an alternative or an explicit when-not case. Guidance is inferred 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description usefully adds that three file formats and dot-notation selectors are supported, but it says nothing about the non-happy paths — missing key, malformed file, unsupported extension — or about what value shape comes back.

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 capability and followed by a concrete example. No filler, no restatement of the tool name, and every clause adds 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?

There is no output schema, so the description carries the burden of explaining the return value, and it does not describe the returned value's type, nesting, or error behavior for an unmatched selector. Given the simplicity of a two-parameter read it is adequate, but not complete for an agent that must handle misses.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the `key` alias and a sample selector. The description's example ({"path": "package.json", "selector": "version"}) restates rather than extends the schema, so the baseline 3 applies.

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

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

The description states a specific verb+resource+mechanism: 'Read a value from a JSON, YAML, or TOML file by selector path.' The supported formats and the selector mechanism distinguish it from read_file (whole-file reads) and from mutation siblings like doc_set/doc_append/doc_delete. It stops short of naming a sibling, so an agent must infer the boundary with doc_query on its own.

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 mechanism (use when you need one value from a structured data file, addressed by dot-notation path), but there is no explicit when-to-use statement, no when-not, and no named alternative such as doc_query or read_file. The inline example shows the calling shape rather than the selection criteria.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the write/destructive profile is covered. The description usefully adds merge semantics (partial update rather than replace) and the selector-target concept, but says nothing about error/failure behavior, staleness handling, or what happens to existing keys not mentioned in the value.

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 semantics front-loaded and an inline example that earns its place by showing the path/value shape. 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?

For a destructive write tool whose safety profile is carried by annotations and whose parameters are fully documented in the schema, the description supplies the essential distinguishing concept (deep-merge into root or selector). Only the missing routing against sibling doc_* tools keeps it from being fully complete.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description's example reinforces path/value usage and it echoes the selector concept, but it adds no format or syntax detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

States a specific verb (deep-merge) and resource (a JSON object into a document root or selector path), which is more precise than a generic 'update'. However, it does not differentiate from close siblings like doc_set, doc_update, or doc_ensure, which an agent would need to disambiguate among.

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 example shows how to call it but gives no when-to-use guidance, no when-not-to-use, and names no alternatives among the many doc_* siblings. The agent must infer that 'merge' rather than 'set' is the selection criterion.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds the same-file constraint but does not disclose the destructive behavior an agent most needs here — whether an existing destination value is overwritten, whether a missing 'from' errors, or whether the move is atomic. With annotations doing the heavy lifting, this is a moderate 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?

Two sentences, zero padding, with the core operation front-loaded and the example immediately following to disambiguate the argument roles.

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 three-required-parameter mutation tool with full schema coverage, annotations, and no output schema, the description is largely sufficient. The main omission is conflict semantics on the destination path, which matters given the destructive hint.

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

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

Schema description coverage is 100%, so all five parameters including agent_preset and expected_sha256 are already documented. The example demonstrates how path/from/to combine, which is mildly useful, but no syntax or format meaning is added beyond the schema.

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

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

States a specific verb and resource (move a value from one selector path to another) and scopes it with 'within the same file,' which usefully separates it from move_file and ast_move. The inline example makes the operation concrete. It stops short of explicitly naming which sibling to prefer for cross-file or AST moves.

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 example illustrates a call but gives no when-to-use guidance, no prerequisites, and no comparison against alternatives like ast_move, move_file, or doc_set. An agent must infer from the name alone when this is the right tool.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation/safety profile is covered by structured data. The description adds nothing beyond that – no mention of write atomicity, the stale/expected_sha256 guard behavior, or what happens when the selector does not resolve to an array.

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; the action and target are stated immediately.

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 mutation tool with no output schema, the description covers the core action and the schema covers all parameters, but it omits behavioral outcomes such as error handling on a stale file or non-array selector, leaving gaps an agent would want filled.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates 'array at a selector path' without adding syntax, type, or constraint detail beyond what the schema already documents for path, selector, and value.

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 (prepend) and resource (a value into an array at a selector path), so an agent can tell it apart from doc_append conceptually. It does not, however, explicitly differentiate itself from the many sibling tools that also mutate documents (doc_set, doc_update, doc_append).

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 choose this tool over doc_append, doc_set, or doc_update, nor any stated prerequisites or exclusions. The usage is only implied by the verb 'prepend'.

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?

Instead of just relying on the readOnlyHint/openWorldHint annotations, the description adds behavioral detail: fail-closed 'ambiguous' results for items[*], the requirement that select uses inline predicates rather than a separate predicate field, and the per-action preconditions. It does not describe return format, but the annotations already establish the read-only, non-open-world safety profile.

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

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

The description is compact and front-loaded with the purpose, then lists actions and their constraints, ending with a worked example. It is dense to the point of being run-on, but every sentence serves a purpose and there is 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?

For a 2-required-param read-only query tool with no output schema and full schema coverage, the description covers all actions, selector semantics, the ambiguity failure mode, and an invocation example. It is complete enough to call correctly; only the exact return shape is unstated, which is minor given the action names imply it.

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

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

Schema coverage is 100%, so the schema already documents all three parameters, including the selector alias 'key' and which actions require or default selector. The description repeats and reinforces the same semantics with examples rather than adding new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource ('Query a JSON, YAML, or TOML file') and enumerates all five query actions with concrete behavior. An agent can distinguish it from read_file, doc_get, and other siblings because it is explicitly a structured-data query tool with has/keys/len/select/flatten.

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

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

The description gives usage constraints per action (e.g., keys need one object, len needs one object or array, items[*] is fail-closed ambiguous, use items[0]/items[1]) which shape how to invoke. It does not, however, state when to choose doc_query over read_file, search_files, or doc_get, so explicit sibling routing is 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known; the description adds substantive context beyond that: parser-backed writes that always produce valid output, default key creation, not_found on missing files, and the if_exists soft-skip semantics. It does not disclose concurrency/rate considerations, so it stops 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?

Front-loaded with the core action and formats, but visibly redundant: the wildcard/predicate exclusion appears twice and the if_exists soft-skip explanation is repeated nearly verbatim. Trimming those duplicates would improve it without losing 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?

For a 7-parameter mutation tool with annotations and no output schema, the description covers the essential semantics: valid-output guarantee, missing-file/key behavior, and the alternative for wildcard writes. It leaves out only edge concerns like rollback interaction (left to the strict schema field) and the SHA-256 staleness guard.

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

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

Schema description coverage is 100%, so the schema already documents path, selector, value, strict, if_exists, agent_preset, and expected_sha256. The description restates if_exists and selector format and adds one concrete example, but mostly duplicates the schema rather than adding new meaning, so baseline 3 applies.

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

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

States a specific verb and resource: set a value at a single concrete selector path across enumerated file formats. It also distinguishes itself from siblings by naming doc_update for multi-match writes. An agent can identify the tool's scope 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?

Explicitly gives when-not-to-use (predicates/wildcards -> doc_update) plus default vs if_exists behavior for missing files/keys, which is genuine routing guidance. However, it references the alternative inconsistently as both 'doc.update' and 'doc_update / plan doc.update', which muddies the handoff slightly.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false; the description adds the crucial multi-match/multi-write semantic ("Multi-match writes") that explains what the destructive behavior actually does. It does not cover the expected_sha256/stale-failure path, but that is documented in the 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?

Front-loaded and includes a useful example, but the wildcard/predicate guidance is stated twice ("Use wildcards (items[*].enabled) or selector predicates (items[name=foo].v)" reappears as "Multi-match writes: use selector predicates or wildcards..."), which is redundant filler.

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

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

For a 5-param mutation with no output schema, the description covers purpose, selector syntax, sibling choice, and an example, which is enough to invoke correctly. It omits mention of agent_preset and the stale-guard behavior, though both are covered in the schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by clarifying that the filter is part of the selector string ("Not a separate --where flag") and by supplying concrete selector examples. It adds real meaning over the terse schema field descriptions.

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

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

States a specific verb and resource ("Set a new value at every location matching a selector") and immediately names the sibling it competes with ("Prefer this over doc_set when filtering by field"). An agent can distinguish it from doc_set and doc_delete_where without opening a 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?

Gives explicit usage context: use selectors/wildcards for multi-match writes and prefer this over doc_set when filtering by field. It stops short of when-not guidance (e.g., when to fall back to doc_set or how it relates to doc_delete_where), so not a full 5.

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

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

Annotations declare destructiveHint=true, and the description adds concrete behavioral contracts: atomicity, cwd sandboxing rules (relative-only, no ../ escapes), that plan.format/validate are ignored on MCP, and the for_each conflict. These go well beyond the annotation's binary flags. Does not state rollback semantics on partial failure beyond 'atomically'.

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 purpose, then constraints, then a worked example. Dense but every clause carries a real constraint. Borderline long, but the sandboxing rules and alias notes justify 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?

No output schema, so the agent has no structured return contract; the description covers inputs and semantics well and even provides an example plan. Missing only return/status reporting and failure handling for an inherently destructive, atomic operation.

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

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

Schema coverage is already 100% with useful per-param descriptions. The description still adds value: the op/ops alias, that arbitrary extra fields are allowed, that plan.cwd must be relative under the workspace, and it redirects to operation_schema for op field details. Slightly exceeds the baseline-3 expectation.

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 ('Execute a multi-step transaction plan atomically') and explains the MCP-to-CLI equivalence ('MCP equivalent of patchloom tx'). An agent can immediately distinguish this from atomic individual-op siblings like apply_patch or doc_set.

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 clear operational context (inline plan or plan_path, use operation_schema to look up op fields) and rules ('Do not set both plan.cwd and for_each'). Lacks an explicit statement of when to prefer this over looping individual atomic tools, though the atomicity framing implies 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the read-only nature is covered. The description reinforces this and adds that output is structured JSON matching the CLI, but adds little beyond what annotations and the CLI reference imply.

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 purpose, then parameter guidance, then the read-only guarantee, ending with a concrete example. Efficient overall, though the embedded example adds some length without new information beyond the schema.

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

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

With no output schema, the description carries the burden of describing return values, and it only says 'structured JSON' with a CLI reference rather than detailing the returned structure. Adequate for invocation but thin on what the agent will receive.

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

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

Schema description coverage is 100%, so both the plan/path alternatives and the format hint are already documented in the schema. The description restates these (inline plan vs plan file, json/yaml/toml) without adding syntax or precedence rules beyond the schema.

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

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

States a specific verb (explain) and resource (tx plan) and clarifies that it returns structured JSON without executing the plan. This implicitly distinguishes it from the sibling execute_plan, though it never names that 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?

By stating 'does not execute the plan', the description implies this is for previewing/understanding rather than running a plan, which is useful context. However, it never explicitly names execute_plan as the alternative or states when-not to use this tool.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds real behavioral context: one write per text file, EOL flattening to the dominant style, opt-out via normalize_eol, and the subtle commit-time write_policy interaction (#1840, #1847). It stops short of describing staleness/error behavior beyond the schema's expected_sha256 note.

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 purpose and scope, then defaults and precedence. Dense but every sentence carries behavioral weight; the embedded example and issue references add slight bulk but are justified.

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

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

For a 10-param mutation tool with no output schema, the description covers scope, defaulting, precedence, EOL handling, and the write_policy edge case. Nothing critical to invoking it correctly is missing.

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

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

Schema coverage is 60%, so the schema documents several params but not all. The description usefully explains defaults for trim_trailing_whitespace, ensure_final_newline, and normalize_eol, plus the override precedence, but leaves lines, dedent, indent, agent_preset, collapse_blanks, and expected_sha256 largely to the schema. Baseline 3 fits given partial coverage.

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 ('Normalize whitespace in a file or directory') and clarifies scope (directory expands with the same ignore-aware walker as CLI tidy fix, one write per text file). An agent can immediately distinguish this mutation tool from the read-only sibling tidy_check.

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?

Explains when fields apply and how defaults behave, plus the precedence chain (defaults → plan write_policy → op fields). However it never explicitly names tidy_check or batch_tidy as alternatives or states when NOT to use this tool, so routing guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description still adds real value by disclosing the return shape (modified/created/deleted lists) and a non-obvious filtering behavior (.patchloom/ paths excluded from --apply undo sessions), which the agent could not infer otherwise.

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

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

Four short sentences, each load-bearing: purpose first, then return contents, then the filtering caveat, then the parameter note. No filler or redundancy.

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

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

With no output schema, the description carries the burden of describing results and does so adequately. It is nearly complete for a zero-parameter read tool; the only minor omission is any statement about untracked/ignored file handling beyond the .patchloom 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?

There are zero parameters, so the baseline is 4; the explicit 'No parameters required.' correctly confirms this rather than leaving the agent to guess. Nothing further is needed for an empty schema with 100% coverage.

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: 'Show uncommitted file changes vs git HEAD.' An agent immediately knows this is a read of working-tree state. It does not, however, explicitly differentiate itself from adjacent status/diff siblings such as undo_list or doc_diff.

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 scope note ('Omits .patchloom/ backup paths from --apply undo sessions'), which hints at the undo workflow context. But there is no explicit when-to-use / when-not-to-use guidance and no named alternative among the many diff/undo siblings.

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

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

Annotations only declare readOnlyHint and openWorldHint, so the description adds substantial behavioral context beyond them: result capping (default max_results=500), truncated+total_matched reporting, and the nuance that max_depth prunes the walk while max_results counts all in-depth matches before truncating. It does not describe return shape, but no output schema exists and the truncated/total_matched signal 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?

Front-loaded with the primary purpose and the substitution guidance, then detail on capping and depth. Slightly dense and mixes several concepts (routing, caps, depth, path preference, example) 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?

For an 8-param read-only listing tool with full schema coverage and annotations, the description covers the key runtime behaviors an agent needs: default cap, truncation signal, depth pruning, and path preference. Missing only explicit return-format detail, which is largely implied by truncated/total_matched.

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

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

Schema coverage is 100%, so the schema already documents all 8 parameters, including defaults, precedence rules, and depth semantics. The description restates max_results, max_depth, and exclude_patterns behavior and adds an example, which is helpful but largely duplicative of the schema. Baseline 3 applies.

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

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

States a specific verb+resource ('List files under the workspace or given roots') and immediately differentiates from siblings by naming search semantics and explicitly telling the agent to use this 'instead of a generic filesystem MCP list_dir/tree.' The sibling list contains search_files, so the cross-reference is meaningful.

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 clear routing guidance ('Use this instead of a generic filesystem MCP list_dir/tree') and a concrete example call. It does not contrast against the actual sibling search_files, which is the closest in-family alternative, so routing is clear but not fully exhaustive.

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

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

Annotations already declare destructiveHint=true, so the safety profile is known, but the description goes further and specifies what is destroyed: the entire second section body is discarded, not merged, and unique second-section content is explicitly lost. That is meaningful context an annotation cannot convey. It still omits irreversibility/undo and idempotency behavior.

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

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

Two sentences state the same rule twice — 'removes later whole sections with the same heading level+text' restates sentence one almost verbatim. Roughly half the text is redundant, which is under-editing rather than concision.

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 markdown mutation with no output schema, the description should cover outcome/reversibility and the expected_sha256 stale-write path; it covers neither. The core removal semantics are present, but an agent still lacks enough to call this safely and correctly.