Server Quality Checklist

Tool Scores

• ssh_downloadA
  3.6/5.0
  Behavior4/5

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

  Beyond the idempotent and destructive hints, the description details the use of temporary names, sha256 checks, handling of root-owned files via /tmp staging, and the 'unavailable' response when sha256 is missing. These are concrete behavioral details not present in annotations.

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

  Conciseness2/5

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

  The description is verbose and uses metaphorical language ('Data lands under a temporary name and takes its place in one rename') that obscures the meaning. It lacks straightforward structure and could be significantly condensed for clarity.

  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 main functional aspects: transfer, verification, root handling, and alternative usage. However, it does not clearly explain when to prefer this tool over others (beyond text files) or address potential pitfalls. It is adequate but not comprehensive.

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

  Parameters3/5

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

  The schema includes descriptions for all parameters, and the tool description does not add further clarification or nuance. Since schema coverage is 100%, the baseline of 3 is appropriate; the description offers no extra meaning.

  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 core purpose: copying a file or directory from a server to this machine. It also mentions the sha256 verification and the alternative for text files. However, the phrasing is convoluted with metaphors, making it less crisp than an ideal purpose statement.

  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?

  It explicitly contrasts with ssh_file_read, indicating when to use this tool for downloads versus reading a text file. It does not explicitly say 'use this when you need to transfer files', but the verb 'copies' makes that implicit. The alternative is clearly stated.

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

• ssh_job_killA
  3.8/5.0
  Behavior4/5

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

  Beyond the annotations (destructiveHint, idempotentHint), the description discloses that the signal 'reaches the whole process group' and that an already-finished job is 'reported as gone rather than refused,' which aligns with and expands on the idempotent hint. This adds valuable operational context without contradicting annotations.

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

  Conciseness4/5

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

  The description is concise, using two sentences to cover purpose, side effects, and signal guidance. It front-loads the primary function and avoids redundancy. Slightly more structure (e.g., separators) could help, but it is efficient and well-paced.

  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 presence of an output schema (which covers return values), the description is sufficiently complete. It explains process-group behavior, idempotent behavior, and signal choices, covering the key operational aspects an agent needs. No critical gaps are evident beyond what the schema and annotations already provide.

  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 100%, so the baseline is 3. The description adds meaningful extra detail for the 'id' parameter (returned by ssh_exec with detach: true, sudo jobs reachable as root) and for 'signal' (KILL only when TERM ignored), going beyond the schema definitions. This enriches parameter understanding.

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

  Purpose4/5

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

  The description clearly states the tool's purpose: 'Stops a detached job.' It uses a specific verb and resource, and the mention of 'detached job' distinguishes it from general job management tools. While it doesn't explicitly differentiate from sibling tools like ssh_job_status, the action is 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 provides guidance on signal selection ('TERM is the default; KILL is for a job that ignored it') but does not explicitly state when to use this tool versus alternatives like ssh_job_status or ssh_job_output. Usage context is implied by 'detached job' but no explicit exclusions or alternatives are given.

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

• ssh_job_listA
  4/5.0
  Behavior3/5

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

  The description discloses the output format ('Ids and states only') and implies read-only behavior (matching the readOnlyHint annotation). However, it does not mention potential errors, timeouts, or edge cases (e.g., behavior when no jobs exist). The annotation already covers read-only, so the description adds only partial transparency about the response structure but omits failure modes.

  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 concise (two sentences) and well-structured. It front-loads the core action and target, then adds clarifications (when to use, output format, alternative tool) without unnecessary fluff. Every sentence contributes to understanding, making it highly efficient.

  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?

  The description provides enough context to call the tool correctly: it explains the purpose, when to use it, and the output format. It also references ssh_job_output for further details, which compensates for the lack of an output schema. However, it does not mention pagination, sorting, or limits, though these may not be critical for this simple list operation. Overall, it is complete for typical usage.

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

  Parameters3/5

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

  The sole parameter 'profile' has a description ('Machine name') in the schema, achieving 100% schema coverage. Since the schema already provides the semantic meaning, the tool description adds no additional parameter details. According to the rubric, a baseline of 3 is appropriate when schema coverage is high.

  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: 'Lists the detached jobs on a machine with their state.' The verb 'Lists' is specific, and the resource 'detached jobs' is well-defined. It also differentiates from sibling tools by explicitly mentioning the use case of not having a job ID and pointing to ssh_job_output for printed output, making 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 provides usage context: 'for when an id was not kept' indicates when to use this tool instead of querying a specific job. It also clarifies scope ('jobs with sudo included') and directs users to ssh_job_output for printed output. While it doesn't explicitly list all alternative tools, the guidance is sufficient to decide when to invoke this tool.

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

