reset_connection

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

The annotations only declare readOnlyHint=false, destructiveHint=false, etc., which provide no positive safety profile. The description compensates fully: it notes the tool changes target state, may occupy shared resources (debug state/serial/Keil instance), and that it is reversible ('可回退'). It also explicitly says it does not restart Keil, avoiding a major misunderstanding. No contradiction with annotations is present.

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 and front-loaded: it states the core purpose first ('只重置 UVSOCK 连接'), then the usage scenario and alternative, followed by a compact parameter/risk/alias section. Every sentence serves a purpose—no filler or repetition. The length is appropriate for the amount of critical context it provides.

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 non-annotated tool with a single optional parameter and an existing output schema, the description covers the essential operational context: purpose, usage triggers, side effects, risk level, rollback possibility, parameter acceptance rules, and distinction from alternatives. The output schema handles return values, so no extra explanation is needed. Nothing critical 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 schema has one optional parameter 'reason' with a default and no description. The description lists the parameter as optional, provides alias mappings (reason ← message/note/why), and states that unlisted parameter names are rejected. However, it does not explain what the 'reason' parameter actually controls or how it affects behavior. While this is helpful, it does not fully compensate for the 0% schema description coverage, so a mid-range score is warranted.

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 states a specific verb-resource pair: 'reset UVSOCK connection (not restart Keil)', and explicitly distinguishes it from the sibling tool 'restart_keil'. It also explains the mechanism (discarding socket and residual receive buffers) and the scenario it addresses. This is far beyond a vague or tautological statement.

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 clearly indicates when to use this tool: when a long-lived session is dirty (debug residue, async message buildup, modal dialog blocking) causing timeout failures. It also explicitly compares to the alternative ('previously only close and reopen Keil, now try this first; if it fails, use restart_keil'), giving a clear decision path.

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