Server Quality Checklist

Tool Scores

• ssh_read_imageC
  2.9/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 full burden. It states the return is an MCP image and supports 'common raster formats,' but doesn't disclose what happens with unsupported formats (error? fallback?), size limits, transfer speed expectations, or how large images are handled. For a remote file operation, this is thin behavioral disclosure.

  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?

  Two sentences, no filler. Concise and to the point. Could arguably be considered under-specified, but for a simple read tool the brevity is reasonable.

  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 tool has 2 well-documented params, 100% schema coverage, no nested objects, no output schema. For a simple read operation, the description's coverage is adequate but not rich. It lacks details about error handling for unsupported formats, size considerations, or the distinction in return type vs ssh_read_file. Middle-of-range is fair.

  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% with both parameters documented in the schema. The description adds no parameter-specific detail beyond the schema. Baseline 3 is appropriate since the schema already 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?

  Clear verb+resource: 'Read a remote image and return it as an MCP image.' It specifies the format scope ('common raster formats') and distinguishes from ssh_read_file by doing image decoding and returning an image type. However, it doesn't explicitly contrast with ssh_read_file, which reads raw bytes, leaving some ambiguity about the key difference.

  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 on when to use this vs ssh_read_file or scp alternatives. It doesn't state that ssh_read_file is for raw text/binary reads, nor that scp_from might be better for large downloads. No when-not-to-use guidance is provided.

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

• ssh_pingB
  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 disclosure, yet it only says it 'tests' connectivity and 'returns the remote identity.' It doesn't disclose what happens on failure (error? empty output?), whether it makes a network round-trip each call, how long it may block, or how the identity is formatted. For a tool that establishes or verifies a session, these behavioral details are 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.

  Conciseness4/5

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

  At just 13 words, it is extremely concise and to the point. However, the brevity comes at the cost of behavioral transparency and usage guidance, so it's not 'zero waste' in the high-quality sense—it's simply minimal. Still, it's well-structured and front-loads the core 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 tool that tests connectivity (a side-effecting network operation with no output schema), the description is thin. Given the complexity of SSH sessions (auth, config resolution, port, identity), the description doesn't clarify error behavior, implications for session state, or how the returned identity relates to other ssh_* tools. Sibling tools like ssh_close and ssh_exec hint at session management, but this description doesn't position itself within that lifecycle.

  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 has 100% description coverage for its single parameter (target = 'user@host[:port]... uses local SSH config and keys'). The description adds useful context beyond the schema by clarifying the target format and that it leverages local SSH config and keys, giving the agent enough to construct a valid value.

  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 uses a specific verb+resource ('Test passwordless SSH connectivity') and identifies what it returns ('remote identity'). It clearly distinguishes itself as a connectivity test tool among siblings focused on file operations, exec, and interactive sessions. The verb 'test' makes the purpose of verification/validation clear.

  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 states the core action but gives no guidance on when to use this tool versus alternatives like ssh_exec or ssh_close. It doesn't mention that it should be used to verify connectivity before attempting operations, nor does it exclude cases where password-based auth is needed. No when-not-to-use context is provided.

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

• ssh_deleteB
  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. As a destructive operation, it should warn about irreversibility, confirm whether deletion is permanent (no trash/recycle), and note that recursive deletion of directories is destructive. It merely states the recursive requirement but discloses no other behavioral traits like permanence or permission requirements.

  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 a single efficient sentence with a clear additional clause about the recursive requirement. Zero wasted words, front-loaded with the core action. Could arguably add a safety note, but as written it's concise and functional.

  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?

  This is a destructive tool with no annotations and no output schema. As the sole delete operation among ssh siblings, it carries high safety responsibility. The description is too thin for a destructive remote operation—it doesn't address irreversibility, partial-failure behavior, permission requirements, or what happens if the target doesn't exist. For a mutation tool, more context is warranted.

  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 67% (path and target are described in the schema). The description adds the key semantic detail that recursive=true is required for directories, but this echoes what the schema's boolean default already implies. It adds no information about target format beyond what the schema provides, and doesn't clarify path semantics further.

  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?

  Description clearly states the verb 'Delete a remote file or directory' with the specific resource (remote file/directory). It distinguishes from siblings by being the only delete operation among the ssh_* tools, though it doesn't explicitly name which siblings to prefer over.

  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 one key usage condition: directories require recursive=true. However, it gives no guidance on when to use this vs alternatives (e.g., no mention of when not to delete, no references to sibling tools, no safety considerations about deleting remote resources).

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

