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?

Annotations already declare destructive/readOnly/idempotent status, but the description adds rich behavior: refuses rather than corrupting, names offending characters with line/column, handles BOM stripping and contradictions, no-ops on target bytes, and continues batches after one bad file.

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 front-loads purpose, then compactly lists parameters, then adds behavioral notes and examples. Although long, every clause adds needed detail for an 8-parameter mutation tool with complex failure semantics.

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

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

With an output schema present, the description need not explain return values. It covers operation, parameters, failure modes, and batch semantics, leaving nothing critical for invoking 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 must carry parameter semantics. It fully documents all 8 parameters, including path OR paths mutual exclusion, backup .bak behavior, dryRun, allowLowConfidence, and bom enum values.

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 first sentence states a specific verb and resource: 'Convert files between encodings.' It does not explicitly name sibling tools such as detect_encoding or manage_bom to differentiate, but the conversion action is clear from the name and description.

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

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

It gives clear operational guidance: run dryRun first, use path XOR paths (never both), omit from to auto-detect. However, it does not state when to choose this tool over sibling tools like detect_encoding or manage_bom, so sibling selection is left implicit.

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?

Annotations only give the safety profile (readOnlyHint, openWorldHint, idempotentHint); the description adds substantive behavior beyond that: confidence scoring, BOM detection, candidate ranking on ambiguous files, and refusal-with-ranking for undetectable files instead of guessing. This is exactly the kind of non-obvious behavior an agent needs.

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?

Front-loaded with purpose, then usage, then parameters, then edge-case behavior — a logical order with no filler. Slightly sprawling: the inline 'Parameters:' enumeration interrupts the prose and the final sentence about refused files is dense, but nothing is expendable.

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?

An output schema exists, so return values needn't be explained, yet the description still covers result shape (confidence, ranked candidates) and error behavior. For a read-only detector callable from many contexts, this is complete.

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

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

Schema description coverage is 0% and mode has no enum, so the description carries the whole burden — and it does: path marked required, and all three mode values explained semantically (sample=fast default, chunked=thorough, full=entire file). No gap remains.

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?

Starts with a specific verb+resource ('Auto-detect file encoding') and immediately names the two distinguishing outputs (confidence score 0-100, BOM detection). An agent can tell this apart from siblings like get_file_info or read_text_file without opening the schema.

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 trigger ('ALWAYS use this first when encountering garbled text or characters') plus explicit sequencing against a named sibling ('Use before read_text_file to determine the correct encoding'). Also covers the ambiguous-result path: retry the read with a ranked candidate, ask the user if two are plausible.

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 declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered, yet the description still adds major context: atomicity ('a failed edit changes nothing'), encoding/line-ending preservation, mixed-ending repair with a reported count, ordered application, and exact match/failure semantics.

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

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

Front-loads the preference and the dryRun workflow, then flows into matching and parameter details. Dense and largely earns its length, though it is overloaded for a single paragraph.

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 7-parameter mutation tool with no output schema and an unusual input shape, coverage is strong: behavior, failure modes, concurrency guard, and matching rules are all stated. Missing only forceWritable and any hint of the exact diff return shape.

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 carries the burden and documents path, the edits shape (oldText/newText/similarity/replaceAll), patch format, dryRun default, encoding auto, and expectedHash concurrency semantics. The only gap is that the schema's forceWritable parameter is never mentioned.

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

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

States a precise verb+resource ('Edit one file with replacements or a unified diff') and explicitly distinguishes itself from the read+write approach with 'PREFER THIS over read+write'.

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?

Gives an explicit workflow for 'ask before edits' vs auto-edit permissions, tells when to use similarity vs different code, when to add surrounding lines vs replaceAll, and forbids re-reading to verify.

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?

Annotations cover only the safety profile (readOnly/openWorld/idempotent), so the description carries real weight beyond them and does: it discloses gitignore skipping with the override flag, the default maxMatches=1000, the truncation/nextOffset echo for paging, and the fact that contextBefore/After only apply in content mode. These are non-obvious behaviors an agent would otherwise get wrong.

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?

