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

Annotations declare destructiveHint=true and readOnlyHint=false; the description adds real value beyond them by disclosing that missing parent directories are created and by flagging the whole-file overwrite/append semantics. It does not cover the return value or the confirmation prompt behavior (that lives in the schema), keeping it below 5.

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

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

Two sentences, zero filler, with the core verb-and-resource statement front-loaded and the sibling disambiguation immediately after. Every clause earns its place.

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

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

For a write tool with no output schema, the description covers modes, side effects, and sibling routing adequately. It omits batching behavior and what the call returns (paths, confirmation results), which are minor but real gaps.

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

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

Schema description coverage is 100% and the schema already documents path, content, append, and overwrite thoroughly, so the baseline is 3. The description echoes the create/overwrite/append modes but adds no syntax or format detail beyond the schema.

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

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

States a specific verb and resource ('Write whole text files') and enumerates the modes (create, overwrite, append). It explicitly distinguishes itself from the edit and patch siblings, so an agent can route 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?

Explicitly names the alternatives (edit, patch) and the boundary condition that selects them: those change part of an existing file, whereas this writes whole files. There is no explicit when-not guidance (e.g. for binary files or very large files), so it falls just short of 5.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds meaningful behavior beyond that: deletion is permanent, applies to files/directories/symlinks, and uses exact path matching. This enriches rather than contradicts the annotation profile.

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

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

Two compact sentences with no filler. The core purpose is front-loaded, and the glob caveat is a single high-value clarification that prevents misuse.

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, the description covers permanence, target types, recursion analogy, and path-matching behavior. Parameters and destructive nature are already handled by the schema and annotations, so nothing critical is missing for an agent to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents all three parameters in detail. The description adds only a high-level rm/rm -r analogy and an exact-paths caveat, which is marginal but not required for parameter understanding.

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

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

States a specific verb and resource set: 'Permanently delete files, directories, or symlinks.' The rm/rm -r analogy clarifies expected semantics and distinguishes this destructive tool from sibling read/write/edit/move operations.

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

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

Gives clear context for when to use—permanent deletion of paths—and adds a useful constraint: paths are exact and globs are not expanded. It does not name explicit alternatives, but no sibling provides a delete operation, so the usage context is sufficient.

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

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

Annotations already establish read-only behavior, so the description need not repeat that. It adds the important ordering behavior (from a to b) and the output format ('unified diff, like diff -u'), which are not in annotations or schema. It does not discuss edge cases such as identical files or how the context parameter is applied, so the disclosure is adequate but not rich.

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

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

A single front-loaded sentence that states action, input, and output with no filler. Every phrase ('Compare', 'two text files', 'unified diff', 'from a to b', 'like diff -u') carries semantic weight.

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

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

For a read-only comparison tool with a self-describing schema, the description covers the key agent-facing facts: inputs, direction, and output format. It leaves edge-case behavior to implementation, but no output schema exists and the phrase 'like diff -u' provides a known format. This is 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?

The schema descriptions already cover all three parameters at 100%, so the default baseline is 3. The description adds meaning by clarifying that a is the source/original and b is the target ('from a to b'), which removes ambiguity in how arguments should be passed. It does not comment on the context parameter, but the schema already defines its default, minimum, and maximum.

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 ('Compare') and names the resource ('two text files') plus the exact output form ('unified diff'), so the tool's core purpose is unmistakable. It does not explicitly name a sibling alternative, but 'compare' is distinct from the create/edit/delete/search siblings.

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

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

The description implies its use case: whenever two text files need to be diffed, rather than edited or searched. It gives no explicit 'when not to use' guidance or sibling routing, so an agent must infer the context from tool name and purpose.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description carries a lighter burden. It adds valuable behavioral context: the atomicity of writes ('a file is written only if all its edits match') and the uniqueness requirement for oldText. This goes beyond the annotations and is useful for the agent to predict outcomes.

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, with the core purpose front-loaded and the key behavioral constraints stated economically. No fluff, and the alternative tool is mentioned in the same breath, making it highly scannable.

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 core semantics (exact match, uniqueness, atomicity) and the primary alternative. It does not mention dryRun or ignoreWhitespace, but these are fully documented in the schema with defaults and descriptions. The batch mode via files is also implied by the sibling contrast but not explicitly highlighted; still, the schema covers it. Overall adequate for a destructive edit tool with strong schema support.

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

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