• ssh_grepB
  3.2/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 disclosure burden. It mentions the output format (file:line:match) which is useful, but fails to disclose that this is a network-executed command on a remote host, that it may be slow or incur SSH latency, that recursive search could be expensive on large trees, or what happens on connection failure or no matches. The fallback behavior detail is helpful but insufficient for an unannotated remote-execution tool.

  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 a tight two-sentence structure that front-loads the core purpose and gives concrete output format. It's efficient with no filler. Could potentially add a sentence on usage/limitations, but what's present is well-organized.

  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 9-parameter remote search tool with no annotations and no output schema, the description is minimal. It covers the core search behavior and output format, but lacks guidance on remote operation costs, recursion behavior on large trees, error handling, connection prerequisites (SSH keys configured, per target param), and interaction with the max_results default (no default stated). The tool is moderately complex and would benefit from more 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 high (~89%), with 8 of 9 parameters documented in the schema with descriptions (only 'pattern' lacks a description). The tool description adds the output format context but does not add parameter-level semantics beyond what the schema provides. Baseline 3 is appropriate given the high schema coverage.

  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?

  Description states a specific verb+resource: 'Search remote text files recursively with ripgrep, falling back to grep.' It distinguishes from siblings like ssh_read_file (which reads a single file) by specifying recursion and search semantics. However, it doesn't explicitly differentiate from ssh_exec (which could also run grep remotely), though the dedicated purpose is reasonably clear.

  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 context (searching remote files) but provides no explicit when-to-use vs alternatives, no exclusions, and no guidance on when grep would be used for local searching or when to prefer ssh_read_file. The fallback-to-grep note gives some implementation context but not selection guidance.

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

• ssh_interactive_listB
  3.2/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. It states it's a list/read operation implicitly, but does not disclose behavioral traits like whether it returns session IDs usable by ssh_interactive_close or ssh_interactive_input, whether results are cached, or any privacy/sensitivity considerations about displaying session metadata.

  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?

  A single sentence, zero waste. Every word contributes to the purpose. For a zero-parameter listing tool, this is appropriately brief and front-loaded.

  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 simple zero-parameter list operation with no output schema and no annotations, the description is adequately minimal. However, given no output schema, it does not hint at what the returned list contains (session IDs? hostnames?), which an agent would need to chain with ssh_interactive_close or ssh_interactive_input. The description is complete for the operation but leaves return-format guessing to the agent.

  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 schema coverage is 100% (empty properties), so there is nothing for the description to add. A baseline of 4 is appropriate for a no-parameter tool since parameter semantics are trivially complete.

  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 'List currently open interactive SSH sessions' has a clear verb (list) and resource (open interactive SSH sessions). It distinguishes from sibling tools like ssh_exec, ssh_exec_result, and ssh_ping which are operational/status tools, so the purpose is reasonably clear despite being brief.

  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 explicit guidance on when to use this vs alternatives. It does not mention that it pairs with ssh_interactive_close or when one would call this (e.g., before closing sessions or checking active ones). The name and description imply usage but no alternatives or exclusions are given.

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

• ssh_scp_fromB
  3.4/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the behavioral disclosure burden. It discloses the scp method and mux reuse, which is useful. However, it doesn't mention that the operation performs a write to the local filesystem (a side effect of interest), potential overwrite behavior, or authentication requirements—though the schema partially covers auth via target description.

  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 a single efficient sentence that conveys the core action, direction, method, and a behavioral detail (mux reuse). No wasted words, front-loaded with the primary purpose.

  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 tool is a straightforward file transfer with 5 params (80% documented) and no output schema. The description covers the essential action but lacks detail on edge cases (recursive requirements, overwrite behavior, large transfers, connection reuse implications) that would round out the picture for a tool that has side effects on the local 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 80% high. The description itself adds little param detail, but the schema already documents target (user@host[:port] form), recursive (required for directories), and path semantics. The description adds no param-specific meaning beyond what the schema states, so baseline 3 applies.

  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 uses a specific verb+resource ('Download a remote file or directory to the local machine via scp'), clearly establishing the direction of transfer and method. It distinguishes from siblings like ssh_scp_to (which transfers in the opposite direction) and ssh_read_file, though it doesn't explicitly name the alternative.

  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 the tool is for downloads from remote to local and mentions 'reuses the multiplexed SSH connection when mux is enabled' as context. However, it provides no explicit guidance on when to prefer this over alternatives like ssh_read_file (e.g., for large files vs. quick reads) or exclusions for when not to use it.

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

