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

The description discloses caching behavior (max 1 GitHub API call per 30 min), bypass condition, and return contents, adding context beyond the annotations (readOnlyHint, idempotentHint). It clarifies the tool's non-idempotent nature through the cache and force explanation.

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 concise sentences, each providing distinct information: purpose, returns, caching behavior, and usage recommendation. Every sentence earns its place with no 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?

For a simple one-parameter tool with an output schema, the description covers purpose, behavior, parameters, and usage. It is fully complete without needing to describe return structure since the output schema exists.

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 'force' is fully explained in the description as bypassing the cache, compensating for the 0% schema description coverage. This adds essential meaning beyond the bare boolean type.

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 checks for a newer version of mcp-file-tools, a specific action on a specific resource. It distinguishes this tool from sibling file operation tools by focusing on self-update functionality.

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 instructs to 'Call once at the start of each session,' providing clear when-to-use guidance. It also explains the force parameter's conditional use (bypassing cache), which helps decide when to invoke it differently.

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 annotations (destructiveHint=true, idempotentHint=true), the description discloses specific behaviors: backup creation, refusal to corrupt with naming missing characters, BOM stripping and contradiction handling, and partial batch failures. This significantly enriches the agent's understanding of side effects and edge cases.

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 densely packed but every sentence earns its place: purpose, parameter guide, behavioral notes, and examples. It is structured logically from high-level operation to specific details, with no filler 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?

Given 8 parameters, a mutation tool, and an output schema, the description covers all necessary contexts: parameter constraints, error handling, idempotency, backup behavior, BOM nuance, and batch execution. The presence of examples further rounds out completeness.

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%, and the description fully compensates. It explains every parameter individually (path vs paths, to, from, backup, dryRun, allowLowConfidence, bom) and provides concrete JSON examples that illustrate correct usage, making the schema's bare properties meaningful.

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 opening sentence "Convert files between encodings" states a specific verb and resource, clearly distinguishing it from sibling tools like detect_encoding, list_encodings, and manage_bom. No ambiguity exists about 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 provides actionable guidance: "Run dryRun over a project first," "confirm it with from, or pass allowLowConfidence=true," and notes when conversion is unnecessary ("No-op if the file already holds the target bytes"). It even explains batch behavior ("one bad file does not stop the rest") which informs usage decisions.

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 provides rich behavioral details beyond the annotations: never overwrites, existing destination causes an error, source must be a file, destination parent must exist, paths must be inside allowed directories, and relative paths resolve against the server start directory. These are exactly the kind of non-obvious behaviors an agent needs to know. There is no contradiction with the 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?

The description is dense but every sentence serves a purpose: core semantics, typical use, parameter preconditions, failure behavior, path constraints, and sibling routing. It is front-loaded with the most important information and uses straightforward language without redundant 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?

Given this is a simple two-parameter copy operation with an output schema available, the description covers everything needed for correct invocation: exact behavior, preconditions, error conditions, path constraints, and alternatives. No critical information 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?

With 0% schema description coverage, the description compensates by naming both parameters and clarifying their roles: source is a required file path and destination is a required path whose parent must exist and which must not already exist. It could have described path formats more explicitly, but it adds meaningful semantics beyond the bare string 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 opens with a precise action: 'Copy one file byte for byte, keeping its encoding, BOM, line endings, permissions and mtime.' This clearly identifies the resource and operation, and it distinguishes copy_file from sibling tools by emphasizing its byte-for-byte preservation semantics.

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 the primary use case ('back up a file before an edit or a conversion') and names concrete alternatives with selection criteria: prefer move_file to relocate, write_file for new content, and convert_encoding with backup=true for a .bak beside a converted file. This leaves no ambiguity about when to choose this tool.

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 details beyond the annotations, specifically the recursive creation ('mkdir -p') and the silent success behavior if the directory already exists. These align with the idempotentHint annotation but provide concrete implementation 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 two sentences, front-loaded with the primary action, and contains no unnecessary words. Every sentence contributes useful 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?

