check_system_health

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

No annotations are provided, so the description must disclose behavior. It mentions what is checked but does not describe side effects, return format, authentication requirements, or whether the operation is read-only. An agent cannot infer what the output looks like or if the call might alter state. This is a notable gap for a diagnostic tool.

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 a single, well-structured sentence that front-loads the action and lists the specific components checked. There is no filler or unnecessary detail, making it efficient and easy to scan.

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?

Given that there is no output schema, the description should explain what the health check returns and how to interpret it. It also does not mention any preconditions (e.g., open document) or potential side effects. For a tool that checks multiple subsystems, this is insufficient for an agent to understand the full context and expected results.

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 100% (the fileId parameter is described as 'Optional target file ID to check'). The description does not add any extra semantics beyond the schema; it simply restates that the file is the target of the check. Since coverage is high, the baseline of 3 applies.

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 the verb ('performs a comprehensive diagnostic health check') and enumerates the specific resources it checks (Paper Desktop, CDP connection, in-memory rate-limit bypass, active document state). This is precise and distinguishes it from any sibling tools, none of which appear to offer a health-check function.

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 the tool is used to diagnose system health, but it does not explicitly state when to use it, when not to, or mention any alternatives. Since no sibling performs a similar role, there is no competitive routing, but explicit usage context (e.g., 'use when troubleshooting connection issues') is missing.

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