Server Quality Checklist

Tool Scores

• ubuntu_read_fileA
  4.1/5.0
  Behavior4/5

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

  With no annotations to lean on, the description carries the full burden and handles it well: it discloses that content is always untrusted, warns callers not to execute embedded instructions, and explains the truncation behavior driven by the 'detailed' flag. It does not, however, describe what happens on missing files or permission failures beyond the generic error contract.

  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 purpose is front-loaded and the Args/Returns sections are neatly organized with no filler. The detailed return-field list is slightly redundant given an output schema exists, but the unified '{ok, data|error}' contract note adds value beyond that schema, so the length is warranted.

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

  Completeness4/5

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

  For a simple 2-param tool with an output schema, the description covers purpose, security posture, parameter behavior, and the return envelope. Minor gaps — concrete error semantics and the practical scope of 'policy-allowed' — do not materially hinder correct invocation.

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

  Parameters4/5

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

  Schema description coverage is 0%, so the description must compensate — and it does. 'detailed' gains real behavioral meaning (full content vs truncated preview), and file_path is given a minimal but sufficient explanation as the file to read. Both parameters are covered adequately for this low-complexity tool.

  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 — 'Read a policy-allowed file' — and names the distinct return envelope. This cleanly separates it from all siblings: execute_command runs commands, list_directory lists entries, write_file writes, and the read tool is the sole content-reading operation.

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

  Usage Guidelines3/5

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

  Usage is implied by the purpose statement and the sibling set, but the description never explicitly names an alternative or gives a when/when-not condition (e.g., 'to see filenames only, use ubuntu_list_directory'). The 'policy-allowed' qualifier hints at a constraint without elaborating on exclusions or prerequisites.

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

• ubuntu_get_system_infoA
  4.2/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full behavioral burden. It discloses that no external commands are run, states the return contract as 'JSON string in unified {ok, data|error}', and explains the difference between compact and detailed output modes. It does not cover permissions or failure conditions, but for a read-only telemetry tool this is solid coverage.

  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 well-structured: purpose, mode behavior, then args/returns. Every sentence earns its place, with no filler or redundant restatement of the tool name.

  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 tool with one optional parameter, the description covers its purpose, output modes, return contract, and the main telemetry fields. The raw payload content is not enumerated, but that is not essential for correct invocation. The description is complete enough for an agent to safely call this tool.

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

  Parameters4/5

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

  Schema description coverage is 0%, so the description must compensate for the bare parameter name 'detailed'. It explicitly explains that detailed=True returns the full raw payload and implicitly that the default/null case uses compact mode, which adds real 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?

  The description opens with a specific verb ('Return') and resource ('host/system telemetry'), making the tool's function immediately clear. It differentiates itself from siblings by explicitly noting it does not run external commands, and the key fields list (OS, memory, disk summary, user, host, platform) further distinguishes it from similar tools like get_server_status.

  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?

  There is no explicit when-to-use/when-not-to-use statement or named sibling alternatives. The phrase 'without running external commands' implies this is the safer alternative to execute_command for telemetry, and 'Compact mode is optimized for agent decision-making' gives a rough selection cue, but the guidance is implied rather than directly stated.

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

• ubuntu_search_packagesA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the return contract ('JSON string in unified {ok, data|error} contract'), the meaning of the detailed flag, and the query format validation. It could additionally state that the operation is read-only or non-mutating, but the word 'Search' and the package-index target make that reasonably clear.

  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 well-structured: a one-sentence purpose statement followed by Args and Returns. Every line adds useful information, and the most important details are 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 two-parameter search tool, the description covers the purpose, parameter semantics, validation, and return format. An output schema exists to handle detailed return structures. The only notable gap is the null behavior of detailed, but overall the agent has enough context to invoke the tool 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?

  The input schema has 0% description coverage, so the description must compensate. It defines the regex requirement for query and explains the True/False behavior of detailed. However, it does not explicitly describe the behavior when detailed is null, even though the schema defaults it to null, so it is not a perfect 5.

  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 ('Search') along with a specific resource ('APT package index') and a 'validated query token' rule. This clearly differentiates it from siblings like ubuntu_install_package or ubuntu_execute_command, since the focus is on querying the package index rather than acting on the system.

  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 usage context is implied by the phrase 'Search APT package index' and the sibling tool names, but there is no explicit guidance on when to choose this tool over alternatives like ubuntu_install_package or ubuntu_get_system_info. It earns an implied-usage score rather than no guidance, because the intended scenario is reasonably clear.

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