For a simple directory creation tool with idempotentHint and a known output schema, the description covers the essential behavior. It notes recursion and silent success, which are the main nuances. No additional return value explanation is needed given the output schema exists.

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 merely repeats 'Parameter: path (required)', which restates the schema without adding any new meaning. It does not explain what kind of path is expected (absolute/relative) or any constraints. Since schema coverage is 0%, the description fails 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?

The description clearly states the tool's function: 'Create a directory recursively (mkdir -p)'. This uses a specific verb and resource, and distinguishes it from sibling tools like write_file or delete_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 provides clear context by noting it creates directories recursively and silently succeeds if the directory already exists. It does not explicitly mention alternatives, but the purpose is distinct and unambiguous given the sibling tool names.

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 declare destructiveHint: true, so the safety profile is known. The description adds a valuable behavioral trait: 'Does not delete directories', which prevents misuse. This goes beyond the annotations without contradicting them.

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 extremely concise, consisting of two short sentences. It front-loads the main action and includes a necessary limitation without any filler, making it highly 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?

For a simple delete tool with one parameter and a destructive annotation, the description covers the core behavior and a key limitation. It lacks details on error handling or return values, but the presence of an output schema and annotations partially fills this gap.

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, and the description only restates 'Parameter: path (required)' without adding semantic detail. It does not explain the path format, whether absolute/relative, or behavior with non-existent paths, so it fails to compensate for the schema gap.

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

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

The description 'Delete a file' uses a specific verb and resource, clearly stating the tool's purpose. It also distinguishes from sibling tools by explicitly noting 'Does not delete directories', which differentiates it from directory-related 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 a clear usage constraint by stating the tool does not delete directories, implying it should be used only for files. However, it does not explicitly name alternative tools for directory deletion, so it lacks a direct comparison but still gives useful context.

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

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

Beyond the readOnlyHint, the description adds behavioral context including confidence scoring, BOM detection, multiple modes (sample, chunked, full), and candidate ranking on low confidence. This fully discloses the tool's behavior and limitations.

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 usage guidance, parameter details, and edge-case behavior. Every sentence adds value without unnecessary 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 the presence of an output schema, the description need not detail return values, but it covers the key aspects of usage, parameters, and exceptional cases, making it complete for 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?

With 0% schema description coverage, the description compensates by explaining path as required and detailing mode values (sample, chunked, full) along with their semantics, exceeding the bare schema types.

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 auto-detects file encoding with confidence score and BOM detection, using a specific verb and resource. It distinguishes itself from siblings like read_text_file and convert_encoding by positioning itself as the preliminary step before reading.

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 instructs to ALWAYS use this first when encountering garbled text, and to use before read_text_file. It also provides guidance on what to do when confidence is low, such as retrying with a supported encoding and asking the user.

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 show destructiveHint=true, but the description goes well beyond that by explaining exact behavior: encoding and line endings are preserved, mixed line endings are repaired to the dominant style, matching ignores leading/trailing whitespace and CRLF/LF, edits apply in order, and a failed edit changes nothing. No contradiction with annotations exists.

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 long but exceptionally dense, with the core guidance front-loaded ('Edit one file... returns a unified diff... PREFER THIS over read+write'). It is a single block rather than structured sections, but every sentence provides useful operational detail, so it earns its length.

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

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

Given six parameters, no output schema, destructive behavior, and multiple sibling tools, this description is remarkably complete. It covers the return value, dry-run flow, matching edge cases, line-ending repair reporting, and no-verification rule. The only minor omission is forceWritable, but the operational workflow is fully specified.

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 carries the burden. It thoroughly documents path, edits, patch, dryRun, encoding, replaceAll, similarity, and matching semantics, and includes a concrete example. The only parameter not mentioned is forceWritable, so the coverage is excellent but not complete.

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

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

