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

With no annotations provided, the description carries the full burden and does so well. It discloses key behavioral traits: idempotency ('if the directory already exists, this operation will succeed silently'), ability to create nested directories, and a constraint ('only works within allowed directories'). It does not mention permissions, rate limits, or error conditions, leaving some gaps.

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 appropriately sized and front-loaded, with the core functionality stated first. Each sentence adds value: idempotency, use cases, and constraints. There is no redundant or wasted text, making it efficient and easy to parse.

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 (creation with idempotency and constraints), no annotations, no output schema, and low schema coverage, the description is mostly complete. It covers purpose, behavior, and usage well, but lacks details on error handling, return values, or specific path format requirements, leaving minor gaps.

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

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

The schema has 1 parameter with 0% description coverage, so the description must compensate. It adds meaning by implying the 'path' parameter specifies the directory location and can include nested structures ('create multiple nested directories'), though it does not detail format or constraints. This partially compensates for the schema 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 clearly states the specific action ('create a new directory or ensure a directory exists') and distinguishes it from siblings like 'list_directory' or 'remove_directory'. It specifies the resource ('directory') and scope ('within allowed directories'), making the purpose unambiguous.

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

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

The description provides clear context for when to use this tool ('setting up directory structures for projects or ensuring required paths exist'), but does not explicitly state when not to use it or name alternatives. It implies usage for creation and existence-checking, which helps differentiate from siblings like 'remove_directory'.

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 burden. It discloses key behavioral traits: the user confirmation workflow, directory restrictions, and preview capability (implied by 'dryRun' parameter). However, it lacks details on error handling, permissions needed, or what 'allowed directories' specifically means. For a mutation tool with zero annotation coverage, this is adequate but leaves gaps.

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, followed by key behavioral details in two concise sentences. Every sentence adds value: the first defines the action and scope, the second explains the user confirmation workflow and directory restriction. 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?

Given a mutation tool with 3 parameters, no annotations, and no output schema, the description is moderately complete. It covers the purpose, workflow, and scope, but lacks details on return values, error cases, or specific parameter semantics. For this complexity level, it's adequate but could be more comprehensive.

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 low at 33% (only 'dryRun' has a description). The description adds some context: it implies 'path' must be within the specified directory and 'newText' is the content to edit. However, it doesn't explain parameter formats (e.g., path syntax) or constraints beyond the directory scope. With low schema coverage, the description compensates partially but not fully.

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 ('Edit') and resource ('a specific file'), and specifies the scope ('under /Users/username/Library/Mobile Documents/iCloud~md~obsidian/Documents/my-vault'). It distinguishes from siblings like 'write_file' by emphasizing user confirmation and preview capabilities. However, it doesn't explicitly contrast with 'write_file' which might be a direct alternative.

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: 'Only works within allowed directories' sets a boundary, and 'Display the modified content... upon user confirmation' indicates a workflow. It implies usage for interactive editing with safety checks, but doesn't explicitly state when to choose this over 'write_file' or other file manipulation 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 burden of behavioral disclosure. It mentions tokenization, returning relevant contents, and summarization, but lacks details on permissions, rate limits, error handling, or output format. For a search tool with no structured annotations, this leaves significant gaps in understanding how it behaves operationally.

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

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

The description is two sentences and relatively concise, but it's not front-loaded with the core purpose. The first sentence mixes tokenization and returning content, while the second adds summarization. It could be more structured, e.g., by starting with a clear verb like 'Search and summarize content based on a query.' Some redundancy exists ('query' mentioned twice), but it's not overly verbose.

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 complexity of a search tool with no annotations, no output schema, and low schema coverage, the description is incomplete. It doesn't explain what 'relevant contents' refers to (e.g., files, text snippets), how summarization works, or what the return value includes. For a tool that likely involves processing and returning data, more context is needed to be fully usable.

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

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

