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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It doesn't state whether the directory can be nested, what happens if it already exists (error or silent success?), whether parent directories are created automatically, or whether permissions are inherited. For a state-mutating operation, this is a minimal disclosure gap.

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

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

The description is a single efficient sentence with no wasted words. It delivers the core purpose in minimal space, which is appropriate for a tool with one self-explanatory parameter.

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

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

The tool is moderately simple (one parameter, no output schema, no nested objects), but the absence of annotations and any behavioral guidance (error handling, nesting behavior, 'allowed folder' definition) leaves meaningful gaps. Given the file-system mutation context and sibling tools like delete_file, the description should clarify behaviors beyond the single sentence to be 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?

There is only one parameter, 'path', and schema description coverage is 0%, meaning the schema itself provides no description. However, for a directory creation tool, 'path' is highly self-descriptive and the single-parameter simplicity reduces the need for elaboration. The description adds minimal semantic value beyond the schema, but the low parameter count mitigates the gap.

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

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

The description states a clear verb+resource combination ('Create a directory') though the qualifier 'inside an allowed folder' is somewhat vague. It distinguishes from siblings like create_file and rename_file adequately since 'directory' is a distinct resource type.

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?

There is no guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites described. The phrase 'inside an allowed folder' implies a constraint but doesn't explain what 'allowed' means or how to determine it, leaving the agent without actionable usage 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?

No annotations provided, so the description carries the behavioral burden. It discloses the UTF-8 encoding and the fail-if-exists behavior, which are useful. However, it doesn't disclose whether parent directories are created automatically, what encoding edge cases apply, file size limits, or what error/response the tool returns. For a write operation with zero annotation coverage, some of this context would strengthen the score.

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, zero waste. Every element — creation, format, failure condition — earns its place. Front-loaded with the core action.

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

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

The tool is moderately complex: 2 params, no annotations, no output schema, and a critical edge case (fail-if-exists). The description captures the core behavior but omits practical details like path handling, whether directories are auto-created, empty-content handling, and return value. For a file creation tool, this falls short of helping the agent handle realistic scenarios confidently.

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 0%, so the description must compensate. It names 'content' implicitly (create a text file) but doesn't explicitly discuss the content parameter's behavior — e.g., whether empty content is allowed, how large content is handled, or any formatting requirements for path. The description does clarify that content is UTF-8 text, but path semantics (absolute/relative, separators) are unexplained. Given 2 undocumented params, the description should do more.

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?

Clear verb+resource ('Create a new UTF-8 text file') with an explicit failure condition that distinguishes it from write_file. It doesn't explicitly contrast with sibling tools, but the 'new file / fails if exists' semantics differentiate it from write_file (which likely overwrites).

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

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

No guidance on when to use this vs write_file or other siblings. The failure-on-existing behavior implicitly signals this is for fresh creation, but there's no explicit when-to-use or when-not-to-use instruction or alternative naming. For a file tool with this prominent write_file sibling, guidance would be valuable.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. For a destructive operation like deletion, it does not disclose whether directory deletion is recursive, whether deletion is permanent or moves to trash, whether there's any undo, or what errors occur for non-existent/empty-pattern paths. The 'inside an allowed folder' constraint is the only behavioral note, which is thin for a mutation tool.

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

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

The description is a single sentence with zero waste. It's efficient and front-loaded with the action verb. However, it's arguably under-specified rather than concise, given the tool's destructive nature.

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

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

This is a destructive mutation tool with no annotations, no output schema, and 0% parameter schema coverage. The description fails to cover critical operational details: recursive behavior for directories, deletion permanence, confirmation requirements, or the meaning of 'allowed folder.' Given the tool's simplicity (1 param) some brevity is acceptable, but destructive tools deserve more disclosure than this provides.

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

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

Schema description coverage is 0%, so the description must compensate for the single 'path' parameter. It does not explain the expected path format (absolute vs relative, file vs directory), whether wildcards/globs are supported, or how directory paths differ semantically from file paths. The only hint is that it operates 'inside an allowed folder,' but no format specifics are given.

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+resource combination ('Delete a file or directory') and adds helpful scope ('inside an allowed folder'), making the action clear. It distinguishes from siblings like read_file, write_file, create_file since deletion is a distinct operation, though it doesn't explicitly name alternatives.

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 no when-to-use guidance. It doesn't explain when to choose this over sibling tools or state whether it recursively deletes directories, requires confirmation, or has restrictions. 'Inside an allowed folder' hints at permission constraints but gives no actionable guidance about when this tool is appropriate vs destructive alternatives.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It's a read-only list operation which is intuitively safe, but the description doesn't explicitly state that it performs no mutations, how it handles empty folders, or what happens when the path is invalid or outside the allowed root.

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 concise sentence with no wasted words. It front-loads the purpose clearly. However, it's arguably under-specified enough that brevity borders on lacking necessary context rather than being efficiently complete.

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 list/read tool operating within permissions constraints, the description is thin. There's no output schema, no annotation coverage, and the single parameter lacks detail. The key ambiguity around 'allowed folder' and path resolution behavior is never addressed, which matters for an agent deciding how to interact with a filesystem.

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

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