The description states a specific action ('Edit one file with replacements or a unified diff'), identifies its result ('Returns a unified diff'), and distinguishes it from the alternate read+write flow. It also names a sibling concept ('PREFER THIS over read+write') so the agent can differentiate it from write_file without inspecting schemas.

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?

Explicit usage guidance is provided: prefer this over read+write, use dryRun=true in ask-before-editing mode, and use dryRun=false with auto-edit permissions. It also gives recovery guidance on no-match ('prefer fixing oldText... Alternatively retry with similarity') and tells the agent not to re-read the file afterward.

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 declare readOnlyHint=true, so the safety profile is covered. The description adds that it returns specific metadata fields and warns about large files, but it doesn't discuss error handling, path existence, or directory-specific behavior. This is modest added context, appropriate given the low bar set by 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?

The description is two sentences, front-loaded with the primary function and metadata types. It includes a practical usage hint and parameter mention without any waste, achieving maximum conciseness.

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, read-only, output schema present), the description covers the main metadata returned and a key use case. It doesn't elaborate on edge cases, but the output schema and annotations fill some gaps, making it fairly 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 schema only provides a required string 'path' with no semantic detail, and the description merely repeats 'path (required)' without explaining accepted formats, relative vs absolute paths, or how directories versus files are handled. With 0% schema coverage, the description fails to compensate sufficiently.

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 retrieves file/directory metadata (size, timestamps, permissions, type), which is a specific verb plus resource. It distinguishes itself from content-reading tools like read_text_file by focusing on metadata rather than file contents.

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 gives an explicit use case: 'Use this to check file size before reading large files with read_text_file.' This names an alternative tool and specifies a scenario. It doesn't explicitly mention when not to use, but the guidance is clear and actionable.

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 many behavioral traits: skips .gitignore'd files unless respectGitignore=false, defaults for caseSensitive and maxMatches, context modes limited to content mode, matchesOnly semantics, offset pagination with nextOffset echo, and glob specifics. This goes well beyond the readOnlyHint annotation, providing substantial operational insight.

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?

Though long, the description is highly organized and front-loaded. It starts with purpose and preference, then systematically covers parameters, output modes, and edge cases. Every sentence contributes useful detail, and the example anchors understanding.

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 16-parameter tool with no schema descriptions, the description is exceptionally complete. It covers defaults, modes, glob semantics, paging, and even includes a concrete example. The output schema can handle return structure, so this is sufficient for an agent to select and 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?

With no parameter descriptions in the schema (0% coverage), the description compensates fully. It defines every parameter, clarifies the difference between singular and plural forms, documents defaults, and explains how contextBefore/After and matchesOnly behave. This is essential for correct invocation.

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 clear verb+resource: 'Regex search in file contents with encoding support.' It explicitly distinguishes from the built-in Grep by recommending this tool for non-UTF-8 files, and the example further illustrates its intended use.

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 'PREFER THIS over built-in Grep for non-UTF-8 files,' naming the alternative. It also provides thorough guidance on when to use outputMode 'files_with_matches' vs 'content', explains the efficiency of 'patterns' for multiple regexes, and warns against combining singular and plural fields.

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 meaningful behavioral context: directories are typically the startup directory, subdirectories are also accessible, and an empty list indicates a configuration issue. This enriches the agent's understanding without contradicting 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?

Two sentences with the primary function first and troubleshooting second. Every sentence adds value; no filler or 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?

For a simple, zero-parameter tool with an output schema, the description fully covers purpose, typical behavior, and the empty-result remediation. No additional context is needed 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?

Tool has zero parameters, so the input schema is inherently complete. The description appropriately does not invent parameter details; baseline of 4 applies for a zero-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?

