reset_reason

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

With no annotations, the description carries the full burden and does so richly: it explains that RCC_RSR flags are cumulative (only cleared by RMVF or power loss), warns against misreading simultaneous bits, discloses that clear_flags is irreversible/destructive and gated by an isolation layer requiring confirm=True, and lists which connection actions self-set flags to distinguish real resets from read noise.

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?

Content is front-loaded with purpose before the ★ behavioral sections, and every section earns its place given the tool's complexity. It is long and somewhat repetitive in the flag-action examples, but the length is largely justified by the operational subtleties.

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 unnecessary; the description fully covers purpose, usage routing, the destructive/irreversible nature of clear_flags, the confirm gating, and the cumulative-flag caveat. Nothing essential for a correct invocation 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?

Schema coverage is 0%, so the description must compensate. It richly documents clear_flags (irreversible, needs confirm), then_reset (only meaningful when clear_flags=True, default True), and confirm, but never explains the 'sn' parameter. Three of four parameters get strong semantics, which is substantial compensation.

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 and resource ('读复位原因（RCC_RSR 标志）与内核运行状态') and immediately scopes it ('走 hotplug：不复位、不停内核'), which distinguishes it from reset/flash siblings. An agent can tell exactly what it does without opening the 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?

It names the concrete question this answers ('板子为什么自己重启了', watchdog issues) and gives an explicit when-not/alternative path: it explains that 'normal' connection resets the target and halts the kernel, so hotplug is mandatory. The clear-then-reproduce-then-read workflow is spelled out.

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