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

Goes well beyond the destructiveHint annotation by explaining the confirmation flow: an existing file pauses the call and returns without writing until the user confirms. It also discloses parent-directory creation and append behavior, which are expected side effects an agent needs to anticipate.

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 dense sentences front-load the core action and limits, then cover confirmation, overwrite, and append. Every sentence earns its place and no information is repeated unnecessarily.

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 batch file-creation tool with a destructive hint and serious side effects, coverage is strong: max batch size, required fields, parent-directory creation, single-path absence, confirmation behavior, and overwrite/append variants are all stated. Nothing an agent needs to invoke 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 each field; baseline is 3. The description adds meaningful value by clarifying array-only input, the no-single-path restriction, and the overwrite confirmation behavior, which in turn explains the effect of overwrite: false.

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 operation ('create one or more files') with explicit limits (max 100) and behavior (creates parent directories). The note that there is no single-path form sharpens the contract and distinguishes it from file-editing siblings like edit and 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?

Gives clear guidance on how to invoke the tool: pass an array of { path, content }, use overwrite: true to bypass the confirmation prompt, and append: true to add to an existing file. It does not explicitly name sibling alternatives or state when not to use create, so it stops short of a 5.

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

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

Annotations already flag destructiveHint=true, but the description goes well beyond that by disclosing irreversibility, the confirmation prompt for non-empty directories, the fact that deletion is deferred until confirmation, the error behavior for non-prompting clients, and workspace root protection. 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 dense but every sentence carries essential information, and the most critical facts (permanent deletion, max 1000, irreversibility) are front-loaded. The paragraph is appropriately sized for a destructive multi-option operation.

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 no output schema, the description covers the key behavioral consequences: what gets deleted, the max batch size, irreversibility, recursive and confirmation requirements, the client-prompting failure mode, and workspace root restrictions. An agent has enough information to use the tool safely and 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 baseline is 3. The description adds value beyond the schema by explaining that there is no single-path form, that non-empty directories require recursive=true and trigger a confirmation flow, and that workspace root directories cannot be deleted. This enriches the semantics of both paths and recursive.

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

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

The description uses a specific verb ('Permanently delete') and names the exact resources ('files, directories, or symlinks'), plus a clear cap of 1000 per call. It also distinguishes itself from a hypothetical single-path form, leaving no ambiguity about what this 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 gives clear operational guidance: paths must be passed as an array, there is no single-path form, non-empty directories require recursive=true, and workspace roots cannot be deleted. It does not explicitly name sibling alternatives like move or rename as the right choice for non-deletion operations, but deletion intent is unambiguous.

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 the tool as read-only and closed-world. The description adds useful behavioral detail by specifying the output form ('unified diff with line counts'). It does not contradict the annotations, and it offers enough beyond them for a safe read operation.

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

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

Two concise sentences cover purpose, output format, parameter mapping, and usage context with no filler. The core action 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 diff tool with read-only annotations, the description covers what it does, what it returns, and when to use it. There is no output schema, so the mention of unified diff and line counts provides the necessary return-value context. Minor gaps like failure behavior or path restrictions are not critical here.

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 parameters are already well documented. The description adds the instruction 'Pass the two paths as a and b,' which is a mild reinforcement but not substantial new 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 opens with a specific verb and resource: 'Compare two files and return a unified diff with line counts.' This clearly differentiates it from sibling read/list/stat tools, which inspect single paths rather than compare two files. The purpose is immediately recognizable.

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 explicit usage contexts: 'Use after an edit dry-run to compare against another file, or to inspect changes between two paths.' It does not name alternatives or exclusions, but the guidance is clear enough for an agent to decide when to invoke this tool.

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

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

Annotations already signal destructive/write behavior, and the description reinforces this by stating edits are applied and that dryRun can preview without writing. It adds useful behavioral details beyond annotations: exact-once matching, failure with matched line numbers, and the 5-file cap. It does not contradict annotations, though it could mention atomicity or partial-apply behavior on multi-edit failures.

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 behavior, modes, matching constraints, dry-run option, and the alternative tool. It is front-loaded with the most important operational fact and avoids 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 destructive 5-parameter tool with no output schema, the description covers the critical invocation aspects: files cap, mode shapes, matching failure behavior, dryRun, and the main alternative. It does not describe the success return format or behavior across multiple files when one edit fails, which would make it fully complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the oldText uniqueness requirement, recommending 3-5 lines of context, and clarifying the two invocation modes. It does not cover ignoreWhitespace, but the schema already documents that parameter.

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

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