The input schema has 1 parameter ('query') with 0% description coverage, so the schema provides no semantic information. The description adds that the query is 'tokenize[d]' and used to 'return relevant contents' and 'summarized those contents', giving some context beyond the schema's type definition. However, it doesn't specify query syntax, length limits, or examples, leaving room for improvement.

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 the tool 'tokenize[s] the user's query' and 'return[s] relevant contents' with summarization, which provides a vague purpose. It mentions 'search engine tool' but doesn't specify what resource is being searched (e.g., files, directories, content). Compared to siblings like 'read_file' or 'list_directory', it's unclear if this searches across files, metadata, or other data, making it somewhat ambiguous.

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 explicit guidance is provided on when to use this tool versus alternatives. The description implies it's for searching and summarizing content, but it doesn't specify scenarios, prerequisites, or exclusions. For example, it doesn't clarify if this should be used instead of 'read_file' for content discovery or how it differs from other file-related tools in the sibling list.

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. It discloses key behavioral traits: it provides detailed listings with [FILE] and [DIR] prefixes, and has a constraint ('Only works within allowed directories'). However, it doesn't mention potential limitations like rate limits, error handling, or whether it's read-only (implied but not stated). The description adds useful context but could be more comprehensive.

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 moderately concise but could be more front-loaded. It starts with a task-oriented sentence, then details the output format and purpose. However, the first sentence includes an overly specific example path that may not be universally relevant, and the last sentence about being 'essential' is somewhat redundant, reducing efficiency.

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 1 parameter with no schema descriptions, no annotations, and no output schema, the description provides basic completeness: it explains the tool's purpose, output format, and a constraint. However, it lacks details on parameter semantics, error conditions, and exact return structure, making it adequate but with clear gaps for a tool with minimal structured data.

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

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

The input schema has 1 parameter with 0% description coverage. The description mentions 'a specified path' and provides a specific example path, but doesn't explain the 'path' parameter's format, constraints, or how it relates to the allowed directories. This adds minimal semantic value beyond what's implied by the schema, insufficiently compensating for the low coverage.

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

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

The description clearly states the tool's purpose: 'list directory' and 'get a detailed listing of all files and directories in a specified path.' It specifies the verb (list/get) and resource (directory/files), but doesn't explicitly differentiate from sibling tools like 'read_file' or 'full_text_search' beyond mentioning it's for understanding directory structure.

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 some usage context: 'essential for understanding directory structure and finding specific files within a directory' and 'Only works within allowed directories.' However, it doesn't explicitly state when to use this tool versus alternatives like 'full_text_search' or 'read_file' for file discovery, leaving usage somewhat implied rather than clearly defined.

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 burden. It discloses key behavioral traits: the operation fails if destination exists, works across directories, and requires allowed directories. However, it doesn't mention permissions needed, whether changes are reversible, error handling details, or rate limits, leaving 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 appropriately sized and front-loaded, with every sentence earning its place: first states core function, second explains capabilities, third covers failure condition, fourth adds scope details, fifth sets constraints. 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?

Given no annotations, 0% schema coverage, and no output schema, the description is moderately complete. It covers purpose, basic behavior, and constraints, but lacks details on permissions, error responses, or return values, which are important for a mutation tool with undocumented parameters.

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. It explains that 'source' and 'destination' parameters represent file/directory paths for moving/renaming, adding meaning beyond the bare schema. However, it doesn't specify path formats or examples, leaving some ambiguity.

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

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

The description clearly states the tool's purpose with specific verbs ('move or rename files and directories') and resources ('files and directories'), distinguishing it from siblings like 'create_directory', 'edit_file', or 'remove_file'. It explicitly covers both moving between directories and renaming within the same directory.

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 for when to use this tool (moving/renaming files/directories) and mentions constraints ('destination exists, operation will fail', 'within allowed directories'). However, it doesn't explicitly state when NOT to use it or name alternatives among siblings (e.g., 'write_file' for editing content vs. renaming).

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 mentions handling 'various text encodings' and 'detailed error messages', which adds useful context beyond basic functionality. However, it lacks details on permissions, rate limits, or specific error types, leaving gaps for a mutation-free but security-sensitive 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?