• ssh_apply_patchA
  3.5/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 does reveal the fallback strategy (tries three tools in order), the strip=0 limitation for apply_patch, and dry-run support. However, it doesn't state side effects, requirements (e.g., the remote must have patch/git available), or behavior on failure across all three tools.

  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?

  Three sentences, no filler, key facts front-loaded. Every sentence contributes: what it does, fallback tools, and supported features. Excellent concise structure.

  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 tool with a fallback strategy and behavioral nuances (patch ordering, strip limitations, dry-run), the description provides reasonable but not exhaustive detail. There's no output schema to clarify return values, and the description doesn't explain what the tool returns on success/failure across the different tools. Adequate but could mention failure modes or prerequisites.

  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 4 parameters are documented in the schema. The description adds context on how strip is handled (strip=0 only for apply_patch) and mentions dry-run, which supplements the schema. However, most of the parameter semantics come from the schema itself, so the description adds only marginal value beyond the baseline.

  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 states the tool applies a unified diff on a remote host via SSH, distinguishing it from the many other ssh_* siblings. It clearly identifies the resource (remote host) and verb (apply_patch). However, it doesn't explicitly contrast with siblings like ssh_write_file or ssh_scp_to, though its purpose is specific enough to be 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?

  The description gives useful context: it tries apply_patch (strip=0 only), then git apply, then patch, and supports dry-run and strip level. This implies applicability for applying diffs to remote files. However, it doesn't explicitly state when to prefer this over alternatives or when not to use it, leaving usage guidance somewhat implied rather than explicit.

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

• ssh_interactive_closeA
  3.5/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. The term 'Kill and remove' implies destructive irreversible behavior on the session, but it doesn't state whether this affects any running process on the remote host, whether it deletes resources, or what happens to in-flight input/output. For a destructive operation with zero annotation coverage and no output schema, the behavioral disclosure is thin.

  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?

  A single, compact sentence that states the action, the resource, and the pairing with the companion tool. Zero wasted words; every element earns its place.

  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 single-parameter destructive close operation, the description is reasonably complete. However, it would benefit from clarifying the difference from ssh_close and ssh_exec_kill siblings, and noting whether killing the session has side effects on remote processes. Adequate minimum for a simple tool, but could add a line distinguishing it from the non-interactive close path.

  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?

  Only one parameter (session_id), and schema description coverage is 0%. However, the parameter is self-explanatory—an identifier for the session to close—so the schema's name already conveys its meaning. The description doesn't clarify where to obtain session_id (e.g., from ssh_interactive_exec return or ssh_interactive_list), though the sibling tool names hint at this. Adequate but not enriched.

  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?

  Clear verb+resource ('Kill and remove an interactive SSH session'). It explicitly references the companion tool ssh_interactive_exec, distinguishing it from the general ssh_close sibling and the exec_kill tool. Slightly less than 5 because it doesn't specify what 'close' produces or confirm the session is actually terminated vs merely detached.

  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 states it applies specifically to sessions 'started with ssh_interactive_exec', which gives clear context and implies it pairs with that tool. It doesn't explicitly name alternatives or exclusion cases (e.g., vs ssh_exec_kill for non-interactive execs), but the reference to the paired tool provides reasonable usage direction.

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

