Server Quality Checklist

Tool Scores

• remote_ssh_execA
  3.5/5.0
  Behavior3/5

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

  The description adds one behavioral context beyond annotations: 'Reuses your local OpenSSH config and keys.' This hints at authentication prerequisites. However, it does not elaborate on effects (e.g., arbitrary side effects, output handling) beyond what the annotations already imply (destructiveHint=true, readOnlyHint=false). No contradiction exists.

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

  Conciseness5/5

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

  The description is two sentences long, front-loads the core purpose in the first sentence, and the second provides useful context about configuration. No filler 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?

  While the schema covers parameters and annotations indicate destructive/open-world behavior, the description omits return value semantics (exit codes, stdout/stderr capture) and does not explain how the tool handled failures or timeouts. It is adequate for a simple exec tool but leaves gaps given no 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?

  Schema description coverage is 100%, so the baseline is 3. The description does not add any parameter-specific meaning beyond 'command' and 'SSH host/keys'; it merely repeats general intent. The schema already documents all six parameters adequately.

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

  Purpose5/5

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

  The description clearly states the tool's function with a specific verb and resource: 'Run a shell command on the configured SSH host.' This distinguishes it from sibling file-operation and diagnostic tools, which focus on specific resource types rather than arbitrary command execution.

  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?

  No guidance is provided on when to use this tool versus alternatives. The description mentions the 'configured SSH host' and 'local OpenSSH config and keys,' but does not explicitly state scenarios, prerequisites, or contrast with siblings like remote_ssh_read_text or remote_ssh_list_dir. This leaves the agent to infer usage.

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

• remote_ssh_write_textA
  3.5/5.0
  Behavior3/5

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

  Annotations already declare destructiveHint=true, so the description is not required to repeat that. It adds the behavioral detail that writing occurs through SSH stdin, but does not disclose whether existing files are overwritten, how errors are handled, or what success looks like. This is moderate additional context beyond annotations.

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

  Conciseness5/5

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

  The description is a single concise sentence with no redundancy. It directly states the core action and audience, fitting the tool's simplicity.

  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 complexity (6 parameters, no output schema, destructive hint), the description is minimal but not severely lacking. It covers the basic purpose and method, but does not address return behavior, error conditions, or overwrite semantics, which would be helpful for a destructive 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?

  Schema coverage is 100%, so all parameters are already described in the input schema. The description adds no extra meaning about parameters like path, content, mode, or createDirs, so baseline 3 is appropriate.

  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 action (write), target (a file on the configured SSH host), and method (through SSH stdin). It also implicitly distinguishes from siblings like remote_ssh_write_file_base64 by specifying UTF-8 text.

  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?

  No guidance is provided on when to use this tool versus alternatives. It does not mention that remote_ssh_write_file_base64 should be used for binary content, nor does it list any exclusions or prerequisites. The only implied context is that it handles text.

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

• remote_ssh_checkA
  3.8/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=true, so the safe-read nature is known. The description adds that the tool prints basic remote identity details, but it does not explain what those details include or what happens on failure. This is modest added value beyond the annotations.

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

  Conciseness5/5

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

  Single sentence, front-loaded with the action, no redundant words. The description earns its length and is appropriately sized for the tool's simple scope.

  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 connectivity check with two optional params and annotations, the description provides adequate context. The vague phrase 'basic remote identity details' leaves some output ambiguity, and failure behavior is not described, but the tool's scope is modest.

  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%: both host and timeoutMs are already well-described in the schema. The tool description adds no further parameter semantics, so the baseline of 3 applies.

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

  Purpose5/5

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

  The description uses a specific verb ('check') with a specific resource ('SSH host') and a concrete outcome ('print basic remote identity details'). It clearly distinguishes this connectivity/diagnostic tool from file operations, exec, and port-forwarding siblings.

  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 a health-check use case (checking reachability) but provides no explicit guidance about when to use this tool versus alternatives like remote_ssh_exec or remote_ssh_local_diagnostics. No exclusions or context are given beyond the basic purpose.

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

