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

With no annotations provided, the description carries the full behavioral burden, and it delivers meaningful context: it discloses the line-ending insertion edge case ('Inserts the file's line ending first when the file does not already end with one') and warns about concurrent-call hazards, implying non-atomicity. It does not mention failure behavior for missing files, 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?

The description is compact and front-loaded: purpose first, then the line-ending nuance, then the critical concurrency warning, then a working example. Every sentence earns its place — there is no filler or repetition of the schema.

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

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

For a simple two-parameter tool with no annotations and no output schema, the description covers the essential ground: purpose, edge-case behavior, concurrency hazard, an atomicity alternative, and a usage example. The main gaps are the missing-file failure behavior and what the tool returns, but these are minor for a simple append 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 0%, so the description must compensate, and it does: 'Append content to an existing file' maps content and path directly, and the example {"content":"#[test]\nfn new_test() {}\n","path":"tests/test.rs"} demonstrates concrete formats for both parameters and clarifies that path must point to an existing file. It lacks deeper parameter nuance (e.g., size limits or encoding) but compensates adequately.

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 sentence uses a specific verb plus resource: 'Append content to an existing file.' The word 'existing' explicitly distinguishes it from create_file, and 'append' contrasts with prepend_file and replace_text. The edge-case detail about line endings and the concrete example reinforce the tool's exact function.

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

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

The description provides clear context for when to use the tool (append to an existing file) and gives an explicit exclusion: 'do NOT issue concurrent calls targeting the same file.' It also routes to an alternative, 'use execute_plan for multi-op atomicity.' It stops short of a 5 because it does not explicitly contrast with direct siblings like prepend_file or create_file.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses that marker lines are stripped, that merging is fail-closed without anchors, that the operation mutates the target file, and that concurrent calls to the same file are unsafe. It lacks explicit return/error behavior, but the core side effects and constraints are clearly stated.

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

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

The description is front-loaded and includes a great example, but it repeats the same core facts: anchor placement appears twice, marker stripping appears twice, and the no-anchor-merge constraint appears twice. The redundancy makes it longer than necessary, though the structure remains logical.

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

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

Given the tool's complexity, the combination of description and rich schema covers the purpose, the one-of anchor invariant, marker stripping, fail-closed behavior, concurrency safety, and a worked example. There is no output schema, and return-value details are not explained, but that is not essential 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?

The schema already documents all 7 parameters at 100% coverage, so the baseline is 3. The description adds useful semantic context beyond the schema by emphasizing the exactly-one-of after/before/old requirement, the uniqueness of the anchor, and by providing a concrete JSON example showing how fragment, path, and after work together.

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

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

The description states a specific verb and resource: applying a fragment to a file by stripping lazy marker lines and inserting or replacing at a required unique anchor. It also differentiates from siblings by explicitly directing precise edits to replace/ast tools rather than this one.

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

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

It gives explicit when-to-use guidance: 'Prefer for lazy-snippet agent output when anchors are known' and 'use replace/ast for precise edits.' It also warns against concurrent calls and points to execute_plan for multi-operation atomicity, which is strong routing and exclusion information.

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

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

With no annotations provided, the description carries the full burden, and it delivers. It discloses unique-match ambiguity leading to no write, empty-hunk unlink behavior, hunked-delete ordering, leftover-byte rewrites, stale-line ambiguity, three-way merge on on_stale=merge, conflict-marker writing, and the warning to never commit conflict markers. This is exceptionally transparent about edge-case 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?

The description is long but every sentence carries substantive information about formats, edge cases, or usage warnings. The density is justified by the tool's complexity. It could be slightly better organized with paragraph breaks, but the front-loaded purpose and example at the end keep it 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 write tool with multiple input formats, ambiguity handling, and conflict behavior, the description is complete. It includes an example, covers all parameter semantics, warns about concurrency, and explains how to handle stale diffs. No output schema is present, but for a mutating tool the input and behavioral coverage is sufficient.

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

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

Schema description coverage is only 40%; diff, on_stale, and allow_conflicts lack schema descriptions. The description explains the diff parameter's accepted formats in detail, clarifies on_stale=merge behavior, and states that allow_conflicts=true writes conflict markers. It also clarifies replace_all semantics beyond the schema. This fully compensates for schema gaps.

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

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

The description opens with a specific verb and resource: 'Apply a unified diff, a Codex *** Begin Patch document, or an Aider SEARCH/REPLACE / DiffFenced document.' It enumerates three distinct input formats, making the tool's scope concrete and separating it from siblings like apply_fragment or replace_text.

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

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

The description provides actionable usage routing: use file.delete for path-only unlink, use execute_plan for multi-op atomicity, and avoid concurrent patches. It also explains when to set replace_all=true and on_stale=merge. It doesn't systematically compare against all sibling tools, but the guidance it does give is explicit and practical.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It communicates the read-only nature of the operation via 'Extract,' names the tool's language coverage, and clarifies the reverse-dependency mode. This goes beyond the raw schema and gives an agent useful expectations about what the tool will do.

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, each carrying useful information: the core operation, language support, and a concrete invocation example. No filler or redundancy; the description is appropriately front-loaded and easy to scan.

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

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

The description covers the main invocation path, optional language support, reverse mode, and a representative example, which is sufficient for an agent to select and call the tool correctly. It does not detail output format or error behavior, but no output schema is available and those omissions are not critical for a straightforward extraction 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 baseline is 3. The description adds a concrete path example and language context, but the reverse behavior is already described in the schema, and the lang parameter receives no additional semantic detail. The description therefore provides only modest value 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?

The description clearly states a specific verb and resource: 'Extract import/dependency statements from source files.' It also lists supported languages and an example path, making the tool's purpose concrete. However, it does not differentiate itself from the similarly named sibling tool ast_imports, so it misses full sibling distinction.

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

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

The description gives a practical usage hint with 'Use reverse=true to find what imports a file' and includes an example call. It does not, however, explain when to choose ast_deps over alternatives like ast_imports, ast_refs, or ast_impact, leaving tool-selection guidance implicit 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?

With no annotations, the description carries the burden of behavioral disclosure. It does explain the diff granularity, the symbol-level output, and git ref comparison, which is useful. But it does not state whether the operation is read-only, whether it modifies anything, or what the output structure looks like.

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

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

The description is compact and front-loaded. Every sentence contributes: the first defines the operation, the second clarifies output granularity, the third establishes git ref usage, and the example provides a concrete invocation pattern. No unnecessary 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 moderately simple tool with full schema coverage and no output schema, the description provides enough to select and invoke the tool correctly. The example clarifies required input. The main gap is that it does not describe the return format, but that is not essential for basic invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description's example demonstrates usage of 'path' and 'from', adding a small amount of practical meaning, but it does not add detail about the 'to' or 'lang' parameters or their interactions.

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

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

The description clearly states that the tool performs a structural diff between two file versions, showing added, removed, and modified symbols rather than line-level changes. This makes the tool's purpose specific and distinguishes it from generic diff or doc_diff 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 description gives clear context: it compares against git refs and is explicitly not a line-level diff. It provides a concrete example showing how to specify path and from. However, it does not name alternative tools or when-not conditions beyond the line-level exclusion.

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 are absent, so the description carries the behavioral disclosure burden. It reveals the un-indenting behavior for modules with unwrap=true, warns about concurrent write hazards, and illustrates a realistic invocation with the example. It does not mention side effects like source-file modification or force-overwrite behavior, but the most operationally critical traits are covered.

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 tight: one purpose sentence, one behavior note, one important warning, and one illustrative example. There is no filler, and the highest-priority warning is clearly marked. The example earns its place by clarifying the parameter relationships.

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

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

Given 11 parameters, no annotations, and no output schema, the description is helpful but not fully complete. It explains core behavior and concurrency constraints, but does not clarify return values, whether the source file is modified in place, or how update_imports and force interact in real usage. The example mitigates some gaps, but not all.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes slightly beyond the schema by supplying a complete example that shows how source, symbol, target, replacement, and prepend relate in practice. This helps an agent understand typical usage patterns more concretely than property descriptions alone.

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

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

The description clearly states the action: 'Extract a symbol (module, function, struct) to a separate file.' This is specific about the verb, resource, and scope. It does not explicitly differentiate itself from sibling tools like ast_move or ast_split, but the phrase 'to a separate file' narrows the intent sufficiently.

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 an explicit usage caution: 'do NOT issue concurrent extracts/writes against the same files; use execute_plan for multi-op atomicity.' This provides a concrete when-not-to-use and points to the correct alternative for atomic multi-op workflows. It does not compare against all sibling extraction/move tools, but the guidance is actionable.

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

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

With no annotations present, the description carries the full burden. It discloses that the tool mutates the file, creates or appends the module, and has an important concurrency hazard; it also points to execute_plan for atomicity. It does not describe return values or error behavior, but the most operationally important behavioral traits are covered.

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: purpose, critical warning, then a concrete example. Every sentence contributes actionable information with no filler.

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

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

For a mutation tool with no output schema and no annotations, the description covers the core usage scenario well: file, module, symbols, preamble, and atomicity. It stops short of explaining failure cases or return values, but the combined schema and example provide enough to call the tool correctly in typical cases.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value with a concrete example binding path, module, symbols, and preamble, and demonstrates a realistic preamble value like 'use super::*;'. Position and lang remain documented only by the schema.

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

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

The description states a specific verb and resource: group symbols into a named module within a file, with clear create-or-append behavior. The example makes the intent unambiguous and distinguishes it from related AST mutation tools like ast_insert and ast_move.

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

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

It explicitly warns against concurrent writes to the same file and directs multi-operation scenarios to execute_plan, which is a clear when-not and alternative guidance. It does not exhaustively compare against all sibling AST tools, but the key usage constraint is stated plainly.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the core algorithm (traversing the reference graph for transitive dependents) but leaves side-effect status implicit and does not describe output format or limitations. The word 'analysis' implies read-only, but that is not stated explicitly.

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 well-structured sentences with a concrete example, leading with the core concept 'Transitive impact analysis' before providing detail. Every sentence earns its place, and the example is placed at the end without disrupting the conceptual summary.

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

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

The tool has no output schema, and the description does not state what the result looks like (e.g., list of symbols, file paths, or a graph). It provides the purpose and an example input, but an agent cannot confidently anticipate the return shape. This is a notable gap for a tool without an output 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 schema already documents symbol, path, and depth. The description adds an example input, which is helpful for understanding parameter combinations, but it does not elaborate on parameter meaning or format beyond the schema. This matches the baseline for high schema 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?

The description states a specific verb and resource: 'Traces the reference graph to find all direct and indirect dependents.' It clearly identifies 'transitive impact analysis' as the core function, which distinguishes it from sibling tools like ast_refs or ast_deps that likely handle direct references or dependencies. The scope ('all direct and indirect') is explicit and unambiguous.

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

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

The phrase 'what symbols are affected by changing a given symbol' gives a clear use case: use this tool when planning a change to assess downstream impact. It does not explicitly name alternatives or exclusion conditions, but the context is unmistakable within the ast_* family, and the transitive nature sets it apart from more direct reference tools.

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

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

With no annotations, the description carries the full burden, and it provides meaningful traits: idempotent adds, deduplication behavior, list mode, and a critical concurrency warning. It does not disclose return format or edge-case behavior such as handling nonexistent files, but the most important behavioral warnings are present.

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: key actions first, then mode behavior, then a critical concurrency warning, then a concrete example. Every sentence adds distinct value with no redundancy.

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

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

For a tool with 5 parameters, no output schema, and no annotations, the description covers the main modes, the concurrency hazard, and gives an example. It could be more complete by describing the return value or format of the listed imports, but the essentials for correct invocation are present.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds useful semantics by explaining that omitting mutation args triggers list mode and that adds are idempotent. The example also demonstrates the expected shape of add values, going 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?

The description clearly states the tool's purpose: managing import/use statements with add, remove, and deduplicate actions, plus a list mode when no mutation args are given. This distinguishes it from sibling tools like ast_read or ast_insert by focusing specifically on import/use statement manipulation.

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

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

It explicitly explains when to use the tool in different modes: mutation args trigger modifications, while no mutation args triggers listing. It also gives a clear when-not-to-use rule: do not issue concurrent writes when mutating, and use execute_plan for multi-op atomicity.

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

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

With no annotations, the description carries the full transparency burden. It mentions that indentation is auto-detected and warns about concurrent writes, but it does not describe failure modes, what happens when the target symbol is not found, or whether the operation is idempotent.

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

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

The description is compact and well-structured, covering purpose, key positioning options, a behavioral warning, and a concrete example. Every sentence contributes actionable information without unnecessary verbosity.

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

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

The description provides enough context to invoke the tool correctly for typical use cases, including the mutually exclusive positioning parameters and the warning about concurrent writes. It omits details about return values and error handling, but no output schema is expected and the core usage is adequately covered.

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

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

Schema coverage is 100% and the description adds useful context such as mutual exclusivity among after/before/inside, the meaning of position within inside, and the path being relative to the working directory. It could clarify the expected format of the symbol name but is otherwise clear.

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

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

The description clearly states that the tool inserts code at a structurally-aware position, either inside a module/impl/struct (at start or end) or after/before a named symbol. This distinguishes it from plain file append/prepend tools in the sibling list.

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 provides a specific warning against concurrent writes and directs users to execute_plan when multiple operations need atomicity. However, it does not explicitly compare itself to other insertion tools like append_file or apply_fragment, relying on the structural-awareness phrasing to imply when it should be chosen.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does convey that the tool enumerates symbol definitions, supports 20 languages, and accepts either a file or directory. However, it omits behavioral details such as whether directories are traversed recursively, how unsupported languages are handled, and what the returned data looks like.

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

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

The description is two sentences plus a short JSON example, with the core purpose front-loaded. Every element earns its place: the verb+resource, the language support claim, and the concrete invocation example. There is no redundant or filler 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?

The input side is well covered: all three parameters are documented in the schema and the description gives a working example. However, the lack of an output schema and the absence of any disambiguation from the many sibling ast_* tools means an agent cannot fully determine what response to expect or when to select this tool over a close alternative.

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, kind, and lang. The description adds a compact example showing how 'path' and 'kind' can be combined, but it does not provide 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?

The description states a specific action ('List symbol definitions') on a concrete resource ('file or directory'), and gives examples of valid invocations. It is clear enough to distinguish from most sibling tools, though it does not explicitly name a differentiating 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?

No guidance is provided for when to use this tool versus alternatives such as ast_search, ast_map, or ast_read. The description implies a use case through the verb 'list', but it never states exclusions, prerequisites, or conditions for preferring another 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?

With no annotations, the description carries the full burden. It does disclose meaningful behavior: PageRank-based ranking and token-budget-aware output. However, it does not explicitly state that the command is read-only or describe error handling, limits, or output formatting edge cases.

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 concrete JSON example. The core ranking behavior is front-loaded, and there is no filler or repetition of 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?

Input-side details are well covered by the schema and example, but there is no output schema, and the description only vaguely says it 'shows' important symbols. The exact returned shape/format is not specified, which is a meaningful gap for an agent consuming the result.

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

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

Schema description coverage is 100%, so the baseline is 3. The example reinforces that path and max_tokens go together, but it adds no substantive meaning beyond the schema's parameter descriptions, especially for boost and focus.

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

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

The description uses a specific verb and resource: 'Generate a ranked repository map' via 'PageRank over the symbol reference graph.' It also clarifies what the output contains ('most important symbols') and distinguishes itself from AST siblings like ast_list or ast_deps.

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 the tool—when an overview of important symbols is needed—but it never explicitly states when to prefer it over alternatives like ast_list, ast_search, or ast_deps. There are no exclusions or explicit when-not-to-use conditions.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It clearly states that the tool removes from the source, inserts into the target, creates the target file if needed, and warns against concurrent writes. It does not disclose reversibility or error behavior, but the core destructive and file-creation traits are transparent.

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

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

The description is compact and well-organized: core semantics first, then the critical concurrency warning, then a concrete example. Every sentence earns its place, and the example makes parameter usage immediately understandable.

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 9 parameters, no annotations, and no output schema, the description covers the central behavior, file creation, and a critical concurrency constraint. It could be more complete by referencing the ast_move alternatives or describing return/error behavior, but the provided example and warning make it largely sufficient 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 description coverage is 100%, so the baseline is 3. The description adds a concrete example showing path, target, symbols, and target_prepend, but does not add extra meaning for position, update_imports, new_module_path, or old_module_path beyond what the schema already provides.

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

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

The description uses a specific verb and resource: 'Move symbols between files' and explicitly states the behavior 'Removes from source, inserts into target (creating it if needed)'. This clearly differentiates it from file-level tools like move_file or copy-like operations, since the destructive nature of the move is stated up front.

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 explicit guidance about when not to use it concurrently and directs users to execute_plan for multi-operation atomicity. However, it does not explicitly contrast ast_move with similar siblings such as ast_extract_to_file or ast_rename, so it stops short of full alternative 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?

With no annotations, the description carries the full burden. It discloses a meaningful behavioral trait: AST parsing finds the exact definition rather than a text match. However, it does not mention output format, error behavior when the symbol is missing, or how lang affects parsing, leaving significant behavior undisclosed.

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 short sentences plus a compact JSON example. The action is front-loaded, and every clause adds information: the target, the method, and a concrete call shape. No filler or repetition of schema details.

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 tool with no annotations and no output schema, the description gives the core behavior and example but omits return format, failure modes, and the role of lang/context. This is adequate for a simple invocation but not fully complete for an agent handling edge cases.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description only supplies example values for path and symbol and does not clarify lang or context beyond their schema descriptions, meeting the baseline but adding no extra semantic 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 action: read a symbol's source code from a file, with the method (AST parsing) and scope (exact definition). This clearly differentiates from siblings like read_file, which reads whole files, and ast_search, which locates symbols rather than returning their code.

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 usage is implied: use when you know the file path and symbol name, as shown in the example. However, there are no explicit when-to-use vs alternatives statements, such as 'use ast_search when the symbol is unknown' or 'use read_file to read the entire file'.

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?

There are no annotations, so the description carries the behavioral burden. It clearly signals a read-only AST analysis operation and calls out a key behavioral distinction: definitions are separated from references. It could add more about output shape or language limitations, but the core behavior is disclosed.

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

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

Two sentences plus an example with no filler. The core behavior is front-loaded, and every part of the description earns its place.

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

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

The description and full schema coverage are enough to know what the tool does and what inputs to provide. However, there is no output schema and no description of the result format, so the agent must infer what the returned references look like.

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 lang, path, symbol, and include_def are already documented in the schema. The example adds a concrete usage illustration but does not provide additional semantic meaning beyond what the parameter descriptions already 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?

Description states a specific action: find all references to a symbol across files using AST analysis. It also distinguishes definitions from references, which separates it from generic AST search or dependency tools like ast_search and ast_deps.

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 an example but no explicit guidance about when to use ast_refs versus sibling tools such as ast_search, ast_deps, or ast_imports. The example implies usage, but no when-not-to-use or alternative routing is provided.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the critical concurrency hazard (no concurrent writes), the AST-aware behavior, and that strings/comments are skipped. This is strong, though it doesn't mention failure modes or what happens when no matches exist.

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: purpose, critical warning, and example. Every sentence earns its place, and the most important constraint is clearly marked with 'IMPORTANT'.

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

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

The description, combined with the rich schema, covers purpose, path semantics, parameter meaning, and the safety constraint for multi-op atomicity. It lacks details about return format or what happens on consecutive renames beyond the warning, but no output schema exists and the key operational context is present.

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 well. The description adds a brief example showing path/old/new values and mentions aliases in the schema itself, but it does not add substantial meaning beyond what the schema already provides.

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

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

The description states a specific verb ('Rename'), a resource ('identifiers across files'), and the key method ('AST-aware renaming (skips strings and comments)'). This clearly distinguishes it from simpler text-replacement siblings like replace_text and ast_replace, and the example reinforces the operation.

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 explicit guidance on when NOT to use it directly ('do NOT issue concurrent renames... use execute_plan for multi-op atomicity') and provides an example of a single rename call. It does not explicitly name alternatives for cases like simple text substitution, but the AST-aware, identifiers-only behavior implies the appropriate 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?

With no annotations, the description carries the full burden. It adds a valuable constraint: 'do NOT issue concurrent writes against the same file; use execute_plan for multi-op atomicity', which signals a mutating operation. But it does not disclose side effects on surrounding code, what happens when the custom order omits or misnames symbols, or whether the operation is reversible.

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

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

The description is appropriately sized: one purpose sentence, one essential concurrency warning, and two compact examples. Every sentence contributes useful information, and the warning is placed prominently before examples.

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

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

For a four-parameter tool with no output schema and no annotations, this covers the essential invocation surface: path, order, inside scope, atomicity guidance, and example payloads. Minor gaps remain, such as the meaning of 'kind-first' and behavior when a listed symbol is absent, but they do not prevent correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by enumerating ordering modes and providing concrete examples such as 'alphabetical' and a custom array with 'inside': 'mod tests', which helps the agent understand how the parameters combine beyond the raw 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: 'Reorder symbols within a file or scope by name, kind, or custom order.' This clearly differentiates the tool from siblings like ast_move or ast_group, which reposition or group symbols rather than sort them by ordering criteria.

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 context by warning against concurrent writes and directing multi-op sequences to execute_plan for atomicity. However, it does not explicitly contrast this tool with sibling reorder/rename/group tools, so selection among alternatives is left partly to inference.

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

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

With no annotations, the description carries the burden and it discloses meaningful behavior: the replacement is scoped to the symbol body and leaves all other code untouched. It also warns about concurrency safety. It does not mention error cases (e.g., symbol not found) or return/result format, but the core side-effect profile is clearly conveyed.

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 purposeful sentences plus a compact example. The main behavior is front-loaded, the critical concurrency warning is prominent, and every sentence contributes either scope, safety, or usage guidance.

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?

Provides the core behavior, an example, and a concurrency rule, but leaves ambiguity about whether all matching occurrences inside the symbol are replaced or only the first, what happens if the symbol or old text is not found, and what output the tool returns. For a mutation tool with no output schema and no annotations, these are meaningful 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 coverage is 100%, so the baseline is 3. The description adds a concrete usage example that demonstrates path, symbol, old, and new, giving agents a clear pattern for emitting values. It reinforces the meaning of the symbol parameter as the AST scope boundary.

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'), resource ('text within a specific symbol's body'), and method ('AST scoping'). It explicitly differentiates itself from broad text editing by claiming only the named symbol's body is changed, which distinguishes it from sibling tools like replace_text or batch_replace.

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?