Description states a specific action ('Returns the list of directories this server is allowed to access') and clearly distinguishes from sibling list_directory by focusing on allowed roots rather than directory contents. The added detail 'normally the directory it was started in' further clarifies the tool's unique role.

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 for when to use the tool: to discover accessible directories. It also gives actionable guidance for the empty-result case (.mcp.json or MCP_FILE_TOOLS_ALLOWED_DIRS). However, it does not explicitly contrast with sibling tools or state when not to use it, 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?

Beyond the readOnlyHint annotation, the description adds behavior details about sorting (sortBy values and their effects) and the reverse option, giving the agent a better sense of the tool's output ordering. It also notes the default pattern '*', 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 a single sentence that packs essential parameter details without fluff. It is front-loaded with the primary purpose and wastes no 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 read-only directory listing tool with an output schema, the description covers purpose, filtering, sorting, and defaults. Output format is handled by the output schema, so no gap exists.

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 no parameter descriptions, but the description compensates fully by explaining path (required), pattern (optional, default *), sortBy (with specific sort options), and reverse (flips order). This adds substantial meaning beyond the raw 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 clearly states the tool lists files and directories with optional glob filtering, using the verb 'List' and specifying the resource. This distinguishes it from sibling tools like 'tree' (which implies hierarchy) and 'search_files' (which implies content search).

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 by explaining the parameters, including the default sort order and reverse flag. However, it does not explicitly compare to alternatives like 'tree' or 'search_files' for when to choose this tool.

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 mark readOnlyHint=true, and the description adds that it lists exactly 25 supported encodings with their metadata. No side effects are implied, and the description aligns with the read-only nature.

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 sentences, both dense with information. The first states the action and output contents; the second explains the use case. No unnecessary 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 the simplicity of the tool, the description fully covers its purpose and usage. The output schema exists, so the description need not list return fields.

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?

This tool has zero parameters, so baseline is 4. The description correctly omits parameter details, as there are none.

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 ('List') and identifies the resource ('encodings'), specifying the exact content ('name, aliases, description') and count (25). This clearly distinguishes it from sibling tools like detect_encoding or convert_encoding.

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 when to use: 'Use this to find the correct encoding name for read/write/convert operations.' This provides clear context for selecting this tool over 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?

Annotations already indicate destructive and idempotent behavior. The description adds specific action semantics (detect, strip, add) and conditional requirements (encoding for 'add'), enriching understanding beyond the generic hints without contradiction.

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: the first defines purpose, the second condenses all parameter details. It is information-dense with no redundancy or unnecessary elaboration.

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, combined with annotations (destructive, idempotent) and output schema, covers purpose, usage context, parameter constraints, and safety implications. Nothing critical is missing for an agent to invoke 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?

With 0% schema description coverage, the description fully compensates by enumerating valid action values, specifying encoding as required for 'add', and listing supported encoding formats. This provides complete parameter meaning beyond the bare 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 detects, strips, or adds a Unicode BOM, using specific verbs and identifying the resource. It also provides context about UTF-8 and UTF-16 implications, clearly distinguishing it from sibling tools like detect_encoding and convert_encoding.

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 conveys when BOM management is relevant (UTF-8 breaking scripts, UTF-16 needing BOMs), giving clear context for use. However, it does not explicitly name alternatives or state when not to use this tool, falling short of full exclusion 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?

Beyond the annotations, the description reveals important behaviors: rewriting the file for convert, no-op when the file already matches (idempotency), preservation of BOM, auto-detection of encoding, and potential misreading for short files. This adds significant context that annotations alone 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?