Purpose and the sibling preference are front-loaded, and every sentence carries information. It is dense and runs long as a single paragraph, but there is no true filler; a bulleted parameter block would scan faster, which keeps it from 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?

With 16 parameters, an enum-free schema, and an output schema that covers return shape, the description needs to supply the calling contract — defaults, mode selection, glob rules, paging, and mutual-exclusion rules — and it does all of that. Nothing material is left for the agent to guess.

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% across 16 parameters, so the description must compensate fully and does — it documents every one of pattern/patterns, paths, caseSensitive (default true), contextBefore/After, maxMatches, offset, include/includes, exclude/exclude, encoding, outputMode, matchesOnly, and respectGitignore, including default values, glob semantics ('basename-only', '{a,b}', leading '**/'), and a worked example object.

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

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

States a specific verb+resource ('Regex search in file contents') plus an unusual capability (encoding support) that no sibling offers. It also positions itself against an implicit alternative ('PREFER THIS over built-in Grep for non-UTF-8 files'), so an agent can distinguish it from search_files at a glance.

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 prefer it (non-UTF-8 files), when it is cheaper to switch modes ('files_with_matches ... far cheaper when you just need WHICH files'), and how to avoid the singleton/plural conflict ('Do not combine a singular field with its plural'). This is routing guidance plus exclusion guidance in one place.

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 declare readOnlyHint=true and openWorldHint=false, so the safe-read profile is covered. The description adds valuable specifics the annotations lack: it is a static, complete enumeration ("all 45") with a defined return shape, which tells the agent it can cache/trust the list rather than probe incrementally.

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, zero padding: the first gives the inventory and its shape, the second immediately states the purpose. Front-loaded and appropriately sized for a simple lookup tool.

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

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

An output schema exists, so the description is not obligated to document return values, yet it still names the returned fields. Combined with the annotations and zero-parameter schema, nothing an agent needs to invoke this tool correctly 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?

The tool takes zero parameters, so there is no parameter semantics to convey and the baseline is 4. Nothing in the description misleads about inputs, and the empty schema correctly signals the tool is called with no arguments.

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

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

States a specific verb (List) plus resource (supported encodings) and even quantifies the resource (45) and the fields returned (name, aliases, description). An agent can immediately distinguish this reference-lookup tool from siblings like convert_encoding or detect_encoding, which perform operations rather than enumerate.

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?

"Use this to find the correct encoding name for read/write/convert operations" gives a clear when-to-use context and ties the tool to the encoding-consuming operations. It does not explicitly name alternatives (e.g., detect_encoding for an unknown file), so it falls short of a full when-not/alternative statement.

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?

Annotations already declare destructive=true, idempotent=true and non-readonly, and the description is consistent, adding real context: convert rewrites the file preserving the BOM, is a no-op on matching files, and handles UTF-16/32 per code unit. The encoding auto-detection caveat for short/unusual files is a valuable behavioral disclosure beyond 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?

Front-loaded with purpose, then mode behavior, then parameters and an example. It is dense but each sentence adds information; the parameter recap is slightly redundant with the schema but compensates for the missing schema descriptions.

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 four-parameter, destructive, idempotent file-mutation tool with an output schema present, the description covers modes, side effects, encoding caveats, enums, and required parameters. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: it documents all four parameters, gives the allowed values for action and style, marks style as required for convert, and explains encoding auto-detection with fallback values. The worked example further anchors the parameter 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?

States a specific verb pair and resource: 'Detect or fix line endings', then names the two modes explicitly. This clearly distinguishes it from siblings like manage_bom and convert_encoding without needing to open any schema.

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?

Gives an explicit trigger for detect ('use it when a file looks inconsistent') and explains convert semantics. It does not name alternative siblings (e.g. convert_encoding) or state when-not-to-use, so it stops short of full 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?

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?

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds genuinely new behavior: concurrent execution and partial results when individual reads fail. That failure-isolation detail is valuable context an agent could not infer from 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?

