Server Quality Checklist

Tool Scores

• ssh_file_readA
  4/5.0
  Behavior4/5

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

  Annotations declare readOnlyHint=true, which the description does not contradict. The description adds meaningful behavioral context beyond annotations: unreadable files are reported with the reason, never returned as empty or truncated content, and multiple files can be read in one call. These are useful operational details not captured by 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 two sentences with no filler. The primary purpose and batch capability are front-loaded, followed by error behavior and an alternative tool reference. Every sentence earns its place and the structure is clean.

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

  Completeness4/5

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

  With a rich schema that documents all parameters, the description covers the core behavior (batch read, error handling) and names an alternative. Since there is no output schema, the error-behavior note partially clarifies return semantics, though the exact response structure isn't specified. For a read-only tool, this is adequate and nothing critical 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% — every parameter (path, sudo, binary, profile, encoding) has a detailed schema description with defaults and enums where applicable. The tool description itself adds no additional parameter semantics beyond the schema, so this dimension sits at the baseline for 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?

  The first sentence states a specific verb ('reads') and resource ('text files from a server') and highlights the batch capability ('several of them in one call'). It explicitly distinguishes itself from ssh_log_search, but does not address other siblings like ssh_file_list or ssh_file_write, so differentiation is partial.

  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?

  Provides an explicit alternative: 'To look for something inside logs rather than read them, ssh_log_search greps on the server.' This is clear when-not-to-use guidance for one specific scenario, but it does not mention when to use ssh_file_list or other file tools, so coverage is limited.

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

• ssh_job_killA
  4/5.0
  Behavior4/5

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

  Annotations already declare destructiveHint and idempotentHint. The description adds valuable context: the signal reaches the whole process group, and already-finished jobs are reported as 'gone' rather than a refusal. This goes beyond the annotation hints.

  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 concise sentences that front-load the primary action and then clarify an edge case. No redundancy or 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?

  The description is sufficient for a destructive operation with an output schema. It explains the scope of destruction (process group) and the idempotent edge case. Combined with schema documentation for parameters and annotation hints, an agent has what it needs 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 covers all 3 parameters with descriptions, so baseline is 3. The tool description itself does not add any parameter-specific meaning beyond the schema.

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

  Purpose5/5

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

  States a specific verb (Stops), resource (detached job), and clarifies it reaches the entire process group. Distinguishes from sibling tools like ssh_job_list and ssh_job_status which are non-destructive. Also clarifies behavior for already-finished jobs.

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

  Usage Guidelines3/5

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

  The description implies usage for stopping detached background jobs, but does not explicitly mention alternatives or conditions when not to use. It clarifies that it targets detached jobs, giving scope, but lacks explicit when-not guidance or reference to alternative sibling tools.

  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.2/5.0
  Behavior4/5

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

  The description adds significant behavioral clarity beyond the readOnlyHint annotation: an empty answer means no match, never a failed search, and unreadable files are listed apart. This prevents an agent from misinterpreting an empty result as an error. The readOnly annotation already covers mutation safety, so the added semantics are above baseline.

  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 dense sentences with no wasted words. The core purpose, output distinction, no-match semantics, failure handling, sibling alternative, and container usage are all packed in efficiently.

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

  Completeness4/5

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

  With a full input schema and an output schema present, the description covers the non-obvious behavioral gotchas an agent needs: empty-result semantics, unreadable-file reporting, and the tail alternative. It could have mentioned the output structure explicitly, but the output schema already supplies that.

  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 every parameter thoroughly. The description reinforces the container-by-name notion and the line-bodies-versus-paths choice, but it does not add meaning beyond what the parameter descriptions already supply. 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 opens with a precise verb and object: 'Greps log files on the server and returns the matching lines with their paths.' It also distinguishes the paths-only mode and immediately contrasts itself with ssh_log_tail, so an agent can disambiguate it from the closest sibling without inspecting 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 Guidelines4/5

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

  It explicitly names when a sibling is cheaper: 'For the tail of a file rather than a search through it, ssh_log_tail is cheaper.' It also conveys the container-vs-path usage pattern. It does not enumerate all alternatives among the many siblings, but the relevant distinction is covered.

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

