Server Quality Checklist

Tool Scores

• control_serviceB
  3.3/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It does make the mutating nature explicit ('start, stop, or restart') and notes a precondition about command control. However, it does not mention permissions, reversibility, side effects, or what happens if command control is not enabled.

  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 with no filler. The core action is front-loaded and the enabling-condition is included without bloating the text.

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

  Completeness2/5

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

  For a mutating control tool with no annotations and three required parameters, the description is too sparse. It omits how command control is enabled, whether elevated privileges are needed, what happens on failure, and how the device parameter influences the operation. The output schema may cover return values, but preconditions and operational context are missing.

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

  Parameters2/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 adds meaning for 'service' as the target and for the action values via the verbs, but it does not explain the 'device' parameter, its allowed values, or how services are named or resolved on each device.

  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: start, stop, or restart a systemd service. It names the resource type and the specific actions, distinguishing it from sibling read-only tools like get_service_status and get_service_logs.

  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 given about when to use this tool versus alternatives such as run_command or get_service_status. The prerequisite 'after command control is explicitly enabled' is mentioned but not explained, and no exclusions or alternative tool routing are provided.

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

• get_raspberry_pi_statusA
  3.5/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the burden of behavioral disclosure. It clearly indicates a read operation and lists the metrics returned, but it does not mention failure modes, permissions, or whether values are live snapshots.

  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, front-loaded sentence with no filler. Every word contributes to defining the tool's purpose and output scope.

  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 read tool with an output schema, the description covers the essential data being read and the target resource. It does not provide usage guidance or potential error context, but the schema and simple scope reduce the need for more.

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

  Parameters2/5

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

  Schema description coverage is 0%, and the description never mentions the required 'device' parameter or its valid values (rpi5, rpi3bplus). The enum in the schema carries the semantic meaning, but the description does not compensate for the low coverage.

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

  Purpose5/5

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

  The description uses a specific verb ('Read') and enumerates the exact resources (hostname, kernel, uptime, memory, disk, CPU temperature) from a Pi. This clearly distinguishes it from siblings like list_raspberry_pis, get_service_status, and read_text_file.

  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?

  There is no explicit guidance on when to use this tool versus alternatives, and no mention of exclusions or prerequisites. Usage is only implied by the verb and resource list; it does not explain how this relates to list_raspberry_pis or get_service_status.

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

• get_service_logsA
  3.5/5.0
  Behavior3/5

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

  With no annotations, the description carries the behavioral burden. It clearly signals a read-only operation scoped to the newest entries for one service, but it does not disclose how the optional lines parameter affects results, unit name expectations, or possible failure modes. This is adequate but not rich.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence with no filler or redundant restatement of the tool name. It conveys the essential operation and scope economically.

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

  Completeness3/5

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

  For a simple read-only tool with an output schema, the description plus schema covers the basic call. However, it omits usage routing and the effect of the optional lines parameter, so it is not fully complete for an agent that has not seen the sibling contexts.

  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 0%, so the description must compensate. It clarifies that service means a systemd service and that the target is a Pi, but it does not explain the lines parameter, leaving its semantics to inference from the default value and parameter name.

  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 (Read) and resource (newest journal entries for one systemd service on a Pi). This differentiates it from sibling tools like control_service and get_service_status, which target service control and status rather than journal output.

  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?

  It provides no when-to-use or when-not-to-use guidance, and names no alternative tool. The only usage signal is implicit in the purpose statement, so an agent cannot tell from the description when to prefer this over get_service_status or run_command.

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

• run_commandA
  3.5/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 disclosing behavioral traits. It mentions the operator-gating requirement, but for a tool that executes an arbitrary remote command, it does not disclose execution context, privileges, potential side effects, or how command control is checked.

  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 front-loaded sentence with no filler. It states the core action first and then the critical precondition, making it efficient and easy to parse.

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

  Completeness2/5

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

  For a high-risk arbitrary command execution tool with no annotations and minimal parameter coverage, the description is too thin. The output schema may cover return values, but the description still fails to provide enough operational and safety context for safe invocation.

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

  Parameters2/5

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

  Schema description coverage is 0%, and the description does not explain the device, command, or timeout_seconds parameters. The schema provides a device enum and a timeout default, but the description adds no meaning to the free-form command parameter or how it should be formed.

  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 and resource: it runs an arbitrary remote command, which clearly distinguishes it from sibling tools that read files or manage services. The added precondition about operator command control further sharpens its identity as a gated execution 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 gives a clear, explicit precondition: it may only be used after the operator enables command control. It does not explicitly name alternatives or state when not to use it, so it falls just short of full guidance.

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