The description names a specific action ('apply sequential literal string replacements'), identifies the resource ('one or more files'), and scopes it with a clear limit (max 5 files per call). It also distinguishes itself from the sibling replace_text, so an agent can tell them apart 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?

The description explicitly routes alternative usage: 'For glob-based bulk regex replacement across many files, use replace_text instead.' It also explains when to use dryRun and lays out the single-file vs per-file modes, giving the agent clear selection criteria.

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

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

Annotations already mark the operation as read-only and non-open-world, and the description adds useful behavioral context beyond that: pagination cursors reference a query-bound snapshot that expires after 60 seconds. This is valuable operational detail an agent would not otherwise know, though it does not describe output formatting or 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 sentences with no filler: the core function is front-loaded, followed by a key pagination caveat and sibling routing. 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 tool's purpose, output shape at a high level, pagination behavior, and when to use alternatives. However, 'optional metadata' is vague and there is no output schema to clarify what the response contains, so a small completeness 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?

Schema description coverage is 100%, so the schema carries most parameter documentation. The description adds meaningful context by explaining the pagination cursor's snapshot semantics and expiration, which directly affects how the cursor parameter should be used. It also reinforces that pattern is a glob.

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 precise verb and resource: 'Find files matching a glob pattern' and explicitly says it returns matched paths with optional metadata. It also names sibling tools it is not (search_text for content, replace_text for replacements), making it easily distinguishable.

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 guidance: use find_files for path/glob-based file discovery, use search_text for content search, and use replace_text with the same glob for bulk replacements. This clearly tells an agent when to choose this tool over its most relevant siblings.

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

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

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds valuable behavioral context: pagination via nextCursor, snapshot expiration (~60s), and the resourceUri on incomplete first pages. It also explains maxDepth semantics. This goes beyond the annotations and helps the agent 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 compact and front-loaded with the core purpose. The first sentence states what the tool does, and the following sentences add key behavioral details. It's efficient, though the pagination details could be slightly more structured. No wasted words.

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

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

For a read-only listing tool with 100% schema coverage and no output schema, the description covers the essential behavior: pagination, snapshot expiration, and depth semantics. It doesn't describe the exact output format of the ASCII tree, but the description says 'ASCII tree' and the tool is a list operation, so an agent can infer the return. The snapshot expiration and resourceUri details are valuable context that make it complete enough.

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 6 parameters. The description adds some value by explaining pagination behavior (nextCursor, resourceUri) and maxDepth semantics, but most parameter meaning is already in the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'List sorted directory entries and an ASCII tree.' It also clarifies the tool's scope (directory listing) and distinguishes it from siblings like read, find_files, and search_text. The mention of maxDepth=1 as top-level and pagination behavior makes the purpose concrete.

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 for when to use this tool: to list directory entries and an ASCII tree. It doesn't explicitly name alternatives or exclusions, but the sibling list and the description's focus on directory listing imply when it's appropriate. It could be improved by explicitly saying 'use read for file contents, find_files for searching' 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 declare readOnlyHint=trueabb, so the description adds value by explaining the scoping relationship among tools and how allowed directories are configured. It does not describe return format, but the zero-parameter nature makes the behavior straightforward.

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. The core purpose is front-loaded, followed by usage guidance and configuration sources, all concisely.

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, read-only discovery tool, the description fully covers what the agent needs: what the tool lists, why to call it first, how access is configured, and that all sibling file tools are scoped to these roots.

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

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

There are no parameters, so the schema needs no additional explanation. The description adds useful context about how directory access is configured, more than the schema alone would provide.

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 ('List') and resource ('allowed workspace root directories'), and immediately establishes its unique role as the entry point for path discovery. The distinction from the sibling 'list' tool is clear through the explicit workspace-root 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?