Clearly establishes when to use it: when a precise, symbol-scoped replacement is needed and everything else must remain untouched. It also provides an atomicity guideline ('use execute_plan for multi-op atomicity') and warns against concurrent writes, but it does not explicitly name non-scoped alternatives or state when to prefer them.

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?

Since no annotations are provided, the description carries the full burden of disclosing behavioral traits. It mentions the multi-language support via tree-sitter and explicitly warns against concurrent writes to the same file, directing to execute_plan for atomic operations. However, it does not disclose potential side effects, error handling, or return values, which are important for an agent to fully understand the tool's 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?

The description is concise and well-structured. It fronts the core purpose, then details the two modes, mentions the language support, adds a critical warning, and finishes with a concrete example. Every sentence serves a purpose, with no redundancy or irrelevant detail, making it easy for an agent to parse quickly.

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

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

The description, combined with the schema, provides enough context for an agent to invoke the tool correctly: it explains the parameters via the schema, offers an example, and includes the atomicity warning. However, it lacks guidance on when to prefer this tool over related siblings (e.g., ast_rename) and does not address edge cases like conflicting parameters (e.g., new_signature vs. structured fields). These omissions prevent a perfect score, but the description is still reasonably complete for the tool's complexity.

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

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

The schema already provides descriptions for all parameters (100% coverage), so the baseline is 3. The tool description adds an example that demonstrates how parameters combine (path, old, parameters, return_type), which clarifies relationships and typical usage. This extra context slightly enhances parameter understanding beyond the schema, justifying a score of 4.

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

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