• ubuntu_get_server_statusA
  4.3/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. It discloses the output contract ('JSON string in unified {ok, data|error} contract') and parameter behavior for the detailed flag. However, it does not explicitly state whether the tool is read-only, requires special permissions, or has performance implications, which would be more transparent for a status tool with zero annotation coverage.

  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 tightly structured and front-loaded. The core purpose appears in the first sentence, followed by a one-line usage directive, then a concise Args/Returns breakdown. No sentence is wasted.

  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 tool is simple with one optional parameter and an output schema is present per context signals. The description covers what the tool returns, the parameter's effect, and the recommended use scenario. Nothing critical 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.

  Parameters4/5

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

  The schema only provides the type and default for the `detailed` parameter, with 0% schema description coverage. The description adds meaningful semantics: if True it includes extended timing fields and full policy lists, if False it returns a compact view. However, it does not explain the behavior when `detailed` is null, which is a permitted default value.

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

  Purpose5/5

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

  The description states a specific verb and resource: 'Return server health, effective policy snapshot, and tool metrics.' It clearly differentiates this diagnostic tool from siblings like ubuntu_execute_command or ubuntu_read_file, and even frames its role as the first diagnostic tool.

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

  Usage Guidelines4/5

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

  The description explicitly tells the agent when to use it: 'Use this as the first diagnostic tool when automations degrade.' It does not explicitly mention alternatives or when not to use it, but the usage context is clear and actionable.

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

• ubuntu_list_directoryA
  4.4/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full burden. It discloses the policy-allowed path constraint, the two output modes, the unified JSON return contract, and the untrusted_content=true marker on detailed entries. It doesn't cover error behavior or permission nuances, but the critical safety-relevant behavior is disclosed.

  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 well organized: purpose first, then mode behavior, then Args/Returns. Every sentence adds useful information without repetition or fluff.

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

  Completeness4/5

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

  For a simple two-parameter directory listing tool with no annotations, this is nearly complete: it covers purpose, modes, return contract, and the untrusted-content flag. The main missing piece is concrete guidance about what 'policy-allowed path' means and what the unified error contract contains, though the output schema likely covers return structure.

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

  Parameters4/5

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

  Schema description coverage is 0%, and the description compensates by explaining both parameters: path is the directory to inspect, and detailed switches between full listing and a summarized preview. It doesn't clarify path format or detailed=null behavior explicitly, but the default-mode sentence implies null/false treatment.

  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: 'List directory entries for a policy-allowed path.' This clearly distinguishes it from siblings like read_file, execute_command, and search_packages, and the two output modes further refine what the tool does.

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

  Usage Guidelines4/5

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

  Explains when to use the default compact summary (agent planning) versus detailed mode (full metadata), whih gives clear contextual guidance. It does not explicitly name alternatives or state when NOT to use this tool vs. read_file/execute_command, so it falls short of a full 5.

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