Explicitly instructs the agent to call this tool first and explains the context: all other tools are scoped to these roots. It does not name a specific alternative or when-not-to-use case, but for a discovery tool this guidance is clear and 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 indicate destructiveHint=true and readOnlyHint=false, so the description goes beyond by disclosing critical behaviors: overwrite confirmation prompts, the lack of a bypass for move operations, self-move skipping, and the effect of copy=true with overwrite=true. This adds significant context beyond the 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 concise and front-loaded with the core purpose, then efficiently covers key behaviors in a single paragraph. There is no fluff; every sentence contributes essential information, and the structure flows logically from purpose to usage 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?

Given the tool's complexity (array of operations, max 100, overwrite logic, copy mode), the description covers all necessary aspects for correct invocation: format, limits, parent directory handling, confirmation behavior, and edge cases like self-moves. No output schema exists, so return values are not required. The description is complete.

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

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

Schema coverage is 100%, with each parameter described. The description adds value by explaining the interaction between copy and overwrite, the array-only format, and the absence of a single-pair form, which the schema does not convey. This goes beyond mere repetition and clarifies 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 clearly states the tool moves, renames, or copies files and directories to explicit paths. It distinguishes from siblings by focusing on move/copy operations, while siblings like create, delete, and edit have different purposes. The mention of 'max 100 operations' and the array format adds specificity.

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 detailed usage instructions, such as the mandatory array format, parent directory auto-creation, and copy vs. move behavior. However, it does not explicitly state when to choose this tool over alternatives (e.g., delete vs. move, create vs. copy), leaving the agent to infer the appropriate context from the 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 declare destructiveHint=true, and the description reinforces that it writes the result. It discloses rejection behaviors (multi-file, context mismatch) and the dryRun preview option, which are not covered by annotations. 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?

Three sentences with no filler. The first sentence front-loads the core action and inputs, the second gives usage guidance, and the third lists constraints and the dryRun option. 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 destructive file-patch tool, the description covers what it does, when to use it, its limitations, and the dryRun option. With annotations providing the destructive hint and no output schema, nothing essential 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% and describes each parameter. The description adds context to the diff parameter by clarifying it should come from a diff tool dry-run and that it rejects multi-file diffs and context mismatches, which goes beyond the schema's basic description. It also briefly mentions dryRun behavior.

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 (apply), a precise resource (a single-file unified diff to one file), and the result (write the result). It clearly differentiates from siblings like edit or replace_text by specifying the diff input and the rejection of multi-file diffs, making it distinct.

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 instructs to use after a diff tool dry-run and to pass the diff blob directly rather than re-expressing it as line edits, which contrasts with edit/replace_text. It also states rejection conditions (multi-file diffs, mismatched context), effectively saying when not to use it.

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

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

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds key behavioral constraints: mutual exclusivity of line parameters, shared line params across batch files, and a limit of 1000 paths. It also implies content is returned but does not detail format, which is a minor 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 compact, front-loads the core function, and clearly bundles related partial-read modes. It uses bullet-like lists and short sentences, with no fluff. Each clause serves a purpose, 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?

Given the tool's moderate complexity (7 params, partial reads, batch mode) and no output schema, the description covers the essential operation modes and constraints. It explains when to use batch, mutual exclusivity, and limits like max 1000 paths (though max limits are in schema, not description). It doesn't detail return format, but that is a minor gap given the read nature.

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, but the description adds crucial semantics about mutual exclusivity and batch behavior not fully captured in the schema. It clarifies how head, tail, and startLine/endLine are alternatives and how paths[] works with line params, going beyond the schema's static 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 reads one or more text files and returns content. It explicitly covers partial reads (head, tail, startLine/endLine) and batch mode via paths[]. This distinguishes it from siblings like find_files or search_text, which are for locating/searching rather than reading content.

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 states that head, tail, and startLine/endLine are mutually exclusive and instructs to use exactly one. It also clearly explains batch mode when to pass paths[] instead of path. This provides explicit when-to-use guidance and exclusion of alternatives.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false. The description adds key behaviors: 'Replaces ALL occurrences per file', literal-by-default matching, and RE2 regex support. However, the wording 'Set returnDiff=true to preview changes... before or after writing' is slightly ambiguous because `returnDiff` alone does not prevent writing; `dryRun` is the true preview-without-write parameter, so this could mislead an agent.

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 tightly focused sentences, front-loaded with the tool's core purpose and key distinction from `edit`. Every sentence earns its place; there is no filler or redundant restating 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?

