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

Adds meaningful behavioral context beyond the annotations: a 600-second timeout, concurrent execution behavior, a warning against concurrent writes to the same files, and the starting working directory. The annotations already cover destructive and open-world hints, so this description enriches rather than repeats.

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

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

Front-loads the core action, then adds timeout, concurrency, use cases, and working directory in a compact set of sentences. Every sentence provides operational information; the use-case list is long but directly useful for tool selection.

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

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

With an output schema present and rich annotations, the description supplies the remaining operational details an agent needs: timeout, concurrency, working directory, and common command categories. Nothing critical about invoking bash safely 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% and the single command parameter is already described. The description adds execution semantics beyond the schema by noting that commands start in the configured base directory and that cd should be used inside the command when needed.

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: running a shell command on the local computer using bash. The use-case list makes its general CLI scope clear, but it never explicitly distinguishes itself from the sibling read/write/edit tools, especially for overlapping file 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 contexts for use: directory listing, file discovery, grep/ripgrep, git, package managers, build/test commands, scripts, network tools, and other CLI work. It does not provide when-not-to-use guidance or name the sibling alternatives explicitly.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered. The description adds genuinely new behavioral context: the call fails when old_text occurs zero times or more than once, which is the key failure mode an agent must handle.

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

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

Two tight sentences, front-loaded with the operation and followed by the constraint. No filler and nothing that could be cut.

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

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

With a full schema, an output schema, and annotations covering safety, the description only needs the failure semantics, which it supplies. Minor gaps remain: no mention of encoding/line-ending handling or what happens on partial-match ambiguity beyond the count rule.

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 all three parameters, including old_text's exact-once requirement and new_text's empty-to-delete behavior. The description restates the uniqueness rule rather than adding format or encoding details, so baseline 3 applies.

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

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

States a specific verb and resource (exact targeted replacement in an existing local text file) and the single-occurrence constraint, which implicitly separates it from whole-file 'write'. It never names the siblings read/write/bash, so an agent gets the operation but not an explicit routing statement.

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

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

Usage is only implied: 'one exact targeted replacement' suggests preferring this over write when changing part of a file, but there is no explicit when-to-use, when-not-to-use, or alternative (e.g. use write for new files, bash for multi-edit operations).

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description still adds non-obvious behavior beyond the schema: it is limited to text files and defines how paths resolve (absolute, ~/, or relative to the configured base directory). It stops short of covering failure behavior (missing file, encoding, non-text input), which keeps it from a 5.

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

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

Three sentences, each carrying a distinct load: what it reads, when to prefer it over bash, and path syntax. No repetition of the schema or annotations and 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?

An output schema exists, so return format and pagination semantics need not be restated. Purpose, routing, and path semantics are all present, leaving nothing an agent needs before invoking the tool.

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

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

Schema description coverage is 100%, so limit/offset defaults and ranges are already documented, establishing a baseline of 3. The description goes beyond that by specifying the accepted path forms (absolute, ~/, base-relative), which the schema's terse 'Path to the local text file' does not.

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 ('Read a local text file') and immediately scopes it against the closest sibling by naming what bash is for. An agent can separate read from bash without opening either schema.

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

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

Explicitly gives the when-to-use condition ('use this for file contents') and enumerates the alternatives handled by bash (directory listings, file discovery, grep/ripgrep, git). This is a real routing rule, not an implied one.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the overwrite is 'complete' (existing content is destroyed, not merged) and parent directories are auto-created, which affects how the call succeeds or fails. It does not mention permission/error behavior, keeping it from a 5.

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

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

Three short sentences, all front-loaded: what it does, then the directory-creation side effect, then the routing hint. No filler and every sentence carries distinct information.

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

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

An output schema exists, so return values need no explanation, and the annotations carry the safety profile. For a two-parameter mutation tool, the description covers purpose, side effects, and sibling routing adequately.

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

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

Schema description coverage is 100%, so both parameters (path, content) are already documented, making 3 the baseline. The description adds the UTF-8 encoding and 'complete contents' framing for content, but nothing extra for path.

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 ('Create or completely overwrite a local UTF-8 text file') and immediately distinguishes itself from the sibling 'edit' by contrast. An agent can tell it apart from read/edit/bash without opening any schema.

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

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

Explicitly names the alternative ('Use edit for a targeted change to an existing file') and gives the condition that selects it. The overwrite semantics also implicitly state when not to use this tool for incremental edits.

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