• ssh_exec_killA
  3.6/5.0
  Behavior3/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. The description is honest that this sends signals (a mutation on a running process) and mentions the cleanup behavior. However, it doesn't disclose what the job_id needs to be valid, whether sending SIGTERM defaults gracefully handle cleanup, or what happens to running output. With zero annotations, more behavioral disclosure would be beneficial.

  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 two concise sentences with zero waste. It front-loads the primary purpose and adds the optional cleanup behavior as a secondary note. It's appropriately terse for a tool that the schema already documents well.

  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 tool with full schema coverage, 3 parameters (all documented), no output schema, and no nested objects, the description could be considered sufficient. However, with no annotations describing the destructive potential (sending signals can kill processes), the description could benefit from noting behavioral implications. The tool has moderate complexity and is reasonably covered.

  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 documents all three parameters (job_id, signal, cleanup) with their meanings and defaults. The description adds the context that job_id comes from ssh_exec background=true (which the schema already states) and notes the optional cleanup behavior. The value added beyond schema is minimal, and the baseline of 3 applies.

  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 verb (send a signal to) and resource (a background job started with ssh_exec background=true). It distinguishes this from siblings since it explicitly refers to ssh_exec background jobs and mentions optional cleanup of the job log directory, which differentiates it from other SSH operational tools.

  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 makes it clear this is for background jobs started with 'ssh_exec background=true' — establishing the context for what jobs this applies to. It does not explicitly state when NOT to use it or name alternative tools, but the prerequisite connection to ssh_exec background jobs is clear and helpful.

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

• ssh_list_dirA
  3.6/5.0
  Behavior3/5

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

  No annotations exist, so the description carries the transparency burden. It implies a read-only operation (listing), which is a useful behavioral signal, but doesn't disclose error behavior (e.g., what happens on permission-denied or nonexistent path), or confirm whether it's a non-destructive operation. For a read-only tool this is adequate but not rich.

  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?

  A single, efficient sentence that conveys the tool's purpose and output style with zero waste. Every word earns its place.

  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?

  This is a straightforward read-only list operation with only 2 parameters, both fully covered by the schema. No output schema exists, but the ls -lAh style hint effectively communicates what the return will contain. For a tool of this complexity, the description is complete enough.

  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 both parameters (target and path) are already documented in the schema. The description adds no additional parameter semantics beyond what the schema already captures—such as the default '.' for path. Baseline 3 is appropriate given full schema coverage.

  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 verb ('List') and resource ('a remote directory'), and specifies the ls -lAh metadata style which adds precision. It doesn't explicitly differentiate from siblings like ssh_read_file or ssh_grep, but the directory-listing scope is clear enough that a knowledgeable agent would distinguish it.

  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 this is for listing remote directories but doesn't state when to prefer it over alternatives or what context makes it appropriate. Given the sibling suite includes ssh_read_file, ssh_exec, and grep, some when-to-use guidance (e.g., for inspection without reading file contents) would help, but the read-only listing purpose is reasonably self-evident.

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

• ssh_mkdirA
  3.6/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries full burden. It discloses the -p (recursive parents) behavior, which is the main behavioral trait. However, it does not mention failure modes (what happens if the directory already exists, permission denied, target unreachable) or that this is a mutating 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?

  One concise sentence that fully describes the purpose and behavior. Zero wasted words; the mkdir -p analogy is highly informative per word.

  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 two-parameter tool with 100% schema coverage and the mkdir -p analogy, the description is largely complete. It could mention what happens on existing directories or permission failures, but the simplicity of the operation and full schema coverage keep this at a solid level.

  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% for both parameters, so the schema already documents target and path semantics. The description adds the mkdir -p nuance but does not elaborate on target's port syntax or path constraints beyond what the schema states. Baseline 3 is appropriate.

  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 states a clear verb+resource ('Create a directory (and parents) on the remote host') with a helpful comparison to `mkdir -p`. It is distinct from siblings, though it could be even more explicit about the remote+filesystem context that differentiates it from utilities like ssh_scp_to or ssh_write_file.

  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 implicitly conveys when to use it (creating directories remotely) by mentioning 'equivalent to mkdir -p' which signals recursive parent creation. However, there are no explicit exclusions or alternatives named, nor prerequisites (e.g., that the SSH target must be reachable, or that parent permissions may be required).

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