The description covers the most critical context for a destructive bulk operation: it replaces all occurrences, can be scoped by glob, and can return a diff. Given a rich 100%-coverage schema and the destructiveHint annotation, it is nearly complete. The only gap is the ambiguous `returnDiff`/`dryRun` preview guidance.

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 by explaining `isRegex` and `replacement` semantics: 'Literal matching by default; set isRegex=true to enable RE2 regex with capture groups ($1, $2).' This synthesizes parameter behavior beyond the schema's individual 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?

Description states a specific verb and resource: 'Bulk search-and-replace across files matching a glob pattern.' It clearly distinguishes itself from a sibling: 'unlike edit, which replaces only the first match.' An agent can immediately tell this tool replaces all occurrences.

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 contrasts with the `edit` tool ('unlike edit, which replaces only the first match'), telling the agent when this tool is the right choice. It also advises using `returnDiff=true` to preview changes, giving practical guidance on how to use it safely.

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, and the description adds meaningful behavior beyond that: it specifies return shape ('matching lines with file path, 1-indexed line number and 0-indexed column offset') and context behavior. It does not mention pagination or snapshot expiration, but the cursor parameter schema covers those details, so the description is reasonably 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 front-loaded with the core purpose and output format, then gives targeted usage examples. Each sentence serves a purpose, though a few points about context and hidden files slightly echo the schema. It remains appropriately sized for an 11-parameter tool.

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

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

For a tool with no output schemaanding many parameters, the description covers the key invocation details: what is searched, what the output looks like, how to get context, how to restrict by file type, and which sibling to use instead. Remaining details like pagination and matching rules live in the schema, which is fully described.

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters. The description repeats a few useful parameter semantics, such as context=N returning N lines and pattern scoping with '**/*.ts', but it does not add meaning beyond what the schema already provides. A baseline 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 opens with a specific verb and resource: 'Search file contents by text or regex (grep-style).' It clearly distinguishes the tool from find_files by stating 'Use find_files to search by filename instead.' This makes the tool's scope unmistakable.

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 names the closest sibling alternative and the condition that routes to it: 'Use find_files to search by filename instead.' It also gives concrete usage direction for context, file-type scoping, and hidden-file inclusion, making when-to-use unambiguous.

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 agent knows this is a safe read operation. The description adds value by disclosing that the tool returns tokenEstimate, which is a behavioral detail beyond the schema, and by explaining that it can operate in batch mode on up to 1000 paths. It doesn't describe error behavior or permission requirements, but for a read-only metadata tool with readOnlyHint=true, the description covers the key behavioral aspects.

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 zero waste. The core purpose and return fields are front-loaded, the usage guidance is concise, and the two invocation modes are stated in a compact, scannable format. 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 read-only metadata tool with 100% schema coverage and readOnlyHint=true, the description is nearly complete. It covers what the tool returns, when to use it, and how to invoke it in both modes. The only minor gap is that it doesn't describe the output structure or error behavior, but since there's no output schema and the tool is simple, this is a small omission rather than a critical one.

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 both parameters (path and paths) including their mutual exclusivity and constraints. The description adds the semantic context that path is for single-file mode and paths is for batch mode, which is helpful but largely mirrors what the schema already states. Baseline 3 is appropriate since 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 states a specific verb ('Get metadata') and resource ('one or more files or directories'), and enumerates the exact metadata fields returned: size, type, permissions, MIME type, timestamps, and tokenEstimate. This clearly distinguishes it from sibling tools like read, list, and find_files, which have different purposes.

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 tells the agent when to use this tool: 'Use tokenEstimate to pre-screen read cost before calling read.' This is a clear usage directive that positions stat as a precursor to read. It also explains the two invocation modes (single path vs batch paths), which is practical guidance for choosing how to call it.

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