Server Quality Checklist

Tool Scores

• copy_fileC
  2.9/5.0
  Behavior1/5

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

  The description states 'Fails if destination exists', which means a second identical invocation would fail because the destination now exists. This contradicts the annotations' idempotentHint: true, so the description directly conflicts with structured metadata.

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

  Conciseness4/5

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

  The description is concise and front-loaded with the core operation and a critical failure condition. The parameter list is slightly redundant with the schema but remains scannable and does not introduce unnecessary verbosity.

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

  Completeness2/5

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

  Despite having an output schema and annotations, the description lacks usage guidance versus sibling tools and does not resolve the idempotence contradiction. It also omits practical details like path semantics, which are important for safe invocation of a file operation.

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

  Parameters3/5

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

  The schema has 0% description coverage, so the description must compensate for parameter meaning. It lists source and destination as required and adds the destination-existence failure condition. However, it does not explain path formats, whether the source must exist, or destination directory handling, so compensation is incomplete.

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

  Purpose5/5

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

  The description uses a specific verb ('Copy') and resource ('a file'), clearly conveying the operation. It also adds the key constraint that it fails if the destination exists, which helps distinguish it from move_file and write_file.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use copy_file versus sibling tools like move_file or write_file. It does not mention alternatives, exclusions, or prerequisites, leaving the selection rationale entirely to the agent.

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

• move_fileA
  3.8/5.0
  Behavior4/5

  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.

  Conciseness4/5

  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.

  Completeness4/5

  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.

  Parameters2/5

  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.

  Purpose5/5

  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.

  Usage Guidelines3/5

  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.

• get_file_infoA
  3.9/5.0
  Behavior3/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters2/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• delete_fileA
  4.1/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters2/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• create_directoryA
  4.2/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters2/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• list_allowed_directoriesA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, and the description aligns by saying 'Returns the list.' It adds context beyond annotations by noting that subdirectories are also accessible and explaining the meaning of an empty list, which is helpful behavioral/config guidance 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.

  Conciseness5/5

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

  The description is two sentences long, front-loaded with the primary purpose, and includes only essential additional details about subdirectories and empty-list handling. No filler or redundancy.

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

  Completeness5/5

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

  For a simple zero-parameter read-only tool with an output schema, the description fully covers the return semantics and a common edge case (empty list). No significant gaps remain.

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

  Parameters4/5

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

  The tool has zero parameters, and schema description coverage is 100% (trivially). The description adds no parameter-specific semantics, but the baseline for zero-parameter tools is 4, and it does add a note about empty-result configuration that indirectly relates to setup.

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

  Purpose5/5

  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 directories the server is allowed to access, using a specific verb and resource. It distinguishes from sibling listing tools like list_directory by focusing on access permissions, and adds that subdirectories are also accessible.

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

  Usage Guidelines3/5

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

  The description provides useful context about what the result means and what to do if empty (add directory paths in .mcp.json), but it does not explicitly discuss when to use this tool vs alternatives like list_directory or tree. The usage is implied rather than clearly differentiated.

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

• search_filesA
  4.3/5.0
  Behavior4/5

  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.

  Conciseness4/5

  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.

  Completeness4/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• list_directoryA
  4.6/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• manage_bomA
  4.6/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• treeA
  4.6/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• list_encodingsA
  4.7/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• write_fileA
  4.7/5.0
  Behavior5/5

  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.

  Conciseness4/5

  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.

  Completeness5/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• read_multiple_filesA
  4.8/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• read_text_fileA
  4.9/5.0
  Behavior5/5

  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.

  Conciseness4/5

  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.

  Completeness5/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• check_for_updatesA
  5/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• convert_encodingA
  5/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• detect_encodingA
  5/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• edit_fileA
  5/5.0
  Behavior5/5

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

  Beyond the destructiveHint annotation, it reveals critical behavioral traits: returns a diff, preserves encoding and line endings, matching ignores whitespace/CRLF but requires interior spacing, and that a success with diff means the edit is on disk while failure changes nothing. It also details multi-match failure behavior and replaceAll semantics.

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

  Conciseness5/5

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

  Although long, every sentence provides necessary operational detail. It is front-loaded with purpose and usage priority, then flows logically through procedures, matching rules, and example. No filler or repetition that does not add value.

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

  Completeness5/5

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

  With no output schema, the description clearly states the return is a unified diff. It covers expected behaviors for success, failure, dryRun, encoding, line endings, and edge cases like multiple matches. For a complex editing tool with 6 parameters, this description is exceptionally complete.

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

  Parameters5/5

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

  Schema coverage is 0%, and the description fully compensates. It explains each parameter: path, exactly one of edits or patch, dryRun default false, encoding auto, oldText matching constraints, replaceAll, similarity range, and provides a complete example. This is far beyond what the bare schema provides.

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

  Purpose5/5

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

  The description starts with a specific verb+resource: 'Edit one file with replacements or a unified diff.' It also distinguishes from siblings by explicitly stating 'PREFER THIS over read+write to modify a file,' making its purpose and differentiation crystal clear.

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

  Usage Guidelines5/5

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

  The description gives explicit when-to-use and when-not-to-use guidance. It says to prefer this over read+write, details the dryRun workflow for 'ask before edits' mode, and explains when to use similarity vs fixing oldText. It also warns against re-reading the file after successful edits.

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

• grep_text_filesA
  5/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• manage_line_endingsA
  5/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.