The description clearly states the tool's purpose: 'Rewrite a function signature' and provides two distinct modes of operation (structured fields vs. full new_signature string). It also specifies the multi-language capability via tree-sitter, which is a key functional trait. The example further clarifies the intended usage, leaving no ambiguity about what the tool does.

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 does not explicitly state when to use this tool over its siblings (e.g., ast_rename, ast_replace), nor does it provide guidance on selecting between the structured-field mode and the full new_signature mode. It does include a warning about concurrent writes and directs to execute_plan for atomicity, but this is a caution rather than a usage recommendation. Overall, usage guidance is implicit rather than explicit, leaving the agent to infer the appropriate 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?

Without annotations, the description carries the full burden and does disclose non-obvious behavior: pattern mode requires valid source after $VAR substitution, literal tokens match exactly, and $$$MULTI is unimplemented. It omits result/error behavior, but the critical query-behavior constraints are clearly 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?

The description is compact and front-loads the core purpose before diving into syntax. Some content (pattern=true validity, literal matching, $$$MULTI) duplicates the schema, but the example and mode selector 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?

For a tool with five parameters, no annotations, and no output schema, the description covers query construction and known limitations well. The main gap is the lack of any detail on the return shape or behavior when no matches are found.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above baseline by adding a concrete S-expression example and a pattern example (fn $NAME() {}) not present in the schema. It also reinforces the interplay between query and pattern mode, which helps an agent formulate valid queries.

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 'Structural search using AST queries,' identifying the specific operation (search) and resource (AST) and distinguishing it from sibling tools like search_files or ast_read. The example and query syntax further clarify exactly what kind of search this performs.

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 explains the two query modes (S-expression vs. pattern=true) and provides an example, so an agent knows how to invoke it. However, it never states when to choose ast_search over search_files or the other ast_* siblings, nor does it give explicit exclusions.

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

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