Schema description coverage is 100%, so the schema fully documents each parameter. The description adds the str_replace analogy and the uniqueness/atomicity constraints, which reinforce but do not substantially extend the schema. This meets the baseline for a well-documented 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 (edit text files in place) with a clear verb-resource pair, and explicitly contrasts with the sibling replace_text tool, which replaces every occurrence across files. This distinguishes it from alternatives immediately.

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

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

It gives clear guidance on when to use this tool versus replace_text ('replace_text replaces every occurrence across files'), and states the exact-match-once constraint. However, it does not explicitly address other siblings like patch or create, leaving some inference to the agent. The guidance is clear for the most relevant alternative but not exhaustive.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds useful behavioral context: returns relative paths, pattern semantics at any depth, and implies it does not search file contents (by directing to search_text). No contradiction with 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?

Two sentences with zero waste. The purpose is front-loaded, the pattern rule is actionable, and the alternative is stated at the end. Every clause adds value, and the structure is ideal for quick scanning.

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

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

For a read-only search tool with 8 params fully documented in the schema, the description is largely complete. It clarifies the output format and pattern behavior, and implicitly indicates content search is out of scope. It does not mention pagination cursor expiry, but that is in the schema, so no critical gap for a well-formed call.

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

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

Schema coverage is 100%, so all parameters are documented. The description adds an extra semantic for 'pattern' (the no-slash rule) beyond the schema examples, which provides meaningful value. It does not repeat schema descriptions, so it earns above the baseline 3.

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

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

The description states a specific verb ('Find') and resource ('files by name or glob pattern'), and clarifies the output is relative paths. It explicitly distinguishes from search_text by noting that tool searches contents, 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?

It provides a clear rule for pattern matching ('pattern without / matches file names at any depth') and names the alternative for content search ('search_text searches contents'). It does not mention the 'list' sibling, which could be a common alternative for directory listing, but the guidance is sufficient for the primary distinction.

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

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

