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

Beyond the destructiveHint and readOnlyHint annotations, the description discloses additional key behaviors: it creates parent directories, silently overwrites existing files, enforces a 100-file limit, and has no single-path convenience form. This gives the agent a full safety picture.

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 earning its place: what the tool does, the exact input shape, and the overwrite warning. The most important constraint is front-loaded and there is no redundant filler.

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

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

For a simple tool with one parameter, no output schema, and no nested objects, the description covers invocation shape, limits, side effects, and safety guidance. An agent has everything needed 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?

The schema already documents files, path, and content well, so the baseline is 3. The description adds real value by stating the exact required array shape 'files: [{ path, content }]' and explicitly ruling out a single-path invocation, which helps avoid incorrect 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 clearly states a specific action (create one or more files) and resource (files with path/content), and distinguishes the batch-only shape with 'there is no single-path form.' It is easy to tell apart from siblings like edit, patch, and delete.

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: use this to create files, and know that it overwrites existing content. It advises reading first when preservation matters, though it does not explicitly contrast with alternatives like edit or patch for modifying existing 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?

Annotations already say destructiveHint=true, and the description goes well beyond that by disclosing irreversibility, the confirmation mechanism that makes calls return without deleting, the error behavior for clients that cannot prompt, and the workspace-root safeguard. This is rich, actionable behavioral context.

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 contributes: scope, irreversibility, path form, recursive behavior, prompting caveat, and root restrictions. It is slightly long due to the confirmation explanation, but that complexity is necessary and not wasted.

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

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

For a destructive tool with three simple parameters and an output schema, the description covers the critical call-time facts: limits, required flags, interaction behavior, irreversibility, and an explicit prohibition. An agent has enough to call this correctly and safely.

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 schema already documents all three parameters. The description adds useful meaning by emphasizing that paths must be passed as an array, that there is no single-path form, and that recursive=true triggers per-directory confirmation. It does not delve into ignoreIfNotExists, but the schema handles that parameter well.

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 clearly states the action ('permanently delete') and the exact resources affected (files, directories, symlinks). It is unambiguous and distinguishes this from the sibling create, edit, and 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?

The description gives clear operational context: the 1000-item cap, the need for recursive=true on non-empty directories, the interactive confirmation requirement, and the workspace-root restriction. It does not explicitly name an alternative tool to use instead, but the conditions for safe use are well specified.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral detail by specifying that the result is a unified diff with line counts, which an agent would not otherwise know.

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

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

Two short sentences with no filler. The first sentence states the core purpose and output; the second gives practical usage guidance. Every part 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 read-only comparison tool, the description plus the high-coverage schema and readOnly/openWorld annotations are complete. It explains what to pass, what is returned, and when to use it. An agent has enough to invoke 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 description coverage is 100%, so the parameters a, b, and context are already fully documented in the schema. The description adds minimal extra semantic value beyond restating that a and b are the two paths.

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 ('Compare'), a clear resource ('two files'), and the output format ('unified diff with line counts'). This is distinct from the sibling tools, which perform creation, editing, reading, or searching — not file comparison.

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 use cases: after an edit dry-run to compare against another file, or to inspect changes between two paths. It does not mention when not to use it or name an alternative, but the provided context is clear enough for an agent.

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 destructiveHint=true and readOnlyHint=false, and the description reinforces that writes occur by contrasting dryRun. It adds useful operational detail: edits are sequential, literal, limited to 5 files per call, and require exact matches with context. It could further state failure behavior when oldText is not found, but the key behavioral 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?

Three dense sentences cover purpose, modes, matching requirements, dry-run usage, and the key alternative. The most important constraint 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?