With no annotations, the description carries the behavioral disclosure burden. It does disclose atomicity ('all targets succeed or all roll back') and a concurrency hazard, which is valuable. However, it does not state whether existing target files are overwritten, whether source is destructively modified, or what happens on partial symbol matches, so some important behavioral traits remain implicit.

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

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

The description is front-loaded with the core operation, followed by the atomicity warning and a compact example. The example is long but earns its place by illustrating a multi-symbol split. Minor formatting noise from 'IMPORTANT' in caps keeps it from being maximally polished.

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 no output schema, the description covers the core operation, atomicity, concurrency constraints, and usage pattern via example. It could be more complete by stating overwrite behavior and error semantics, but the essential context for an agent to invoke this correctly is present.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a concrete example showing how 'targets', 'prepend', 'keep_in_source', and 'source_suffix' combine in practice, which clarifies intended usage beyond the schema's generic field descriptions. It does not add much for 'lang' or 'require_exhaustive', but those are already well described in the schema.

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

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

The description states a clear verb and resource: 'Split a file into multiple target files by distributing symbols.' This is specific enough to distinguish it from many sibling tools like ast_move or ast_extract_to_file, though it does not explicitly name an alternative for contrast.

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 useful usage context: it warns against concurrent splits/writes and explicitly points to execute_plan for multi-op atomicity. It does not fully enumerate when to prefer this tool over other ast_* file-mutation siblings, but the atomicity guidance is concrete and actionable.

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

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

With no annotations provided, the description carries the full behavioral burden. It usefully discloses that it returns parse errors with line numbers and supports 20 languages. However, it does not state whether the operation is read-only, how directories are handled, what happens for unsupported languages, or the exact output shape. These are notable gaps for a tool with no annotations.

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

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

The description is compact and front-loaded: core action, expected result, and a concrete example in three sentences. The only slightly weak point is the vague phrase 'Supports 20 languages' without a list, but overall there is no wasted 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 simple two-parameter tool, the description covers the core purpose and return behavior. However, with no output schema and no annotations, an agent still lacks details about directory semantics, unsupported-language behavior, side effects, and the full output structure. It is minimally viable but has 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 explains both 'path' and 'lang'. The description adds an example using 'path' and notes 20-language support, but it does not enumerate valid language values or explain how 'lang' interacts with auto-detection. It meets the baseline but does not significantly enhance schema meaning.

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

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

The description clearly says 'Validate syntax of source files' and states the result: 'Returns parse errors with line numbers.' This is a specific verb and resource, and validation is distinguishable from sibling AST tools like ast_read, ast_search, or ast_reorder. It does not explicitly name a sibling it differs from, so it falls 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 intended use is implied: call this when you need to check whether source files have valid syntax. However, there are no explicit when-to-use or when-not-to-use statements, and no alternative tools are mentioned. The purpose is distinct enough to guide selection, but the guidance is left to inference.

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

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

With no annotations provided, the description carries the transparency burden. It discloses that the tool writes to files and warns about concurrency risks, recommending execute_plan for atomicity. However, it does not describe what happens to existing code, reversibility, or any side effects beyond the concurrency caveat.

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: purpose, selection mode, safety warning, and a concrete example in four short segments. Every sentence earns its place and the critical concurrency warning is prominently included.

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-parameter tool with complete schema coverage and no output schema, the description is nearly sufficient. It covers purpose, how to choose targets, example usage, and a key safety constraint. It would benefit from saying what the tool returns or rejects, but that is not required by the schema context.

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 a small amount of practical meaning by showing a valid wrapper and symbol selection in the example, but it does not materially go 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?

The description opens with a specific verb and resource: 'Wrap existing code in a structural block (module, impl, cfg, etc.).' This clearly distinguishes ast_wrap from sibling AST operations like ast_insert, ast_move, or ast_split, and the example reinforces the intended action.

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

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

It gives concrete selection guidance ('Specify symbols by name or a line range'), and warns against concurrent writes. It does not explicitly name alternatives or when-not-to-use cases, but the context is clear enough for an agent to decide when wrapping is appropriate.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly explains atomic staging, soft pattern misses surfaced in refused[], fuzzy fallback behavior with allow_absent_old, the JSON report shape, and a strong concurrency constraint. This is far more than the schema alone would reveal.

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 dense but well organized: purpose first, then atomicity, failure mode, aliases, fuzzy behavior, output shape, concurrency warning, and example. Every sentence adds operational value, and important warnings are capitalized and highlighted. The issue-tracker references are minor and do not detract.

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 complex 15-parameter mutation tool with no output schema and no annotations, the description covers all the high-risk behaviors: atomicity, soft failures, fuzzy matching outcomes, report fields, and concurrent-write prohibition. Since the schema comprehensively documents individual parameter semantics, no critical contextual gap remains.

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

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

The schema already covers all 15 parameters, so the baseline is 3, but the description goes beyond it by clarifying that files is canonical while singular file is an accepted alias, by explaining fuzzy fallback and allow_absent_old semantics, and by giving a concrete JSON example. This materially improves the agent's ability to construct correct calls.

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

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

The description uses a specific verb and resource: 'Replace the same text across multiple files in one call.' It clearly distinguishes this from single-file text tools and AST/structural tools by emphasizing the batch, multi-file scope. The first sentence immediately communicates what the tool does and what makes it different.

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

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

The description explicitly warns against issuing concurrent write calls to the same files and directs the agent to use execute_plan for multi-op atomicity. It also explains the soft-miss vs require_change behavior, giving the agent concrete criteria for when the batch will succeed, partially succeed, or fail.

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

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

With no annotations, the description carries the full burden and meets it: it discloses atomic all-or-nothing behavior, the canonical/alias input behavior, and the concurrency hazard. These are non-obvious operational traits an agent must know before calling.

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 sections front-load the operation, state key semantics, give a parameter example, and warn about concurrency with no filler. Every sentence earns its place.

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

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

For a three-parameter write tool with no annotations and no output schema, the description plus fully documented schema covers behavior, parameter precedence, concurrency constraints, and example usage. 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 100%, so the schema already documents files/file/strict; the description adds a plain-language statement of the canonical field and gives a concrete usage example. That is marginal but real added value 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?

The opening phrase 'Fix whitespace in multiple files' names a concrete verb and resource, and the body spells out exact transformations (trim trailing spaces, ensure final newline). This clearly distinguishes batch_tidy from single-file fix_whitespace and batch_replace.

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

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

The description states the multi-file batching intent and provides an important exclusion: do not issue concurrent writes targeting the same files, with execute_plan named as the alternative for multi-op atomicity. It does not explicitly contrast every sibling (e.g., fix_whitespace for single files), but the guidance is sufficient for correct 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?