• ssh_scp_toA
  3.6/5.0
  Behavior3/5

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

  No annotations exist, so the description carries the behavioral burden. It discloses the scp mechanism and the multiplexed-connection reuse, which is useful. However, it doesn't explain side effects like overwriting existing remote files, permission requirements, or behavior on failure. It's adequate but thin for a mutation tool with zero 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, zero waste, front-loaded with the primary purpose and direction. No filler or redundant restatement of the schema.

  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 tool is moderately complex (5 params, scp directionality), and the description covers core purpose well. However, without annotations or output schema, it could add value by clarifying the mux requirement (does enabling mux require it to be pre-established?), overwrite behavior, and what the tool returns on success/failure. Adequate but with clear gaps for a network mutation tool.

  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?

  Schema coverage is 80% (4 of 5 params documented), so baseline is 3. The description adds the key semantic insight that 'recursive' is required for directory uploads and that the connection may be reused via mux. While most param meaning is in the schema, the description's recusal of scp/mux behavior adds value above baseline.

  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?

  Description clearly states the verb (upload), resource (local file/directory to remote host), and mechanism (scp). It distinguishes from sibling ssh_scp_from (which is download) through the 'upload' direction, and from read/write tools. However, it doesn't explicitly name the sibling alternative, only implying direction via 'to'.

  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 conveys when to use it (uploading local files to remote), but gives no explicit when-not-to or alternative recommendations. The clear 'upload' vs sibling 'from' direction implies when to choose this tool, but no explicit exclusions are stated (e.g., for text content use ssh_write_file instead).

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

• ssh_exec_resultA
  3.7/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden. It discloses that the tool reads status/output and can block (wait) until exit or timeout. However, it doesn't describe what the result structure looks like, whether it's a poll-then-return pattern, or what happens on timeout (error vs return partial status). These are material gaps for a status-checking 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?

  One concise sentence that captures the core purpose and the optional wait feature. Zero wasted words, efficient and front-loaded with the key action.

  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?

  No output schema and no annotations, so the description must cover return semantics, which it doesn't fully address. The tool is fairly simple (read status/output of a background job), but the agent needs to know what fields the result contains and how timeout behaves. Still, the purpose is clear enough for basic usage, giving a mid-range score.

  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 three parameters (job_id, wait, timeout_ms) are documented in the schema. The description adds the 'optionally wait until it exits' framing which orients the wait/timeout_ms pair. This maps to the baseline 3 given high schema coverage, with minimal added value beyond the schema.

  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 checks status/output of a background job started with ssh_exec background=true, and optionally waits for exit. It uses a specific verb+resource combination and references the sibling ssh_exec tool for context, distinguishing it from other siblings.

  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 indicates this tool is for jobs started with ssh_exec background=true, clarifying its context. It mentions the optional wait behavior. However, it doesn't explicitly contrast with alternatives like ssh_exec_kill or ssh_exec, though the context makes the pairing reasonably clear.

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

• ssh_read_fileA
  3.7/5.0
  Behavior2/5

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

  With no annotations at all, the description must bear the full weight of transparency, and it only partially does. It conveys the line-limiting defaults but omits critical behavioral context: whether this is a safe read-only operation (contrast with ssh_write_file/ssh_delete), error behavior for missing files or permissions, and handling of non-UTF-8/binary content despite the UTF-8 claim.

  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?

  Exceptionally concise and efficient: two short sentences that pack the core purpose plus range semantics without redundancy. Front-loaded with the primary action and immediately followed by the most consequential parameter behaviors.

  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 4 fully documented params, no output schema, and no annotations, the description is adequate but not rich. The 200-line default and line-range semantics are valuable additions, but the tool lacks disclosure about return value structure and error conditions (missing file, permission denied, binary content) that the agent would benefit from knowing before invoking.

  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 baseline 3 applies. The description does provide a helpful synthesis of offset/limit ('1-based line range; limit=0 means unlimited') that clarifies the interplay beyond the individual schema descriptions, but it doesn't add fundamentally new parameter context beyond what the well-documented schema already provides.

  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 states a specific verb+resource combination ('Read a UTF-8 text file from a remote host') and then clarifies line-range semantics. It clearly distinguishes from siblings: ssh_read_image (image files), ssh_grep (search), ssh_list_dir (directory listing), and ssh_write_file (write operation). Purpose is precise and contextually differentiated.

  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 explains the offset/limit semantics and default behavior, giving the agent practical guidance on how to invoke the tool for partial reads. It doesn't explicitly state when to prefer this over ssh_grep or ssh_read_image, but the parameter explanations combined with clear sibling differentiation in names provide adequate usage context.

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

