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

No annotations provided, but description clearly conveys a read-only operation (returns usage guide). No misleading or missing behavioral traits given its simple nature.

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

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

Two sentences plus bullet list; no wasted words. Front-loaded with purpose. Could be slightly improved by aligning topic list with schema.

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 help tool with one parameter and no output schema, the description adequately covers purpose and usage. Does not explain default topic behavior but schema covers it.

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

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

Schema has 100% coverage for the single parameter. Description adds list of topics but is incomplete compared to schema's enum-like list (missing memtool, wintool, etc.). Adds marginal value beyond 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?

Clearly states it returns usage guide for agent-tool, with specific verb and resource. Distinguishes from sibling tools like analyze or debug by focusing on help for the tool itself.

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 when to call (encoding warnings, garbled text, need to understand features). Lacks explicit when-not or alternatives, but context is clear.

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

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

With no annotations, the description carries the full behavioral burden, and it delivers: smart indentation conversion, encoding preservation across multiple encodings, CRLF/LF-insensitive matching, newline-style preservation in mixed files, .editorconfig awareness, and a dry-run preview mode. It lacks disclosure of failure/error behavior and return semantics, but the non-obvious mutation-safety traits are well detailed.

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?

Six sentences with the core purpose front-loaded and each subsequent sentence earning its place by disclosing a distinct, non-obvious behavior (indentation, encoding, line endings, editorconfig, dry-run). It is longer than average, but nearly every sentence prevents a real-world correctness bug.

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 10-parameter tool with no output schema, the description covers behaviors well but leaves gaps: it never states what a successful call returns, what happens when old_string is not found or ambiguous, or how replace_all/expected_hash/indent_style interact behaviorally. Core editing semantics are covered; edge and result semantics are 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 100%, so all 10 parameters are already documented (including aliases, replace_all, indent_style, and expected_hash). The description adds no parameter-level meaning beyond what the schema provides; it revisits dry_run but without new information. Baseline 3 applies.

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: 'Replaces old_string with new_string in the specified file.' This identifies a targeted in-file substitution and separates it from read/write-style siblings. However, it does not explicitly differentiate itself from the similarly named siblings patch and multiedit, so it stops short of a 5.

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

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

The description gives no guidance on when to choose edit over siblings such as patch, multiedit, or write, and no exclusions or alternative conditions. The only usage hint is 'Use dry_run=true to preview changes,' which is a safety option rather than a selection rule.

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?

Since no annotations are provided, the description fully carries the burden of explaining behavior. It discloses result ordering by modification time, default pagination limits, hidden and generated directory skipping, and the metadata/cursor shape, giving rich insight beyond mere function naming.

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 tight and front-loaded: the core purpose appears first, followed by behavioral specifics and return metadata. Every sentence conveys necessary information without redundancy or filler.

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

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

For a read-only file discovery tool with eight parameters and no output schema, the description covers key operational behaviors: recursive matching, sorting, defaults, path skipping, pagination metadata, and cursor semantics. The agent has enough information to invoke the tool correctly and interpret the result.

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 100%, so each parameter is already documented in the input schema. The description adds useful context such as 'supports ** recursive matching' and default behaviors, but it does not meaningfully enhance per-parameter semantics beyond the schema.

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

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

The description opens with a specific verb and resource: 'Finds files matching a glob pattern.' This clearly communicates the tool's core function and differentiates it from siblings like listdir and grep by focusing on pattern-based file discovery.

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

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

The description gives clear context for when to use the tool: when matching files with glob patterns. It does not explicitly name alternative tools or provide when-not guidance, but the purpose is clear enough for an agent to select it over simpler directory listing tools.

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

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

With no annotations supplied, the description fully carries the behavioral burden and does so thoroughly. It discloses encoding detection, CRLF/CR line-ending semantics, output modes and their defaults, context behavior, binary-file skipping and the exception when passed directly, and large-result continuation behavior through has_more. These are exactly the non-obvious behaviors an agent needs to predict side effects and output.

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

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

