restart_keil

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

The description discloses several behaviors beyond the destructiveHint annotation: it closes ALL Keil instances, including windows the user may be viewing, and warns that unsaved debug sessions or source changes may be lost. It also details the relaunch process (detached from parent process) and the UVSOCK wait mechanism, plus it states the return of phase results and a final health snapshot. This goes well beyond simply saying 'destructive' and gives the agent a precise mental model of side effects.

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 thorough and well-structured, starting with the main purpose and then breaking down the workflow, parameters, risk, and aliases. It is longer than a typical description but every section adds essential operational detail. The front-loading of the core purpose and the use of labeled sections (【参数】, 【风险】, 【参数别名】) make it scannable. It is slightly verbose but not wasteful.

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?

Given the tool's complexity—it orchestrates multiple steps and has destructive side effects—the description covers all necessary aspects: the actions performed, the parameters, the return behavior, the risks, and the aliases. The presence of an output schema reduces the burden of describing return values, and the description still states what it returns ('各阶段结果与最终健康快照'). An agent has enough information to call it correctly and safely.

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 input schema provides no descriptions (coverage 0%), so the description carries the full burden. It explains each parameter: 'project 为 .uvprojx 路径（省略用默认工程）', 'force=True 直接强制结束残留实例', and 'wait_ready 为等待 UVSOCK 监听的秒数（默认 20）'. It also lists parameter aliases, preempting naming mismatches. This fully compensates for the schema's lack of detail.

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 clearly states the tool's purpose: '一键重启 Keil 并重建调试通道' (restart Keil and rebuild debug channel). It enumerates the exact sequence of actions (close all instances, relaunch with project, wait for UVSOCK, reset connection) and explains that it packages the entire recovery workflow into one call. This is specific and distinguishes it from siblings like close_uvision, launch_uvision, and reset_connection, which each handle only a portion of the process.

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 provides context on when to use: '把「Keil 死了 / 会话脏了只能人工关掉再开」整条恢复流程变成一次调用' – i.e., when Keil is dead or the session is dirty. It also warns about destructive effects (closing all instances, losing unsaved changes), which informs the decision to avoid using it casually. However, it does not explicitly name alternative tools or state when NOT to use it in favor of more granular operations (e.g., reset_connection for a simple reset). The guidance is clear but not explicitly comparative.

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