stm32_fus_bootstrap

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

With no annotations at all, the description carries the full burden and does the important part: it discloses that FUS operations wipe flash sectors [0..3] via a helper binary, which is exactly the destructive side effect an agent must know before invoking. It also states the return content (full transcript of both steps). It does not mention duration, prerequisites such as an active probe/debug session, or whether a partial failure leaves the device in a recoverable state.

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?

Front-loaded with the action and the destructive caveat, then structured Args/Returns. Efficient overall. Minor redundancy: the follow-up re-flash instruction appears both in the body and again in the Returns section as 'a reminder to re-flash user firmware.'

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 two-stage destructive operation with an output schema, the definition covers the critical facts: what it does, what it destroys, and the required follow-up. The output schema relieves it of explaining return format. The remaining gap is preconditions (probe availability, whether a debug session must be active first), which matters for a bringup 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 0%, so the description must supply meaning and it does for both parameters: 'probe' is a board nickname, probe nickname, or ST-Link SN, and 'wireless_dir' is an optional path to STM32WB_Copro_Wireless_Binaries. This is genuinely additive over bare string types. It omits that both default to an empty string and what the empty default resolves to.

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?

Names a specific composite action (FUS upgrade followed by BLE stack full install) scoped to STM32WB, and immediately narrows it with 'Does NOT re-flash user firmware.' That negative scope is what separates it from the sibling tools stm32_fus_upgrade and stm32_ble_stack_install, so an agent can pick correctly without opening either 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?

Gives explicit sequencing guidance: after this call, run stm32_build_and_flash with the correct project_path. That names an alternative tool and the condition that selects it. It stops short of saying when to prefer this one-shot tool over calling stm32_fus_upgrade and stm32_ble_stack_install individually, which is the one routing decision left to inference.

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