The description is front-loaded with the core purpose and uses concise, informative sentences. It packs a lot of detail without redundancy, and the example is well-placed. Every sentence contributes meaningful 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 tool's complexity (two actions, encoding nuances, BOM handling), the description covers all necessary aspects: return values for detect (style, total lines, line numbers), convert behavior, parameter details, and example usage. It is complete for an agent to invoke 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 has no descriptions and 0% coverage, but the description explains every parameter: path, action (with valid values), style (required for convert), and encoding (with auto-detection and fallback options). The example ties them together, fully compensating for the schema's lack of detail.

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 'Detect or fix line endings', which clearly states the verb and resource. It distinguishes between two actions (detect and convert) and provides details on what each does, making it distinct from sibling tools like convert_encoding or manage_bom.

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 detect ('use it when a file looks inconsistent') and describes the convert behavior with encoding and BOM handling. It also gives an example, making usage clear, though it does not mention alternative tools directly. The context is sufficient for an agent to decide when to invoke it.

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 signal destructive behavior, and the description adds a critical behavioral detail: it fails if the destination exists, meaning no overwrite. This is valuable context beyond annotations. It also clarifies it operates on both files and directories.

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 short and front-loaded with the core purpose in the first sentence. The second sentence about parameters is redundant with the schema but does not significantly bloat the 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?

For a simple two-parameter move tool, the description covers the core operation, the failure mode, and the applicable resources. With annotations already providing destructive hints and an output schema available, the description is sufficiently complete for an agent to use it correctly.

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

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

Schema description coverage is 0%, so the description should compensate for the bare schema. However, it merely repeats 'source (required), destination (required)' without explaining the meaning of each parameter, such as source being the current path and destination being the target path. The parameter names are self-evident, but the description adds no semantic depth.

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 ('move/rename') with a clear resource ('files/directories') and explicitly states a key constraint ('fails if destination exists'), which distinguishes it from siblings like copy_file and delete_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 implies usage by its clear verb and resource, but does not explicitly reference alternatives or when-not-to-use. It mentions a failure condition but not when to choose this over copy_file or write_file.

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 reveals that 'Individual failures don't stop the batch — partial results are returned,' and that encoding is 'auto-detected per file.' These behavioral details help an agent anticipate outcomes.

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 efficiently cover purpose, usage guidance, and parameter semantics. No redundant information, and the key action is front-loaded.

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 concurrency, encoding support, and partial failure behavior, which are the main operational concerns. With an output schema present, no return-format details are needed. It is well-rounded for a batch-read 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?

With 0% schema description coverage, the description fully compensates by explaining 'paths (required array)' and 'encoding (optional, auto-detected per file),' adding semantic meaning beyond the raw 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 clearly states it 'Read multiple files concurrently with encoding support,' which specifies both the verb and the resource, and distinguishes it from sibling tools like read_text_file by emphasizing the multi-file and non-UTF-8 use case.

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 advises to 'PREFER THIS when reading several non-UTF-8 files at once,' providing a concrete when-to-use scenario. It does not name sibling alternatives directly, but the context makes the guidance clear enough.

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 discloses encoding auto-detection, UTF-8 conversion, return metadata (totalLines, fileSizeBytes), line number prefix behavior with a caution to strip it before use in edit_file, and maxCharacters to prevent token overflow. It also details offset as 1-indexed and limit as max lines, adding substantial 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?

The description is dense but efficient, with each sentence adding value. The parameter explanation is packed into one long but factually complete sentence; however, bullet points would improve scannability. The pagination example is a useful addition that justifies its length.

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

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

The description covers the tool's purpose, usage guidance, parameter semantics, and return metadata, and even includes a concrete paging example. Since an output schema exists, detailed return structure is unnecessary. For a tool with 6 parameters, this description is remarkably 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?

With 0% schema description coverage, the description compensates by explaining every parameter: path is implicit, encoding auto-detected, offset as 1-indexed start line, limit as max lines, maxCharacters to avoid token overflow, and lineNumbers with default false and prefix format. It also provides a pagination example demonstrating offset/limit usage, making parameter semantics clear.

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 with encoding auto-detection and converts to UTF-8, using a specific verb and resource. It also distinguishes itself from the built-in Read tool by specifically targeting non-UTF-8 files, making its purpose unique among 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?

