net_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 of behavioral disclosure. It discloses what the tool does (runs a comprehensive diagnostic across five categories) and what it produces ('report each finding with concrete suggestions about what to change'). The diagnostic/preflight framing strongly implies a read-only, non-mutating operation. It does not state permission requirements or response format, but for a zero-parameter diagnostic tool the disclosed scope and output behavior are solid.

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?

Two sentences with zero waste. The first sentence front-loads the full scope and output behavior; the second delivers the usage guidance. Every word earns its place and nothing is redundant with the schema, which is empty. This is model concision.

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 zero-parameter diagnostic with no output schema, the description covers the essential ground: the full check scope, the reporting behavior with suggestions, and the timing of use. An agent can decide to call it and know what to expect. It could marginally improve by routing to specific siblings for targeted checks, but nothing an agent needs to invoke 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?

The tool has zero parameters and an empty schema, so per the rubric the baseline is 4. There is nothing for the description to add beyond what the schema provides, and it correctly requires no parameter explanation. This is the appropriate ceiling for a parameterless tool.

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 uses a specific verb ('Run') and a clearly scoped resource ('the full network preflight'), then enumerates the five check categories (system proxy, proxy ports, TUN adapters, GitHub reachability, hosts conflicts). The 'full' designation plus the enumerated scope clearly distinguishes it from the targeted sibling tools like net_proxy_status and net_hosts_check, which each cover only one slice. An agent can tell exactly what this does and how it differs from its siblings without opening any schema.

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 gives an explicit usage directive: 'Use this before blaming the network for a failure.' This tells the agent when to invoke it as the first diagnostic step. It stops short of naming alternatives or explicit when-not-to-use conditions, but the 'full preflight' framing plus the enumerated sibling tools makes the intended decision point reasonably clear.

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