Given the output schema and full parameter descriptions, the tool definition leaves no critical gap: modes, limits, matching behavior, dry-run previews, and the intended alternative are all covered. An agent has enough information to decide when to invoke edit and how to formulate a safe call.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by clarifying that replacements are applied sequentially, explaining the two call modes, and reinforcing the 5-file cap and exact-match requirement.

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 starts with a precise verb and object: 'Apply sequential literal string replacements to one or more files.' It clearly distinguishes this tool from replace_text, which handles glob-based bulk regex replacement, 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 gives an explicit routing rule: use replace_text for glob-based bulk regex across many files. It also directs users to dryRun=true for previewing diffs, clarifying the safe way to test edits before applying 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds value by disclosing the query-bound snapshot semantics and 60-second expiry for pagination cursors, which is behavioral context beyond the structured fields. 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, each earning its place: purpose and return shape, pagination snapshot behavior, and sibling routing. Zero filler, and the core purpose is front-loaded before secondary 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 an 8-parameter tool with 100% schema coverage, the description covers the essentials: purpose, return shape ('matched paths with optional metadata'), pagination semantics, and alternatives. No output schema exists, but the description gives a reasonable return-shape hint. Slightly more detail on return format would push it to a 5, but 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?

Schema coverage is 100%, so the schema fully documents all 8 parameters with examples (e.g., '**/*.ts') and defaults. The description adds no parameter-level detail beyond what the schema provides; the baseline of 3 applies 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?

States a specific verb and resource ('find files matching a glob pattern') with a clear scope. It also names the siblings it is not (search_text for content, replace_text for regex replacement), so an agent can distinguish it from the most confusable tools 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 routes to alternatives: 'For content search use search_text; for bulk regex replacements use replace_text with the same glob.' This tells the agent exactly when not to use this tool and which sibling to pick instead.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds behavioral details such as the ASCII tree output, sorting, and the pagination mechanism ('continue with nextCursor'). However, it omits details like snapshot expiration (which is only in the cursor schema) and does not fully describe output format, keeping it at an average 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 a single, tightly packed sentence with a clear front-loaded purpose. It avoids redundancy and every clause adds value, efficiently conveying the core function and key parameter behaviors without 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?

For a tool with no output schema and six fully documented parameters, the description provides adequate but not exhaustive context. It explains the main behavioral aspects (tree structure, pagination) but does not describe the output format or error handling. Given the tool's simplicity and the rich schema, this is minimally sufficient but leaves room for more detail.

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 extra semantic context beyond the schema by explaining maxDepth semantics ('maxDepth=1 is top-level') and pagination behavior ('maxEntries sets page size; continue with nextCursor'), including a note about 'resourceUri' for hard-cap overflow, which enriches 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?

The description clearly states a specific action ('List') and the resource ('sorted directory entries and an ASCII tree'), going beyond a tautology. It provides useful keywords like 'sorted' and 'ASCII tree' that help distinguish the tool from others like find_files, though it does not explicitly contrast them.

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

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

The description offers parameter-level guidance (e.g., 'maxDepth=1 is top-level', 'maxEntries sets page size') but does not explain when to use this tool versus its siblings (e.g., find_files, search_text). There is no mention of exclusions or alternatives, 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?

Annotations already establish readOnlyHint=true, and the description adds meaningful context beyond that: it explains where the allowed directories come from (CLI arguments, FS_ALLOWED_DIRS, --allow-cwd). This gives the agent useful operational knowledge about the tool's behavior and configuration without contradicting 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?

Three tight sentences, each earning its place: the primary action, the critical usage instruction, and the configuration sources. The most important information is front-loaded in the first 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 parameterless, read-only listing tool, this is complete. It tells the agent when to call it, what it returns conceptually (accessible paths), and how those roots are configured. No output schema exists, but the description sufficiently implies a list of path strings.

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

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

The tool takes zero parameters and the schema is empty, so there is nothing for the description to document. The baseline for 0 params is 4, and the description appropriately avoids inventing parameter details, keeping the tool's parameterless nature 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?