• ubuntu_install_packageA
  4.6/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the tool is read-only, does not install packages, uses `apt list --installed`, passes through command-security validation, and returns a unified `{ok, data|error}` JSON contract. This gives strong transparency about side effects and output 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 well-organized: a first-line functional summary, a clarification of the misleading name, an Args section, and a Returns section. Every sentence adds necessary value 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?

  Despite no annotations, the description covers the tool's actual behavior, parameter meaning, safety characteristics, and return contract. For a read-only inspection tool with two parameters, this is sufficient for an agent to select and invoke the tool correctly. The only minor gap is explicit sibling comparison, but that is addressed under usage guidelines.

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

  Parameters5/5

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

  Schema description coverage is 0%, so the description must compensate. It fully explains both parameters: `package_name` includes an explicit regex pattern, and `detailed` explains the behavioral difference between True and False. This is more informative than the bare schema properties alone.

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

  Purpose5/5

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

  The description states a specific verb and resource: 'Check installed-package status using `apt list --installed`.' It explicitly corrects the misleading tool name by saying it does not install packages, which removes ambiguity. This clearly distinguishes it from an installation action and clarifies its role as an inspection helper.

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

  Usage Guidelines3/5

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

  The description gives implied usage context by calling itself a 'read-only package inspection helper' and noting it passes 'command-security validation.' However, it does not explicitly say when to use this tool versus siblings like ubuntu_search_packages or ubuntu_execute_command, nor does it 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.

• ubuntu_write_fileA
  4.6/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full behavioral disclosure burden. It goes beyond a minimal statement by revealing atomic-write semantics via 'temporary-file + atomic move,' backup behavior with timestamped filenames, and the unified {ok, data|error} return contract. It could add failure-mode details, but the disclosed behavior is substantive.

  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 well-structured with a front-loaded purpose statement, compact Args and Returns sections, and no filler. Every sentence contributes behavioral, parameter, or return-value information that an agent needs.

  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 no annotations, no schema-level parameter descriptions, and the presence of sibling tools, this description is unusually complete. It covers what the tool writes, the safety mechanism, backup behavior, create_dirs policy nuance, and the response contract. No critical invocation detail is obviously missing.

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

  Parameters5/5

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

  Schema description coverage is 0%, so the description must compensate, and it does. It clarifies content as a UTF-8 text payload, file_path as the destination, and create_dirs with the important policy-allowed parent-directory condition. This adds real meaning beyond the bare schema titles.

  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 statement: 'Write text content to a policy-allowed file path.' It clearly identifies the destination, content type, and safety constraint, and it is easily distinguishable from sibling tools like ubuntu_read_file and ubuntu_execute_command.

  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 clear context for when to use the tool: when persisting UTF-8 text to a policy-permitted path, and it clarifies the create_dirs behavior under policy restrictions. It does not explicitly compare against alternatives or state when not to use it, but the context is strong enough for an agent to route correctly.

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

• ubuntu_execute_commandA
  4.8/5.0
  Behavior5/5

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

  No annotations are provided, so the description carries the full burden, and it delivers: it discloses shlex parsing, allow/deny validation, no shell expansion in secure mode, blocked chaining, and the output contract including security_notice marking output as untrusted. This is far beyond a generic 'execute a command' statement.

  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 organized into clear sections (purpose, args, returns) and every sentence carries operational information. There is no filler or redundant restating of the schema, and the most important security constraints are 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 generic command execution tool with no annotations, it covers security constraints, argument semantics, and the return contract including both success and error shapes. The presence of an output schema supplements this, but nothing essential is missing for correct and safe invocation.

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

  Parameters5/5

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

  Schema description coverage is 0%, so every parameter needed semantics, and the description provides them all: command must be a single line with no chaining, working_dir is optional and policy-restricted, and detailed controls raw vs compact output. This fully compensates for the bare 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 opening line states a specific verb ('Execute'), a resource ('one validated command'), and a governing constraint ('under the active security policy'). This clearly distinguishes it from the listed sibling tools, which are narrower read/write/package/system operations.

  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 frames the tool as 'for controlled command execution' and spells out what is blocked (chaining, injection patterns, shell expansion in secure mode), giving clear context for when it is appropriate. It does not name specific sibling alternatives to prefer, so it stops short of full when-to-use vs alternative guidance.

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