Reflash firmware within a debug session

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

With no annotations, the description carries full burden. It discloses that it operates within an already-open session holiding the probe, avoiding USB conflict, which is significant behavioral info beyond the tool name. It also implies state (session must be open) and mentions setting a temporary breakpoint and reset behavior via parameters. Minor gap: doesn't state whether it halts the target or affects current execution state beyond the parameters.

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 tightly packed sentences. Front-loaded with the core action, technical method, and immediate operational context. Every word adds value; no filler.

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 no annotations, no output schema, and 3 parameters, the description covers essential purpose and key behavioral note (no USB conflict). It could be more complete by specifying prerequisites (must be in a debug session) and side effects (target reset default), but the description is largely sufficient for a fairly simple flashing tool.

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 67% (sessionId lacks description, but runToMain and resetAfter have descriptions). The description itself adds no parameter-specific detail beyond what schema provides, but it does clarify the overall action's effect on parameters indirectly (e.g., 'run to it after loading' aligns with runToMain). With moderate coverage, baseline 3 is appropriate; it doesn't compensate for sessionId's lack of description.

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 it reflashes the currently loaded ELF via gdb's `load` inside an already-open debug session. It specifies the verb (reflash), resource (ELF), and method (gdb load), and distinguishes from siblings like flash_standalone by emphasizing the in-session context.

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 implicitly conveys when to use: inside an existing debug session, as opposed to standalone flashing. It mentions 'No USB conflict — ST-LINK_gdbserver retains ownership' which implies a key benefit/alternative path, but lacks explicit exclusions or comparisons like 'use flash_standalone when no session is open'.

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