States a specific verb ('List') and a specific resource ('allowed workspace root directories'), and immediately clarifies how it differs from the file-operation siblings: every other tool is scoped to these roots. An agent can distinguish list_roots from the generic 'list' sibling 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 instructs the agent to 'Call this first' and explains why — the results determine which paths are accessible to all other tools. This is clear, actionable usage guidance that leaves no ambiguity about when this tool should be invoked.

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?

Given destructiveHint is already true, the description adds substantial behavioral context: parent directories are created automatically, existing destinations trigger a confirmation that causes the call to return without moving anything, overwrite bypass exists only in copy mode, and self-moves are silently skipped. This goes well 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 dense but every sentence earns its place. It front-loads purpose, then gives the input form, then explains edge-case behaviors. 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?

The description covers the operation limit, required array form, destination handling, parent directory creation, copy semantics, overwrite confirmation, and self-move behavior. For a tool without an output schema, this provides ample context for correct invocation.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds meaning beyond the schema by clarifying the exact call shape ('Pass moves: [{ source, destination }]') and emphasizing that there is no single-pair form, plus the effect of copy and overwrite on runtime 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 begins with a specific verb and resource: 'Move, rename, or copy files and directories to explicit destination paths.' This clearly distinguishes the tool from siblings like create, delete, and edit, while also noting the 100-operation limit.

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 use: pass an array of move pairs, there is no single-pair form, and copy=true switches to copy mode. It does not explicitly state when not to use this tool versus siblings like edit or delete, but the intended use is strongly implied by the tool's 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?

Beyond the destructiveHint annotation, the description discloses that the tool writes to a file, supports dryRun=true to preview without writing, and rejects multi-file diffs or diffs whose hunk context does not match. These are meaningful behavioral constraints that help the agent anticipate 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?

Three tight sentences front-load the core purpose, then provide usage context, constraints, and the dryRun option. No filler or redundant explanation; 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 required inputs, the key failure modes, and the safety dryRun option. Even without an output schema, an agent has enough information to invoke this tool correctly and to avoid common misuse.

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, diff, and dryRun. The description adds little beyond restating 'Pass { path, diff }' and the dryRun preview behavior, which 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 action ('Apply a single-file unified diff'), the target resource ('to one file'), and the outcome ('write the result'). It also distinguishes itself from line-edit workflows by explicitly saying the diff blob should be passed directly, so an agent can differentiate this from sibling edit 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 gives explicit when-to-use guidance: after inspecting a diff-tool dry-run. It also gives a clear when-not-to-use signal by saying 'instead of re-expressing it as line edits', and it describes rejection conditions for multi-file and mismatched diffs.

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

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

Annotations already carry read-only and closed-world hints; the description adds valuable behavioral details on partial reads, batch-mode parameter sharing, and mutual exclusivity of head/tail/line-range options. It does not cover edge cases like missing files or directory input, but the core 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?

Three sentences with zero fluff. The action is front-loaded, partial-read modes are listed compactly, and the batch-mode rule and mutual-exclusivity constraint are stated in a single final sentence. 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 tool with a rich schema, read-only annotations, and an output schema, the description is nearly complete: it covers modes, parameter sharing, and exclusivity. It omits only minor edge-case behavior such as missing-file or directory-handling semantics, which are not critical 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?

All 7 parameters are documented in the schema (100% coverage), so the baseline is 3. The description adds semantics beyond the schema: line parameters are shared across files in batch mode, and head/tail/startLine-endLine are mutually exclusive. That grouping and relationship information justifies a 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?

States a precise verb+resource ('Read one or more text files and return content') that unambiguously separates it from sibling tools like list, stat, and search_text. The action is inherently distinct, so no explicit sibling naming is needed.

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 first sentence establishes the core use case (reading text file content), and the description gives clear context for partial reads and batch mode. However, it does not explicitly contrast with sibling tools or state when not to use read, so no exclusions are 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?