• ssh_monitorA
  4.2/5.0
  Behavior4/5

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

  The description reveals important behavioral nuance beyond the annotations: close and reload drop live connections while the other actions only read. Annotations already signal idempotent and non-destructive, so this is additive rather than repetitive, and it does not contradict the annotations.

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

  Conciseness5/5

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

  Two sentences, front-loaded with the core scope and followed by practical guidance. Every phrase earns its place; there is no redundant filler or repetition of schema content.

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

  Completeness4/5

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

  With only two parameters, an output schema, and strong annotations, the description covers the essential usage guidance, side-effect differences, and conceptual scope. It could explicitly enumerate which action to use in which scenario, but the existing context is sufficient 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 coverage is 100%, with both parameters already well described in the schema. The description adds a high-level summary of actions but does not materially improve on the schema's per-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.

  Purpose5/5

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

  The description clearly states a specific verb-and-resource purpose: managing SSH connections themselves, listing profiles, testing, reporting pool stats, closing, and reloading. It explicitly distinguishes itself from tools that operate on machines behind the connections, which differentiates it from the many ssh_ sibling 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?

  It gives concrete usage context: 'Start here on a machine you have not used yet' and recommends that 'test names the state before anything else runs.' It does not explicitly name which sibling tools to use instead, but its scope exclusion ('not the machines behind them') makes the appropriate context clear.

  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.3/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 reinforces this with 'Reads only, nothing is deleted.' It adds useful context about what areas are inspected (docker, journald, package caches) without contradicting the annotations.

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

  Conciseness5/5

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

  Two tight sentences. The first explains scope and read-only behavior, and the second routes to the alternative for a different need. There is no filler or repeated schema content.

  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 rich input schema, an output schema, and a readOnlyHint annotation, the description covers what an agent needs: what it inspects, that it is safe, and how it relates to ssh_snapshot. No critical behavioral or selection information 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 does not add parameter-specific meaning beyond the schema, but it does relate the tool's purpose to the 'paths' concept. It neither improves nor harms parameter understanding.

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

  Purpose5/5

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

  The description opens with a specific verb-resource pair ('Finds what filled a disk') and enumerates the concrete outputs: free space per filesystem, largest directories per path, and cache contents. It also differentiates itself from ssh_snapshot by framing this as the detailed breakdown versus the one-line fullness answer.

  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 gives a clear alternative and selection rule: use ssh_snapshot when only overall disk fullness is needed, and this tool when a breakdown is required. It could be slightly more explicit about when not to use the tool, but the guidance is strong enough for an agent to make the right choice.

  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.3/5.0
  Behavior4/5

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

  Annotations already mark the tool as read-only, so the description adds value by explaining the 'lost' status semantics and clarifying that 'lost' does not mean the work failed. It also discloses that the output remains available via ssh_job_output, which is useful behavioral context beyond what the annotations state.

  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 convey the core purpose, the extra output detail, and the important 'lost' edge-case semantics. Every phrase carries meaning, and the key 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 simple read-only status tool with complete schema descriptions and an output schema present, the description covers all essential context. The 'lost' clarification removes a likely source of confusion, and the readOnlyHint addresses safety.

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

  Parameters3/5

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

  The input schema already provides 100% parameter coverage with descriptive text for both 'id' and 'profile', including the note about sudo. The tool description itself adds no additional parameter-level meaning, so the baseline of 3 applies.

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

  Purpose5/5

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

  The description uses a specific verb ('Reports') and a specific resource ('the state of a detached job'), and also states it includes the last lines written for progress visibility. This distinguishes it from sibling tools like ssh_job_output (which retrieves full output) and ssh_job_list (which lists jobs).

  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 clear when to use this tool: to check the state of a detached job and see where it got to via its last lines. It also gives an implicit when-not by pointing to ssh_job_output for cases where the job is 'lost' but output still exists. It does not explicitly contrast with ssh_job_list, but the single-job framing is enough.

  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
  Behavior4/5

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

  Beyond the destructiveHint annotation, the description adds behavior: each command returns its own exit code, stdout, and stderr, and long-running work should be detached rather than given a bigger timeout. It doesn't fully warn about the arbitrary-command risk, but the annotation and phrasing imply raw execution.

  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 carry both the core behavior and the key usage caveat. Every clause earns its place, and the most important routing guidance comes second but remains succinct.

  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 combination of a rich schema, output schema, and a description that covers command granularity and tool routing gives an agent enough to invoke this correctly. It does not name the exact sibling tools, but the categories are identifiable from the sibling list.

  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 explains every parameter. The description reinforces the detach-vs-timeout tradeoff at a high level, but adds no new parameter-specific meaning. 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 states a specific verb and resource: running one command or a list on a server, with per-command exit code, stdout, and stderr. It also differentiates from specialized siblings by saying files, logs, transfers, health, and jobs each have their own tool, making this the raw fallback.

  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?

  Provides explicit when-not-to-use guidance: work measured in minutes belongs in detach, not a longer timeout. It also tells the agent to prefer category-specific tools because they batch round trips and parse answers, which is clear routing advice.

  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.4/5.0
  Behavior4/5

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

  Annotations declare readOnlyHint=true, which covers safety, and the description adds meaningful behavioral context: reads only output produced 'so far' (non-blocking), merges stdout and stderr, and supports reading from a chosen byte offset with the next offset returned. This goes beyond annotation data without contradicting 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?

  Two sentences carry the full purpose, the key behavioral detail, and the alternative-tool routing. The most important information is front-loaded, and there is no filler or repetition of schema fields.

  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 streaming tool with a complete schema, the description is largely sufficient: it conveys non-blocking behavior, combined streams, byte-offset seeking, and the cursor semantics. There is no output schema, so a bit more detail about the exact return shape would push this to 5, but nothing essential to invoking 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 three parameters. The tool description itself does not add new parameter-level meaning beyond what the schema says; it merely restates the offset concept. This meets the baseline for full schema coverage but does not exceed it.

  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 opens with a specific verb and resource: 'Returns what a detached job has written so far', and clarifies that stdout and stderr are combined. It also distinguishes this from ssh_job_status by explicitly contrasting output content with run-state. This leaves no ambiguity about the tool's core function.

  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 second sentence gives clear routing guidance: if an agent cares whether the job is still running, use ssh_job_status instead. This is an explicit condition that selects between two closely related siblings, which is exactly what an agent needs.

  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.4/5.0
  Behavior4/5

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

  Beyond the readOnlyHint annotation, the description adds behavioral context: 'whatever their size — nothing is shipped here to be trimmed locally' and explains container resolution 'through the file its driver writes.' These clarify how the tool behaves 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?

  Three purposeful sentences: core behavior and scope come first, container nuance follows, and the sibling alternative closes. No filler, no repetition of schema details.

  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 tail tool, the description plus fully described schema covers file paths, globs, container mode, sudo behavior, and search routing. It does not describe the return format, but that is reasonably inferable from 'returns the last lines' and no output schema exists.

  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 parameter descriptions already carry the meaning. The main description adds tailing/container framing but does not materially extend individual parameter semantics beyond what the schema 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?

  States a specific verb and resource: 'Returns the last lines of one or more log files'. It also distinguishes itself from the sibling ssh_log_search by explicitly contrasting tailing with searching for something.

  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 routes the agent: 'To look for something rather than read the end, use ssh_log_search.' It also clarifies the container-read path vs ordinary file paths, giving concrete context for when each mode applies.

  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.4/5.0
  Behavior5/5

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

  Beyond the readOnlyHint annotation, the description reveals that the handshake is made from the server itself, so it sees hosts closed to the outside, and clarifies that null fields mean the check could not run rather than certificate failure. This is meaningful behavioral context the annotation does not provide.

  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 information-dense and front-loads the core purpose, then adds null semantics and usage sequencing. The first sentence is a bit long with several em-dash interruptions, but every clause adds signal and there is no 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?

  With annotations declaring read-only behavior, an output schema present, and 100% parameter coverage, the description adds the remaining needed context: what the check sees, how to interpret nulls, and when to run it relative to ssh_audit_baseline. Nothing critical is missing for an agent to select and call this tool 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 input schema already documents all five parameters. The tool description adds useful context around domains and null results, but it does not add new parameter-level meaning beyond what the schema provides, matching the baseline of 3.

  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 ('Checks') and resource ('the TLS certificate a domain serves'), and enumerates the concrete outputs: days left, SAN match, issuer, renewal configuration. This clearly differentiates it from sibling SSH tools like ssh_exec or ssh_audit_baseline.

  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 explicitly says to 'Run it per domain, once ssh_audit_baseline has named the sites,' giving a clear prerequisite and invocation pattern. It does not enumerate when not to use it or name alternatives, but the sequencing guidance is actionable and specific.

  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?

  The annotation already declares readOnlyHint=true, and the description reinforces this with 'Reads only'. It adds useful behavioral context beyond the annotation by stating that sections are marked CRITICAL/WARNING/OK and that it replaces 'a dozen commands' in one round trip. 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 with no filler: the first defines purpose and output shape, the second states safety and efficiency, and the third routes to the sibling tool. The most important 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 audit tool, the description covers what it reports, how the output is categorized, why it is efficient, and which sibling to use in the alternate use case. Combined with full parameter documentation and an output schema, nothing essential 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%, with every parameter documented including defaults and allowed values. The tool description contributes high-level context but does not need to compensate for missing parameter docs, so the 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 opens with a specific verb and resource: 'Reports how a machine is set up', then enumerates exact domains (sshd, firewall, updates, services, docker, ports, disk) and the severity marking scheme. It also distinguishes itself from ssh_snapshot, so an agent can tell it apart from the closest sibling.

  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 routing guidance: 'For load and health at this moment rather than settings, use ssh_snapshot.' It also frames the tool as a one-round-trip setup audit, making the intended use case clear without ambiguity.

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