The description explicitly says 'PREFER THIS over built-in Read for non-UTF-8 files (Cyrillic, legacy codebases)', giving clear when-to-use guidance and naming an alternative. It also provides concrete pagination instructions for files larger than 2000 lines, showing exactly how to structure offset and limit for subsequent reads.

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 mark the tool as readOnlyHint, lowering the bar. The description adds meaningful behavioral detail: skips .gitignore'd files unless respectGitignore=false, sorts lexically by name by default, and ranks the whole tree before trimming to maxResults for mtime/size sorts. No contradiction with 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?

The description is dense but every sentence contributes value, from the core purpose to sorting rules and an example. The parameter list is a bit run-on, yet the overall length is justified by the tool's complexity. Minor structural improvements would earn a 5.

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 output schema exists, so return values need no description. The description covers search semantics, sort options, gitignore behavior, and result capping, which is largely sufficient. The lack of excludePatterns explanation is the main gap, making it complete but not flawless.

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?

With 0% schema description coverage, the description must explain parameters. It thoroughly covers sortBy options, reverse, maxResults behavior, and respectGitignore, and shows path/pattern via example. Only excludePatterns is left with no semantic detail, preventing a 5.

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 begins with a clear verb and resource: 'Recursively search for files matching a glob pattern,' and expands with specifics about supported patterns and output (full paths). It also distinguishes itself from the built-in Glob by noting the missing mtime default, which differentiates it from sibling file tools.

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

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

Usage context is provided via the contrast with the built-in Glob and the explanation of sortBy behavior (e.g., no mtime default, pass sortBy for newest first). However, it does not explicitly state when to prefer this over siblings like list_directory or tree, so it misses the top 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?

Annotations already declare readOnlyHint=true. The description adds behavioral details (skips .gitignore/.git, includes when respectGitignore=false, showEncoding feature) without contradicting 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 with no redundancy: purpose, preference, behavior, and parameter list. Front-loaded with essential info and each 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?

Covers all 7 parameters with defaults and semantics, gives usage context, and an output schema exists. Adequate for a tree tool with no missing operational details.

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

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

Schema coverage is 0%, so the description must compensate. It lists path (required), maxDepth (0=unlimited), maxFiles (default 1000), dirsOnly, exclude (array of patterns), and showEncoding. respectGitignore is also explained in the behavior sentence. All parameters have semantic 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?

States 'Compact indented tree view of directory structure' with a specific verb+resource. The directive 'PREFER THIS for directory visualization' clearly distinguishes it from siblings like list_directory and 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?

Explicitly says 'PREFER THIS for directory visualization' and gives a concrete use case via showEncoding. Does not name alternative tools but the preference is strong and 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?

Although annotations already indicate destructiveHint=true and idempotentHint=true, the description adds substantial behavioral context: encoding default behavior, BOM modes ('auto', 'preserve', 'never', 'always') with failure cases, and lineEndings 'preserve' ensuring LF does not mix into CRLF files. These details enrich the annotation hints without contradiction.

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 dense but not bloated; every clause adds value. It could be more structured with bullets, but the linear narrative with the example is effective and front-loaded with the primary 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?

The tool has five parameters, no enum constraints, and an output schema, so the description need not cover return values. It covers all parameter semantics, behavioral subtleties, and provides a practical example. No critical gaps remain.

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 explain all parameters. It does so exhaustively: path and content are straightforward, encoding has a default, bom has four modes with behavior, lineEndings has four modes. A concrete PHP BOM-stripping example further clarifies usage.

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 'Write file with encoding conversion from UTF-8', a specific verb+resource statement. It further distinguishes the tool from alternatives by saying 'PREFER THIS over built-in Write for non-UTF-8 files', 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?

The description gives explicit guidance: 'PREFER THIS over built-in Write for non-UTF-8 files' and 'Use after read_text_file to keep the original encoding'. It names alternatives (built-in Write, read_text_file) and provides a workflow context, though it does not explicitly contrast with sibling tools like edit_file or convert_encoding.

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