The schema has 1 parameter with 0% description coverage and no enums. The path parameter is self-explanatory given the tool name, but the description doesn't clarify path format expectations (absolute vs relative), whether the allowed folder is the base, or what errors occur for disallowed or nonexistent 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 clear action ('List files and folders') applied to a resource ('an allowed folder'), which is reasonably specific. However, it doesn't distinguish this from sibling tools like read_file or find-style operations, and 'allowed folder' is vague about what defines 'allowed'.

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

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

No guidance is provided on when to use this tool versus alternatives. The mention of 'allowed folder' hints at a permission restriction but doesn't explain what makes a folder 'allowed' or when the agent should choose this over create_directory or other navigation tools.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the file is UTF-8 and that only allowed folders are accessible, which is useful. However, it does not state what happens with binary files, large files, encoding failures, line-ending normalization, or whether the returned content is raw or processed. For a read tool with zero annotation coverage, more disclosure is warranted.

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 concise sentence with zero waste. However, it is arguably under-specified rather than appropriately concise. The brevity is clean, but important details about parameters and behavioral boundaries are omitted, so it scores slightly below perfect.

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

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

For a single-parameter read tool with no output schema and no annotations, the description should carry more weight. It mentions UTF-8 and allowed-folder constraints, but does not cover error cases, supported sizes, encoding handling, or return semantics. Sibling read-style tools suggest nuance (e.g., text-only vs binary) that this description does not address.

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

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

Schema description coverage is 0%, so the description must compensate for the 'path' parameter. The description only implies that path is a file path within an allowed folder but does not explain path format (absolute vs relative), whether directories are rejected or accepted, or any validation rules. With a single undocumented parameter, the description adds minimal value beyond the schema.

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

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

The description says 'Read a UTF-8 text file from an allowed folder.' It states the verb (read), resource (file), and a key constraint (UTF-8, allowed folder). However, it does not distinguish itself from siblings like search_text or list_directory, and the purpose is somewhat generic for a read tool that is one of many 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?

The description gives no guidance on when to use this tool versus alternatives. It does not mention that binary files must use other approaches, that search_text is preferred for searching content, or any exclusions. The 'allowed folder' phrase hints at scope but does not clarify selection among 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. As a mutating operation, it doesn't state whether the operation overwrites existing files at newPath (destructive risk), whether the original is preserved, what happens in the case of dir vs file behavior differences, or permission requirements. 'Inside allowed folders' hints at restriction but doesn't explain enforcement or failure 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 a single efficient sentence with zero wasted words. It front-loads the core action clearly. However, it could arguably be slightly under-specified rather than concise, but for what it attempts to convey it is tight and readable.

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

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

This is a mutating tool with no annotations, no output schema, and 0% schema coverage on parameters. The description is a single sentence that fails to address behavioral expectations (overwrite behavior, return values, failure modes). With two undocumented parameters and no annotation safety flags, the description should provide substantially more guidance for an agent to invoke this 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 description coverage is 0%, meaning 2 parameters (oldPath, newPath) have zero documentation in the schema. The description mentions 'rename or move' which implies oldPath→newPath mapping, but doesn't specify path formats (absolute vs relative), whether directories are supported for both params, or constraints on the newPath (e.g., must the parent directory exist?). The description does not compensate for the 0% schema coverage.

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

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

The description uses a specific verb+resource ('Rename or move a file or directory') and specifies the scope ('inside allowed folders'). It clearly distinguishes from sibling tools like create_file, delete_file, and write_file, all of which have different operations. However, it doesn't go beyond the basic verb+resource to add value, and could be sharper about distinguishing 'rename' from 'move' behaviors.

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

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

The description implies usage through 'inside allowed folders' but gives no when/when-not guidance or explicit alternatives. Given the sibling tools include run_terminal_command (which could also move files) and delete_file (rename is sometimes used as a workaround for delete), the description could offer clearer context on when to choose this tool. There's no explicit exclusion or alternative guidance.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It doesn't state whether the operation is destructive/irreversible, whether it replaces all occurrences or just the first, how caseSensitive affects matching, or whether replacements must be exact string matches vs regex. These are significant gaps for a mutation tool.

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

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

The description is a single short sentence, which is concise. However, under-specification is not true conciseness — the brevity sacrifices essential behavioral and usage information that the tool clearly needs.

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

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

For a mutation tool with 4 parameters, 3 required, no output schema, and no annotations, the description is too sparse. It fails to explain matching semantics (all vs first), whether regex is supported, default casing behavior, error conditions (file not found, non-UTF-8), or the 'allowed' file constraint. A tool this simple should still document these basics.

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

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

Schema description coverage is 0%, so the description must compensate for all 4 parameters. It does not explain any of them — notably 'search' (first vs all occurrences, regex support) and 'caseSensitive' (default behavior) are unexplained. The description adds zero value beyond the schema's type information.

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 'Replace text inside one allowed UTF-8 text file' which has a clear verb (Replace), resource (text file), and one constraint ('one allowed UTF-8'). However, it doesn't distinguish this from sibling tools like search_text or write_file, and 'allowed' is undefined — it doesn't clarify which files are permitted.

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

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

