Preview upgrades for a hardwareMappings burn

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

Annotations already assert readOnlyHint/idempotent/non-destructive, but the description adds real value beyond them: it discloses that the check mirrors the app's checkDeviceConfigSync, that 'Nothing is written', and the subtle caveat that upgradeTargets is authoritative while the app log may report a loader upgrade that is then skipped. That last point is a behavioral nuance no annotation could convey.

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 core dry-run statement, then caveats and the consent use case in tight order. Every sentence carries distinct information; nothing is repeated from the schema or annotations.

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?

There is no output schema, and the description compensates by explaining what upgradeTargets contains and warning about its divergence from the app log. With annotations covering safety and the schema covering the two inputs, only minor details (error behavior, latency) are absent.

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 50% and the description contributes no parameter-level meaning — it never mentions firmwareListId or hardwareMappings, and 'upgradeTargets' is a return field, not an input. The half-documented parameters are adequately covered by the schema's own descriptions, so baseline 3 applies rather than a penalty.

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 verb and resource ('Dry-run of flash_config's hardwareMappings path') and states exactly what is produced: per-board firmware / MPY / loader upgrades that runSendConfigTask would execute. An agent can distinguish it from flash_config and the flash_* siblings without reading any 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?

Explicitly scopes usage: run this before sending config and pairing, and specifically 'to get the user's consent for upgrades first' — a clear precondition. It stops short of naming when NOT to use it (e.g. when no upgrades are expected or when the user already consented), so no exclusions are stated.

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