The description is appropriately sized and front-loaded with the core purpose in the first sentence. Each sentence adds value: the first states the task, the second elaborates on functionality, and the third provides usage constraints. It could be slightly more concise by merging some clauses, but overall it's efficient with minimal waste.

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 (file I/O with encoding handling), no annotations, no output schema, and low schema coverage, the description is partially complete. It covers purpose, usage, and some behavioral traits but lacks details on return format, error specifics, or security implications, making it adequate but with clear gaps for safe operation.

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

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

The input schema has 0% description coverage for its single parameter 'path', and the tool description doesn't explicitly mention or explain this parameter. However, the description implies the parameter through context ('read file from...'), and with only one parameter, the baseline is 3 as the schema minimally defines it without additional semantic value from the description.

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 specific action ('read file', 'read the complete contents') and resource ('from the file system', 'from /Users/username/Library/Mobile Documents/iCloud~md~obsidian/Documents/my-vault'), distinguishing it from siblings like edit_file, write_file, or read_multiple_files by focusing on single-file examination.

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 'Use this tool when you need to examine the contents of a single file' and 'Only works within allowed directories', providing clear context for when to use it. However, it doesn't specify when to use alternatives like read_multiple_files or list_directory, which would require explicit sibling differentiation for a higher score.

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 burden and does well: it discloses that failed reads for individual files won't stop the entire operation (partial failure behavior), mentions efficiency benefits, and specifies access restrictions ('Only works within allowed directories'). It doesn't cover rate limits or detailed error handling.

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?

Four sentences, each earning its place: states purpose, explains efficiency benefit, describes output format, and specifies access restriction. Front-loaded with core functionality, zero wasted words, appropriately sized for the tool's complexity.

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 annotations, no output schema, and 1 parameter with 0% schema coverage, the description provides good coverage: purpose, usage context, behavioral traits, and parameter meaning. It lacks details on output format structure, error types, or directory allowance specifics, but is largely complete for a read operation.

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. It explains that 'paths' parameter should contain multiple file paths and that each file's content is returned with its path as reference. This adds meaningful context beyond the bare schema, though it doesn't detail path format or constraints.

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 specific action ('Read the contents of multiple files simultaneously'), distinguishes it from the sibling 'read_file' tool by emphasizing batch efficiency, and explains the resource scope ('Only works within allowed directories'). It provides verb+resource+differentiation.

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 when to use this tool ('more efficient than reading files one by one when you need to analyze or compare multiple files'), but does not specify when NOT to use it or name alternatives. It provides clear context for usage without exclusions.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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. It discloses key behavioral traits: it can create new files or overwrite existing ones without warning (destructive), handles text content with proper encoding, and is restricted to allowed directories. However, it lacks details on error handling, permissions, or rate limits, which are important for a write 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?

The description is appropriately sized with four sentences that are front-loaded: it starts with the core task, then details behavior, warnings, and constraints. Every sentence adds value, such as the caution about overwriting and directory restrictions, but minor redundancy exists (e.g., 'write file' and 'Create a new file' could be streamlined).

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 complexity (a write operation with 2 parameters, no annotations, no output schema), the description is somewhat complete but has gaps. It covers purpose, behavior, and parameters adequately, but lacks details on return values (e.g., success/failure indicators), error cases, or specific encoding standards, which are important for agent invocation in this context.

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. It adds meaning by explaining that 'path' should be 'an appropriate path under /Users/username/Library/Mobile Documents/iCloud~md~obsidian/Documents/my-vault' and must not be occupied, and 'content' is 'text content with proper encoding'. This clarifies usage beyond the bare schema, though it could specify path format or content constraints more precisely.

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 'write file' and specifies the resource as files under a specific directory path. It distinguishes from siblings by explicitly stating it 'Create[s] a new file or completely overwrite[s] an existing file', unlike edit_file which might imply partial updates, and unlike read_file or list_directory which are read-only 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 provides clear context on when to use this tool: for writing files to a specific directory with text content. It implies alternatives by mentioning 'overwrite existing files', suggesting edit_file might be for modifications without full overwrites, but does not explicitly name when-not scenarios or list all sibling alternatives like create_directory for directories instead of files.

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