With no annotations provided, the description carries the full disclosure burden. It clearly discloses the failure condition for existing files, the force=true escape hatch, and the concurrency hazard. That is strong behavioral transparency for a simple file-creation tool, though it does not detail permission requirements or error response formats.

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 core action. The failure condition, concurrency warning, and example all earn their place without unnecessary fluff. It uses only a few sentences to cover meaning, edge cases, and a concrete usage example.

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 simple 3-parameter tool with no output schema, the description is nearly complete. It covers the essential operation, failure behavior, overwrite option, and a critical concurrency caveat. A return-value note or mention of parent-directory handling would round it out, but nothing essential is missing 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 description coverage is 0%, so the description must compensate. It does: the example demonstrates path and content together, and the force parameter is given explicit semantics via 'unless force=true.' The parameter meaning is mostly clear, though path/content formatting or path constraints are not deeply specified.

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

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

The description opens with a specific verb and resource: 'Create a new file with specified content.' It also distinguishes itself from siblings like append_file and prepend_file by stating 'Fails if the file exists unless force=true,' making it clear this is not an update or append operation.

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 explicit usage constraints: 'do NOT issue concurrent calls targeting the same file' and 'use execute_plan for multi-op atomicity.' This effectively tells the agent when not to use this tool directly and names an alternative. It does not explicitly route to append_file/prepend_file for existing files, but the overwrite behavior implies that boundary.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the default not_found failure, the no-write success behavior when if_exists=true, and warns against concurrent calls. It could mention irreversibility or path scope, but the key failure modes and write semantics are clearly covered.

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

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

The description is front-loaded with 'Delete a file' and stays fairly compact, but it contains a redundant duplicate sentence: 'Set if_exists=true to soft-skip a missing file (no write, success).' followed by 'Set if_exists=true to soft-skip when the file is missing.' This wastes a sentence and slightly hurts structure.

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

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

For a simple two-parameter delete tool with no output schema, the description is reasonably complete. It covers default failure, soft-skip behavior, atomicity guidance, and includes an example call. Minor details like path normalization or response payload are not specified, but they are not essential 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 description coverage is 100%, so the parameters are already well documented. The description mostly restates what the schema says about if_exists and adds a concrete example path, which is mildly useful but does not substantially expand the parameter semantics.

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

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

The description opens with a clear verb and resource: 'Delete a file.' It also gives the default failure behavior, so an agent knows what the core operation is. It does not explicitly differentiate from sibling tools like move_file or doc_delete, but the operation is unambiguous.

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

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

The description gives practical guidance: use if_exists=true for soft-skip behavior, and do not issue concurrent calls to the same file, pointing to execute_plan for multi-op atomicity. It does not explicitly discuss all sibling alternatives, but the most important routing and exclusion guidance is present.

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

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

With no annotations, the description carries the burden of explaining behavior. It clearly states the mutation (append to an array) and warns about concurrency/atomicity, but it does not mention whether the file or selector must already exist, what happens on failure, or the return value. These gaps leave some behavioral uncertainty.

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

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

The description is concise: two sentences plus an example. The critical concurrency warning is front-loaded, and the example is compact and informative without unnecessary detail.

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

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

Given the tool's simplicity and the presence of a clear example, the description is adequate for an agent to invoke it correctly. It omits return-value details and edge-case behavior, but these are less critical for a basic append operation and are partially covered by the example and the atomicity warning.

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?

Each parameter has a description in the schema, and the example clarifies the role of path, selector, and value. However, the description adds little beyond the schema—it does not elaborate on the value type, selector syntax beyond 'dot-notation', or path constraints, so the baseline score of 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 clearly states the action ('Append a value to an array at a selector path') and provides a concrete example mapping all parameters. It also distinguishes itself from file-level append tools by specifying the selector-path domain, which helps an agent choose between doc_append and append_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 includes explicit usage guidance: do not issue concurrent calls to the same file and use execute_plan for multi-operation atomicity. It also provides an example that illustrates parameter usage, though it does not explicitly compare with alternative doc manipulation tools such as doc_update or doc_set.

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

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

With no annotations, the description claims full burden. It discloses idempotent behavior for missing keys, return fields (changed/removed), and exit-success semantics, which are valuable beyond the schema. It does not address permissions or file-creation side effects, but the core mutation behavior is transparent.

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-loads the core purpose before the warning and example. The important concurrency warning is prominent, and the example is concise. Every sentence adds value, with no filler.

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

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

For a mutation tool with no output schema and no annotations, the description provides enough detail about return values, idempotency, and concurrency constraints. It does not describe exactly what 'changed' and 'removed' appear as, but the wording ('include changed and removed') and exit behavior cover the practical needs of calling the tool correctly.

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

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

Both parameters are fully described in the schema (100% coverage), so the description is not responsible for compensating missing semantics. Its example clarifies selector/path composition but adds little meaning 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?

The description clearly states the action ('Delete a value at a selector path'), the resource ('JSON, YAML, or TOML file'), and uses 'selector path' to distinguish from nearby doc_delete_where and doc_update/delete_file. The example reinforces the expected input shape.

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

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

The description gives clear negative guidance (do NOT issue concurrent calls to the same file) and routes multi-op atomicity to execute_plan. It does not explicitly compare against doc_delete_where for conditional deletions, but the selector-path framing makes the intended use reasonably apparent.

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

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

With no annotations provided, the description carries full behavioral burden and succeeds: it discloses idempotent behavior (0 changed/removed, exit 0/ok), mentions the CLI and plan predicate field variants, and warns about concurrent calls targeting the same file. This is far beyond a bare 'delete matching elements' statement.

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 dense but every sentence earns its place: core action, predicate variants, sibling distinction, return/exit semantics, concurrency warning, and an example. It is front-loaded with the most important behavior and uses compact examples rather than 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?

Given the tool's moderate complexity and absence of an output schema, the description is remarkably complete. It covers semantics, predicate formats, success/result behavior, idempotence, concurrency constraints, and alternatives, leaving no major gap an agent would need to infer.

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

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

Although schema description coverage is 100%, the description adds substantial meaning beyond the schema by explaining predicate syntaxes ('.=x', '_=x', 'value=x', 'field=value'), giving concrete examples for object arrays, simple arrays, and nested paths, and providing a full usage example mapping all three parameters. This materially helps an agent construct correct invocations.

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

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

The description opens with a specific verb-resource pair: 'Delete array elements matching a key=value predicate,' which precisely states what the tool does. It also names doc.update as a different tool and clarifies where that tool operates, helping distinguish it from a 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?

The description explicitly contrasts this tool with doc.update ('Different from doc.update, which filters inside the selector path') and provides concrete usage guidance for object arrays, simple arrays, and nested paths. It also warns against concurrent calls and directs users to execute_plan for multi-op atomicity, giving clear when-to-use and when-not-to-use guidance.

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

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

With no annotations, the description must carry the behavioral burden, but it only says 'show differences' without specifying the output format, whether the operation is read-only, or any side effects. The example shows input shape but not expected result. For a tool lacking an output schema, this is a significant gap.

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

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

The description is a single front-loaded sentence stating the verb and resource, followed by a compact illustrative example. There is no filler or redundant 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 simple two-parameter tool with fully documented schema, the description gives enough to identify inputs and basic operation. However, with no output schema, it leaves the return value unspecified, and the lack of sibling differentiation weakens completeness for tool selection.

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 parameters are already documented. The description adds value by using the example {'file_a': 'old.json', 'file_b': 'new.json'} to clarify parameter ordering semantics (first file vs second file), which the schema's 'First/Second file path' descriptions do not fully 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?

The description clearly states a specific action ('Compare two structured files') and defines the supported formats (JSON, YAML, TOML), making the tool's purpose unambiguous. It doesn't explicitly name sibling alternatives like ast_diff, but the file-format focus helps distinguish 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?

The description provides an invocation example but no guidance on when to choose this tool over siblings such as ast_diff or doc_merge. No alternatives, exclusions, or selection criteria are mentioned, leaving the agent to infer appropriate usage.

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

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

With no annotations, the description carries the behavioral burden. It discloses conditionality and the concurrency caveat, which is valuable, but it does not state what happens when the selector already exists (no-op vs error), whether missing files are created, or any return/error 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?

Three compact components—primary behavior, critical caveat, and a concrete example—with no filler. The most important semantics are front-loaded before operational guidance.

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

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

For a 3-parameter write tool with no annotations and no output schema, the description covers core behavior, concurrency constraints, and an alternative for atomicity. The main gap is explicit no-op/error semantics when the selector path already exists.

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

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

