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

Annotations provide idempotent and non-destructive; description adds that existing directories succeed silently and that operation is scoped to allowed directories, providing full behavioral context.

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 concise sentences, each adding distinct value without redundancy.

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?

Covers behavior, constraints, and use cases; missing return value info but not critical for simple creation tool.

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

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

Schema has no description for 'path' and description doesn't specify format or examples; since coverage is low, this is a 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?

Clear verb 'create' and resource 'directory'; distinguishes from sibling tools by mentioning nested creation and idempotent behavior.

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

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

Explicitly states ideal use cases (setting up structures, ensuring paths) and constraint (only within allowed directories), giving clear when-to-use guidance.

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

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

The description adds behavioral detail beyond the readOnlyHint annotation by specifying the recursive nature and JSON structure of the output. It also mentions the constraint of working only within allowed directories, which is useful context.

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 (two sentences) and well-structured, with no redundant information. Every sentence adds meaningful detail about the tool's behavior and constraints.

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 mentions 'within allowed directories', it fails to explain the required 'path' parameter or the optional 'excludePatterns' parameter. Given the schema has no descriptions and the output schema is not visible, the description is insufficient for full usage clarity.

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 zero description coverage, and the tool description does not explain any of the two parameters (path and excludePatterns). Without compensation, the agent cannot fully understand what values are valid or how they affect the output.

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 ('Get') and resource (recursive tree view). It distinguishes from sibling tools like list_directory by emphasizing 'recursive', making its 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?

No explicit guidance is provided on when to use this tool versus alternatives. It does not mention that list_directory or search_files are better suited for flat or filtered needs, leaving the agent to infer usage.

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?

The description goes beyond the annotations by revealing that the tool returns a git-style diff and is restricted to allowed directories. It confirms the destructive nature (edits) consistent with the destructiveHint annotation but adds useful behavioral context about the output and scope. It does not fully disclose edge-case behaviors (e.g., multiple matches, error handling), but the additional information is valuable.

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, consisting of two short sentences. It packs essential information—purpose, mechanism, output, and constraint—without any redundant or fluff content. Every sentence adds value, and the structure is straightforward 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?

For a tool with three parameters and a nested edits array, the description provides sufficient context to understand the main functionality: line-based edits with exact matching and a diff result. It also covers the directory restriction. It omits details like error handling when oldText is not found, the exact format of the diff, and the behavior of dryRun, but these are not critical for a basic understanding. The description is complete enough for typical usage.

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 explains the core semantics of the edits array by stating that each edit replaces exact line sequences (oldText) with new content (newText). It also indirectly describes the path via the allowed-directories constraint and mentions the diff output, which relates to the dryRun parameter (though not explicitly named). However, it does not clarify the dryRun flag's purpose or behavior, and path semantics are only implied, so coverage is partial given three parameters.

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: making line-based edits to a text file. It specifies the action (edits), the resource (text file), and the specific mechanism (replacing exact line sequences). It also distinguishes itself from sibling tools by mentioning the git-style diff output and the restriction to allowed directories, making its scope clear.

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 precise line-based changes) by explaining that it replaces exact line sequences and returns a diff, but it does not explicitly compare it to alternatives like write_file or search_files. The constraint 'Only works within allowed directories' is more of a limitation than a usage guideline, so the guidance is implicit rather than explicit.

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?

The description accurately reflects the readOnlyHint annotation by framing the operation as retrieval with no side effects. It adds the meaningful constraint that it only works within allowed directories, though it does not describe error behavior for invalid paths.

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 well-structured, using two sentences to convey purpose, output content, and constraints without extraneous detail.

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 metadata-retrieval tool, the description covers the key aspects: what it returns, that it does not read content, and the access boundary. It lacks explicit error/edge-case details, but these are not critical given the read-only, closed-world annotations.

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 does not mention the 'path' parameter at all, and the input schema provides only its type and required status. Since schema coverage is 0%, the description fails to compensate by explaining what the path should refer to.

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

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

