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

No annotations are provided, so the description carries the burden of behavioral disclosure. It transparently reveals idempotent behavior ('If the directory already exists, this operation will succeed silently'), supports nested directory creation, and states the allowed-directory restriction. It does not cover edge cases like invalid paths or permission failures, but for a mkdir-style tool, this is substantial transparency.

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

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

The description is concise, using three sentences that front-load the main action and follow with important behavioral details. No redundant information is present; every sentence adds value, from the basic function to the idempotency and the allowed-directory constraint.

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 simplicity (one parameter, no output schema, no annotations), the description is quite complete. It covers the core action, the nested-directory capability, the silent success for existing directories, and the access restriction. An agent can confidently invoke the tool based on this description alone.

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 provides only a 'path' property with no description, and schema description coverage is 0%. The description partially compensates by implying that 'path' can include multiple nested levels ('Can create multiple nested directories in one operation') and must be within allowed directories. However, it does not explicitly explain path format (absolute vs relative) or the exact nature of the path parameter, leaving some ambiguity for a single-parameter tool.

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 function with the verb 'create' and resource 'directory', and adds the crucial nuance of 'ensure a directory exists' (idempotency). It distinguishes itself from sibling tools like write_file or delete_file by focusing on directory creation, including the ability to create nested directories.

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 explicit use cases: 'Perfect for setting up directory structures for projects or ensuring required paths exist.' It also includes a constraint ('Only works within allowed directories') that implicitly guides the agent to check list_allowed_directories. However, it does not explicitly mention when not to use the tool or compare it with 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 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 the full burden of behavioral disclosure. It discloses key failure conditions ('If the destination exists, the operation will fail' and 'Both source and destination must be within allowed directories'), which are valuable beyond the basic move/rename semantics. It does not mention permissions or reversibility, but the disclosed behaviors are material and not redundant with schema or 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 adding value: the first states purpose, the second adds the fail-fast behavior, and the third adds the allowed-directories constraint. No fluff, front-loaded with the core action, and appropriately sized for a simple two-parameter tool.

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

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

The tool is simple and has no output schema or annotations. The description covers the essential context: what the tool does, dual purpose (move/rename), failure conditions, and allowed-path constraints. It could mention what happens if source is missing or if moving directories with contents, but these are likely self-evident. Overall, it's adequately complete for this tool's complexity.

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 provides only parameter names (source, destination) with no descriptions (0% coverage). The description helps by explaining that the operation 'move[s] files between directories and rename[s] them in a single operation,' implying that 'source' is the original path and 'destination' is the target path/name. It also clarifies constraints on both parameters. This compensates for the lack of schema descriptions, though it could explicitly map the names to roles.

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: 'Move or rename files and directories.' It specifies the action (move/rename), the resource (files and directories), and distinguishes it from all sibling tools by being the only one that performs moving/renaming. The description also adds detail about 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 the tool: for moving or renaming files/directories, including moving across directories or renaming in place. It also gives important constraints: fails if destination exists, and operation limited to allowed directories. While it doesn't explicitly name alternatives, none of the sibling tools serve the same purpose, so the usage context is sufficiently clear.

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

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

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 the full burden of behavioral disclosure. It reveals key behaviors: simultaneous reading, return format (content plus path), partial failure handling ('Failed reads for individual files won't stop the entire operation'), and path restrictions ('Only works within allowed directories'). This goes well beyond the minimal and covers critical behavioral traits.

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 four sentences with no wasted words. It front-loads the core purpose, then efficiently adds efficiency rationale, return format, failure behavior, and permission scope. 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 tool has only one parameter, no annotations, and no output schema, the description is remarkably complete. It covers return format, failure handling, scope restrictions, and the comparative advantage over single-file reads. It leaves little ambiguity for an agent deciding when and how to invoke this 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?

The schema has one parameter 'paths' with zero description coverage. The description compensates by explaining the purpose of paths indirectly ('Each file's content is returned with its path as a reference') and adds a constraint ('Only works within allowed directories'). It clarifies the parameter's role, though it does not specify path format (e.g., absolute vs relative).

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

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

The description clearly states the tool reads multiple files simultaneously, using a specific verb and resource. It distinguishes itself from the sibling 'read_file' by noting it is 'more efficient than reading files one by one', which clarifies its unique purpose.

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 usage context: 'when you need to analyze or compare multiple files'. It implies the alternative of reading files individually, but does not explicitly name 'read_file' as an alternative or specify when not to use this tool. This is clear guidance but lacks explicit exclusions or named 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?

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.