• remote_ssh_local_diagnosticsA
  3.8/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds the specific focus on the local process and OpenSSH launch capability, which adds context. However, it does not disclose what the diagnostics entail, potential limitations, or what output to expect.

  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, well-structured sentence that immediately states the purpose. It is concise with no wasted words and is front-loaded with the verb 'Diagnose'.

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

  Completeness4/5

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

  Given the tool's simplicity (two optional parameters, no output schema, read-only annotations), the description is mostly adequate. It clearly identifies the tool's scope and purpose. However, it does not mention what kind of results or diagnostics are returned, which could be useful for an agent. Still, overall it is reasonably complete for a simple diagnostic 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?

  Schema description coverage is 100%, as both parameters (host and timeoutMs) have descriptions. The tool description does not add any additional meaning or context to these parameters beyond what the schema provides. Baseline of 3 is appropriate.

  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 uses the verb 'Diagnose' with a specific resource: the local MCP server process and its ability to launch OpenSSH. This distinguishes it from sibling tools that all focus on remote SSH operations, making it uniquely positioned as a local diagnostic tool.

  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 context is implied: this tool is for diagnosing local MCP server issues, not for remote operations. However, there is no explicit guidance on when to use it versus alternatives, nor any exclusions. The description states what it does but not when to prefer it over other tools.

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

• remote_ssh_write_file_base64A
  3.8/5.0
  Behavior3/5

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

  Annotations already indicate destructive and non-read-only behavior. The description adds the decoding step and write operation, but does not disclose overwriting, directory creation, or side effects. It does not contradict annotations, but provides minimal additional context.

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

  Conciseness5/5

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

  The description is a single concise sentence that front-loads the core action with no wasted words. It is easily scannable and directly conveys the tool's purpose.

  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 full schema and annotation coverage, the description is sufficient to understand its function and context. It does not explain return values, but no output schema is present and the simple write action is adequately described.

  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?

  All six parameters have descriptions in the schema, so the description does not need to explain them. The description itself adds no parameter-level meaning beyond what the schema provides, resulting in a baseline score.

  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 action: decode base64 and write bytes to a file on the SSH host. The base64 qualifier distinguishes it from sibling remote_ssh_write_text, making the purpose specific and easily understood.

  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?

  No explicit when/when-not guidance or alternatives are provided. The description implies usage for binary content via base64, but it does not mention when to prefer this over remote_ssh_write_text or how it relates to other siblings.

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

• remote_ssh_start_port_forwardA
  3.9/5.0
  Behavior4/5

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

  The description adds a key behavioral trait beyond annotations: the tunnel stays alive only while the MCP server process is alive, which is crucial for lifecycle management. Annotations already flag this as non-read-only and open-world, and the description does not contradict them. It stops short of disclosing other behaviors like port conflict handling or return value.

  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 only two sentences: the first front-loads the primary action, the second provides a critical lifetime detail. Every word earns its place, with no redundancy or extraneous content.

  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?

  The description covers the core action and lifetime, and the schema fills in parameter details, but it does not mention the expected return value, error conditions, or how the tunnel is stopped. Given there is no output schema, these gaps remain for the agent to infer, making it adequate but not complete.

  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 covers 83% of parameters with meaningful descriptions (e.g., localPort, remotePort, host, localHost, remoteHost), leaving only connectTimeoutSeconds undocumented. The description adds no additional parameter semantics, so the schema already carries the burden; baseline 3 is appropriate.

  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 'Start' and the resource 'local SSH -L tunnel' through the configured SSH host. This distinguishes it from sibling tools like remote_ssh_list_port_forwards and remote_ssh_stop_port_forward, making the action unambiguous.

  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 does not explicitly mention alternatives or when-not-to-use scenarios, but it provides context that the tunnel remains alive only while the MCP server process is alive, implying temporary use. Sibling tool names suggest alternatives, but the description itself does not offer direct comparative guidance.

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