The schema already documents all three parameters (100% coverage), so the baseline is 3; the description's concrete example maps path, selector, and value into a valid invocation and adds a formatting model beyond the schema prose.

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 conditional write operation: 'Set a value only if the selector path does not already exist.' This clearly identifies the resource (a value at a dot-notation selector in a config file) and separates it from unconditional set/update siblings such as 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 explicit concurrency guidance ('do NOT issue concurrent calls targeting the same file') and points to execute_plan for atomic multi-operation workflows. It does not explicitly name doc_set/doc_update as alternatives for overwrite semantics, but the conditional wording conveys the main use case.

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

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

With no annotations, the description carries full responsibility for behavioral disclosure. It does a decent job by stating the operation is a read, enumerating supported formats, and providing an example. However, it does not explain what the returned value looks like, how errors are handled for missing files or selectors, or whether the `key` alias is accepted at the tool level.

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 one focused sentence plus an example, with no filler or redundant restatement of the schema. The core action and mechanism are front-loaded, making it easy to scan.

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

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

The tool is simple and both parameters are fully documented in the schema, so the description does not need much. Still, with no output schema and no annotations, the description should at least mention the return representation and behavior on missing files or invalid selectors. These gaps keep it merely adequate rather than complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by specifying the supported file formats (JSON, YAML, TOML) and giving a concrete usage example that ties `path` and `selector` together, which helps an agent invoke the tool correctly.

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

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

The description clearly states the operation (Read), the resource (a JSON, YAML, or TOML file), and the method (selector path), with a concrete example. It does not explicitly differentiate from sibling tools like doc_query or read_file, but the read-by-selector semantics are specific enough for an agent to understand the tool's purpose.

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

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

The description gives no guidance on when to use this tool versus alternatives such as read_file or doc_query. There are no exclusion criteria, prerequisites, or context hints, so an agent must infer the appropriate use case solely from the phrase 'Read a value...'.

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

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

With no annotations, the description carries the behavioral burden and does note an important concurrency hazard and the deep-merge semantics. It stops short of explaining whether the file must already exist, what happens on key conflicts, or what the return value/error behavior is.

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: core operation, warning, then example. The IMPORTANT note earns its place, and the JSON example is useful rather than filler.

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

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

The description covers the essential operation and a critical concurrency constraint, but for a mutation tool with no output schema it should also mention expected return behavior, file existence assumptions, or conflict semantics. Still adequate for a moderately simple 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?

The schema already covers all parameters, but the description strengthens this by clarifying that value is a JSON object and adding selector examples for multi-doc YAML. The concrete merge example also gives the agent a working model beyond raw schema field names.

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

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

The description clearly states the operation: deep-merge a JSON object into a document root or a selector path. It distinguishes itself from basic doc_* mutations by emphasizing 'deep-merge', though it does not explicitly name sibling 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?

Provides an explicit operational warning about not issuing concurrent calls on the same file and recommends execute_plan for multi-op atomicity. However, it does not clarify when to choose doc_merge over doc_set, doc_update, or doc_append.

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

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

No annotations are present, so the description carries the behavioral burden. It usefully discloses the same-file constraint and the concurrency/atomicity caveat, which is important for a mutating tool. However, it does not say what happens when the destination path already exists or whether the move is destructive in edge cases.

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

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

Three sentences with no filler: purpose first, then the critical concurrency warning, then a concrete example. Every sentence earns its place.

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

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

For a simple 3-parameter tool, the definition covers the operation, file scope, and atomicity caveat. Missing overwrite/failure semantics are a notable gap for a mutation without annotations, but the definition is still sufficient for basic correct invocation.

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

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

Schema description coverage is 100%, and the schema already documents path, from, and to as dot-notation paths. The example adds a concrete mapping but does not significantly expand parameter 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 and resource: 'Move a value from one selector path to another within the same file.' This clearly differentiates doc_move from sibling write tools like doc_set/doc_update and from file-level move_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?

Explicitly warns against concurrent calls targeting the same file and points to execute_plan for multi-op atomicity. This gives clear when-not-to-use guidance and names the relevant alternative, though it does not broadly enumerate comparisons with other doc_* 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?

With no annotations, the description carries the full burden of behavioral disclosure. It does disclose one important non-obvious trait: same-file concurrent calls are unsafe, and atomic multi-op execution requires execute_plan. However, it does not describe what happens on missing files, missing arrays, non-array selectors, or whether the mutation is in-place or returns a result.

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 with no filler: the first states the core operation, and the second delivers a critical concurrency/atomicity warning. Information is front-loaded and every sentence earns its place.

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

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

For a simple 3-parameter tool with fully described parameters, the description is nearly complete: it defines the behavior and adds the key caveat about concurrency and atomicity. Minor gaps remain—no value type constraints, no statement about array creation or existence requirements, and no return-value note—but these are not blocking for a tool this simple.

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, and value. The description adds no additional parameter semantics; it essentially restates the schema's own descriptions. Baseline 3 is appropriate because 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?

The description opens with a specific verb and target: 'Prepend a value to the beginning of an array at a selector path.' This clearly states the operation, the resource (array at a selector path), and the position (beginning). The word 'beginning' also implicitly distinguishes it from sibling doc_append, which would target the end.

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 includes one explicit usage guideline: do NOT issue concurrent calls targeting the same file, and use execute_plan for multi-op atomicity. This is helpful for the concurrency case, but it does not explain when to prefer doc_prepend over sibling doc_* tools such as doc_append or doc_set. Most selection guidance remains implied by the operation name.

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

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

With no annotations provided, the description carries the full behavioral burden and does so thoroughly: it states per-action return semantics ('has' true/false, 'keys' list, 'len' count, 'select' filter, 'flatten' leaf paths), the fail-closed 'ambiguous' behavior for multi-match selectors, and the accepted 'key' alias. This is strong disclosure for a read-only query tool.

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

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

The description is dense but every clause carries actionable detail: actions, selector constraints, fail-closed behavior, an alias note, and a complete invocation example. It is front-loaded with the core verb and resource and organized by action, with no filler.

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

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

For a tool with no output schema, the description defines the return nature of each action, the shape of valid selectors, the required/optional parameter behavior, and gives a complete example. An agent has enough information to correctly invoke every action; the only minor gap is the exact full predicate grammar for 'select', which is not blocking.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful usage examples ('database', 'items[0]', 'users[role=admin]') and clarifies that 'select' has no separate predicate field. It reinforces selector defaults and requiredness already in the schema without introducing new parameters.

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

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

The description opens with a specific verb and resource: 'Query a JSON, YAML, or TOML file,' and then enumerates five concrete query actions with examples, making the tool's scope clear. It does not explicitly compare itself to sibling doc_* tools (e.g., doc_get), so differentiation is functional rather than explicitly named.

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 action list and per-action selector constraints tell an agent when to use the tool and how to shape each call, including fail-closed ambiguous-selector behavior and a concrete example. It gives clear context but does not state when to prefer an alternative sibling tool or include explicit exclusion cases.

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

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

With no annotations provided, the description carries the full burden and does substantial work: it discloses the parser-backed validity guarantee, the default create-missing-key behavior, the not_found failure mode, the if_exists soft-skip semantics, and an explicit concurrency prohibition ('do NOT issue concurrent calls targeting the same file'). It stops short of describing exact success-return behavior or overwrite semantics, which keeps it a step below exhaustive.

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

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

The core sentence is strong and the example is useful, but the description is visibly redundant: the 'not for predicates or wildcards / use doc.update' guidance appears twice, and the 'Set if_exists=true to soft-skip' sentence appears twice nearly verbatim. Roughly 40 of ~130 words are duplicated, which wastes tokens and dilutes the signal despite the otherwise sensible front-loaded structure.

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

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

For a 5-parameter mutation tool with no output schema and no annotations, the description covers the key decision points: supported file types, selector scope, failure modes, soft-skip behavior, concurrency constraints, and the sibling/plan alternative for atomicity. The only notable gap is that success return values are not described, which is minor for a setter; the duplicated sentences are the main blemish.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine value beyond the schema by delineating what selectors are NOT valid (predicates, wildcards), clarifying that only concrete key/index paths are accepted, and providing a full worked example tying value/path/selector together. This pushes it above baseline, though it doesn't add much per-parameter detail beyond the boundary constraint.

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

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

