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?

No annotations are provided, so the description carries the full burden. It explicitly discloses the irreversible nature ('cannot be undone'), the recursive behavior for non-empty directories, and the scope restriction to allowed directories. This is excellent transparency for a destructive 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 concise, using four short sentences. It front-loads the purpose, then adds critical warnings and scope constraints. Every sentence provides essential information without 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?

For a delete tool with no annotations or output schema, the description covers everything essential: what it deletes, irreversibility, recursive handling, and directory restrictions. It is complete enough for an agent to use 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 coverage is 50% (recursive has a schema description, path does not). The description adds meaningful context: 'non-empty directories and their contents' clarifies the recursive flag's behavior beyond the schema's generic 'delete directories recursively.' It also implies path semantics via 'only works within allowed directories.' However, path itself is not explicitly explained, and the schema handles recursive reasonably well.

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

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

The description clearly states the tool's function: 'Delete a file or directory.' It specifies both file and directory targets, distinguishing it from sibling tools like read_file, write_file, and move_file. The verb 'delete' is specific and 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: use with extreme caution, cannot be undone, recursive flag for non-empty directories, and restriction to allowed directories. It implies when to use it (destructive deletion) but does not explicitly mention alternatives or when not to use it, which would elevate it to a 5.

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, the description carries the full burden. It discloses syntax validation for specific file types, detailed error messages, dryRun and skipValidation options, git-style diff output, and allowed-directory restrictions. It does not mention atomicity or what happens if oldText is not found, but covers key behaviors well.

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 and front-loaded with the core purpose. Every sentence adds value: purpose, edit semantics, validation, options, return format, and 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?

For a 4-parameter tool with no output schema, the description is highly complete. It covers the edit operation, validation behavior, preview option, return format, and directory restrictions. It is sufficient for an agent to use the tool correctly.

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

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

The description adds meaning beyond the schema: 'Each edit replaces exact line sequences with new content' explains oldText/newText semantics, and 'Use dryRun=true to preview changes' clarifies the boolean parameters. Path format is unspecified, but the allowed-directories constraint gives context.

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 'Make line-based edits to a text file' with a specific verb, resource, and approach. It also distinguishes itself from siblings like write_file (full-file overwrite) and delete_file by emphasizing targeted line replacement and syntax validation.

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?

Clear context is given: line-based edits, syntax validation, and dry-run previews. However, it does not explicitly mention alternatives like write_file or when not to use this tool, so it lacks explicit exclusions or 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, the description carries the burden of disclosure. It states what it returns (size, creation time, permissions, type) and explicitly says it does not read content, implying a read-only behavior. It also discloses the allowed-directories restriction. However, it doesn't describe error behavior (e.g., nonexistent paths) or permission requirements, leaving minor 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 three sentences long, front-loaded with the primary purpose. Each sentence adds value: what it does, what it returns, and when/where it can be used. No redundancy or filler.

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

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

For a tool with a single parameter and no output schema, the description covers essential aspects: target type (file/directory), return details, and access restriction. It doesn't cover error handling or return format specifics, but given the tool's simplicity and the absence of annotations, it is reasonably 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?

The schema provides only a 'path' string with 0% description coverage. The description adds that the target can be a file or directory and that it must be within allowed directories, which is helpful. However, it doesn't specify path format (absolute vs relative) or whether trailing slashes matter, so the compensation is partial.

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 'Retrieve' with a clear resource: 'detailed metadata about a file or directory'. It distinguishes itself from siblings like read_file (which reads content) and list_directory (which lists contents), 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?

It explicitly states the tool is for 'understanding file characteristics without reading the actual content', implying when to use it over content-reading tools. It also mentions 'Only works within allowed directories', providing a crucial constraint. It doesn't explicitly name alternatives but the context is 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, the description carries the full burden. It states the return value ('Returns the list') and implies read-only behavior. It does not describe the return format or error cases, but for a zero-parameter getter this is sufficient.

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

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

Two concise sentences with no redundant information. The main function is front-loaded, and the second sentence adds practical usage guidance without bloat.

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

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

For a simple tool with no parameters and no output schema, the description adequately covers what it returns and when to use it. A minor gap is the lack of return format specification, but this is not critical for a discovery list.

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

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

The tool has zero parameters and the schema coverage is 100% (empty). Baseline for 0 params is 4, and there is no additional parameter semantics to explain.

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?

Description clearly states the tool returns a list of allowed directories, using a specific verb ('Returns') and resource ('directories'). It distinguishes from sibling tools like list_directory by specifying 'allowed to access' rather than listing contents of a given path.

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?

Provides explicit guidance to use this tool before accessing files, making the intended use case clear. It does not name alternatives or exclusions, but the context of sibling file-access tools makes the usage obvious.

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 adds useful behavioral details: results are prefixed with [FILE] and [DIR], and the tool is restricted to allowed directories. However, it omits other potentially relevant behaviors like recursion, hidden files, or error handling for invalid paths, so transparency is moderate.

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 (4 sentences) and each sentence earns its place: purpose, output format, usage context, and a critical constraint. There is no fluff or redundant information, and it is well-structured with front-loaded purpose.

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

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

For a simple tool with one parameter and no output schema, the description covers the main aspects: what it does, what results look like, and a usage constraint. It is mostly complete, though it could mention whether the listing is recursive or only immediate children, but given the tool's simplicity, it is sufficiently 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?