• ssh_job_statusA
  4.1/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint: true, so the description doesn't need to restate safety. It adds valuable behavioral detail: reporting the last lines and defining the 'lost' state (no exit code but output still available). This goes beyond the basic hint and helps the agent understand what to expect. No contradiction.

  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 short sentences with zero filler. The main purpose is front-loaded in the first sentence, and the lost-job clarification is a useful addendum. No wasted words.

  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?

  The description covers all essential context: it targets detached jobs, reports state and last lines, and flags the lost case with a pointer to an alternative. The output schema exists, so return format needs no explanation. An agent has everything needed to call it correctly.

  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%, meaning both 'profile' and 'id' are fully documented in the input schema. The tool description adds no extra parameter semantics, so the baseline of 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 clearly states the tool's function: reporting the state of a detached job along with its last written lines. This effectively distinguishes it from siblings like ssh_job_output (full output) and ssh_job_list (listing jobs) by focusing on status and a snippet. However, it does not explicitly name alternatives, so it falls short of a 5.

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

  Usage Guidelines4/5

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

  The description provides a clear use case: to see where a job got to. It also mentions a specific alternative for lost jobs (ssh_job_output still has output). While it doesn't explicitly exclude other tools or cover all sibling comparisons, the context is informative and actionable.

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

• ssh_file_listA
  4.3/5.0
  Behavior4/5

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

  Annotations include readOnlyHint=true, so the description doesn't need to restate that. It adds valuable behavioral context: the recursive walk that hits the output limit says so instead of silently returning a shortened list. Additionally, the sudo parameter is described as needed for directories the profile user cannot open. These provide beyond-annotation insight into failure modes and security 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 compact three-sentence paragraph that front-loads the core purpose, then clarifies important caveats (glob narrowing, recursive limit signaling) and ends with a routing directive to ssh_file_read. No filler, every sentence provides distinct value.

  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 read-only directory listing tool with 5 parameters all fully documented in the schema, the description covers all necessary behavioral aspects: what is returned (each entry fields), optional globbing, recursive limit behavior, and a clear pointer to the sibling for file content. No output schema exists, but the return value is adequately described by the entry fields. Complete for an agent to call correctly.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already documents all parameters. The description adds a bit of context about the pattern glob ('*.conf') and the recursive limit behavior, but does not significantly enhance the parameter understanding beyond implicating that pattern is optional and recursive is optional. With full schema coverage, a baseline of 3 is appropriate; the added detail is marginal.

  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 'Lists a directory on a server' with specific details about what each entry includes (size, mode, owner, modification time). It also distinguishes itself from sibling ssh_file_read by saying to use that for file contents, while mentioning globbing and recursive behavior. The tool name 'ssh_file_list' is fully expanded and contextualized.

  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?

  It provides clear context for when to use this tool vs alternatives: 'To see what is inside a file, use ssh_file_read.' This is an explicit exclusion for file content. It lacks guidance on when not to use it vs other sibling tools like ssh_disk_breakdown or ssh_log_search, but the primary alternative is addressed. A 4 is appropriate since the main use case and primary alternative are clear.

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

• ssh_file_writeA
  4.4/5.0
  Behavior4/5

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

  The description details important behavioral aspects: atomic write (temp name + rename), no partial files, optional sha256 verification, and whole-file replacement with no append. These align with the destructive and idempotent hints. Minor imprecision: says 'text files' while the schema supports binary via base64, but this is a small oversight.

  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 concise and well-structured: it opens with the core function, explains the atomic mechanism and verification, notes the append limitation, and closes with an alternative. Every sentence contributes to the understanding.

  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 that an output schema exists, the description appropriately avoids detailing return values. It covers the essential behavioral aspects, including atomicity, permissions, verification, and the distinction from ssh_upload. It doesn't discuss error handling, but that is not required given the output schema.

  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 input schema already provides comprehensive descriptions for all parameters, so the description doesn't need to repeat them. It adds context like 'each with its own permissions' (mode) and 'optional sha256 check' (verify), which enriches understanding without contradicting the schema.

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

  Purpose5/5

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

  The description clearly and specifically states the tool's function: writing text files to a server, supporting multiple files per call, each with its own permissions. It also explicitly contrasts with ssh_upload, making 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 provides a clear alternative usage condition: 'For something that already exists on this machine, use ssh_upload.' This gives guidance on when to prefer another tool. It doesn't explicitly discuss other alternatives, but the provided hint is sufficient for typical usage.

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