Annotations declare `destructiveHint: true`, and the description strengthens this by stating that replacements are written and that `returnDiff` can preview changes before or after writing. It also discloses default literal matching and RE2 regex behavior. It could add more about dry-run usage, but the description already goes beyond the annotations usefully.

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 sentences front-load the core purpose, the key distinction from `edit`, the preview mechanism, and the regex/literal behavior. Every sentence contributes meaning and there is no redundant restatement of schema or annotations.

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 bulk-operation tool with 14 parameters, the description efficiently covers the essential decision points and safety mechanism. The comprehensive schema and output schema cover the remaining parameters and return shape. A direct mention of `dryRun` in the description would make it slightly more complete, but the existing guidance via `returnDiff` and the `path` schema is strong.

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 value by explaining tool-level semantics: literal vs. regex matching, capture-group references, all-occurrence replacement, and diff previews. This clarifies how the core parameters interact without replacing 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 identifies the action ('Bulk search-and-replace'), the resource ('files matching a glob pattern'), and the key behavioral scope ('Replaces ALL occurrences per file'). It also explicitly contrasts itself with the sibling `edit`, so an agent immediately knows how this tool differs.

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 an explicit alternative and the deciding condition: use this tool for all occurrences, whereas `edit` replaces only the first match. It also gives concrete guidance on when to enable `returnDiff` for previewing changes, helping agents choose safe invocation patterns.

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 safety profile is covered. The description adds meaningful behavioral context beyond the annotations: it discloses the return format (matching lines with file path, 1-indexed line number, 0-indexed column offset) and highlights grep-style semantics. It does not mention pagination or snapshot behavior, but those are documented in the schema's cursor parameter, so the extra context is sufficient.

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: the first states the core function, the second describes the output format, the third explains scoping, the fourth covers hidden files, and the fifth routes to the correct sibling. It is front-loaded and contains no filler or redundant 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?

Given the rich input schema (100% coverage across all 10 parameters) and the absence of an output schema, the description adequately fills the remaining gap by specifying the return format. It also covers the key searching behaviors (regex/literal, hidden files, glob scoping) and points to the alternative for filename search. An agent has enough to select and invoke this 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 description coverage is 100%, so the baseline is 3. The description reinforces the meaning of 'pattern' with an example and explains includeHidden's effect, but it largely repeats what the schema already provides. It adds value for output semantics rather than parameter semantics, so a 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'), states the method (text or regex, grep-style), and immediately distinguishes itself from the sibling find_files ('search by filename instead'). An agent can tell exactly what this tool does and how it differs from nearby tools without inspecting the schema.

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

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

It explicitly names the alternative tool (find_files) and the exact condition that selects it (searching by filename instead of content). It also gives practical usage tips such as scoping with a glob pattern and enabling includeHidden for dotfiles, giving the agent clear guidance on when and how to use the tool.

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

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

Annotations already declare readOnlyHint=true, so the safe read-only nature is established outside the description. The description adds useful behavioral context with tokenEstimate as a cost pre-screening signal and lists the metadata categories returned, though it does not detail batch response shape 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?

The description is three tight sentences: the first states what the tool returns, the second gives the key workflow rationale, and the third covers parameter mode selection. 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?

For a simple, read-only stat tool, the description is nearly complete: it lists return fields, explains tokenEstimate utility, and covers both invocation modes. The main gap is that without an output schema, it does not specify the exact response structure for batch calls, but the enumerated fields mitigate this.

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 fully documents path and paths, including mutual exclusivity and the 1000-item limit. The description only restates 'Single path: pass path. Batch mode: pass paths[]', adding little beyond the structured 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: 'Get metadata for one or more files or directories' and enumerates the returned fields (size, type, permissions, MIME type, timestamps, tokenEstimate). This clearly distinguishes it from siblings like read (content access) and list (directory enumeration).

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 to use tokenEstimate to pre-screen read cost before calling read, naming the alternative tool and the exact condition that selects stat. It also clarifies single-path vs batch-mode usage, giving practical selection guidance.

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