The first sentence states a specific verb ('Set'), a specific resource ('value at a single concrete selector path in a JSON, YAML, or TOML file'), and the supported selector forms (keys and indexes such as server.port or items.0.v). It explicitly distinguishes itself from doc_update/doc.update by stating 'single concrete path only' and naming the sibling for multi-match writes, so an agent can tell them apart without opening schemas.

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

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

The description gives explicit routing: predicates/wildcards should use 'doc.update for multi-match writes' (repeated with the doc_update sibling name), and multi-op atomicity should use execute_plan. It also states the default behavior (creates missing key, fails with not_found on missing file) and the if_exists=true soft-skip alternative, leaving no ambiguity about when to invoke this tool versus 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?

With no annotations, the description carries the full behavioral disclosure burden. It explains multi-match write semantics, selector predicate/wildcard behavior, and the concurrency limitation. It does not describe return values or no-match/error behavior, but the critical operational traits are 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?

The description is front-loaded with the core purpose and selector syntax, followed by usage guidance and a concrete example. It is slightly redundant in repeating wildcard/predicate examples, but every sentence contributes useful information and the structure is logical.

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

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

The description covers the essential operational context: selector syntax, multi-match behavior, example invocation, sibling differentiation, and concurrency safety. It lacks explicit return-value or failure-mode details, which would improve completeness given there is no output schema, but the information needed to call the tool correctly is present.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds valuable semantics beyond the schema by explaining selector syntax (wildcards, predicates) and providing a concrete example mapping value, path, and selector. This meaningfully helps an agent construct valid parameters.

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

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

The description clearly states a specific action ('Set a new value at every location matching a selector') on a specific resource (document files via selector paths). It also distinguishes itself from doc_set by saying to prefer this tool when filtering by field, which helps an agent pick the right 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?

The description explicitly says to prefer this over doc_set when filtering by field, and warns against concurrent calls on the same file, directing to execute_plan for atomicity. It also clarifies that filtering is part of the selector string rather than a separate flag, leaving little ambiguity about when and how to use it.

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

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

With no annotations provided, the description carries the full behavioral burden and delivers: atomic execution, path-safety rules (absolute plan.cwd and ../ escapes rejected, op paths must resolve inside the workspace), the cwd/for_each conflict, and the MCP-specific stripping of format/validate steps. It stops short of describing the return format, which matters since no output schema exists.

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

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

Every sentence in this dense paragraph earns its place — purpose, input modes, op breadth, aliases, path safety, exclusions, lifecycle caveat, and recommendation. The final nested example is high-value. It loses one point for being a single wall of text without paragraph or bullet structure, which makes the many constraints harder to scan.

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

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

For a tool of this complexity (3 params, a huge nested Plan schema, no output schema, no annotations), the description covers the decision-critical and safety-critical facts: how to supply the plan, path containment rules, MCP-specific behavior, and where to find full schema examples. The main gap is the absence of any indication of what the tool returns on success or failure.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds real value on top by documenting the `ops` alias for `operations`, flagging the cwd/for_each mutual exclusion, and giving a complete nested example that shows exactly how an inline plan is shaped. The schema's cwd description is also exceptionally detailed, so the agent is well equipped.

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 an arbitrary multi-step transaction plan atomically' — and anchors it to a known CLI equivalent ('MCP equivalent of patchloom tx'). The phrase 'Strongly recommended for multi-file or multi-op work' clearly differentiates it from the many single-op sibling tools in the list.

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 when-to-use guidance ('Strongly recommended for multi-file or multi-op work') and practical constraints ('Do not set both plan.cwd and for_each', 'plan.format/validate lifecycle shell steps are ignored on MCP (use project config)'). It does not explicitly name a single-op sibling as the alternative for one-off edits, but that is strongly implied by the multi-op framing and the sibling list.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses defaults, precedence order, write_policy behavior at commit, and the concurrency warning. It does not mention whether the file must already exist or what the return/error behavior is, leaving some behavioral gaps.

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

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

The description is front-loaded with the core purpose and contains a helpful example. However, it repeats the defaults information: 'defaults match CLI tidy fix (trim trailing whitespace + ensure final newline; normalize_eol stays keep)' is followed by 'Defaults: trim trailing whitespace and ensure final newline...'. This redundancy makes it longer than 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?

There is no annotations object, no output schema, and eight parameters to account for. The description covers the common defaults and concurrency safety well, but it omits the role of dedent/indent/lines entirely and does not describe return values or failure behavior, leaving notable gaps for a mutation 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 only 50%, so the description needs to compensate. It adds meaningful detail for trim_trailing_whitespace, ensure_final_newline, and normalize_eol defaults, but it does not explain dedent, indent, lines, or collapse_blanks beyond what the schema already provides. Partial compensation, not complete.

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

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

The description opens with a specific verb and resource: 'Normalize whitespace in a file.' It adds concrete default behavior and an example, making the tool's main function clear. It does not explicitly differentiate it from related siblings like batch_tidy, so it stops short of full sibling-level clarity.

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

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

The description provides clear context: defaults apply when op fields are omitted, and it explicitly warns against concurrent calls on the same file, directing the agent to execute_plan for multi-op atomicity. It lacks broader guidance on when to prefer this tool over batch_tidy or other editing tools, so it does not fully cover exclusions.

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

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

With no annotations, the description carries the transparency burden. It discloses the comparison reference (git HEAD), the output structure (lists of modified, created, deleted files), and a non-obvious filtering behavior (omitting .patchloom/ backup paths). This is strong behavioral context beyond the empty 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?

Three short, information-dense sentences. The primary purpose is front-loaded, followed by output details and a special-case omission. Every sentence earns its place with no repetition or filler.

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

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

This is a simple, zero-parameter tool with no output schema and no annotations. The description sufficiently explains what it does, what it returns, and the one notable filtering behavior. An agent has enough information to call it correctly and interpret its results.

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

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

The tool has zero parameters and the schema already reflects that with an empty object and no properties. The description reinforces this with 'No parameters required,' which is helpful and accurate. Since there are no parameters to document, a baseline of 4 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 states a specific verb ('Show'), a clear resource ('uncommitted file changes vs git HEAD'), and the exact scope of the operation. It also names the output categories (modified, created, deleted), making it unmistakable and distinct from the sibling file and AST 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 description makes it clear this tool is for inspecting uncommitted changes and explicitly says no parameters are required, which tells an agent exactly how to invoke it. It does not explicitly contrast it with alternatives, but no sibling tool provides comparable git-status functionality, so the usage context is still 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?

With no annotations, the description carries the full burden and does an excellent job: it discloses result capping, default max_results=500, truncated/total_matched reporting when capped, max_depth pruning behavior, honest max_results counting, and hidden-file handling. This goes well 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?

Every sentence earns its place: purpose is front-loaded, key behavioral caveats are explained compactly, and the example anchors parameter usage. 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?

For an 8-parameter tool with no annotations and no output schema, the description is remarkably complete. It covers filtering, capping, depth semantics, truncation honesty, hidden files, path preference, and invocation parameters, leaving no critical ambiguity for an 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 coverage is 100%, so the schema already documents every parameter. The description adds extra value by clarifying that omitted/0 max_results means 500, explaining what total_matched reports, and giving a concrete example mapping path, exclude_patterns, max_results, and max_depth.

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 action and resource: 'List files under the workspace (or given roots)'. It also distinguishes itself from generic filesystem list_dir/tree tools and aligns with search's ignore/exclude/glob rules, so an agent can tell this apart from siblings like search_files.

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 says 'Use this instead of a generic filesystem MCP list_dir/tree', giving a clear when-to-use signal. It does not explicitly contrast against search_files for content-vs-name searches, but the context is clear enough for correct 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?

With no annotations provided, the description fully carries the behavioral burden. It explicitly discloses destructive behavior: 'unique second-section content is discarded' and 'body under the second heading is discarded, not merged.' It also warns against concurrent calls, which is valuable operational transparency.

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

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

The description is front-loaded with the core action and contains important warnings, but the first two sentences are largely redundant: both explain that later duplicate sections are removed and their content discarded. The 'not merged' clarification is useful but could have been folded into one sentence.

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

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

For a single-parameter mutation tool with no annotations or output schema, the description is fairly complete: it defines scope, discloses destructive behavior, and includes a concurrency warning. It could still add explicit file-type constraints or expected return behavior, but the essentials for safe invocation are present.

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

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

The schema provides no description for the single path parameter, and the description does not describe the expected path format or constraints. The phrase 'same file' implies path identifies a target file, but that is minimal compensation for 0% schema description 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?