• ssh_audit_baselineA
  4.5/5.0
  Behavior4/5

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

  Annotations provide readOnlyHint=true, and the description reinforces this with 'Reads only'. It adds valuable behavioral context: the sudo behavior (without sudo, sshd section reads from config file rather than sshd itself), and the compact/include parameters' effect on output size. This goes beyond the annotation by explaining the non-sudo fallback behavior.

  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 compact and front-loaded: it states the core purpose first, then the key differentiator (one round trip), then the sudo caveat, then usage guidance. Every sentence earns its place with no 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?

  Given the output schema exists (which likely describes the report structure), the description covers the essential context: what sections are included, severity markers, the sudo behavior, and when to use it. The tool is a read-only audit with clear parameters, and the description is complete for an agent to call it correctly.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already documents all parameters. The description adds context about the 'include' parameter's default behavior ('Default: all') and the sudo-related parameter's effect, but these are also in the schema. The description doesn't add significant meaning beyond what the schema provides, 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 purpose: reporting machine setup (sshd, firewall, pending updates, failed services, docker, listening ports, disk) with severity markers. It distinguishes itself from siblings by mentioning 'one round trip instead of a dozen commands' and explicitly contrasts with ssh_snapshot for load/health.

  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?

  Explicitly states when to use: 'Use it on a machine you have not audited yet; for load and health at this moment, use ssh_snapshot.' This provides clear usage context and names the alternative tool, making the decision unambiguous.

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

• ssh_disk_breakdownA
  4.5/5.0
  Behavior4/5

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

  The readOnlyHint annotation already declares this as a safe read operation, and the description reinforces it with 'Reads only, nothing is deleted.' It adds context about the output scope (docker, journald, package caches) which is not in the annotation. No contradiction; description supplements but does not contradict the annotation.

  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 short sentences achieve high information density without waste. The core purpose is front-loaded, followed by a safety note and a usage routing pointer. No filler or redundant phrasing.

  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 output schema exists to describe return values, and annotations convey the read-only safety, the description covers all essential operational context: purpose, scope, usage trigger, and the distinguishing alternative. Nothing an agent needs to call this tool correctly is missing.

  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%, meaning every parameter (sudo, paths, top_n, profile) already has a detailed description. The main description adds no additional parameter-level meaning, so it does not exceed the baseline of 3 for a fully documented schema.

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

  Purpose5/5

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

  The description states a specific verb ('finds what filled a disk') and resource (disk), and enumerates concrete outputs: free space per filesystem, largest directories, and contents of docker, journald, and package caches. It also distinguishes itself from sibling ssh_snapshot by explaining that snapshot gives a one-line overall fullness, while this tool provides breakdown details.

  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?

  Explicitly says 'Use it after a disk alarm' and gives a contrasting use case: 'for how full the disks are at all, ssh_snapshot answers in one line.' This tells the agent when to invoke this tool and when to prefer an alternative, leaving no ambiguity about selection.

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

• ssh_execA
  4.5/5.0
  Behavior4/5

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

  Annotations already carry destructiveHint=true, so the tool's risk profile is available. The description adds genuinely useful runtime behavior: every command runs an independent shell, so variables and cd are not shared across entries, and detached commands outlive the requesting call and return a job id. This goes beyond what the annotations alone communicate.

  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?

  Every sentence earns its place: the first states what the command returns, the second captures the shell-isolation caveat, the third gives the long-running work guidance, and the fourth points to better alternatives. It is tight, front-loaded, and free of filler.

  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 tool with six parameters, an output schema, and a destructive annotation, the description covers the key behavioral risks, the shell semantics, the detach path, and the existence of specialized sibling tools. The parameter docs and output schema carry the remaining details, so nothing essential for correct invocation is missing.

  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 reinforces the command-list semantics and timeout/detach tradeoff, but it largely paraphrases what the parameter docs already say rather than revealing new parameter-specific meaning.

  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 is explicit: 'Runs one command or a list of them on a server and returns the exit code, stdout and stderr of each.' It names the verb, the resource, and the observable result. The closing instruction 'Reach for it last' distinguishes it from the specialized file, log, transfer, health, and job 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 gives explicit when-to-use guidance: long work in minutes should be detached rather than given a longer timeout. It also provides clear when-not-to-use direction by pointing to dedicated tools for files, logs, transfers, health, and jobs that batch round trips and parse answers.

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