• get_service_statusA
  3.6/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. It conveys that this is a read-only status query against systemd, which implies no mutation, but it does not disclose potential behaviors such as authentication needs or behavior when the service is not found. The read-only nature mitigates the concern, but the description is still thin.

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

  Conciseness5/5

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

  The description is a single sentence with no filler. It front-loads the action and the resource, and every word contributes to the meaning.

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

  Completeness3/5

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

  For a simple two-parameter tool with an output schema, the description is close to adequate, but it leaves usage differentiation and parameter semantics underspecified. An agent can probably invoke it correctly, but not with strong confidence about when it is the best choice over sibling tools.

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

  Parameters2/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 clarifies that 'service' is a systemd service and 'device' is a Pi, but does not define service name format, device scope, or how the two parameters interact beyond that. This adds minimal value over the raw parameter names.

  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 ('Get'), a specific resource ('detailed systemd status'), and scopes it to 'one service on a Pi'. This clearly distinguishes it from device-level status retrieval (get_raspberry_pi_status) and from log or control operations (get_service_logs, control_service).

  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 intended use is implied by 'status for one service' versus the sibling tools, but no explicit when-to-use or when-not-to-use guidance is provided. An agent can infer it is for service-level status rather than logs or actions, but the description does not name alternatives or exclusions.

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

• power_actionA
  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 burden of behavioral disclosure. It does disclose the important gating requirement ('opt-in and confirmation') and the disruptive nature of reboot/shutdown. Yet it is vague about what 'separate power-control opt-in' means and does not describe side effects, permissions, or irreversible consequences.

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

  Conciseness5/5

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

  A single, front-loaded sentence that efficiently communicates the core action and a critical precondition. There is no redundant or filler content; every word contributes to understanding.

  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 minimally adequate for a 3-parameter, destructive tool with no annotations. It names the actions and the opt-in/confirmation requirement, but it lacks detail on how to obtain the opt-in, what the confirmation means operationally, and what the tool returns. The output schema may cover return values, but the external opt-in process remains unexplained.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description should compensate for parameter meaning, but it does not mention any parameters. The schema itself provides useful enums and the confirmation constraint, but the description adds no value to parameter understanding beyond restating 'confirmation'.

  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 specific action ('Reboot or shut down a Pi') and the resource type (Pi), which distinguishes it from sibling tools like control_service, run_command, and status tools. Even without naming siblings, an agent can reliably understand what this tool is for.

  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 context for use: power actions on a Pi. It also includes a strong precondition: 'only after a separate power-control opt-in and confirmation', which tells the agent when it is appropriate to invoke. However, it does not explicitly compare against alternatives or state when not to use it.

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

• read_text_fileA
  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 behavioral transparency burden. It explicitly states the operation is non-mutating ('without modifying it') and caps the read at one MiB, which are useful behavioral guarantees. More detail on error conditions or binary-file handling would be nice, but the key safety trait 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?

  A single, front-loaded sentence with no filler. It communicates the action, the target, the limit, and the non-destructive nature 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?

  For a simple file-read operation with an output schema present, the description covers the essential context: what is read, from where, how much, and the non-modifying guarantee. It could add explicit notes about required access or failure modes, but the tool is straightforward enough that those omissions are not critical.

  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 0%, so the description must compensate, but it only adds the one MiB limit. The parameter names (device, path, max_bytes) are reasonably self-explanatory and device has an enum, but the description does not explain how max_bytes relates to the one MiB cap, path format expectations, or any parameter-specific behavior beyond what the schema structure implies.

  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 clear verb ('Read') with a specific resource ('text file from a named Pi') and a scope limit ('up to one MiB'). It distinguishes this tool from sibling commands that manage services, run commands, or control power, leaving no ambiguity about what this tool is for.

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

  Usage Guidelines4/5

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

  The description clearly implies when to use this tool: when you need to read a text file from a Pi. It does not explicitly contrast with alternatives like get_service_logs or run_command, but the resource and read-only nature provide enough context for correct selection.

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

• list_raspberry_pisA
  4.3/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 burden of behavioral disclosure. 'List' clearly signals a non-mutating operation, and 'available to this MCP server' adds useful scoping context. It does not explicitly state that no state changes occur, but for a simple listing operation this is a minor 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 a single, front-loaded, unambiguous sentence. Every word contributes meaning: it lists, it is scoped to named Raspberry Pis, and it is limited to those available to the server.

  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 zero-parameter enumeration tool with an output schema present, the description is fully adequate. It identifies the resource and the scope without needing to explain parameters or return values, since those are handled by the schema.

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

  Parameters4/5

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

  The tool takes zero parameters, and schema coverage is 100%, so there are no parameter semantics to document. The description correctly does not attempt to invent parameter information.

  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 ('List') and resource ('named Raspberry Pis available to this MCP server'), making the tool's purpose immediately clear. It also distinguishes itself from siblings like get_raspberry_pi_status, which targets status rather than enumeration.

  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 when to use this tool: when you need an inventory of the Raspberry Pis available to the MCP server. However, it does not explicitly mention alternatives or exclusions, such as using get_raspberry_pi_status when you need status for a specific Pi.

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