q402_doctor

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 discloses read-only behavior, no API key requirement, automatic phase detection, and the two output surfaces (agentInstructions, userInstructions). It also reveals the security policy for handling exposed private keys and warns about slot-mismatch scenarios in live-check mode. This is exceptionally transparent for a tool with no annotations.

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 long but well-structured, starting with the core purpose and then layering usage triggers, output surfaces, multi-turn flow, and security policy. Every section provides essential operational guidance for a complex diagnostic tool. It is not concise in word count, but the length is justified by the tool's multi-phase behavior and critical onboarding 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?

With no output schema, the description thoroughly explains what the tool returns: agentInstructions, userInstructions, recommendedActions, securityNotice, and phase-specific live-check diagnostics (quota, delegation, relay reachability, slot warnings). It also covers the multi-turn interaction pattern and security handling, making the tool fully understandable for an agent without needing external docs.

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?

The tool has zero parameters, so the baseline is 4. The description adds no parameter-specific details because there are none to explain. It instead explains how the output varies based on the detected phase, which is more relevant than any parameter semantics.

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 opens with a specific verb and resource: 'Run a Q402 health check' and explicitly states it covers both 'first-install onboarding AND ongoing diagnostics'. It further clarifies that it detects the current phase, distinguishing it from siblings like q402_pay, q402_balance, and q402_wallet_status. The purpose is unambiguous and differentiates from other q402_* tools.

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?

Provides explicit trigger phrases ('Use when the user says any of: "set up Q402", "verify Q402", ...'), declares itself the 'FIRST tool to call after install, BEFORE q402_pay or q402_balance', and gives detailed multi-turn instructions for the first-install phase. This clearly tells the agent when and how to use the tool, including what to do in subsequent turns.

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