• ssh_log_tailA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, and the description adds meaningful behavioral context beyond that: files are never trimmed locally, globs are expanded by the server's find rather than a shell, and names with spaces or newlines remain single paths. This helps an agent understand remote behavior without contradicting the annotation.

  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 tight and front-loaded with the core action, followed by one crucial behavioral nuance and a sibling routing sentence. No sentence is wasted; the glob detail earns its place because it changes how paths are interpreted.

  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 read-only tail tool with a fully detailed schema, no output schema, and no complex side effects, the description covers purpose, edge cases, and the relevant alternative tool. Nothing an agent needs to select and invoke it correctly is missing.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already documents all four parameters. The description adds no new parameter-level meaning beyond what the path schema already states about glob expansion and non-shell handling, so the 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?

  States a specific verb and resource: 'Returns the last lines of one or more log files'. Explicitly distinguishes itself from ssh_log_search by saying the search tool is for finding something instead of reading the end.

  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?

  Gives clear context for when to use the tool (reading the end of log files) and explicitly names the alternative ssh_log_search when the need is to look for something rather than tail. Also clarifies glob expansion behavior that changes how paths should be supplied.

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

• ssh_snapshotA
  4.5/5.0
  Behavior4/5

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

  Annotations already establish readOnlyHint=true, so the read-only nature is covered. The description adds valuable behavioral context: unmeasured values return null and are marked unavailable rather than zero, preventing misinterpretation. This goes beyond annotations by defining output semantics, so a 4 is justified.

  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 with no filler. It front-loads the core purpose, adds the critical null-behavior detail, and ends with 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.

  Completeness5/5

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

  Given that an output schema exists (which explains return structure) and the description covers what it measures, the round-trip efficiency, and the null unavailable convention, nothing essential is missing for an agent to invoke it correctly.

  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 sole parameter 'profile' is already fully described in the schema as 'Machine name.' (100% coverage). The description does not add any further detail about the parameter, so baseline 3 applies—the schema carries the full semantic load.

  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 reports current machine health (cpu, memory, disk, containers, listening ports, services, recent errors) in one round trip, and explicitly contrasts it with ssh_audit_baseline for setup vs. running state. This makes its purpose unambiguous and distinguishes it from siblings.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance on when to use this tool: for current operational status, and when not to (for configuration use ssh_audit_baseline). This directly names the alternative and the condition, leaving no ambiguity about selection.

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