• ssh_interactive_execA
  4.1/5.0
  Behavior3/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. It does disclose key behaviors: waits until output goes quiet or process exits, returns output plus session_id, auto-closes session if no prompt, idle sessions expire after 10 minutes. However, it doesn't specify auth requirements (uses local SSH config/keys is mentioned in schema), what the return format looks like, or how errors/timeouts are surfaced. The waiting threshold (quiet_ms) is documented in schema, not description.

  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 three well-structured sentences that front-load the core purpose with concrete use cases, then proceed to lifecycle behavior and follow-up tool routing. It's appropriately sized and every sentence carries information. Minor waste: could be seen as slightly dense but nothing is redundant.

  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 stateful, multi-tool interactive workflow with no output schema and no annotations, the description does a strong job covering the key semantics: PTY allocation, quiet-wait behavior, session lifecycle (auto-close, follow-up tools), and expiry. It integrates well with the sibling tool ecosystem. Slight gap is not explaining the return structure/output format for the initial call, but this is partly compensated by listing what it returns (output + session_id).

  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 67%. The description explains the 'command' parameter conceptually (programs that prompt for input) and mentions quiet_ms behavior indirectly ('waits until output goes quiet'). However, the description doesn't add depth to 'target' beyond what schema already states (user@host[:port], local config/keys) or explain the quiet_ms tuning semantics (what the tradeoffs of shorter/longer wait are). Baseline 3 is appropriate with moderate 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+resource (start a command on remote host with PTY) and the purpose (for programs that prompt for input). It lists specific use cases (sudo, y/N confirmations, setup wizards, REPLs) which sharply distinguishes it from siblings like ssh_exec (non-interactive execution) and ssh_interactive_input (a separate follow-up tool).

  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?

  Excellent guidance on when to use this vs alternatives. It explicitly names the sibling tools to use (ssh_interactive_input to reply/poll, ssh_interactive_close to finish), describes the behavior when the command finishes without prompting (session auto-closes, nothing further to do), and provides the auto-expiry timeout (10 min). This is explicit when/how guidance with named alternatives.

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

• ssh_write_fileA
  4.1/5.0
  Behavior4/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 clearly states the file is created or overwritten, and that append=true changes behavior. The create_dirs default behavior is not described in the tool description itself, but is documented in the schema. It doesn't mention failure modes, permissions requirements, or what happens on errors.

  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, zero waste. The first sentence states the core purpose and option, the second explains the advantage over the alternative. Every word earns its place.

  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 tool description is clear and the schema covers all parameters, there's no output schema and no description of what the tool returns (e.g., success indicator, byte count, error messages). For a write operation with mutation side effects and no annotations, more behavioral context about result/errors would improve completeness, though the core usage is adequately covered.

  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 5 parameters are documented in the schema. The description adds some value by clarifying the append=false default means overwrite and by mentioning create/overwrite semantics, but most parameter meaning is already in the schema. This meets the baseline 3 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 states a specific verb+resource+action: 'Write UTF-8 text content directly to a file on the remote host' with create/overwrite/append semantics. It distinguishes itself from ssh_scp_to by explicitly calling out 'Avoids the round-trip of writing a local temp file and scp-ing it.'

  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 when to use this tool (write text content directly) and contrasts with the scp alternative, implying use when avoiding the temp-file round trip. It doesn't explicitly state when not to use it versus ssh_apply_patch or other write-related tools, but the alternative context is present.

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

• ssh_closeA
  4.2/5.0
  Behavior3/5

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

  The description discloses a key behavioral trait: that it becomes a no-op when multiplexing is disabled. However, there are no annotations, so the description carries the full burden. It doesn't mention whether this closes any active running commands, what happens to in-flight operations, or side effects on other tools using the same master connection. Adequate but could be richer.

  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?

  A single, efficient sentence that conveys purpose, scope, and a critical edge case (no-op when multiplexing disabled). Zero 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 simple single-parameter no-op-capable tool, the description is largely complete. It covers the action, scoping, and the edge case of disabled multiplexing. Minor gaps include not detailing side effects on connected sessions or what the response looks like, but given the tool's simplicity these are not critical omissions.

  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 single 'target' parameter is fully documented in the schema (100% coverage) with format 'user@host[:port]' and notes it uses local SSH config and keys. The description adds the behavioral context of what the target refers to (the multiplexed master). With full schema coverage, baseline is 3 and the description's scoping adds minimal extra value, so 4 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?

  Clearly states the verb (close), resource (multiplexed SSH master connection), and target scope. It also distinguishes itself from the sibling ssh_interactive_close by specifying it operates on the multiplexed master connection rather than an interactive session.

  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 this tool is applicable (when multiplexing is enabled) and notes the no-op behavior when multiplexing is disabled (e.g., native Windows OpenSSH). It could be stronger by explicitly contrasting with ssh_interactive_close, but the behavioral note about no-op provides practical usage context.

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