The schema description coverage is 0% with only a single 'path' parameter. The description compensates somewhat by implying the path should be a directory ('...in a specified path') and adding the constraint about allowed directories. However, it does not clarify whether the path must be absolute, relative, or what happens for nonexistent paths, so the compensation is partial.

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: 'Get a detailed listing of all files and directories in a specified path.' This is a specific verb+resource that uniquely identifies the tool as a directory listing operation, distinguishing it from siblings like read_file (content) or search_files.

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 context on when to use the tool: 'essential for understanding directory structure and finding specific files within a directory.' It also notes the constraint 'Only works within allowed directories,' giving clear usage boundaries. It does not explicitly name alternatives, but the purpose is clear enough for an agent to choose it appropriately.

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, the description carries the full burden of behavioral disclosure. It mentions handling various text encodings, detailed error messages for unreadable files, and the restriction to allowed directories. This adds useful context beyond the schema, though it doesn't detail return format or size limits.

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

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

The description is three sentences, front-loaded with the core purpose, then adding behavioral nuances and parameter usage. Every sentence earns its place with no fluff.

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

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

Given no annotations and no output schema, the description covers the essential context: purpose, usage, head/tail semantics, and directory constraints. It could explain the return format or maximum file size, but for a simple read tool, it is sufficiently 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?

Schema coverage is 67% (head and tail have descriptions), and the description repeats their purpose without adding new syntax or format details. The path parameter has no schema description, and the description only implies it via 'file from the file system', not adding explicit meaning. Overall, the description adds marginal value over 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 explicitly states the tool reads the complete contents of a file, which is a specific verb+resource. It distinguishes itself from siblings by noting 'single file' and mentions head/tail for partial reads, making its purpose clear and unique.

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

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

It provides clear guidance on when to use the tool ('when you need to examine the contents of a single file') and how to use head/tail parameters. It doesn't explicitly mention alternatives like read_multiple_files, but the 'single file' qualifier implies the distinction, which is adequate.

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?

With no annotations, the description carries the transparency burden. It mentions timeout, secure environment, and stderr capture, but does not disclose exit code handling, output format, or what happens on timeout. These are significant behavioral gaps for a command execution 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 three sentences, front-loaded with the primary action and followed by concise context. Every sentence adds value without redundancy or fluff.

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

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

While the description covers allowed directories and timeout, it lacks critical context for a command runner: no output schema exists, and the description does not specify the return structure (e.g., object with stdout/stderr/exit code). This leaves agents uncertain about how to parse results, making it only partially 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?

Schema coverage is 100%, so the schema already documents all parameters. The description adds no substantive parameter-specific guidance beyond what the schema provides, only hinting at timeout and stderr which are already in 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 states 'Execute shell commands and return their output' with a clear verb and resource. Sibling tools are all file operations, so this tool is unambiguously the command executor, distinguishing itself without needing explicit contrast.

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

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

It says 'Useful for development tasks, file operations, git commands, package management, etc.', providing clear usage context. However, it does not explicitly state when not to use the tool or mention alternatives, so it falls short of a 5.

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 recursive search, case-insensitivity, advanced glob support, return of full paths, traversal of all subdirectories, and restriction to allowed directories. This is substantial context beyond basic 'search files' and provides enough transparency for an agent to anticipate 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 somewhat verbose and repetitive (mentions 'glob patterns' multiple times, repeats 'searches'). It also includes the unrelated 'FIXED VERSION' prefix, which is noise. However, the core purpose is front-loaded and the examples are useful. It could be tightened without losing information.

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

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

Given three parameters, no annotations, and no output schema, the description covers the key behaviors: recursion, glob matching, case-insensitivity, path return, and allowed directory restrictions. It lacks details on excludePatterns and edge cases, but it is sufficiently complete for an agent to decide to invoke the tool and understand what to expect.

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 clarify the parameters. It explains 'path' as the starting path (via 'from the starting path') and 'pattern' as the glob pattern, with examples. However, it does not mention 'excludePatterns' at all, leaving one of three parameters undocumented. The description adds value for two parameters but misses the third.

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

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

The description clearly states a specific verb and resource: 'Recursively search for files and directories matching a glob pattern.' It provides concrete glob examples and differentiates from sibling tools like list_directory by emphasizing searching by pattern rather than listing a directory. The purpose is unmistakable.

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 says 'Great for finding files when you don't know their exact location,' giving a clear use case. It also notes the constraint 'Only searches within allowed directories.' While it doesn't name alternatives or explicitly say when not to use it, the context makes the appropriate usage 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explicitly warns about destructive overwriting ('will overwrite existing files without warning'), mentions text encoding ('proper encoding'), and notes path constraints ('Only works within allowed directories'). This is strong transparency for a write 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 three sentences, front-loaded with the primary action, and each sentence adds crucial information (overwrite semantics, caution, encoding, directory restriction). It is concise without being underspecified.

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

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

For a simple two-parameter write_file tool with no output schema and no annotations, the description provides essential context: the destructive nature, text handling, and directory restrictions. It does not mention return values or error behavior, but these are less critical for a straightforward write 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 provides no descriptions (0% coverage), so the tool description must compensate. It indirectly explains that 'content' is the new text payload and that 'path' refers to a file location subject to allowed directories, but it does not elaborate on path formats, file type restrictions, or any content size limits. Some meaning is added but not comprehensive.

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

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

The description opens with a specific verb plus resource: 'Create a new file or completely overwrite an existing file with new content.' This clearly distinguishes it from sibling render_file by emphasizing complete overwrite, and it is easy to understand exactly what the tool does.

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 when to use the tool—for creating or fully replacing files—but does not explicitly name alternatives like edit_file for partial modifications. The cautionary phrase 'Use with caution' gives some situational context, but there is no explicit when-to-use versus when-not-to-use guidance.

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