Server Quality Checklist

Tool Scores

• copy_pathB
  3.1/5.0
  Behavior2/5

  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 mentions the default recursive behavior for directories, which is useful, but lacks critical details such as permission requirements, error handling (e.g., what happens if source doesn't exist or destination already exists), side effects, or whether it overwrites files. For a mutation tool with zero annotation coverage, this is a significant gap.

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

  Conciseness4/5

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

  The description is concise and front-loaded, with two sentences that efficiently convey the core action and a key behavioral trait. There's no wasted text, though it could be slightly more structured (e.g., separating purpose from guidelines).

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

  Completeness2/5

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

  Given the complexity of a file system mutation tool with no annotations and no output schema, the description is incomplete. It lacks information on permissions, error conditions, return values, and how it interacts with sibling tools. The description alone doesn't provide enough context for safe and effective use.

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

  Parameters3/5

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

  The schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema by reiterating that paths can be relative or absolute and noting the default recursive behavior, but doesn't provide additional syntax, format, or semantic details. Baseline 3 is appropriate when the schema does the heavy lifting.

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

  Purpose4/5

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

  The description clearly states the tool's purpose: 'Copies a file or directory to a new location.' It specifies the verb ('Copies') and resource ('file or directory'), but doesn't explicitly differentiate from sibling tools like 'move_path' or 'write_file' beyond the inherent meaning of 'copy' versus 'move' or 'write'.

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

  Usage Guidelines3/5

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

  The description provides some implied usage context by mentioning 'Defaults to recursive copy for directories,' which suggests when to use default behavior. However, it doesn't explicitly state when to choose this tool over alternatives like 'move_path' or 'write_file,' nor does it mention prerequisites or exclusions.

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

• create_directoryB
  3.2/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that the tool can fail if parent directories are missing (when create_parents is false) and supports relative/absolute paths, but doesn't cover critical aspects like permissions needed, error handling, or whether it overwrites existing directories. For a mutation tool with zero annotation coverage, this leaves significant gaps.

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

  Conciseness5/5

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

  The description is extremely concise with three short sentences that each add value: the core action, the parent directory feature, and path flexibility. There is no wasted text, and it's front-loaded with the primary purpose.

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

  Completeness2/5

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

  For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what happens on success (e.g., returns the created path), error conditions beyond missing parents, or permissions required. Given the complexity of filesystem operations and lack of structured safety hints, more behavioral context is needed.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema fully documents both parameters. The description adds minimal value by restating that paths can be relative or absolute (already in schema) and hinting at parent directory creation (implied by create_parents). It doesn't provide additional syntax, format, or usage details beyond what the schema offers.

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

  Purpose5/5

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

  The description clearly states the specific action ('Creates a directory') and distinguishes it from siblings like 'delete_directory' or 'list_files' by focusing on creation. It also adds nuance about parent directory creation, which further differentiates it from simple file operations.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives like 'write_file' for creating files or 'set_filesystem_default' for configuration. It mentions optional parent directory creation but doesn't explain when to enable or disable this feature in practice.

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

• move_pathB
  3.2/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action but doesn't cover critical aspects like whether it overwrites existing files, requires permissions, handles errors, or affects file metadata. This leaves significant gaps for a mutation tool.

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

  Conciseness5/5

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

  The description is a single, efficient sentence that front-loads the core action and key parameter feature. Every word contributes meaning without redundancy, making it appropriately sized and well-structured.

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

  Completeness2/5

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

  For a mutation tool with no annotations and no output schema, the description is incomplete. It lacks details on behavioral traits (e.g., overwrite behavior, error handling), usage context, and return values, leaving the agent with insufficient information for reliable invocation.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema fully documents both parameters. The description adds minimal value by reiterating that paths can be relative or absolute, but doesn't provide additional syntax, format, or usage details beyond what the schema already specifies.

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

  Purpose5/5

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

  The description clearly states the specific action ('Moves or renames') and resource ('a file or directory'), distinguishing it from siblings like copy_path (copies) or delete_file (deletes). It precisely defines the tool's function without being vague or tautological.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives like copy_path or update_file, nor does it mention prerequisites or exclusions. It lacks context for selection among similar file operations.

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

• delete_directoryB
  3.3/5.0
  Behavior2/5

  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 mentions the recursive option and path types, but lacks critical details such as permission requirements, whether deletion is irreversible, error handling (e.g., for non-existent paths), or side effects. For a destructive tool with zero annotation coverage, this is a significant gap.

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

  Conciseness4/5

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

  The description is appropriately sized with two sentences that are front-loaded and efficient. The first sentence states the core action, and the second adds necessary context about recursion and path types, with zero wasted words.

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

  Completeness2/5

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

  Given the tool's destructive nature, lack of annotations, and no output schema, the description is incomplete. It should address risks (e.g., irreversible deletion), permissions, or error responses to help an agent use it safely. The current description leaves too many behavioral aspects unspecified for a tool that modifies the filesystem.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already documents both parameters (path and recursive) with clear descriptions. The description adds minimal value by repeating that paths can be relative or absolute and hinting at recursive behavior, but doesn't provide additional syntax or format details beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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

  Purpose5/5

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

  The description clearly states the tool's purpose with a specific verb ('Removes') and resource ('a directory'), distinguishing it from sibling tools like delete_file (which removes files) and create_directory (which creates directories). The description provides unambiguous action and target.

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

  Usage Guidelines3/5

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

  The description implies usage through the mention of 'Optionally removes recursively,' suggesting when to use the recursive parameter, but it doesn't explicitly state when to choose this tool over alternatives like delete_file or provide exclusions (e.g., when not to delete system directories). No named alternatives or clear context for tool selection are provided.

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

• delete_fileA
  3.6/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action is destructive ('Removes') but fails to mention critical behaviors: whether deletion is permanent or reversible, any permission requirements, error handling (e.g., for non-existent files), or side effects. This leaves significant gaps for a destructive operation.

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

  Conciseness5/5

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

  The description is extremely concise—two sentences that directly state the tool's purpose and parameter acceptance. Every word serves a purpose, with no redundancy or unnecessary elaboration, making it easy to parse and understand quickly.

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

  Completeness2/5

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

  Given the tool's destructive nature and lack of annotations or output schema, the description is incomplete. It doesn't address key contextual aspects: the permanence of deletion, permission requirements, error responses, or what happens upon success. For a mutation tool with significant behavioral implications, this leaves too much unspecified.

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

  Parameters4/5

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

  The schema description coverage is 100%, so the schema already documents the single parameter 'path' with details on format and resolution. The description adds minimal value by restating that it 'Accepts relative or absolute paths,' which is already covered in the schema. With only one parameter, the baseline is high, but the description doesn't enhance understanding beyond the schema.

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

  Purpose5/5

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

  The description clearly states the specific action ('Removes') and target resource ('a specific file'), distinguishing it from siblings like delete_directory (which removes directories) or move_path (which relocates files). It precisely communicates the tool's function without ambiguity.

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

  Usage Guidelines3/5

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

  The description implies usage for file deletion but provides no explicit guidance on when to use this tool versus alternatives like move_path (for relocation) or delete_directory (for directory removal). It lacks context about prerequisites (e.g., file existence, permissions) or exclusions, leaving usage decisions to inference.

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

• list_filesA
  3.7/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context about recursive listing and output limiting, but doesn't cover important aspects like error handling, permission requirements, performance implications for large directories, or what the return structure looks like. It's adequate but has clear gaps for a read operation tool.

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

  Conciseness5/5

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

  The description is efficiently structured in three sentences that each add value: stating the core purpose, explaining optional recursive behavior, and detailing the maxEntries parameter. There's no wasted language or redundancy, making it easy to parse quickly.

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

  Completeness3/5

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

  For a read-only tool with no output schema and no annotations, the description provides basic operational information but lacks details about return format, error conditions, or performance characteristics. It's minimally viable but doesn't fully compensate for the missing structured metadata that would help an agent understand the complete behavior.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description mentions the maxEntries parameter and its default, and implies recursive functionality, but doesn't add significant meaning beyond what the schema provides. This meets the baseline for high schema coverage.

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

  Purpose5/5

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

  The description clearly states the specific action ('Lists files and directories') and resource ('within the specified directory'), distinguishing it from siblings like copy_path, delete_file, or read_file that perform different operations on files. It precisely communicates the tool's function without being vague or tautological.

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

  Usage Guidelines3/5

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

  The description implies usage for listing directory contents but doesn't explicitly state when to use this tool versus alternatives like read_file or other file operations. It mentions optional parameters but provides no guidance on scenarios where this tool is preferred over others or any prerequisites for use.

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

• read_fileA
  4/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden. It discloses that the tool reads files as UTF-8 and handles path resolution, but it does not mention error conditions beyond the relative path case, performance implications for large files, or return format details. It adds some behavioral context but leaves gaps.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose in the first sentence, followed by essential usage details in the second. Both sentences earn their place by providing critical information without waste, making it highly efficient and well-structured.

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

  Completeness4/5

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

  Given the tool's low complexity (one parameter, no output schema, no annotations), the description is mostly complete. It covers the purpose, usage, and path semantics adequately, but it lacks details on return values (e.g., text content format) and error handling, which would be beneficial for full completeness.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already fully documents the single parameter. The description adds no additional meaning beyond what the schema provides about the path parameter, such as examples or edge cases. Baseline 3 is appropriate as the schema does the heavy lifting.

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

  Purpose5/5

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

  The description clearly states the specific action ('Reads the entire content') and resource ('of a specified file'), with additional details about encoding ('as UTF-8 text') that distinguish it from siblings like write_file or update_file. It precisely defines what the tool does without being tautological.

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

  Usage Guidelines4/5

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

  The description provides clear context about when to use this tool by explaining path resolution rules and referencing set_filesystem_default, but it does not explicitly state when not to use it or name alternatives (e.g., list_files for metadata). The guidance is helpful but lacks explicit exclusions.

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

• set_filesystem_defaultA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden and does well by disclosing key behavioral traits: it sets a session-scoped default, affects other tools, and clears on server restart. However, it lacks details on permissions, error handling, or validation of the path.

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

  Conciseness5/5

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

  The description is appropriately sized and front-loaded, with two sentences that efficiently convey purpose and behavior without wasted words, making it easy for an agent to parse quickly.

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

  Completeness4/5

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

  Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is mostly complete, covering purpose, usage, and key behavior. However, it could benefit from mentioning error cases or interactions with specific sibling tools for full context.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already documents the 'path' parameter thoroughly. The description adds no additional meaning beyond what the schema provides, such as format examples or constraints, meeting the baseline for high coverage.

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

  Purpose5/5

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

  The description clearly states the tool's purpose with specific verbs ('Sets a default absolute path') and resource ('for the current session'), and distinguishes it from siblings by explaining its unique role in resolving relative paths for other filesystem tools like readFile.

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

  Usage Guidelines4/5

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

  The description provides clear context on when to use this tool (to set a default path for resolving relative paths in other filesystem tools) and mentions the session scope, but does not explicitly state when not to use it or name specific alternatives among siblings.

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

• write_fileA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries full burden and discloses key behaviors: it creates files/directories if missing, overwrites existing files, and resolves paths similarly to readFile. It does not mention permissions, error handling, or rate limits, but covers core mutation traits adequately.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose, followed by essential behavioral details in two concise sentences. Every sentence adds value without redundancy, making it efficient and well-structured.

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

  Completeness4/5

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

  For a mutation tool with no annotations and no output schema, the description provides good context on behavior and parameters. It could be more complete by mentioning error cases or return values, but it adequately covers the tool's functionality given the structured data available.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema fully documents both parameters. The description adds minimal value beyond the schema, only reiterating overwrite behavior for 'content' and path resolution for 'path', aligning with the baseline for high schema coverage.

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

  Purpose5/5

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

  The description clearly states the verb 'writes' and the resource 'content to a specified file', specifying both creation and overwrite behaviors. It distinguishes from siblings like read_file (read-only), update_file (partial updates), and delete_file (removal).

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

  Usage Guidelines4/5

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

  The description implies usage for writing or creating files, with context on path resolution and directory creation. However, it lacks explicit guidance on when to use this versus alternatives like update_file (for partial updates) or create_directory (for directories only), and no exclusions are stated.

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

• update_fileA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it modifies existing files (implies mutation), requires the file to exist, supports path resolution, and mentions optional parameters with defaults. It doesn't explicitly mention error handling or permissions requirements, but covers most operational aspects.

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

  Conciseness5/5

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

  The description is efficiently structured with zero waste: first sentence states core purpose, second provides usage guidance, third covers path handling and prerequisites, fourth explains optional parameters. Every sentence earns its place and information is front-loaded appropriately.

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

  Completeness4/5

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

  For a mutation tool with no annotations and no output schema, the description does well by covering purpose, usage context, prerequisites, and parameter overview. It could be more complete by mentioning what happens on success/failure or typical return values, but given the schema's 100% coverage and clear behavioral disclosure, it's mostly adequate.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already fully documents all 4 parameters. The description adds minimal value beyond the schema - it mentions the 'blocks' parameter structure and the optional boolean parameters, but doesn't provide additional semantic context. Baseline 3 is appropriate when schema does the heavy lifting.

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

  Purpose5/5

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

  The description clearly states the tool performs 'targeted search-and-replace operations within an existing file' using specific data structures. It distinguishes from sibling tools like 'write_file' by specifying it's for 'smaller, localized changes' rather than large-scale overwrites.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance: 'Preferred for smaller, localized changes' and 'For large-scale updates or overwrites, consider using `write_file`.' It also states prerequisites: 'File must exist' and 'Accepts relative or absolute paths.' This gives clear when-to-use and when-not-to-use criteria.

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