router_run_diagnostic

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses little beyond the checks performed. It does not say whether the test is disruptive (an NCSI reachability check can briefly affect the link), how long it takes, whether it needs an active WAN session, or whether results are cached. For an operational action on a live router, that is a significant gap.

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?

One tightly written sentence that front-loads the action and follows with the specifics of what is verified. Nothing is padded and nothing needs to be moved earlier.

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?

An output schema exists, so return-value explanation is not needed, and the purpose is fully covered. However, the unexplained 'force' flag and the absence of any disruption/duration/auth context leave real gaps for a live-network operation.

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% for the single parameter, and the description never mentions 'force' at all. The agent is left to guess whether it re-runs a cached test, bypasses a cooldown, or overrides a safety check — none of which is stated.

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?

States a specific verb ('Runs') and resource ('router-side diagnostic self-test') and enumerates exactly what is verified: physical link, WAN IP, Internet NCSI reachability. This is clearly distinguishable from read-only siblings like router_get_status or router_calibrate, though the description never names those alternatives explicitly.

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?

No guidance on when to run this diagnostic versus simply calling router_get_status, nor any exclusions or prerequisites. The agent must infer that this is the connectivity-troubleshooting path rather than the routine status path.

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