Server Quality Checklist

Tool Scores

• list_directoryA
  3.9/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 describes the behavior (listing files/directories with specific metadata) and output format, but doesn't disclose important traits like whether it requires specific permissions, handles symbolic links, has pagination for large directories, or error conditions (e.g., invalid paths). The description adds value 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 appropriately sized (two sentences) and front-loaded with the core purpose. Every sentence earns its place: the first states what the tool does and what information it returns, the second provides usage context. Zero waste.

  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?

  Given the tool's moderate complexity (directory listing with metadata), no annotations, and no output schema, the description is adequate but has clear gaps. It explains the purpose and output format well, but lacks details on behavioral traits (permissions, error handling, etc.) that would be needed for robust use. It's complete enough for basic understanding but not for full operational 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% (the single parameter 'path' is fully documented in the schema as 'The path of the directory to list'), so the baseline is 3. The description adds no additional parameter semantics beyond what the schema already provides, but doesn't need to compensate for gaps.

  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 verb ('Get a detailed listing') and resource ('files and directories in a specified path'), distinguishing it from siblings like 'search_files' (which filters) or 'get_file_info' (which gets metadata for a single file). It explicitly mentions what information is included in results.

  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 for when to use this tool ('Useful for understanding directory structure and finding files'), which implicitly differentiates it from siblings like 'search_files' (which is for searching with criteria) or 'get_file_info' (which is for single files). However, it doesn't explicitly state when NOT to use it or name alternatives.

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

• search_filesA
  3.9/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 effectively describes the recursive nature and wildcard support, but lacks details on permissions needed, error handling, or output format (e.g., pagination, sorting).

  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 efficient sentences that directly convey the tool's functionality and use case without any wasted words or redundancy.

  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?

  Given the tool's moderate complexity (search with recursion and pattern matching), no annotations, and no output schema, the description is adequate but incomplete—it covers the core behavior but omits details like return format, error conditions, or performance considerations.

  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 both parameters fully. The description adds minimal value by mentioning wildcard examples ('*.ts', '**/*.json'), but does not provide additional syntax or format details beyond what the schema implies.

  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 ('recursively search for files matching a pattern'), resource ('files'), and scope ('in a directory'), distinguishing it from siblings like list_directory (which lists without pattern matching) or get_file_info (which retrieves metadata for a specific file).

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

  Usage Guidelines4/5

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

  The description provides clear context for when to use this tool ('useful for finding files by name or extension'), but does not explicitly state when not to use it or name alternatives among the siblings (e.g., list_directory for unfiltered listing).

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

• edit_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 key behaviors: the tool performs mutations (edits), returns a git-style diff, and operates on exact line sequences. However, it lacks details on permissions needed, error handling (e.g., if lines don't match), or whether edits are atomic. The description doesn't contradict annotations (none exist).

  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 supporting details. Every sentence earns its place: the first states the action, the second explains parameters and output, and the third clarifies the edit mechanism. No wasted words.

  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 moderate complexity (mutating files with structured edits), no annotations, and no output schema, the description is reasonably complete. It covers the purpose, parameter intent, and output format (git-style diff). However, it could benefit from more behavioral context like error cases or idempotency, especially since there's no output schema to describe the diff structure.

  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 edits array with oldText/newText). The description adds some context by mentioning 'exact line sequences' and 'line-based edits,' which clarifies the semantics of oldText/newText, but doesn't provide additional syntax or format 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 tool's purpose with specific verbs ('Make line-based edits') and resource ('to a text file'), and distinguishes it from siblings like write_file (which presumably creates/overwrites entire files) and read_file (which only reads). The phrase 'line-based edits' provides precise differentiation.

  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 context by specifying 'line-based edits' and 'exact line sequences,' suggesting this tool is for targeted modifications rather than full file rewrites. However, it doesn't explicitly state when to use alternatives like write_file for complete replacements or when not to use this tool (e.g., for binary files).

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