• remote_ssh_list_dirA
  4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint and openWorldHint, so the safety profile is clear. The description adds the concrete command 'ls -la', giving insight into exactly what executes on the remote host. It does not go into deeper behavior like output formatting or edge cases, but it adds useful context beyond the annotations.

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

  Conciseness5/5

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

  The description is a single, concise sentence that conveys all essential information without any filler. It is appropriately front-loaded and every word contributes to understanding the tool's purpose.

  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 directory-listing tool, the description is largely complete. It lacks an explicit mention of return format or output behavior, but the ls -la command implies standard output. Given the absence of an output schema, a bit more detail might help, but the tool is simple enough that the current description is 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?

  The input schema has 100% parameter coverage with descriptions for each parameter. The description does not add any semantic meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

  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: 'List a directory on the configured SSH host using ls -la.' It names the resource (directory), the method (ls -la), and the host relationship, which distinguishes it from sibling tools like remote_ssh_exec or remote_ssh_read_text.

  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?

  Usage is implied but not explicitly laid out. The description indicates when you would use it (to list a directory), but it does not mention alternatives or when to avoid it, such as when you need to read a file or execute arbitrary commands. Sibling tool names hint at alternatives, but the description itself lacks explicit guidance.

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

• remote_ssh_read_file_base64A
  4/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=true, establishing this as a safe read operation. The description adds the intended use case (small binary files) and encoding (base64), which goes beyond annotations, but it doesn't disclose size limits, error behavior, or return format details. The added context is useful but limited, so a 3 is appropriate.

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

  Conciseness5/5

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

  The description is two short sentences with no redundant information. Every word adds value: 'Read a file from the configured SSH host as base64' defines the action, and 'Use this for small binary files' gives usage guidance. Highly concise 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?

  With 100% schema coverage and a read-only tool, the description is sufficiently complete for an agent to select and invoke it correctly. It doesn't explain return values (no output schema) but mentions base64 encoding. The 'small binary files' hint aligns with maxBytes constraints, though it doesn't specify the 20MB maximum explicitly. Minor gaps in error handling are acceptable given the simplicity.

  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 all parameters (host, path, maxBytes, timeoutMs) individually documented. The description does not add meaning beyond the schema, such as clarifying parameter relationships or defaults. Baseline 3 is correct when schema handles parameter documentation.

  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 'Read a file from the configured SSH host as base64', specifying the verb (read), resource (file), and format (base64). It also distinguishes itself from sibling tools like remote_ssh_read_text (for text) and remote_ssh_write_file_base64 (for writing) by focusing on reading binary files.

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

  Usage Guidelines4/5

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

  The phrase 'Use this for small binary files' provides clear context on when to use the tool, but it does not explicitly name alternatives or state when not to use it (e.g., for text or large files). Sibling tool names imply alternatives, but the description itself doesn't reference them, so it stops short of a 5.

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

• remote_ssh_stop_port_forwardA
  4/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=false and destructiveHint=false, signaling a mutating but non-destructive operation. The description adds the context that it stops a tunnel created by the start tool, but it does not disclose failure modes, side effects on other tunnels, or whether the operation is reversible. This adds some value beyond annotations but lacks rich behavioral detail.

  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, succinct sentence that immediately states the tool's purpose with no filler. Every word earns its place, and it is well-structured for quick parsing by an AI agent.

  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 stop operation with one parameter, the description and schema together cover the essentials. The reference to the start tool provides context, and there is no output schema requiring explanation. It could mention return behavior or error handling, but these are not critical given the tool's straightforward nature.

  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 'id' parameter is fully described). The description adds no additional parameter semantics beyond what the schema provides. Per the rubric, high schema coverage yields a baseline of 3, and there is no compensating information in the description.

  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 action 'Stop a tunnel' and references the specific start tool, distinguishing it from sibling tools like remote_ssh_list_port_forwards or remote_ssh_start_port_forward. The verb 'stop' plus the resource 'tunnel' make the purpose 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 when to use it: to stop a tunnel previously created by remote_ssh_start_port_forward. It provides clear context and differentiates from siblings by referencing the start tool, though it does not explicitly mention alternatives or when not to use it. For a simple inverse operation, this is adequate.

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

