keil_flash

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

With no annotations, the description carries the full burden and does disclose key behavior: this writes to hardware (flash download), requires an environment gate and explicit human authorization, and is explicitly 'Not hardware-tested', which is an important risk signal. It stops short of saying whether existing flash contents are overwritten or whether the target is reset after flashing.

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?

Three terse fragments with zero filler and the critical gate conditions front-loaded. The terseness borders on cryptic given the shorthand command syntax, but nothing is wasted.

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 values need not be explained. For a hardware-mutating tool with zero annotations, the description covers authorization and risk but omits device side effects (overwrite, reset) and the meaning of the target and project_path inputs, leaving meaningful gaps.

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%, so the description must compensate for all three parameters. It only explains 'confirm' (human authorization); 'target' and 'project_path' remain completely undocumented in both schema and description, leaving half the parameter surface opaque.

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 names the underlying invocation 'UV4 -f download', which implies flashing firmware to the target device, but it never states the purpose in plain terms. An agent must already know what 'UV4 -f download' means, and nothing distinguishes it from siblings like keil_build or keil_start_debug.

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?

Two hard prerequisites are stated (host KEIL_ALLOW_FLASH=true and human-authorized confirm=true), which is genuinely useful gating context. However, there is no guidance on when to choose this over keil_build, nor any statement about preconditions such as a built project being present.

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