• ssh_tls_checkA
  4.5/5.0
  Behavior5/5

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

  Beyond the readOnlyHint annotation, the description discloses key behavioral details: the handshake is executed on the server so it sees internal-only hosts, null fields mean the check didn't run (not that the certificate is bad), and the sudo flag affects whether renewal config can be read. These are precisely the kind of nuances an agent needs to interpret results correctly.

  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?

  Four sentences, each adding essential information: purpose and perspective, reported fields, error semantics, and usage order. No filler or repetition; the description is tightly structured and front-loads the core function.

  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?

  With an output schema present, the description does not need to detail return values. It covers the operational context (server-side view), the meaning of ambiguous output (null), the effect of sudo, and the recommended invocation order. Nothing an agent needs to call it correctly is omitted.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already documents each parameter. The description reinforces the meaning of 'sudo' and 'domain' in context but does not add new parameter-level semantics beyond what the schema provides. 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 identifies the action (checks TLS certificate), the resource (a domain), and the specific angle (from the server's perspective). It also differentiates from siblings by naming ssh_audit_baseline as a prerequisite, making the tool's role within the suite explicit.

  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?

  It states explicit sequencing ('Run it per domain, once ssh_audit_baseline has named the sites') and indicates the per-domain granularity. It lacks an explicit list of when not to use it, but the context is clear enough; the only minor gap is not naming alternative tools for other checks.

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

• ssh_file_readA
  4.6/5.0
  Behavior5/5

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

  Discloses non-obvious failure behavior: oversized/non-text files produce a named failure instead of a partial file, and unreadable paths do not block the rest. It also reveals the command-channel size limit and transports-vs-command distinction. With only readOnlyHint in annotations, this description carries the behavioral burden well and does not contradict it.

  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?

  Four sentences, each earning its place: purpose, failure semantics, binary routing, and sibling alternative. Front-loaded with the core operation, no filler.

  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?

  Covers purpose, alternatives, failure modes, and binary handling, which is nearly complete for a read-only file tool. The only notable gap is that with no output schema it does not describe the shape of the returned multi-file result (for example, how file contents are keyed).

  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% and the schema already describes path arrays, binary/encoding relationships, and sudo. The description adds operating context, but most parameter meaning is already present in the structured definitions, so it barely moves beyond the baseline.

  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?

  Opens with a specific verb and resource ('Reads text files from a server, several of them in one call') and distinguishes itself from ssh_log_search by pointing out the log-grep alternative. An agent can tell exactly what this sibling does without opening the schema.

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

  Usage Guidelines5/5

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

  Explicitly says to use ssh_log_search when searching inside logs rather than shipping the file here, and says real binary should travel over the transport. These when/not-when rules leave no ambiguity about choosing this tool over alternatives.

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

• ssh_job_outputA
  4.6/5.0
  Behavior5/5

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

  Beyond the readOnlyHint annotation, the description discloses critical behavioral details: the tool is non-consuming (reading again never overlaps or skips a line), merges stdout/stderr, and uses a server-side cursor (the answer names the next offset). This goes beyond the schema and gives the agent confidence that this is a safe, idempotent read-only operation. No contradiction with 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?

  Three sentences, each earning its place. The first gives the core action, the second explains the offset contract, and the third redirects to a sibling for a different concern. No redundancy, perfectly 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 read-only tool with no output schema, the description covers the essential behavior: how to page through output (offset), what data is returned (stdout+stderr), and how to know if more is available (next offset). It could mention error cases like invalid job ID or end-of-output behavior, but the schema and annotations carry a lot of weight. Minor gap keeps it from a 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% (all three parameters have descriptions). The description reinforces the meaning of 'offset' by explaining the next-offset pattern, which is helpful. However, it does not clarify the 'profile' parameter beyond the schema's 'Machine name', and the description does not compensate for that ambiguity. 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 states the tool 'Returns what a detached job has written so far' with explicit details on stream merging ('stdout and stderr together') and pagination ('from a byte offset you choose'). It differentiates from the sibling ssh_job_status by pointing out that status is not this tool's purpose. The verb 'Returns' is specific and the resource is well-defined.

  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?

  It explicitly tells the agent when to use this tool (when you need the output of a detached job) and when not to ('For whether the job is still running, ssh_job_status answers in one line'). It also implies usage context by referencing detached jobs from ssh_exec with detach:true in the parameter schema, so the agent knows the prerequisite.

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

• ssh_log_searchA
  4.7/5.0
  Behavior5/5

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

  Annotations only supply readOnlyHint, so the description carries the behavioral burden. It discloses empty-answer semantics ('An empty answer means no match, never a failed search'), that unreadable files are 'listed apart', and the two-stage time-window filtering behavior. This is meaningful context beyond structured fields and 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?

  Four sentences, front-loaded with the operation and return shape, then caveats, then sibling routing. Every sentence carries distinct information; only 'which is what lets a year of logs finish' is slightly ornamental, but it does not hurt clarity.

  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?

  With a 100%-covered schema and an output schema present, the description adds exactly the missing decision-level context: no-match vs failed-search, unreadable-file handling, time-window mechanics, and the cheaper tail alternative. Nothing essential is missing for correct invocation.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline is 3. The description reinforces namesOnly and since semantics ('paths alone when line bodies are not wanted', 'a time window first skips files...') but does not add parameter-level meaning beyond the already rich input schema.

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

  Purpose5/5

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

  The first sentence states a specific verb ('Greps'), a resource ('log files on the server'), and the two return modes (matching lines with paths, or paths alone). This is easily distinguishable from ssh_log_tail and the 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 Guidelines5/5

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

  Ends with an explicit routing rule: 'For the tail of a file, ssh_log_tail is cheaper.' It clearly implies this tool is for searching log content across files, giving an agent a concrete decision point against the most relevant sibling.

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

• ssh_monitorA
  4.7/5.0
  Behavior5/5

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

  Discloses concrete side effects beyond annotations: close and reload drop live connections, while the other actions only read. It also explains the test output states (ready, limited, no-route, rejected). This does not contradict the annotations; destructiveHint=false is consistent with affecting only transient connections rather than data.

  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 tight sentences: the first scopes and enumerates capabilities, the second gives side-effect warnings and usage guidance. No filler; information is efficiently front-loaded.

  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 tool with two parameters and an output schema, the description covers all actions, side effects, read/write behavior, and a clear starting use case. Nothing an agent needs to select and invoke it correctly appears missing.

  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 fully covers both parameters, including profile requirements per action, so the baseline is 3. The description adds real meaning to the action enum by explaining what stats, reload, test, list, and close actually do, going slightly beyond the schema's generic 'Which of the five to do.'

  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?

  States a precise scope: manages SSH connections, not the machines behind them, and enumerates the five actions (list profiles, test, stats, close, reload). This clearly distinguishes it from the ssh_* sibling tools focused on machine health, file operations, and logs.

  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?

  Gives explicit entry-point guidance: start here on an unfamiliar machine because test tells whether other tools will work. It also warns that close/reload are destructive to live connections while other actions only read, though it does not name specific sibling alternatives or state 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_service_statusA
  4.7/5.0
  Behavior5/5

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

  Beyond the readOnlyHint annotation, it discloses the NOT CHECKED sentinel for non-systemd machines so the agent doesn't misread it as an outage, and clarifies how sudo affects journal trimming. These are valuable non-obvious behaviors.

  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?

  Four compact sentences, each earning its place: purpose, non-systemd sentinel, sudo behavior, and sibling routing. Key scoping information is front-loaded.

  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 read-only status tool with a complete schema and an output schema, this description covers the important edge cases and the main alternative. Nothing essential is missing for correct invocation.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already fully documents all parameters. The description reinforces the sudo/journal-trimming relationship but adds little new parameter-level meaning beyond that.

  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 and resource: it reports one systemd unit and its loaded/active/enabled state plus journal tail. It also distinguishes itself from ssh_audit_baseline by making the single-unit scope explicit.

  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?

  It explicitly routes the multi-failed-unit case to ssh_audit_baseline, telling the agent when not to use this tool. The opening 'Reports one systemd unit' also sets the single-unit scope clearly.

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

• ssh_uploadA
  4.9/5.0
  Behavior5/5

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

  The description discloses critical behaviors beyond the annotations: atomic rename with sha256 verification, directory replacement whole rather than file-by-file, /tmp staging for sudo, disk space implications, and owner permission requirements. This goes far beyond the basic idempotent/destructive hints, providing exact operational expectations.

  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?

  Four sentences, each packed with necessary information: the core operation, the atomicity guarantee, directory replacement and sudo caveats, and tool selection guidance. No word is wasted, and the most crucial details are front-loaded in the first sentence.

  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 destructive nature (destructiveHint: true) and 10 parameters, the description covers all key operational aspects: atomicity, verification, directory behavior, disk space, ownership, and alternatives. Combined with a complete schema and output schema, an agent has everything needed to invoke it correctly.

  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?

  While schema coverage is 100%, the description adds meaningful behavioral context to parameters like sudo (staging in /tmp), owner (requires sudo), and verify (sha256), explaining consequences not obvious from schema alone. It doesn't enumerate parameters but enriches understanding of their side effects, which is more valuable than simple restatement.

  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 opening sentence, 'Copies a local file or directory to a server,' uses a specific verb and resource, immediately clarifying the tool's function. It also distinguishes itself from siblings by explicitly contrasting with ssh_file_write and ssh_exec, making its role unmistakable.

  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 states when to use alternatives: 'For text you can paste, ssh_file_write is cheaper; piping base64 through ssh_exec truncates silently.' This gives clear conditions for choosing this tool over its siblings, leaving no ambiguity about context.

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