Server Quality Checklist

Tool Scores

• service_restartA
  3.6/5.0
  Behavior4/5

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

  描述披露了写入操作、非幂等性和重复调用会中断服务，这些信息在annotations中未提及（annotations仅有destructiveHint），补充了关键行为。但没有说明权限要求或返回格式等，不过仍有实质增量。

  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?

  两句话简洁明了，第一句说明功能和写入性质，第二句补充参数和幂等性，没有冗余，信息密度高。结构合理，关键信息前置。

  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?

  有输出schema但内容未知，描述中通过引用service_start的返回结构提供间接说明。但confirm参数如何填写（如需要什么值）未说明，依赖外部定义，整体完整性一般。

  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覆盖率为0%，描述指出'参数与返回结构同service_start'，提供了参考路径但未直接解释每个参数。对于已知service_start的用户有帮助，但独立使用仍显不足，因此评分中等。

  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?

  描述以'重启指定服务'开头，明确动词和对象，并注明是写入操作。但未直接说明与service_start、service_stop的区别，如重启与先停再起的差别，因此未完全区分开兄弟工具，但基本清晰。

  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?

  提到'需二次确认'暗示应谨慎使用，且强调非幂等和重复中断，提供了使用时的注意事项。但未明确说明何时应该用restart而不是start或stop，也没有排除场景。

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

• router_infoA
  3.7/5.0
  Behavior3/5

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

  Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description reinforces this by using the read-only verb '查询' and disclosing the return structure, which adds context about the sort of diagnostic data provided. It does not go deeper into operational behavior beyond what annotations already state, so a 3 is appropriate.

  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 efficient: one line states the purpose, then a compact return structure is provided. The return structure is helpful and well organized, though the scattered fields inside the 'data' object could be slightly more compact. Overall every sentence earns its place.

  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 adequately covers what an agent needs to know to call this parameterless, read-only diagnostic tool. It explains the key data sections and the availability of an output schema means result documentation is already present. It could mention how this information supports other actions, but that is not essential for 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?

  The tool has zero parameters and schema description coverage is 100%, so there is nothing for the description to add. Baseline for 0 params is 4; the description simply confirms no inputs are needed.

  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 queries SSH connection health, detected init system, device system, and effective security policy. It uses a specific verb (查询/'query') with a concrete resource (router information), which is distinct from the sibling service_* and run_shell tools.

  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 explicit guidance is given on when to use this tool versus alternatives. The description only lists what it returns; it doesn't say that it is diagnostic, that it should be used before service operations, or when another tool would be a better choice. Usage must be inferred.

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

• service_stopA
  3.8/5.0
  Behavior4/5

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

  Annotations already provide destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the bar is lower. The description adds meaningful behavioral context: '需二次确认' (requires second confirmation) and the warning that stopping ssh/dropbear will interrupt the connection, both of which are absent from the annotations and schema.

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

  Conciseness5/5

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

  The description is compact and front-loaded: the first clause states the operation, followed by confirmation and connection-risk warnings. Every sentence contributes useful information with no filler 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 description covers the key safety context and confirms the return-structure relationship to service_start, and an output schema exists. However, it relies on sibling service_start for parameter semantics and does not specify how the confirm parameter should be set, leaving a real gap for a destructive tool.

  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 only says parameters mirror service_start without explaining 'name' or the expected value/format of 'confirm'. Even though the confirmation requirement is implied, the agent is left with insufficient information about how to satisfy the confirm parameter.

  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 '停止指定服务' (stop specified service), naming both the verb and the target resource. This distinguishes it from siblings like service_start and service_restart, and it additionally flags that this is 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 Guidelines3/5

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

  The usage is implied by the verb 'stop', but there is no explicit when-to-use versus alternatives guidance. The description does add a valuable warning about stopping ssh/dropbear causing disconnection and mentions the confirmation requirement, which helps the agent execute correctly but not select the tool.

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

• service_listA
  4.2/5.0
  Behavior4/5

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

  Annotations already mark the tool as readOnly, idempotent, and non-destructive, lowering the burden on the description. The description adds valuable behavioral context: with_start_time grows the number of commands with service count and is off by default, and the output includes warnings. This meaningfully exceeds what annotations and schema alone 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?

  The description is compact and front-loaded: a one-sentence purpose, then a short parameter list with defaults/costs, then the return structure. Every section earns its place and there is no padding or redundant schema repetition.

  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 listing tool with three optional parameters, the description covers purpose, all parameter semantics, performance implications, and output shape. An agent has everything needed to invoke it correctly.

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

  Parameters5/5

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

  Schema description coverage is 0%, so parameter semantics depend entirely on the description. It fully explains all three parameters: case-insensitive substring filtering, running-only filtering, and with_start_time including its performance cost and default behavior. This adds real meaning beyond the bare schema types and defaults.

  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 opening sentence states '列出路由器上的服务及其运行状态' (list services and their running status on the router), a clear verb+resource description. The plural 'services' separates it from the more specific service_status sibling, though it does not explicitly name the alternative.

  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 explains options such as name_filter, running_only, and with_start_time, and even warns about the command-count cost of with_start_time, giving some invocation guidance. It does not explicitly advise when to choose service_list over service_status or service_logs, so usage context is only implied.

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