States a specific action ('Retrieve') and resource ('detailed metadata about a file or directory'), and explicitly distinguishes itself from content-reading tools by noting it returns metadata without reading content. This clearly differentiates it from siblings like read_file and list_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?

Provides clear context on when to use it ('understanding file characteristics without reading actual content') and states the allowed-directory constraint. It does not explicitly enumerate alternative tools, but the intended use case is evident from the 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?

The description discloses that the tool returns allowed directories and that subdirectories are also accessible, adding useful behavioral context. Since readOnlyHint=true is already annotated, the description does not need to restate read-only behavior but still provides additional scope information.

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, front-loaded with the primary purpose, and then provides usage context. No redundant 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 the simplicity of the tool (no parameters) and the presence of an output schema, the description fully covers the purpose and usage. No missing information for correct invocation.

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, so the schema coverage is 100% by definition. Baseline for 0 params is 4; the description appropriately does not need to add parameter-specific details.

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 returns the list of allowed directories, distinguishing it from sibling tools like list_directory or read_file. It is specific about the resource (allowed directories) and the action (listing).

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

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

Explicitly tells the agent when to use it: before trying to access files, to understand which directories and nested paths are available. This provides clear guidance and implicitly contrasts with guessing directory paths.

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?

The readOnlyHint annotation indicates no modifications, and the description does not contradict this. It adds the constraint of working only within allowed directories, which is useful context beyond the annotation.

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 well-structured, with the purpose stated first and the prefix detail second. The third sentence contains some redundant fluff about being essential, but overall it is efficient.

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 description mentions the [FILE] and [DIR] prefixes but does not specify whether the listing is recursive or how the paths are formatted. It also lacks information about error handling or the exact output structure, leaving some 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 only parameter 'path' is described merely as 'a specified path' in the description, with no details on format (relative/absolute) or constraints. Since the schema has no description, the tool description fails to adequately define the parameter semantics.

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 that the tool lists files and directories in a given path and highlights the [FILE] and [DIR] prefixes. It distinguishes from sibling tools by focusing on a simple listing, though it doesn't explicitly contrast with directory_tree or list_directory_with_sizes.

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

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

The description implies usage for exploring directory structure and finding files, but it does not explicitly specify when to prefer this over search_files or directory_tree. It provides a constraint that it only works within allowed directories, but lacks direct comparisons to 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?

The description adds useful behavioral context beyond the readOnlyHint and openWorldHint annotations by stating that the tool only works within allowed directories and that results use [FILE] and [DIR] prefixes. This does not contradict the annotations and gives the agent additional expectations about output and constraints.

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 reasonably concise at three sentences, but the sentence 'This tool is useful for understanding directory structure and finding specific files within a directory' adds little value and could be removed or replaced with more specific guidance. The core information is present without excessive verbosity.

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 output schema exists, return-value details are not required, but the description omits important operational details such as whether listing is recursive, how hidden files are handled, and what path values are valid. It also lacks differentiation from list_directory, leaving the agent without enough context to confidently select and 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?

Schema coverage is only 50%: sortBy has a description and enum, but path has no description. The tool description does not compensate by explaining path format, whether it must be absolute/relative, or how it relates to allowed directories. This leaves a key parameter underspecified.

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: to get a detailed listing of files and directories in a specified path, including sizes. It also mentions the distinguishing [FILE] and [DIR] prefixes, which sets it apart from the sibling list_directory, though it does not explicitly name the 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 gives no explicit guidance on when to use this tool versus the sibling list_directory or other tools. The phrase 'useful for understanding directory structure and finding specific files' is generic and applies equally to list_directory, so it does not help an agent choose between them.

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?

