service_status

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.

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.

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.

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.

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.

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.