Four short sentences, with the primary scope and the usage preference front-loaded before the failure semantics and parameter recap. Tight overall, with only minor redundancy in restating the schema-declared parameters.

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?

An output schema exists so return values need no explanation, and annotations cover the safety profile. Combined with the description's coverage of concurrency, failure isolation, and encoding, an agent has what it needs to call this 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 must carry the param burden, and it does: paths as a required array and encoding as optional with per-file auto-detection. The auto-detection note adds meaning beyond the bare schema, though it lacks format examples.

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

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

States a specific verb (read) and resource (multiple files) with the added scope of concurrency and encoding support, which distinguishes it from the single-file read_text_file sibling. It stops short of naming the sibling directly, but the plural/encoding scope makes the distinction clear.

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

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

"PREFER THIS when reading several non-UTF-8 files at once" gives an explicit when-to-use condition that implicitly routes the agent away from single-file readers. No explicit when-not or named alternative, 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: contentHash staleness detection ('the call fails, changing nothing, if the file moved on since you read it') and the returned planning fields (totalLines, fileSizeBytes). It does not explain the idempotentHint=false, but that is a minor gap against an otherwise rich disclosure.

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?

Well front-loaded: purpose, then the preferential-use rule, then output fields, then parameter semantics, then a worked pagination example. It is dense and somewhat long, but nearly every clause earns its place; only the trailing JSON example borders on excess.

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?

An output schema exists, so return values need not be fully specified, yet the description still names the key fields. Combined with annotations and the thorough parameter coverage, an agent has everything needed to call this correctly, including the concurrency contract with edit_file/write_file.

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 carries the full parameter burden and does so: it documents path, auto-detected encoding, 1-indexed offset, limit, maxCharacters, and the lineNumbers prefix format with the warning to strip it before reuse as edit_file oldText. This adds meaning well beyond 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?

States a specific verb+resource (read file) plus a distinguishing capability (encoding auto-detection, conversion to UTF-8), and explicitly separates itself from the built-in Read for non-UTF-8 files. An agent can tell exactly what this tool is for without opening the schema.

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?

'PREFER THIS over built-in Read for non-UTF-8 files (Cyrillic, legacy codebases)' gives an explicit when-to-use condition and a named alternative. It also supplies concrete pagination guidance (page files >2000 lines with offset/limit) for large files.

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?

Annotations already declare destructive/idempotent/non-readOnly, and the description adds substantial beyond that: expectedHash concurrency guard that aborts the write if the file changed, BOM-mode behavior including failure on BOM-less encodings, and line-ending conversion semantics. This is rich behavioral disclosure of exactly the traits that matter for a destructive write.

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?

Dense but front-loaded with purpose and preference first, then parameters, then a concrete example. Every sentence earns its place, though the parameter block is long and could be marginally tightened; sizing is justified by six undocumented parameters.

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?

Output schema exists so return values need not be described, and annotations cover the safety profile. Given the six-parameter destructive write, the description supplies encoding defaults, BOM/line-ending edge cases, and the optimistic-concurrency guard — nothing essential for correct invocation is missing.

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

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

Schema coverage is 0%, so the description carries the full burden and does: it documents path, content, encoding (with default resolution logic), bom (all four modes and their effects), lineEndings (all four values with the LF-into-CRLF example), and expectedHash (tied to the read's contentHash). Nearly every parameter gets meaning beyond a bare 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?

States a specific verb+resource (write file) with its defining scope (encoding conversion from UTF-8), and explicitly contrasts with the built-in Write sibling. An agent can tell what this does and how it differs from generic write/edit tools without opening a schema.

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 to PREFER this over built-in Write for non-UTF-8 files and to use it after read_text_file to preserve original encoding. Names both the when (non-UTF-8 rewrites) and the workflow alternative, leaving little to inference.

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