The description reveals a key behavioral trait: the operation fails if the destination already exists, which prevents accidental overwrites. This complements the annotations (destructiveHint=true, readOnlyHint=false) by specifying a concrete safety behavior. However, it does not explicitly state that the source is removed after a successful move, though this is implied by the semantics.

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 to the point, but it contains slight redundancy (e.g., 'Can move files between directories and rename them in a single operation' appears twice with similar phrasing). Overall, it is efficient and not verbose, fitting within a couple of sentences.

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 description covers the primary behavior and a critical failure condition, which is sufficient for a basic move operation. It does not describe the output (likely void or a confirmation), but this is not essential for the agent to invoke the tool correctly. The context provided by the description and annotations is adequate for the given 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. The tool's name and description imply they are file paths, but the description does not elaborate on expected formats, relative vs. absolute paths, or whether directories are allowed. The basic intent is clear, but the lack of explicit detail leaves some ambiguity for edge cases.

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: moving and renaming files/directories. It explicitly differentiates between moving across directories and renaming, and the verb 'Move' is specific enough to distinguish it from other file operation tools like read, write, or edit.

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 explains what the tool does but does not provide explicit guidance on when to use it versus alternatives (e.g., copy, edit). The mention of 'move between directories or rename' gives some context, but no direct comparison or conditional advice is given, leaving the decision to the agent's inference.

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

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

Annotations already provide readOnlyHint and openWorldHint, so the safety profile is covered. The description adds useful non-annotation context: the tool is deprecated and returns file contents as text. This goes beyond what the structured annotations alone communicate.

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

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

Two short sentences contain the core operation and the deprecation directive. The critical information is front-loaded, and there is no filler or repetition of schema details.

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 deprecated read-only tool with an output schema present, this description is complete: it states the operation, the return type, the deprecation status, and the replacement tool. Remaining behavioral details such as partial reads are already present in the schema, so nothing critical is missing.

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

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

Schema description coverage is 67%; head and tail are documented in the schema, and path is self-evident from its name and type. The description adds no further parameter-level meaning, but the existing schema coverage is adequate enough that the description does not need to compensate.

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

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

States a specific verb and resource: 'Read the complete contents of a file as text.' The DEPRECATED label and pointer to read_text_file make the differentiation from sibling tools explicit. There is no ambiguity about what this 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 explicitly says 'DEPRECATED: Use read_text_file instead.' This is direct when-not-to-use guidance and names the exact alternative. An agent can immediately route to the correct tool without needing sibling-tool inference.

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?

The description adds the constraint about allowed directories, which is not present in the annotations. It is consistent with the readOnlyHint and does not introduce any side effects, but does not describe error behavior or failure modes.

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, concise and directly to the point. No extraneous information is included.

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 description provides enough information about the output format and behavior for different file types for an agent to use the tool effectively. It does not detail the output schema or error handling, but these are not critical for a simple 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?

The path parameter is not described in the schema or the tool description beyond the context of reading a file. This is adequate for a simple string path, but lacks any detail about expected format or validation.

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 a file and returns a base64-encoded content block with its MIME type. It also distinguishes behavior for image/audio versus other file types, making its purpose distinct from sibling tools like read_file and read_text_file.

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 mentions the restriction that it only works within allowed directories, but does not explicitly state when to prefer this tool over alternatives such as read_file or read_text_file. This leaves some room for inference.

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?

Beyond the readOnlyHint annotation, the description adds valuable behavioral detail: operation can partially succeed, individual file failures don't stop the batch, results include the path as a reference, and access is limited to allowed directories. These are the kind of behaviors an agent needs to know and the annotations do not provide.

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 tight sentences, each adding relevant information: purpose, when to use it, return shape, failure behavior, and scope. There is no filler, and the most important content comes first.

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

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

With one parameter, complete schema coverage, an output schema, and helpful annotations, the description covers everything needed to call it correctly: partial-failure semantics, per-file path referencing, and directory restrictions. Nothing critical is missing.

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

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

