select_serial_device

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

The description discloses side effects that the annotations do not, most importantly that the local selection is saved and old plans are invalidated, which explains readOnlyHint=false. It also states boundaries: it does not write to the device and does not start the motor, consistent with destructiveHint=false. It does not address repeated invocation behaviour (idempotentHint=false), nor what happens if the port or verification fails.

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?

The core binding action and the read-only verification scope are front-loaded in the first clause. The remaining sentences each add a distinct fact: the downstream transport dependency, the no-UID reselection trigger, the an_pn_910 fallback, and the no-device-write/no-motor guarantee. The density of domain jargon (AN MAC, transport='serial', 旧计划失效) makes it terse to the point of requiring prior context, but there is 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?

An output schema exists, so the description does not need to explain return values, and it focuses on what matters instead: the persisted state change, the downstream tools that depend on it, and the profile-specific caveat. What is missing is the failure and prerequisite surface, such as what happens when the port is wrong or verification fails, and how to inspect the device without binding.

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?

With input-schema description coverage at 0%, the description must carry parameter meaning, and it does: 'CM55 EC 6.12' maps to the cm55_ec_612 profile, and an_pn_910 is explained as the path that restores the original serial configuration after verifying the original COM7 and the recorded AN MAC. The port parameter's default COM7 is only implied through the examples, and the default profile behaviour is not spelled out.

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 opens with a specific verb and resource: it binds the user-specified CM55 EC 6.12 serial port, verifies the platform, software and board number, and saves the local selection. It also distinguishes itself from the parameter, backup, capture and rpm tools by noting that those downstream consumers rely on transport='serial'. It stops short of naming inspect_serial_device or probe_device_read_only as the non-binding alternatives, so the sibling boundary is implied rather than stated.

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 states the context in which this tool is needed, namely that the existing parameter, backup, capture and rpm tools operate over transport='serial'. It gives a reselection trigger: 'CM55 has no unique UID, so changing machines requires reselecting'. It also gives a conditional path for the an_pn_910 profile: verify the original COM7 and the recorded AN MAC, then switch back to the original serial configuration. It does not say when not to use this tool, nor does it point to the read-only inspection siblings.

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