The description is long but densely packed with useful, non-redundant information. It leads with the main action, then systematically covers output modes, edge cases, context, large results, and binary handling. Every sentence provides behavioral or parameter knowledge that would be hard to discover from the schema alone, earning its place.

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

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

Given the 18 parameters, high schema coverage, and no output schema, the description is exceptionally complete. It explains result-limiting and pagination-related behavior (has_more, max_output_chars, continuation), which is crucial for an agent calling a search tool that may return a lot of text. It also covers boundary-case semantics like CRLF and binary files, making the tool surprisingly predictable without an output schema.

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 100%, so the baseline is 3, but the description adds genuinely useful parameter semantics beyond the schema, including 'like grep -B/-A/-C' for context terms, the default compact output format versus output_format=classic, binary-file bypass when path points directly to a file, and the max_results/max_line_chars/max_output_chars caps. This helps agents understand how parameters combine without inspecting JSON 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?

The description opens with the specific verb-resource pair 'Searches file contents for a regex pattern,' which precisely identifies what the tool does and differentiates it from siblings like read, glob, and listdir. It further clarifies scope ('single file or recursively search a directory') and output modes, leaving no ambiguity about the tool's purpose.

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

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

The description gives clear context for using the tool: when searching file contents by regex, by file or directory, with context-line behavior, and with binary-file handling. It does not explicitly name alternatives or state 'use this instead of X,' but the purpose is concrete enough that an agent can infer when to select grep over read/glob/listdir. The reference to 'same as read' subtly ties behavior to a sibling tool, adding 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?

With no annotations, the description carries the full burden and does a good job: it discloses pagination mechanics, skip behavior for hidden/build/vendor entries, the flat/tree distinction, counting mode, and token-saving relative paths. It does not describe the exact response fields, but it mentions has_more and next_cursor sufficient to drive pagination.

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?

Each sentence carries a distinct responsibility: definition, defaults, pagination, filtering, output modes, skipped entries. There is no filler or repetition, and key information is front-loaded.

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

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

The description covers defaults, pagination, filtering, output modes, and behavioral exclusions, which is a solid level of context. Since there is no output schema, the only minor gap is omitted return record shape, but the provided behavior is enough for a capable agent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds relationship semantics beyond the schema: pagination binds has_ more to the cursor parameter, name_pattern versus include as single/multi OR patterns, and counts_only relative_paths as output modifiers. These are not obvious from names alone.

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 directory contents' and immediately adds the defining scope: bounded, pageable output. This is a specific verb plus resource and distinguishes the tool from siblings like read, write, and grep, even before 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?

The description gives practical usage guidance: paginate with cursor when has_more=true, filter with directories_only/files_only, and use counts_only or relative_paths for optimization. It does not explicitly tell an agent when to prefer listdir over sibling tools like glob, but the tool's 'list directory contents' purpose implies the 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?

No annotations are provided, so the description carries the full burden, and it does this well. It discloses sequential application, atomic rollback on any failure, encoding preservation, CRLF/LF line-ending awareness, and alias support. These are meaningful behavioral characteristics beyond what the schema shows and are critical for correct agent use.

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?

Each sentence earns its place: core function first, then ordering, atomicity, encoding, line endings, alias, and dry-run. It is detailed but compact, and the most important operational facts are front-loaded before the alias and dry-run notes.

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 multi-edit file mutation tool with no annotations and no output schema, this description is unusually complete: it tells the agent what action, in what order, with what safety guarantees, and how to preview. Return format is not described, but the invocation-relevant behavior is covered thoroughly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that old_string matching is encoding- and line-ending-aware, that newlines in inserted text follow the edited region, that path is an alias for file_path, and that dry_run preveview changes. This supplements the schema rather than restating it.

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

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