• remote_ssh_uriA
  4.1/5.0
  Behavior4/5

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

  Annotations declare readOnlyHint=true and openWorldHint=false, and the description aligns by indicating a read-only return operation. The description adds context that both a URI and CLI command are returned, and that the host is 'configured' (i.e., has a default). It does not contradict annotations.

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

  Conciseness5/5

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

  The description is one sentence, front-loaded with the action and output. No unnecessary words, making it efficient.

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

  Completeness5/5

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

  For a simple tool with two optional parameters and no output schema, the description sufficiently explains the return value (URI and CLI command). It lacks details on how the host is resolved (e.g., REMOTE_SSH_HOST) but that is left to the schema. Overall, it is complete for its scope.

  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?

  Both parameters (host and path) have descriptions in the schema, covering 100% of parameters. The description does not add parameter semantics beyond the schema, such as syntax or defaults, so it meets the baseline for parameter understanding.

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

  Purpose5/5

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

  The description clearly states the tool returns a VS Code Remote-SSH URI and CLI command, using a specific verb and resource. It differentiates from siblings like remote_ssh_exec or remote_ssh_list_dir, which perform actions rather than generate connection strings.

  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?

  No explicit when-to-use or alternative guidance is provided. The phrase 'for the configured SSH host' implies the use case of retrieving connection info, but it does not exclude or compare with siblings. Usage 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.

• remote_ssh_read_textA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds the behavioral trait 'Large files are clipped by maxBytes', which is not in annotations, and mentions the 'configured SSH host' context. This provides useful additional transparency beyond annotations.

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

  Conciseness5/5

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

  The description is just two sentences: the first states the core purpose, the second adds a critical behavioral detail (clipping). No waste, no repetition, and the most important information is front-loaded.

  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 tool with complete schema and readOnly annotation, the description covers the essential behavior (reading text, clipping). It lacks details like return format or handling of missing files, but these are not critical given the tool's simplicity and the absence of an output schema. Slightly more detail on encoding or return would push it to 5.

  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 all parameters (host, path, maxBytes, timeoutMs) are already fully documented. The description's mention of clipping by maxBytes aligns with the schema's maxBytes description but does not add new meaning. Baseline 3 is appropriate when the schema handles parameter semantics.

  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 'Read a text file from the configured SSH host' with the specific verb 'read' and resource 'text file from SSH host'. This distinguishes it from siblings like remote_ssh_read_file_base64 (binary/base64) and remote_ssh_list_dir (directory listing).

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

  Usage Guidelines4/5

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

  The description provides clear context by specifying the tool is for reading text files, implying it is not for binary files (which have a sibling tool). However, it does not explicitly name alternatives or exclusions, so it falls short of a 5 but still offers enough guidance for an agent to select it appropriately.

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

• remote_ssh_list_port_forwardsA
  4.5/5.0
  Behavior4/5

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

  The annotations already declare readOnlyHint=true, so the description adds value by specifying the scope 'started by this MCP server process', which clarifies that it does not list system-wide or other external tunnels. This behavioral insight goes beyond the annotation and is appropriate for a simple list 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 a single clear sentence that immediately states the action and scope. There is no redundancy or filler, making it highly efficient for an agent to parse.

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

  Completeness5/5

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

  Given the tool's simplicity (no parameters, no output schema, read-only behavior confirmed by annotations), the description fully specifies what the tool does and its scope. No additional behavioral details are needed for correct invocation.

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

  Parameters4/5

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

  The tool has zero parameters and the input schema is empty, so the baseline for this dimension is 4. The description does not need to explain parameters, and it correctly avoids adding irrelevant information.

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

  Purpose5/5

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

  The description uses the specific verb 'List' with the resource 'SSH tunnels' and adds a scope limitation 'started by this MCP server process', which clearly distinguishes it from sibling tools like remote_ssh_start_port_forward and remote_ssh_stop_port_forward. It fully states what the tool does and its exact domain.

  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 clearly indicates this tool is for viewing tunnels created by this specific MCP server process, providing a clear context for use. While it does not explicitly name alternatives or exclusions, the sibling tool names make the usage obvious. It stops short of a 5 due to lacking explicit when-not-to-use guidance.

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