crosspad_flash

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

Annotations declare destructiveHint=true and readOnlyHint=false (mutating). The description adds substantial behavioral context: hardware prerequisites (bootloader mode, passthrough mode, boot-pin states), the need for prior build steps, boot_request_dfu trigger for DFU, and the flasher resolution chain. It explains the rev-2.0 STM CDC-bridge passthrough mechanism. Doesn't explicitly warn about data loss from flashing, but the destructiveHint annotation covers the safety profile and the description adds hardware context beyond annotations.

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?

Well-structured with clear bullet lists per target. Each section is tersely written. Slightly dense—the rev-2.0 ESAB bridge explanation is a long parenthesis—but each clause earns its place and the format aids scanning. Could trim a couple of embedded caveats but overall efficient.

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?

Six parameters with 100% schema coverage, full enum constraints, and an output schema present. For a high-complexity flashing tool spanning two hardware targets with multiple transports and methods, the description covers prerequisites, defaults, hardware behavior across generations, and flasher resolution—effectively complete for the complexity level.

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 100%, so baseline is 3. The description adds meaningful context beyond the schema: firmware_path defaults per-target (ESP OTA-only vs STM per-preset), target/transport/method interplay (transport is ESP-only, method is STM-only), and build_type defaulting to Debug. This clarifies cross-parameter constraints that the flat schema doesn't encode.

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+resource: 'Flash firmware to a connected CrossPad device' with explicit targets ('esp' vs 'stm'), transports ('uart' vs 'ota'), and methods ('swd' vs 'dfu'). It clearly distinguishes from siblings like crosspad_build (which builds firmware rather than flashing it) and crosspad_run (which runs on-device).

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?

Provides explicit when-to-use guidance: requires prior crosspad_build platform=idf for ESP, crosspad_build platform=stm for STM. It names specific prerequisites (bootloader mode for uart, passthrough mode for rev-2.0, ST system memory for dfu) and documents the STM32_Programmer_CLI resolver chain. No alternatives are named but preconditions are unusually thorough.

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