The description states a specific action ('Applies multiple old_string -> new_string replacements to a single file'), includes the precise edit primitive, and differentiates itself from siblings like edit by emphasizing multiple replacements, sequential application, and atomicity. An agent can clearly understand what the tool does and roughly how it differs from single-edit or patch alternatives.

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

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

It provides clear use-context: a single file with many ordered replacements, plus a dry_run option for previewing. It does not explicitly name sibling alternatives or state when not to use it, but the description makes the intended scenario obvious and includes an actionable preview-first workflow.

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

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

No annotations exist, so the description carries the full behavioral burden. It discloses encoding auto-detection, default line and character budgets, truncation metadata with continuation positions, per-file error isolation, and the 50-file cap. This is unusually transparent for a tool with no annotation support.

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?

Every sentence contributes a distinct behavior or usage constraint: purpose, encoding, line/character limits, per-file modes, failure handling, and max file count. It is dense but not bloated, and the most important fact is front-loaded.

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

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

For a tool with 9 parameters, no annotations, and no output schema, the description is remarkably complete. It covers defaults, limits, semantics, file failure handling, encoding behavior, and truncation continuation positions, leaving an agent with the practical knowledge needed to invoke it and interpret its results.

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 already covers 100% of parameters, so the baseline is 3. The description adds value by tying parameters to usage modes: global offset/limit vs per-file files entries, the interaction of all=true with the total character budget, and the 50-file request cap not visible in the schema. These aggregates help an agent pick the right parameter shape.

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

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

The description opens with a specific verb and resource: 'Reads multiple files in a single call to reduce API round-trips.' This immediately distinguishes it from the single-file 'read' sibling and clearly states the batching purpose.

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

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

The description provides strong contextual guidance: use the tool for reading multiple files efficiently, choose global file_paths/paths vs per-file files objects depending on offset/limit needs, and understand failure/encoding/limit behavior. It does not explicitly name the single-file 'read' tool as the alternative, but the multiple-vs-single distinction 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?

The description directly contradicts the provided annotations: it says the tool 'applies changes' and can modify a file, while annotations mark readOnlyHint=true and destructiveHint=false. This is an annotation contradiction, which forces the lowest score regardless of the strong encoding and line-ending details.

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

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

The description is concise and well-structured: it front-loads the primary action, then adds useful encoding/line-ending behavior, and ends with an actionable dry-run usage. Every sentence contributes unique information.

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

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

The tool description covers the behavioral full picture: diff format, context verification, encoding preservation, line-ending behavior, and dry-run safety. The confusing annotation contradiction prevents a 5, but as a standalone spec it is nearly complete.

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

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

The input schema already describes all four parameters clearly, including patch, dry_run, and the path aliases. The description adds little beyond restating that dry_run previews without modifying, so baseline 3 applies.

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 starts with a precise verb-resource pair: 'Applies a unified diff patch to a file.' It further clarifies behavior with hunk parsing and context verification, making it clearly distinct from nearby siblings like edit, write, or multiedit.

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 a clear use-case: applying unified diff output to a file, with dry_run for preview. It does not explicitly contrast with edit or write, but the diff-specific framing makes the correct context fairly obvious.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It covers encoding detection, binary-image base64 output, SVG as text, default text limits, truncation reporting, negative-offset semantics, path resolution, and concurrency hash inclusion. This is unusually transparent for a tool with no 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 long but front-loaded with the core purpose, and nearly every sentence adds distinct behavioral detail for a complex 10-parameter tool. Some information, such as the path alias and default limits, overlaps with schema fields, but the density is justified because there is no other documentation.

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 no output schema, the description explains the return shape concretely: line numbers, base64 ImageContent for images, SVG as text, and text results annotated with total line count, truncation state, and next_offset. Combined with the schema's full parameter descriptions, this gives an agent everything needed to correctly invoke and use the function.

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 already documents all parameters at 100% coverage, but the description adds meaning through examples and combination rules, such as offset=-5, offset/limit continuation, and the explicit interpretation of 'all' and max_output_chars. It does not simply repeat the schema word-for-word, though some redundancy exists with the offset and alias descriptions.

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

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

