prepare_device_parameter_write

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

The description is framed as '只读预览' (read-only preview), but annotations declare readOnlyHint=false and idempotentHint=false. The tool has side effects: it mints a one-time plan that expires after 10 minutes, so repeated calls create new plans. An agent trusting the 'read-only' wording could call it repeatedly thinking it is a safe, cacheable read. The otherwise useful disclosure (plan lifetime, old value/target value, power-loss persistence impact, no device write) is undermined by this conflict.

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?

A single dense sentence that front-loads the operation, then the value format, then the plan lifetime, then the payload contents, then the safety boundary. Every clause carries information an agent needs, with 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 return-shape details are correctly omitted, and the description covers lifetime, idempotency-relevant plan semantics, and the no-write boundary. But for a 4-parameter tool with zero schema descriptions and a prepare/apply workflow, the missing guidance on the follow-up tool and on transport/port selection leaves the call underspecified.

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 carry every parameter's meaning, and it only explains 'value' ('显示单位下的精确十进制字符串' in display units, exact decimal string). The critical formatting rule is covered well, but 'code' (the parameter identifier), 'port', and 'transport' (including the selected_tcp vs serial enum choice) are undocumented in both the schema and the description.

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 and resource: a read-only preview of a single parameter modification that produces a 10-minute one-time plan. It is clearly distinct in spirit from apply_device_parameter_write ('不实际写设备'), though it never names the sibling explicitly. The one gap is that the identifier 'code' is never described, so the agent must infer that it names the parameter being previewed.

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?

The description implies that this is the step to take before an actual write ('不实际写设备', a one-time plan valid for 10 minutes), which signals a preview-then-apply workflow. It never names apply_device_parameter_write or cancel_* as the follow-up/cancel path, and it does not state prerequisites such as whether a device must already be selected or probed.

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