• ssh_interactive_inputA
  4.2/5.0
  Behavior3/5

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

  No annotations provided, so the description carries the burden. It discloses that it returns 'newly produced output and status' and that omitting input causes a wait/poll. However, it doesn't disclose blocking/session timeout behavior, whether the session runs to completion, or what happens if the session already closed. Moderate transparency, some key gaps for a potentially blocking call.

  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 parenthetical sentence, front-loaded with purpose, then the omit-input variant. Zero wasted words. 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 4-param tool with no output schema and no annotations, the description covers the core use cases (send input, poll). It explains the return (newly produced output and status). Minor gaps remain around quiet_ms semantics and failure/closed-session behavior, but it's reasonably complete for an interactive I/O utility.

  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?

  Schema description coverage is 50%; the 'input' and 'newline' parameters have schema descriptions. The description text adds meaning by explaining the omit-input-to-poll behavior (which maps to 'input' being optional) and that polling returns newly produced output. This goes slightly beyond the schema, though 'quiet_ms' and 'session_id' semantics rely on the schema alone.

  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?

  Description clearly states a specific verb (send input) + resource (running ssh_interactive_exec session), plus the poll/read-only alternative when input omitted. 'Or just poll for more output if input is omitted' explicitly distinguishes the two primary uses. It clearly differentiates from siblings like ssh_interactive_close, ssh_interactive_exec, ssh_exec (non-interactive).

  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?

  Explains the intended usage context (answer sudo password or y/N prompt) and the polling behavior when input is omitted. It doesn't explicitly state when NOT to use it versus siblings, but the interactive-session context is clear. No explicit alternatives named, but scope is well-defined by the session-based framing.

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

• ssh_execA
  4.4/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries full burden for behavior disclosure. It conveys key behaviors reasonably: background mode returns job_id, stdin is disallowed for background jobs, and timeout/output-limit are configurable. However, it doesn't disclose side-effect risks of arbitrary shell execution (e.g., no confirmation/warning about destructive commands), what happens on non-ok exit codes, or behavior on timeout beyond there being a limit. For a mutating/powerful exec tool with zero annotations, some behavioral disclosure is present but gaps remain.

  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?

  Three sentences, all information-dense with zero filler. The description prioritizes the core purpose first, then capability list, then the background-job workflow and sibling handoff. Slightly more than the minimum needed, but each clause adds distinct value. No waste or redundancy.

  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 complex 9-parameter tool with nested objects (env) but no output schema, the description covers the operational workflow well. It explains the two execution modes (foreground vs background), the stdin-background incompatibility, and directs users to ssh_exec_result/ssh_exec_kill for follow-up. The high schema coverage (89%) handles parameter details, and the description fills the cross-tool workflow gap thoroughly. It doesn't describe return values, but none are promised in an output schema, and background job_id is mentioned.

  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?

  Schema coverage is high (89%), so baseline is 3. The description adds meaningful semantic context beyond the schema: 'stdin is not allowed for background jobs' ties two parameters together, 'Set background=true to run a command detached and get a job_id' explains the background param's behavior, and 'acceptable exit codes' frames ok_codes semantically. The description meaningfully complements the 89% covered 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?

  Description uses a specific verb ('Execute an intentional shell command') with a clear resource ('remote host') and enumerates the capabilities it supports. It clearly distinguishes itself from siblings like ssh_read_file, ssh_write_file, ssh_interactive_exec, and ssh_apply_patch by being the general 'execute a shell command' tool. The mention that it's for 'intentional' commands hints at purpose and distinguishes from exploratory/ping tools.

  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 references sibling tools for related workflows: 'Use ssh_exec_result to poll/wait and ssh_exec_kill to stop or clean up.' It also explains when background=true is appropriate versus standard execution and notes the stdin restriction for background jobs. The sibling context includes ssh_interactive_exec, and the description frames ssh_exec as the non-interactive general command runner.

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