Schema coverage for the single 'paths' parameter is 100%, so the baseline is 3. The description adds some context about multi-file behavior but does not provide any per-parameter semantics beyond what the schema already states about paths pointing to valid files within allowed directories.

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 and resource: 'Read the contents of multiple files simultaneously.' It further distinguishes itself from single-file reads by noting its efficiency when analyzing or comparing multiple files, so an agent can clearly tell it apart from read_file and similar siblings.

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 says when to use this tool: 'more efficient than reading files one by one when you need to analyze or compare multiple files.' It also notes the allowed-directory constraint. However, it does not explicitly address read_text_file or read_media_file, so the guidance is clear but not exhaustive.

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?

The annotations already indicate readOnlyHint and openWorldHint. The description adds context about error messages and the restriction to allowed directories, which goes beyond the annotations and clarifies expected 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 information-dense without being verbose. It front-loads the core purpose and then explains the head/tail options and constraints. All sentences contribute meaningful details, though a slight redundancy exists in repeating the purpose at the start.

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 description covers when to use the tool, what it does, and its constraints (allowed directories, encoding handling). Since an output schema is present (as indicated), the absence of return-format details is acceptable. Overall, an agent has sufficient context to call this 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 schema covers head and tail descriptions (67% coverage). The description explicitly explains the head and tail parameters and their partial-read behavior. The path parameter is not described in the schema, but its role is implied by the tool's purpose and the 'single file' wording, so the description compensates adequately.

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 action (read), the resource (file), and the scope (complete contents as text). It distinguishes itself from siblings like read_media_file and read_multiple_files by explicitly mentioning 'as text' and 'single file', so an agent can select it appropriately.

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 when to use the tool ('when you need to examine the contents of a single file') and explains head/tail for partial reads. It does not explicitly state when not to use it, but the sibling names and the 'single file' and 'as text' qualifiers provide implicit 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?

The description discloses key behaviors: recursive search, returning full paths, glob-style pattern matching, and restricting to allowed directories. It does not contradict the readOnlyHint annotation. However, it omits details about edge cases (e.g., no matches) which might be expected but are covered by the output schema.

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 succinct and well-organized. It provides essential information in a few sentences, includes illustrative examples, and avoids unnecessary jargon or repetition.

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 description covers the core functionality, usage context, and constraints (allowed directories). It does not address error conditions or performance implications, but the output schema likely defines return structure, and the sibling tools list offers alternatives. Overall it is reasonably complete for the 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 description explains the 'pattern' parameter well with examples and clarifies path relativity, but it does not explicitly define the 'path' parameter or mention 'excludePatterns' at all. Since schema coverage is 0%, the description only partially compensates for the missing parameter documentation.

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: 'Recursively search for files and directories matching a pattern.' It also provides concrete examples of pattern usage, making the intended action and resource 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 notes it is 'Great for finding files when you don't know their exact location,' which gives a clear use case. It also implies a contrast with tools like read_file or list_directory, though it does not explicitly name alternatives or provide a decision tree.

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?

Beyond the destructiveHint annotation, the description adds behavioral details: overwrites without warning, handles text encoding, and only works within allowed directories. This provides transparency about side effects and constraints.

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, with three sentences covering purpose, caution, and constraints. It is well-structured and contains no unnecessary 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?

The description covers the essential aspects: purpose, caution, text handling, and directory restrictions. It does not mention output/return values, but an output schema exists, so that is not required. It could mention idempotency or error conditions, but these are not critical for basic usage.

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 types for path and content with no descriptions, and the description does not elaborate on these parameters. While straightforward, the description adds no meaning beyond the parameter names.

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

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

The description clearly states the action (create/overwrite), the resource (file), and the scope (new content vs. existing file), distinguishing it from sibling tools like edit_file or create_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?

It explicitly warns about overwriting without confirmation and notes the constraint of allowed directories, giving clear guidance on when to use this tool and what to expect.

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