Server Quality Checklist

Tool Scores

• write_fileB
  3.3/5.0
  Behavior2/5

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

  There are no annotations, so the description must fully disclose behavioral traits. It does not state whether the file is overwritten, whether parent directories are created, or what permissions are needed. The only extra context is 'remote server', which adds minimal value.

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

  Conciseness5/5

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

  The description is a single, concise sentence that directly states the tool's purpose. It has no unnecessary words or repetition.

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

  Completeness3/5

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

  The tool is simple with only 2 params and no output schema, but the description lacks details about overwrite behavior, return values, or creation of parent directories. It is minimally complete for a basic write operation but leaves some important questions unanswered.

  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 both parameters clearly. The description adds no additional parameter-specific meaning beyond the remote server context, so baseline 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 clearly states the verb 'write' and the resource 'content to a file on the remote server'. It is specific and distinguishes from siblings like read_file and list_directory by indicating a write operation.

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

  Usage Guidelines2/5

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

  No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or comparison with sibling tools like execute_command or read_file.

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

• execute_commandA
  3.5/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full responsibility for behavioral disclosure. It reveals that the tool returns stdout, stderr, and exit code, but omits important traits such as side effects (e.g., modifying system state), required permissions, or shell environment. For a command execution tool, this is a significant gap.

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

  Conciseness5/5

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

  The description is only two sentences, front-loaded with the tool's purpose and followed by return-value information. Every sentence contributes meaning, with no unnecessary fluff.

  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?

  With no annotations or output schema, the description covers the primary function and return format, which is adequate for a simple two-parameter tool. However, it lacks safety caveats, usage boundaries relative to sibling tools, and any mention of environmental context, leaving it minimally complete.

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

  Parameters3/5

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

  Schema description coverage is 100%, and the parameter descriptions in the schema (e.g., 'The shell command to execute') already provide clear meaning. The description adds no additional parameter details, so the baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states it executes a shell command on the remote server, using a specific verb+resource structure. It distinguishes itself from sibling tools like read_file, write_file, and connect_ssh by targeting arbitrary command execution.

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

  Usage Guidelines3/5

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

  The description implies it should be used when a shell command needs to run, but it provides no explicit when-to-use or when-not-to-use guidance, and does not reference alternatives. Sibling tool context exists but is not leveraged in the description.

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

• list_directoryA
  3.6/5.0
  Behavior2/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, but it only states the basic action. It does not mention whether listing is recursive, includes hidden files, what error occurs for invalid paths, or the output format. This is a sparse disclosure for a tool that will be used in scripted contexts.

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

  Conciseness5/5

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

  The description is a single, focused sentence with no redundant words. It front-loads the action and resource, making it easy for an agent to parse quickly. Length is appropriate for the tool's simplicity.

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

  Completeness2/5

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

  The tool has no annotations and no output schema, so the description must compensate by explaining what the tool returns and how it behaves in edge cases. It only says 'list contents' without specifying the response structure (e.g., file names only, metadata, sorting) or handling of errors like nonexistent directories. This leaves a significant gap for an agent to correctly interpret results.

  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 documents the only parameter 'path' with a clear description including default behavior (home directory). Schema coverage is 100%, so the description does not need to add parameter details. Baseline of 3 applies because the schema handles the semantics effectively.

  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 'List contents of a directory on the remote server' clearly specifies the action (list) and resource (directory contents) within a remote context. This distinguishes it from siblings like read_file (reads files) and write_file (writes files), making its purpose unmistakable.

  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 context for use: whenever directory contents need to be listed. It does not explicitly name alternatives or exclusion cases, but the siblings are visually distinct (execute_command, read_file, write_file, connect_ssh), so the tool's scope is evident. Lacks explicit 'when not to use' guidance.

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

• connect_sshA
  3.7/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries the full burden of disclosing behavior. It only restates the fact of connecting and gives a usage order; it does not mention session persistence, key generation, or other side effects that would be relevant for an SSH connection tool.

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

  Conciseness5/5

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

  Two short sentences that each serve a purpose: one states the function, the other gives ordering guidance. There is no wasted words or redundant information.

  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 is minimal and does not explain the implications of establishing a connection (e.g., whether it persists for subsequent commands or what authentication flow occurs). However, the schema covers the password/key generation detail, and there is no output schema needed, so the description is not entirely incomplete.

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

  Parameters3/5

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

  The input schema has 100% description coverage for all parameters, so the schema already documents parameters. The tool description adds no additional 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?

  The description clearly states the tool's function: connecting to a remote SSH server. The phrase 'Use this first before any other operations' distinguishes it from the sibling operation tools by indicating it is a prerequisite step.

  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 instructs to use this tool before any other operations, providing a clear when-to-use guideline. It does not mention when not to use it or alternatives, but the sibling tools are operations that logically depend on this connection, so the guidance is sufficient.

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

• read_fileA
  3.8/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden for behavioral disclosure. It correctly indicates a read-only operation ('Read the contents'), which is non-destructive, but it does not disclose error behavior, return format, or any limitations (e.g., binary files). This is minimally adequate but lacks depth.

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

  Conciseness5/5

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

  The description is a single concise sentence that is front-loaded with the action and resource. Every word earns its place, with no redundancy or 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?

  For a simple one-parameter tool with a 100% schema, the description is mostly complete. It lacks an explicit statement about the return value (since there is no output schema), but 'Read the contents' implies the file data is returned. Adequate overall, though a note on encoding or error handling would improve it.

  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% (path described as 'Absolute or relative path to the file'), so the schema already documents the parameter. The description adds no additional meaning beyond what's in the schema, which is acceptable but not enhancing.

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

  Purpose5/5

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

  The description clearly states the action ('Read the contents') and the resource ('a file from the remote server'). It is distinct from sibling tools like write_file (write), list_directory (list), execute_command (execute), and connect_ssh (connect).

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

  Usage Guidelines3/5

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

  The description implicitly indicates when to use this tool (for reading files) but does not explicitly state when not to use it or mention alternative tools. Sibling names like write_file suggest the contrast, but no explicit guidance is provided.

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