The description opens with a specific verb and resource: 'Reads a file and returns its contents with line numbers.' It also distinguishes itself from siblings by emphasizing single-file reads, image/SVG handling, and encoding detection, so an agent can differentiate it from multiread, edit, and other siblings without inspecting schemas.

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

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

The description gives rich operational context, such as using offset/limit to continue and negative offsets to read from the end, and it explains parameter aliases. However, it never explicitly says when to choose this tool over alternatives like multiread or grep, and there is no exclusion or routing guidance. Usage is implied rather than directly stated.

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

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

With no annotations available, the description carries the full burden, and it delivers. It discloses output expiration ('expire after 30 minutes'), bounded output size with paging ('next_offset'), and the enable/program behavior. The 'even when the MCP client ignores the raw tool list' statement adds infra-level transparency. The description does not fully disclose all safety or side-effect nuances of call/enable/disable, but it is far beyond a minimal 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 has a clear, structured format: a purpose sentence, then one per operation, and then the profiles. Every sentence adds new operational detail; no filler. Front-loaded with the core actiom, and compact despite covering many features.

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

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

Given no output schema, seven operations, and nine parameters, the description covers each operation with its relevant parameters, paging / workspace / expiry behavior. It also explains the 'profiles' concept and provides a list of all profiles. The only small missing pieces are explicit return shapes for describe/call, but the description already hints that 'output' returns captured raw output and the gateway is otherwise well explained.

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?

Even though the schema covers 100% of parameters with descriptions, this plumbing meaningfully supplements that. It maps operation arguments to parameters (e.g., 'output_id', 'output_offset', 'therapy'), explicitly tells the agent to 'Use operation=describe first when the schema is any', lists profiles, and 'large records report next_offset' enriches semantics. This is more than baseline schema coverage.

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

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

The description opens with a specific verb+resource account: 'Discover and call any AgentTool capability without loading every tool schema into the model context.' It clearly identifies this as a gateway/dispatcher distinct from the concrete sibling tools (read, edit, grep, etc.), and gives a compact summary of what it provides.

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 is spelled out operation by operation: 'Use operation=describe... then... operation=call...', 'Use operation=output...', and 'Use operation=list...' It even adds a strong preference note: 'Prefer describe/call because they work even when the MCP client ignores dynamic tool-list changes.' Missing an explicit when-not-to-use or direct comparison to the sibling tools, but the intended gateway use case is clear.

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

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

With no annotations, the description carries the transparency burden, and it handles it well: it discloses overwriting behavior, encoding preservation, editorconfig usage for new files, and automatic creation of parent directories. It doesn't describe return values or error conditions, but the core behavioral risks are covered.

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

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

The description is three short sentences, each carrying distinct useful information: core write behavior, encoding behavior, and directory behavior. It is front-loaded with the main operation and contains no filler.

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

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

For a simple write tool with no output schema and no annotations, the description covers the essential input semantics (content, path), the destructive write behavior, and the main edge cases (encoding and parent directories). It could mention return values or error handling, but an agent has enough to call and 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?

The schema already documents all three parameters with descriptions, and schema description coverage is 100%, so the description is not required to add parameter-level detail. The description provides useful global context about encoding and parent directory behavior, but not parameter-specific semantics beyond the schema.

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

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

The description states a specific operation: 'Creates or overwrites a file with the given content', making clear this is a full-file write. It is distinguished from sibling tools like edit or patch by the overwrite semantics, though it doesn't explicitly name those alternatives.

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 primary usage is clear: use this tool when creating a new file or fully replacing existing content. However, there is no explicit guidance about preferring edit or patch for targeted modifications, so the routing decision is implied rather than stated.

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