• get_file_infoA
  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 full burden. It discloses that this is a read-only operation that doesn't access file contents, which is helpful behavioral context. However, it doesn't mention error conditions (e.g., what happens if path doesn't exist), performance characteristics, or authentication requirements.

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

  Conciseness5/5

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

  Two sentences with zero waste - first sentence states purpose and specific metadata attributes, second sentence provides crucial differentiation from sibling tools. Perfectly front-loaded with all essential information in minimal space.

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

  Completeness4/5

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

  For a simple read-only metadata tool with 1 parameter and no output schema, the description is reasonably complete. It covers purpose, scope, and differentiation from siblings. However, without annotations or output schema, it could benefit from mentioning return format or error behavior 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% with the single 'path' parameter fully documented in the schema. The description doesn't add any parameter-specific information beyond what the schema provides, such as path format examples or constraints. 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 specific verb 'retrieve' and resource 'detailed metadata about a file or directory', listing specific metadata attributes (size, creation time, etc.). It explicitly distinguishes from sibling tools by stating 'This does not read file contents', differentiating it from read_file.

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

  Usage Guidelines4/5

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

  The description provides clear context for when to use this tool (to get metadata without reading contents), but doesn't explicitly mention when not to use it or name specific alternatives. It implies usage vs. read_file but doesn't provide explicit exclusions or comparisons to other metadata-related tools.

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

• move_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 of behavioral disclosure. It effectively describes the core behavior (move/rename with failure on existing destination) but lacks details about permissions needed, whether the operation is atomic/reversible, error handling beyond the failure case, or what happens to file metadata. It provides basic behavioral context but could be more comprehensive.

  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 perfectly concise with three sentences that each earn their place: first states the core functionality, second clarifies the dual operation capability, third provides critical behavioral constraint. No wasted words, and the most important information (failure condition) is appropriately positioned.

  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 2 parameters, 100% schema coverage, but no annotations or output schema, the description provides good context about what the tool does and a key behavioral constraint. However, it could better address the mutation nature (e.g., mentioning it modifies the file system state) and provide more guidance about error scenarios or return values given the lack of output schema.

  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 both parameters (source and destination) are fully documented in the schema. The description doesn't add any additional parameter semantics beyond what the schema provides (e.g., path format examples, relative vs absolute paths, or special cases). The baseline of 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 specific verbs ('move or rename') and resources ('files and directories'), distinguishing it from siblings like create_directory, delete_file, or edit_file. It explicitly mentions the dual functionality of moving between directories and renaming in one operation.

  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 for when to use this tool (moving/renaming files/directories) and includes an important exclusion ('If the destination exists, the operation will fail'). However, it doesn't explicitly mention alternatives like using edit_file for content changes or create_directory for new directories, which would be helpful for sibling differentiation.

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

• create_directoryA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden and does well by disclosing key behavioral traits: it can create nested directories, succeeds silently if the directory exists, and performs a write operation. However, it lacks details on permissions, error conditions, or side effects.

  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 important behavioral details in two concise sentences. Every sentence earns its place by adding 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?

  Given the tool's moderate complexity (write operation with one parameter) and no annotations or output schema, the description is fairly complete: it covers purpose, behavior, and parameter implications. However, it could improve by addressing permissions or error handling for full contextual coverage.

  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. The description adds some context by implying the path can include nested directories, but does not provide additional syntax or format details beyond what the schema offers. 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 ('create a new directory or ensure a directory exists') and resource ('directory'), distinguishing it from siblings like delete_directory or list_directory. It precisely defines the verb and scope of the operation.

  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 it ('create a new directory or ensure a directory exists') and its behavior with existing directories, but does not explicitly mention when not to use it or name alternative tools. It implies usage for directory creation needs without specifying alternatives.

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

• delete_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 the full burden of behavioral disclosure. It effectively describes key traits: the operation is permanent ('cannot be undone') and immediate ('immediately removed'), which are critical for a destructive action. It lacks details on error handling (e.g., if the file doesn't exist) or permissions required, but covers the core behavioral impact well.

  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 critical behavioral warnings. Both sentences earn their place by conveying essential information without redundancy, making it efficient and well-structured for quick comprehension.

  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 destructive tool with no annotations and no output schema, the description is reasonably complete: it explains the action, permanence, and immediacy. It could improve by mentioning error cases or return values, but given the simplicity (one parameter, high schema coverage), it provides sufficient context for safe usage.

  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%, with the parameter 'path' clearly documented in the schema. The description does not add any additional meaning or context about the parameter beyond what the schema provides (e.g., path format or constraints), so it meets the baseline for high schema coverage without extra value.

  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 ('permanently delete') and resource ('a file from the file system'), distinguishing it from sibling tools like delete_directory (which targets directories) or move_file (which relocates rather than removes). The verb+resource combination is precise and unambiguous.

  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 context through the warning 'cannot be undone,' suggesting it should be used cautiously for irreversible deletions. However, it does not explicitly state when to use this versus alternatives like move_file (for relocation) or edit_file (for modification), nor does it mention prerequisites like file existence or permissions.

  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 does well by disclosing critical behavioral traits: it's destructive ('overwrite existing files without warning'), handles text content with encoding, and implies mutation. It lacks details on permissions, error handling, or response format, but covers the core safety concern 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 a warning and technical detail. Every sentence earns its place: the first defines the action, the second warns of risks, and the third adds encoding context. It's appropriately sized with zero waste.

  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 complexity (destructive write operation) and lack of annotations or output schema, the description is mostly complete: it covers purpose, risks, and content handling. It could improve by mentioning response format or error cases, but it provides sufficient context for safe 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?

  Schema description coverage is 100%, so the schema already documents both parameters (path and content). The description adds no additional meaning beyond what the schema provides, such as path format examples or content constraints. 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 ('create a new file or completely overwrite an existing file') and resource ('file'), distinguishing it from siblings like edit_file (partial updates) and read_file (read-only). It precisely defines the tool's scope and behavior.

  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 with 'Use with caution as it will overwrite existing files without warning,' indicating when to be careful. However, it does not explicitly mention alternatives like edit_file for partial updates or when to choose this over create_directory for directories, leaving some sibling differentiation implicit.

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

• delete_directoryA
  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 the full burden of behavioral disclosure. It effectively describes key traits: the operation is permanent and irreversible ('cannot be undone'), recursive ('all of its contents, including all files and subdirectories'), and high-risk ('Use with extreme caution'). However, it doesn't mention potential errors (e.g., if the path doesn't exist), permissions required, or system-specific constraints.

  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 action and scope in the first sentence, followed by critical warnings. Every sentence earns its place: the first defines the operation, the second emphasizes irreversibility, and the third advises caution. It's appropriately sized without redundancy or fluff.

  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 high complexity (destructive, recursive operation) and lack of annotations or output schema, the description does a good job covering essential context: purpose, scope, and risks. However, it could be more complete by mentioning error handling, permissions, or system limits, which are important for such a critical tool.

  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 input schema has 100% description coverage, with the 'path' parameter clearly documented. The description adds no additional parameter semantics beyond what the schema provides, such as path format examples or validation rules. Since schema coverage is high, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.

  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 ('permanently delete'), the target resource ('a directory and all of its contents'), and distinguishes it from sibling tools like 'delete_file' (which only deletes individual files) and 'create_directory' (which creates rather than deletes). The phrase 'recursive operation' further clarifies the scope beyond just the directory itself.

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

  Usage Guidelines5/5

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

  The description explicitly provides usage guidance with 'Use with extreme caution' and 'cannot be undone,' indicating when to use this tool (for irreversible deletion) versus alternatives like 'delete_file' for single files or 'move_file' for relocation. It effectively warns against casual use, though it doesn't name specific alternatives.

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

• execute_commandA
  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 an excellent job disclosing critical behavioral traits: security implications ('direct system access'), permission context ('run with the same permissions as the MCP server process'), and trust requirements. It doesn't contradict any annotations since none exist, and provides substantial behavioral context beyond what the input schema offers.

  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 perfectly front-loaded with the core purpose, followed by critical warnings and context. Every sentence earns its place: the first states what it does, the second provides security warning, the third gives usage guidance, and the fourth explains permission context. No wasted words.

  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 high-risk tool with no annotations and no output schema, the description provides excellent contextual completeness regarding security, permissions, and usage constraints. It appropriately focuses on the critical behavioral aspects rather than trying to explain return values (which would be needed if there was an output schema). The only minor gap is not explicitly mentioning what happens with command output.

  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 both parameters are well-documented in the schema. The description doesn't add specific parameter semantics beyond what's in the schema (command execution and optional working directory). This meets the baseline expectation when schema coverage is complete.

  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 ('execute shell commands') and resource ('on the system'), distinguishing it from sibling tools like create_directory or edit_file which perform file operations rather than arbitrary command execution. It precisely defines what the tool does 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 Guidelines5/5

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

  The description provides explicit guidance on when to use this tool ('Only use with trusted commands') and strongly implies when not to use it (for untrusted commands). It distinguishes this tool from siblings by highlighting its direct system access nature, which is not present in file operation tools like list_directory or read_file.

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

• read_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 the full burden. It discloses key behavioral traits: it reads complete contents (not partial), handles various text encodings, and returns full file content. However, it doesn't mention error handling (e.g., for missing files or permissions) or performance aspects like file size limits.

  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 additional context in a second sentence. Both sentences earn their place by providing essential information 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?

  Given the tool's low complexity (one parameter, no output schema) and no annotations, the description is mostly complete. It covers purpose, usage, and key behaviors. However, it lacks details on error cases or return format specifics, which would be helpful for a read operation.

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

  Parameters3/5

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

  The input schema has 100% description coverage, with the 'path' parameter well-documented in the schema. The description doesn't add any meaningful parameter semantics beyond what the schema provides (e.g., it doesn't clarify path resolution or encoding specifics), so it 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 tool's purpose with a specific verb ('Read') and resource ('complete contents of a file from the file system'). It distinguishes from siblings like get_file_info (metadata) and edit_file/write_file (modification) by focusing on content retrieval.

  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 on when to use this tool ('to examine file contents before editing'), which differentiates it from edit_file (for modifications) and get_file_info (for metadata). It also implies when not to use it (e.g., for file operations like moving or deleting).

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