No guidance on when to use replace_text versus write_file or search_text. It doesn't state whether a full rewrite via write_file is preferable, or whether search_text should be used for locating text first. The word 'allowed' hints at a permission system but provides no context about conditions.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Without a shell' hints at a restricted execution environment, but nothing is said about potential mutations, security implications, process lifetime, output handling, or permission requirements. For a command-execution tool, this is a minimal disclosure.

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?

One sentence, utterly zero waste. Every word carries meaning. Front-loaded with the core action. Ideal length for this modestly complex 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?

Given no output schema and no annotations, the description must explain behavior more thoroughly. It omits what the return/result looks like, error behavior for disallowed commands, and whether the command is deterministic. For a tool capable of arbitrary side effects, this level of description is insufficient.

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

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

Schema description coverage is 0%, so the description must compensate. However, it mentions 'allowlisted command' and 'allowed folder', giving some context to the `command` and `cwd` parameters respectively. The description adds a bit of meaning but doesn't clarify expected formats, defaults, or interactions between command and cwd.

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

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

The description states a clear verb+resource: 'Run' + 'one allowlisted command' inside 'an allowed folder'. It distinguishes itself from file-operation siblings by being the sole command-execution tool. However, it doesn't explicitly differentiate itself among siblings, though the distinct nature is obvious.

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

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

The phrase 'allowlisted command' and 'allowed folder' imply usage constraints, but no explicit when-to-use vs alternatives guidance is given, nor when NOT to use it. There's no mention of fallbacks or when a file operation would be preferable. Usage context is implied only.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, but it's thin. It mentions 'allowed' files/folders (implying access restrictions) and UTF-8 encoding, but doesn't disclose what the tool returns (matches with line numbers? just boolean?), case-sensitivity default behavior, behavior when no match is found, or whether multiple matches are returned. For a search operation, return format is a significant unknown.

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 efficient sentence with no wasted words. It's appropriately brief, though it could add a bit more behavioral detail without becoming verbose. Still, conciseness is well achieved given the length.

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

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

The tool has no output schema, no annotations, and 0% parameter coverage, so the description must carry substantial weight, but it's underspecified. For a search tool with three parameters and unknown return format, the description should clarify what output the agent can expect (matches, line positions, counts) and default behaviors. It's minimally viable but leaves key questions unanswered.

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

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

Schema description coverage is 0%, so the description must compensate for the three parameters (path, query, caseSensitive), but it provides no parameter-level detail. It doesn't explain whether 'path' defaults to anything, what 'query' format is expected, or how 'caseSensitive' affects matching. The description adds almost no meaning beyond the raw schema property names.

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

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

The description states a specific verb ('Search') plus resource ('UTF-8 text files') and scope ('inside an allowed file or folder'). It clearly distinguishes itself from siblings like read_file (reads whole content) and replace_text (modifies), since search implies matching without returning full content. It doesn't explicitly name a sibling alternative but the purpose is clear and distinct among the listed tools.

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

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

The description implies usage context: searching text files for a string, which naturally distinguishes from read_file (whole content) and replace_text (modification). However, it doesn't explicitly state when NOT to use it or name alternative tools. The phrase 'inside an allowed file or folder' hints at permission boundaries but gives no concrete guidance on choosing between this and other search-like 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states this is a write/mutation operation implicitly by 'replace', but does not disclose what happens if the file doesn't exist (does it create it?), whether it creates parent directories, whether the operation is atomic, or what errors may occur. For a mutation tool with zero annotation coverage, this is a significant behavioral 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 single sentence is efficient and front-loaded with the core action. However, it's under-specified for the complexity of a file-writing operation; conciseness at the expense of critical behavioral detail (file existence, error handling, path semantics) veers toward under-specification rather than disciplined brevity.

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 that this is a mutation tool with no annotations, no output schema, and 0% parameter schema coverage, the description should do substantially more work. It leaves critical questions unanswered: behavior for nonexistent files, directory creation, error cases, and path format expectations. For a file write tool among many sibling file operations, this is incomplete.

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

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

Schema description coverage is 0%, so the description must compensate for parameter documentation. It mentions no details about the 'path' parameter (relative vs absolute, encoding expectations) or 'content' parameter (size limits, whether it accepts arbitrary text). The description adds only that the file is UTF-8 text, which partially informs content semantics but leaves path handling undocumented.

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 verb and resource: 'Replace the full content of a UTF-8 text file.' It distinguishes this from siblings like create_file (which creates new files) and append operations. It's specific enough to convey it overwrites entire content rather than appending or patching, though it doesn't explicitly contrast with sibling tools.

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

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

The description implicitly signals usage context ('replace the full content'), which helps differentiate from create_file or replace_text (which does targeted edits). However, it provides no explicit when-to-use vs when-not-to-use guidance, no mention of file existence requirements, and doesn't note that replace_text / search_text might be better for partial edits.

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