register_firmware_build

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

Annotations already state non-read-only, non-destructive, non-idempotent, closed-world, and the description adds substantial context beyond that: it validates the product package, seals and records a SHA-256 plus the declared release/parameter version, and does not flash. The caveat that a package cannot prove application-model compatibility is a genuinely useful behavioural limit. The gap is that it never says what happens on re-registration or when validation fails, despite idempotentHint=false.

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 dense sentences, each front-loaded with the actionable fact: purpose first, product/profile mapping second, the no-flash/serial caveat last. No boilerplate and 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?

An output schema exists, so return values need not be described. However, for a 7-parameter mutating tool with zero schema descriptions, the definition leaves the identity fields (label, firmware_path, source_revision) and the failure/duplicate path unexplained, which an agent needs in order to call it correctly the first time.

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 carry the parameter burden. It explains the profile enum values against real products, ties expected_software_raw to 910/612, and maps expected_release_hex and expected_parameter_version_raw to the declared release number and parameter version. It says nothing about label, firmware_path, or source_revision, leaving 3 of 7 parameters without any added meaning.

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 a specific verb and resource ('登记编译产物' / register build artifact) and immediately contrasts it with what it is not ('不烧录' – does not flash), which separates it from sibling tools such as prepare_firmware_validation and start_firmware_upgrade. It also names the concrete sub-resources validated (product package, SHA-256, declared release/parameter version).

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 gives concrete selection guidance for the profile parameter (AN PN 9.10 → default profile/software 910; CM55 EC 6.12 → cm55_ec_spi_612/software 612) and states that CM55 can only be upgraded over serial. It does not explicitly say when to choose this tool over the neighbouring validation/preflight tools, so there is no exclusion rule, only clear context.

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