• ssh_downloadA
  4.5/5.0
  Behavior4/5

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

  Annotations already provide idempotentHint and destructiveHint, and the description adds meaningful behavioral detail: 'checked by sha256 on both sides.' This goes beyond the annotations by explaining the verification mechanism. It does not explicitly state that an existing local_path may be overwritten, but the destructiveHint annotation covers the general risk, and the schema's verify parameter adds mismatch semantics.

  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 concise sentences with no redundant wording. The core action and verification detail are front-loaded, and the sibling alternative follows in a clearly conditional form. Every sentence contributes useful information.

  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 rich input schema, output schema, and annotations, the description is complete enough for an agent to know what the tool does, when to use it, and when not to. It covers direction, verification, and the key sibling alternative, with no missing information necessary 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 documents all seven parameters in detail. The description adds no parameter-level meaning beyond the schema; it only restates the overall transfer and verification behavior. A baseline of 3 is appropriate since the schema carries the semantic weight.

  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 action and resource: 'Copies a file or directory from a server to this machine.' This clearly identifies the tool's direction and purpose. It also differentiates from ssh_file_read by noting the alternative is for reading text without keeping a copy, and the title 'Download from a server' reinforces the intent.

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

  Usage Guidelines5/5

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

  The description explicitly provides an alternative and a usage condition: 'To read a text file rather than keep it, ssh_file_read skips the disk.' This tells an agent when to prefer a sibling tool instead. The copy direction is unambiguous, so there is no confusion with ssh_upload.

  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.5/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 discloses that files are replaced whole, atomically, and never appended to. This adds useful behavioral context that the annotations alone do not provide.

  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, all high-signal: the core action, the atomic/replace behavior, and the sibling alternative. No filler or redundant restatement.

  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 rich input schema, annotations, and output schema, the description covers the essential behavioral semantics and alternative routing. Nothing critical is missing for an agent to invoke this 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 explains each parameter thoroughly. The description contributes the multi-file and per-file ownership/sudo framing, but most parameter-level meaning is in 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?

  States a specific verb and resource: writes files on a server. It also differentiates itself from the closest sibling by saying anything already on this machine should use ssh_upload.

  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 names ssh_upload as the alternative for files that already exist locally, and clarifies the tool supports multiple files in one call. The no-append note also sets an important boundary.

  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/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 detail beyond that: it lists detached jobs including sudo-started ones, and clarifies that only IDs and states are returned. This goes beyond the annotation without contradicting 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?

  Two sentences with no filler. The core purpose is front-loaded, followed by a scope caveat and a pointer to an alternative. Every clause 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?

  For a simple one-parameter read-only tool with an output schema, the description is complete. It explains scope, inclusion of sudo jobs, return content, and when to use it, while relying on annotations and the output schema for the rest.

  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% because the only parameter, 'profile', is documented as 'Machine name.' The description does not add parameter-level meaning beyond the schema, 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 states a specific verb ('Lists') and resource ('detached jobs on a machine with their state'), and adds a distinguishing constraint ('jobs started with sudo included'). It also explicitly differentiates itself from ssh_job_output by limiting scope to 'Ids and states only', so an agent can select it correctly.

  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 when-to-use guidance: 'for when an id was not kept'. It also names the alternative for related needs: 'for what a job printed, use ssh_job_output'. This directly helps an agent choose between sibling tools.

  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_file_listA
  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 useful behavioral edge cases: unreadable directories are named rather than silently omitted, and listings truncated by the output limit are explicitly flagged. This gives the agent accurate expectations for permission failures and large listings.

  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 tight sentences with no filler: core purpose first, then key behavioral guarantees, then the routing note to ssh_file_read. Every sentence 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?

  With a readOnlyHint, 100% schema parameter coverage, and an output schema present, the description covers the remaining contextual needs: result contents, error behavior, truncation signaling, and the relationship to the closest sibling. Nothing essential 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 input schema fully documents all five parameters. The description adds context about output fields and truncation but not new parameter-level semantics, matching the baseline for fully documented schemas.

  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 opens with a specific verb and resource: 'Lists a directory on a server' and names the returned fields (size, mode, owner, modification time). It distinguishes itself from ssh_file_read by explicitly directing file-content needs to that sibling.

  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 clearly states the tool's use case (listing directories) and provides an explicit alternative for the adjacent case ('To see what is inside a file, use ssh_file_read'). No ambiguity remains about which sibling to pick for file-content access.

  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?

  With readOnlyHint=true, the safety profile is already known, so the description adds valuable behavioral context beyond annotations: the NOT CHECKED distinction for non-systemd machines and the journal-tail behavior. This prevents a false outage conclusion and clarifies return semantics.

  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 with no filler. The main purpose is front-loaded, and each subsequent sentence contributes either a behavioral caveat or a sibling alternative. Nothing is repeated from the schema.

  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 and the input schema fully documents parameters, the description covers the essential agent-facing context: single-unit scope, journal tail, systemd-absence semantics, and the relevant sibling tool. No critical gap remains.

  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 input schema already documents all five parameters well. The description does not materially add parameter-level detail beyond the schema, so the baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description opens with a specific verb and resource: 'Reports one systemd unit: whether it is loaded, active and enabled, with the tail of its journal.' It also differentiates from ssh_audit_baseline by noting that sibling names failed units at once, making the tool's single-unit scope clear.

  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 an explicit alternative and condition: 'For every failed unit at once, ssh_audit_baseline names them.' It also provides a crucial usage caveat—machines without systemd return NOT CHECKED, not stopped—so an agent knows when not to interpret the result as an outage.

  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?

  Beyond the idempotentHint and destructiveHint annotations, the description discloses the critical behavior: sha256 verification on both sides, atomic writes that are never half-left, and full replacement of the target directory unless merge:true is set. This is substantive behavioral detail, not just a restatement of 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 states the action and key guarantees, the second clarifies the destructive directory behavior, and the third routes to an alternative. 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?

  Given the rich parameter schema, the output schema, and annotations, the description covers the essential operational invariants: atomicity, verification, destructive replacement, and the relevant alternative. Nothing needed to correctly invoke the tool is 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 already covers all 11 parameters richly, so the baseline is 3. The description adds cross-cutting meaning not obvious from individual parameters: the transfer is atomic, directories replace the target whole, and verification is built in. This is useful, but the per-parameter semantic burden is largely carried by 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 opens with a specific verb and resource: 'Copies a local file or directory to a server.' It also distinguishes itself from siblings by noting that ssh_file_write is cheaper for pasteable text, making the tool's role clear against the other SSH 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 gives a decision rule: for text you can paste, use ssh_file_write instead, and warns that piping base64 through ssh_exec truncates silently. This tells an agent when not to use this tool and which sibling to prefer.

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