The description names a specific operation (removing later duplicate sections) and a specific resource (sections identified by heading text+level). It clearly distinguishes itself from merge-like alternatives by emphasizing that later content is discarded, not merged.

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 intended use is implied through the deduplication semantics, and the description gives an operational warning about concurrency and points to execute_plan for multi-op atomicity. However, it does not explicitly state when to choose this tool over sibling tools like md_replace_section or md_move_section.

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

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

With no annotations present, the description carries the full transparency burden. It does disclose the core insertion behavior—content goes immediately under the heading, before existing body content—and flags a concurrency hazard. However, it does not say what happens if the heading is missing, whether content is inserted as raw markdown, or which characteristics of the target file might affect 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?

The description repeats itself: 'Insert content immediately after a markdown heading line (before any existing body)' is functionally restated as 'Inserts immediately under the heading line (before existing body).' The sibling alternative also appears twice, once with a dot separator ('md.insert_after_section') and once with underscores ('md_insert_after_section'), which adds no value and creates confusion. The useful concurrency note is buried amid 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?

The tool has three required parameters, no annotations, and no output schema, so the description is the only documentation. It clarifies the insertion position and gives one concurrency warning, but it omits parameter conventions, heading-match behavior, failure modes, and any semantics around the inserted content. An agent is likely to guess at critical details when calling 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 description coverage is 0%, so the description must compensate for the three undocumented parameters. It only hints at the purpose of the file by referring to markdown headings; it never explains what 'path' should be, how 'heading' should be formatted (e.g., with or without '#'), or how 'content' is used beyond being inserted. This is a significant gap.

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

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

The description uses a precise verb-resource pair: 'Insert content immediately after a markdown heading line' and explicitly contrasts it with md_insert_after_section, which places a sibling section after the full body. An agent can distinguish this tool from its closest sibling 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?

The description tells the agent when to use the sibling tool ('after the full body') and gives an explicit concurrency rule: do not issue concurrent calls; use execute_plan for atomicity. It does not exhaustively list all alternatives, but the key decision point versus its direct sibling is clearly stated.

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

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

With no annotations, the description carries the full burden. It does disclose the sibling-placement behavior and the concurrency warning, which is useful. However, it does not explain what happens if the heading is not found, whether insertion is idempotent, or what the return/error behavior is, so transparency is only partial.

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 repeats itself: 'Insert content after the full section body (sibling placement)' appears twice, and the preference for md_insert_after_heading is stated twice with inconsistent naming ('md.insert_after_heading' vs 'md_insert_after_heading'). This redundancy wastes tokens and reduces 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?

The tool is fairly simple with three required string parameters, and the description includes an example, a usage rule, and a concurrency warning. Still, it omits key context such as what happens when the target heading does not exist, whether the heading must match exactly, and what the tool returns or reports on success or failure.

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

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

The schema itself provides no parameter descriptions (0% coverage), so the description must compensate. It offers a complete example mapping content, path, and heading, which clarifies their shapes. However, it does not specify the exact expected format of the heading parameter beyond the example showing '## Config', and it does not describe each parameter explicitly.

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

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

The description clearly states the action: insert content after the full section body, with sibling placement. It also differentiates itself from md_insert_after_heading by specifying that the sibling tool is for content directly under the heading line. This distinguishes it well from closely related sibling 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?

It explicitly says when to use this tool ('Use when adding a new ## section after this section's content') and when to prefer the alternative ('Prefer md_insert_after_heading for content under the heading line'). It also warns against concurrent calls and directs the agent to execute_plan for multi-op atomicity, providing clear operational guidance.

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

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

With no annotations present, the description carries the full burden and does disclose an important behavioral constraint: do not run concurrent calls on the same file. It does not explain edge-case behavior such as exact heading matching, multiple matching headings, or what happens when the heading is not found.

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

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

The description is two concise sentences with no filler. It front-loads the core operation and places the critical concurrency warning in a clearly marked second sentence.

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 simple three-parameter mutation tool, the core usage is clear and the concurrency warning is valuable. However, without annotations, output schema, or parameter descriptions, the description leaves matching semantics and failure behavior to inference, making it incomplete for edge cases.

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

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

The schema has no parameter descriptions, but the description implies that 'content' is the text to insert and 'heading' is the target heading line. 'path' is not explicitly explained in the description, though it is inferable from context; heading format details are also unspecified.

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 action ('Insert content immediately before a markdown heading line') with a clear resource and positional qualifier. This unambiguously differentiates it from similar siblings like md_insert_after_heading.

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

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

The description provides useful operational guidance by warning against concurrent calls and recommending execute_plan for multi-op atomicity. However, it does not explicitly state when to choose this tool over alternatives such as md_insert_after_heading or md_upsert_bullet.

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

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

With no annotations, the description carries the burden of behavior, and it does a good job: it specifies the return envelope, warns that the result is not a bare array, and explains isError/ok branching. It also gives CLI parity context. It stops short of stating whether the file is left unmodified, but 'lint' strongly implies a read-only check.

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 every sentence earns its place; the example and envelope details are not padding. Slightly dense but efficient.

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

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

For a one-parameter, no-output-schema tool, the description covers invocation, return shape, and error semantics. Missing only details about the shape of individual `issues` items, which is a minor 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%; the schema already documents `path` as a file path relative to the working directory. The description only reinforces with an example path, adding no new constraints. 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 names a specific verb ('lint'), a resource ('markdown rules file'), and three concrete checks, which distinguishes it from editing/deduping siblings like md_dedupe_headings. It is immediately obvious what the tool does and where it fits.

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 clearly targets linting a markdown rules file (typically AGENTS.md), but it doesn't explicitly say when to choose this over md_dedupe_headings or other md_* tools, nor does it state exclusions. Usage context is clear, but sibling differentiation is left to inference.

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

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

No annotations are provided, so the description must carry the behavioral burden. It makes the mutating nature clear through 'Move' and adds a valuable concurrency warning about concurrent writes and execute_plan. However, it does not explicitly describe what happens to the source section, error behavior, or whether the move is destructive if a target heading is missing.

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: core action first, then parameter rules, then a high-value concurrency warning, then a concrete example. Every sentence contributes, and the example earns its place by disambiguating the cross-file move case.

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 mutating tool with five parameters, no output schema, and no annotations, the description covers the main operation, the before/after requirement, same-file vs cross-file behavior, and a usage example. Remaining gaps include exact heading matching semantics and error behavior, but an agent has enough to invoke the tool correctly in the common cases.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful cross-parameter semantics by stating that exactly one of before or after is required and that omitting to means same-file reorder. The JSON example also clarifies how path, heading, to, and before combine in a realistic call.

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

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

The description opens with a specific verb and resource: 'Move a markdown heading section to a new position.' It also distinguishes the two modes, same-file reorder and cross-file, and provides an example that clarifies the operation. This is clearly differentiated from insert/replace/copy-style sibling 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 description gives concrete invocation rules: exactly one of before or after is required, and omit to for same-file reorder. It also warns against concurrent writes and recommends execute_plan for multi-op atomicity. It does not explicitly list sibling alternatives or state when not to use this tool, so it falls just short of full routing guidance.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It transparently defines the replacement range, including nested headings, and warns about concurrency hazards. It does not mention error cases like a missing heading or return values, but the core destructive behavior is clearly 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?

The description is mostly concise and front-loads the core purpose, but it repeats the section-boundary rule almost verbatim: 'section ends at the next same-or-higher-level heading; nested lower-level headings are included' appears twice. This redundancy wastes space, though the example and warnings are valuable.

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 simple three-parameter tool with no output schema, the description covers the key operational details: replacement scope, concurrency constraint, atomicity guidance, and an example invocation. It could mention behavior when a heading is missing or duplicated, but the provided context is sufficient for most agent invocation scenarios.

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

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

The input schema provides zero property descriptions, so the description must compensate. It explains that heading identifies the section to replace and includes a concrete JSON example mapping content, path, and heading. This makes the parameter roles much clearer than the bare schema alone.

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 precise verb and resource: 'Replace the body of a markdown section identified by heading.' It also defines the exact replacement range by explaining same-or-higher-level heading boundaries and inclusion of nested lower-level headings. This clearly distinguishes it from sibling tools like md_insert_after_section or md_move_section.

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