Annotations already declare readOnlyHint=true, so the description correctly does not contradict this. However, the description adds no behavioral context beyond what annotations provide—it does not mention pagination, snapshot semantics, or any side effects (which would be none given read-only). The schema itself documents cursor behavior and expiration, but the description itself adds no extra value beyond the annotation.

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, well-structured sentence that starts with the core function and ends with a helpful pointer to an alternative. It wastes no words and is appropriately front-loaded, fitting within the ideal length for a tool this simple.

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 6 parameters and no output schema. The description is very brief, but the schema carries rich information (pagination, snapshot expiry, defaults, limits). For a listing tool, an agent can likely infer most behavior from the schema. However, the description does not mention that results are paginated or that deeper recursion is possible, which could be useful context. It is adequate but not comprehensive; a 3 reflects that it covers the essentials without being fully self-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 100%, so the baseline is 3. The description does not elaborate on any parameter (e.g., path, maxDepth, includeHidden), relying entirely on the schema. It adds no additional meaning beyond what the schema already provides, so a 3 is appropriate per the rubric.

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 ('List') and resource ('directory's files and subdirectories') and clarifies the output format ('as a tree of names'). It also distinguishes itself from a sibling tool ('stat returns sizes and dates'), making it easy for an agent to know what this tool does and what it does not.

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

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

The description gives an implicit usage guideline by noting that 'stat returns sizes and dates,' implying that stat is the tool for metadata. However, it does not explicitly state when to use this tool versus alternatives like find_files or list_roots, nor does it mention any exclusions or prerequisites. The guidance is minimal and mostly inferred.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds useful context beyond that: results are absolute paths and include any directories granted during the current session. This helps the agent understand what the returned set represents.

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 with no filler. The core behavior is stated first, and the companion behavior about other tools granting access is a useful one-line addition. 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 zero-parameter listing tool, the description fully explains what is returned (absolute paths of accessible directories), the session-grant aspect, and how it relates to other tools. No output schema is present, but the return concept is simple and clearly stated.

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 parametersasi, so the schema cannot provide parameter detail. With no parameters to document, the baseline of 4 applies; the description fully clarifies what the tool returns without needing 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 uses a specific verb ('List') with a clear resource ('directories this server can access, as absolute paths'). It distinguishes list_roots from the generic sibling 'list' by scoping it to server-accessible workspace roots, including session-granted paths.

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 discovering accessible directories. It also notes that other tools can request access to paths outside these roots, giving the agent a hint about when this tool is not sufficient. It does not explicitly name alternatives, but the context is clear.

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

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

Annotations already mark destructiveHint=true, and the description adds useful context about path interpretation ('full new path, not a folder') and automatic parent directory creation. However, it does not disclose whether move mode overwrites existing destinations by default, a critical behavioral detail given the destructive hint and the copy-only scope of the overwrite parameter.

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

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

The description is two sentences with no redundancy. It front-loads the primary purpose, then immediately adds a key behavioral caveat. Every phrase 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 covers purpose, path semantics, and parent creation, which are essential. However, it leaves overwrite behavior in move mode ambiguous—whether move overwrites without confirmation—especially since the schema states overwrite applies only to copy mode. This is a significant gap for a destructive tool and reduces completeness.

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 parameters are fully documented in the schema. The description adds minor clarification for the destination parameter (full path semantics) but does not add value beyond the schema for copy or overwrite, which are already described in their property descriptions.

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

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

The description clearly states the tool's function: 'Move, rename, or copy files and directories, like mv or cp -r.' It names specific operations and the resource type, distinguishing it from siblings like create, delete, or edit. The additional note about destination being a full path further clarifies scope.

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

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

The description implies usage for moving, renaming, or copying but does not explicitly state when to use this tool over alternatives like create or delete. It lacks exclusions or conditions that would help an agent choose between tools, leaving the decision 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?

The description goes well beyond the annotations (destructiveHint=true) by detailing the atomicity: 'Nothing is written unless every hunk applies in file order with exactly matching context.' It also discloses a critical quirk: hunks are located by context, so line numbers may be off. This is essential behavioral information that the annotations do not provide.

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

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

Two sentences, front-loaded with purpose and behavioral nuance. Every clause earns its place; the critical atomicity rule and context-matching caveat are delivered without padding.

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

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

For a tool with three well-documented parameters, no output schema, and annotations covering destructiveness, the description supplies everything an agent needs: the exact operation, the single-file constraint, the atomicity guarantee, and the context-matching behavior. Nothing critical 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?

The input schema already provides complete descriptions for all three parameters (diff, path, dryRun) with 100% coverage. The tool description adds no additional parameter-level detail beyond what the schema states, so the baseline score of 3 applies.

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

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

The description opens with a precise verb and resource: 'Apply a single-file unified diff to one existing text file.' The analogy 'like git apply' anchors it firmly in a well-known operation, and the distinction of single-file vs. multi-file and the context-matching behavior clearly separate it from sibling tools like edit 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 makes it obvious when to use this tool: whenever you have a unified diff for a single file. It does not explicitly enumerate alternatives or exclusions, but the context is clear enough that an agent can infer the correct use case. The mention of 'existing text file' also implicitly signals it is not for new files.

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?

Beyond the readOnlyHint annotation, the description discloses concrete behaviors: it can return the whole file or a slice via head/tail/startLine/endLine, images/audio return as media, and other binary files are rejected. This adds significant behavioral context about return types and error handling that the annotation does not cover.

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. The first sentence front-loads the core purpose and the slicing mechanisms; the second covers media and binary handling. Every word earns its place with no redundancy or fluff.

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 explains the key return behaviors (text vs media vs rejection) and the slicing mechanisms. It does not mention batch mode (paths array) or the includeHash parameter, but these are fully described in the schema. Since there is no output schema, the description adequately covers return expectations, though it could note directory handling if applicable. Overall, it is sufficiently complete for an agent to call 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?

Schema coverage is 100%, so all parameters are already documented. The description adds only a high-level mention of slicing options (head, tail, startLine/endLine) but does not elaborate on mutual exclusivity, batch mode, or includeHash. Since the schema already provides full parameter descriptions, the description adds marginal value, consistent with the baseline of 3.

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

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

The description clearly states a specific verb ('read') and resource ('text files'), with the analogy 'like cat' making the purpose instantly recognizable. It also distinguishes itself from siblings like edit, delete, and diff by focusing on read-only content access, and explicitly covers slicing and binary handling.

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: it reads text files and can return whole or sliced content. It also mentions that binary files are rejected, which implies when not to use it. However, it does not explicitly name alternative tools (e.g., list, stat) for other use cases, so it lacks explicit when-not-to-use or alternative routing, but the context is sufficient for an agent to decide.

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?

The description adds substantial behavior beyond the destructiveHint annotation: patterns run over the whole file, can span lines, and '^ and $ anchor to file start and end.' It also clarifies literal vs RE2 semantics and the sed -i in-place behavior. No contradiction with the annotations was 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?

Three tight sentences carry high-signal information with no filler. The core operation is front-loaded, the regex/anchor nuance earns its place, and the sibling distinction is a single useful closing clause.

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

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

For a 14-parameter destructive tool, the description covers the essential operational model and the key alternative. The schema already documents every parameter, including dryRun and returnDiff, so the description need not repeat those details. A small gap is not explicitly warning to pair wide scopes with dryRun, though the schema's path parameter does mention it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description enriches meaning by explaining that searchPattern operates over the entire file and that anchors behave file-wide rather than line-wise. It also ties the glob option to directory scanning. This adds genuine semantics beyond the schema's field-level descriptions.

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

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

The description states a specific verb and resource: 'Find and replace every occurrence of literal text or an RE2 regex... in one file or all files under a directory.' It also differentiates itself from the sibling edit tool by noting 'edit replaces one unique exact match,' so an agent can immediately distinguish bulk replacement from single-match editing.

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 clearly conveys when to use this tool: for every occurrence across one file or a directory. It also gives an explicit alternative by noting 'edit replaces one unique exact match,' which routes single-match use cases elsewhere. It does not mention read-only search alternatives like search_text, but the destructive context is otherwise 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?

The annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds valuable behavioral detail: patterns match within one line and the return format includes line numbers and relative paths, which goes beyond the annotations without contradicting them.

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 only two sentences long, front-loaded with the primary function and immediately followed by a clear contrast to the sibling tool. There is no filler or redundancy; 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?

The description covers the essential behavior, including return format and the line-matching limitation. However, it omits explicit mention of pagination via the cursor parameter and the default handling of hidden/ignored files, though these are documented in the schema. Given the rich schema and read-only annotations, this is adequate but not exhaustive.

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

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

Schema description coverage is 100%, so all 11 parameters are well-documented in the schema. The description does not add meaningful parameter-level information beyond what the schema already provides, so it meets the baseline for high 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 clearly states the tool searches file contents for literal text or an RE2 regex, like grep, and returns matching lines with line numbers and paths. It also explicitly distinguishes itself from the sibling tool find_files, which matches file names, making the purpose unambiguous.

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

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

It explicitly names find_files and states that it matches file names, implying that search_text is for content search while find_files is for name search. This provides direct guidance on when to use this tool versus the alternative.

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?

The description adds meaningful behavioral details beyond the readOnlyHint annotation: directory size refers to the directory entry itself, MIME type is guessed from extension, and symlink target is included. This sets correct expectations for stat semantics that a generic read-only hint does not convey. There is no contradiction with 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: the core purpose appears in the first few words, followed by a useful ls -ld analogy and a tight list of returned fields. The final existence-check sentence earns its place by clarifying behavior on missing paths. There is no filler.

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

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

For a two-parameter metadata tool with no output schema, the description covers the key return fields, directory behavior, and existence checking. It does not specify the exact output structure or error behavior, but the field list is sufficient for an agent to invoke stat correctly and interpret 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?

Both parameters are fully described in the input schema, so the description does not need to add parameter-level semantics. The metadata list applies to both path and paths modes but does not enrich the schema's already clear descriptions. A baseline of 3 is appropriate given the 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 opens with a specific action ('Get metadata without reading contents') and names the exact resource (path(s)) plus the metadata fields returned. It clearly distinguishes itself from read/list siblings by emphasizing that it does not read file contents. This is unambiguous and immediately actionable.

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

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

The description clearly indicates this tool is for metadata retrieval, not content access, and adds that it checks whether paths exist. It does not explicitly name sibling alternatives or state when not to use it, so the agent must infer the choice from the 'without reading contents' contrast. That is clear context but not an explicit exclusion.

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