• service_logsA
  4.2/5.0
  Behavior4/5

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

  注释已声明 readOnlyHint=true、idempotentHint=true、destructiveHint=false，安全概况清楚。描述在此基础上补充了执行细节（具体命令 logread/journalctl）和返回结构，包括 'truncated' 字段暗示可能截断，增强了行为透明度。没有与注释矛盾，且为只读工具提供了有用的上下文。

  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?

  描述简洁且结构清晰：首句概括功能，随后分列参数，最后给出返回结构。无冗余信息，关键约束前置，便于快速理解。

  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?

  对于简单的只读工具，描述涵盖了调用所需的核心信息：参数意义、返回结构、实现方式。虽有输出模式的定义在描述中而非独立 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?

  Schema 覆盖率为 0%，描述完全承担参数解释：为 name 提供含义（服务名），为 lines 提供范围约束和上限说明（1 <= lines <= ROUTER_MCP_MAX_LOG_LINES，默认500）。这远超 Schema 中仅有类型和默认值的信息，有效补偿了 schema 的空白。不过默认值措辞存在一定模糊性（可能指上限默认值而非 lines 默认值），小有扣分。

  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?

  描述明确说'读取服务日志尾部内容'，具体动词+资源，并指出底层实现（OpenWrt logread / systemd journalctl），与兄弟工具（service_status 查看状态、service_start 控制服务）明显区分。这比简单的'查看日志'更为具体，界定了范围。

  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?

  描述暗示这是获取服务日志的专用工具，但没有明确说明何时使用它而非兄弟工具（如 run_shell 直接执行命令，或 service_status 查看状态）。没有提供使用场景的排除条件或替代说明，因此仅靠隐含语境，未给出明确指引。

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

• service_startA
  4.2/5.0
  Behavior5/5

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

  The description adds substantial behavioral context beyond the annotations: it warns that this is a write operation needing secondary confirmation, states that confirm must equal the service name, and documents the exact error code CONFIRMATION_REQUIRED. It also previews state_before/state_after and output fields, which helps the agent anticipate side effects and return behavior.

  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 well-organized and front-loaded, opening with the operation type and confirmation requirement before listing parameters. The return-structure block is useful but somewhat redundant given that an output schema exists, which prevents a perfect conciseness score.

  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 covers the core invocation contract, confirmation logic, error behavior, and return shape, so an agent can call the tool correctly. It is slightly incomplete in not mentioning prerequisites such as service existence or permissions, and it does not route the agent to related service tools for discovery.

  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?

  With 0% schema description coverage, the description fully compensates by explaining both parameters: name is the service name, and confirm must match the service name to execute. This is essential semantic information that the bare input schema does not provide.

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

  Purpose4/5

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

  The description clearly states a specific action and resource: '启动指定服务' (start the specified service), and further marks it as a write operation requiring confirmation. This makes the tool's purpose unmistakable, though it does not explicitly differentiate itself from sibling tools like service_stop or service_restart.

  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: use this tool to start a service and provide confirmation. However, the description gives no explicit guidance about when to prefer this over siblings such as service_restart or service_status, and no exclusions are mentioned.

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

• service_statusA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description need not labor the safety profile. It adds value by disclosing the exact return structure (fields like running, enabled, pid, started_at, source, init_system) and error behavior (ok=false with error.code=SERVICE_NOT_FOUND and details with examples). This informs the agent about response shape and failure mode beyond the schema.

  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 well-structured: purpose statement first, then parameter explanation, return structure, and error handling. Each section is concise and earns its place. It is not overly verbose, though it could be slightly tightened; the parameter and return details are essential. The front-loaded purpose immediately clarifies the tool's role.

  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, single-parameter read-only query, the description is complete: it covers the parameter format (for both init systems), the exact return structure, and the error case with a specific error code and guidance. Since an output schema exists (as per context signals), the description correctly focuses on the naming semantics and error behavior rather than repeating the schema. Nothing an agent needs to call it correctly is 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 carries the full burden. It explains that 'name' is the service name, with concrete naming conventions: OpenWrt uses /etc/init.d script names, systemd uses unit names like 'sshd.service'. It also gives an example. This goes well beyond the bare schema property and compensates completely for the lack of schema documentation.

  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 queries the running status, PID, start time, and auto-start state of a single service. The phrase '单个服务' (single service) explicitly distinguishes it from sibling tools like service_list (which would enumerate services) and service_start/service_stop (which mutate state). The verb '查询' (query) is specific and matches the read-only intent.

  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 checking a single service, but does not explicitly state when to use this over service_list (e.g., 'use service_list to enumerate services; use this to check a specific one'). It provides no exclusions or alternative routing. The 'service not found' error handling hints at expected input, but there's no direct guidance on when to choose this tool versus siblings.

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

• run_shellA
  4.8/5.0
  Behavior5/5

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

  The description goes far beyond the annotations, detailing exact error codes (SHELL_DISABLED, BLOCKED_COMMAND, CONFIRMATION_REQUIRED), command-blocking rules, root execution, bypass of the service whitelist, and the required confirm mechanism. This is exemplary behavioral disclosure.

  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 high-level warning, bullet-pointed safety constraints, parameter explanations, and return structure. Each sentence carries necessary operational information, and the risk warning 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 complex, destructive, gated tool, this description covers enablement, blocked commands, confirmation requirements, execution identity, error codes, parameters, and return fields. An agent has everything it needs to invoke the tool safely and interpret results.

  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?

  The input schema only provides types and nullability, with no description. The tool description fully compensates by explaining the command parameter and, crucially, that confirm must exactly equal the command string including spaces and quotes. This is essential semantic information the schema lacks.

  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: execute arbitrary shell commands on the router. It also immediately flags this as a high-risk capability, distinguishing it from the sibling service-management and read-only 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?

  The description provides strong context: it is for arbitrary shell commands and is high-risk, default-disabled, and requires confirmation. It does not explicitly name sibling tools as alternatives, but the scope is clear enough for an agent to know when this tool is intended.

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