umouse_set_dpi

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

With no annotations, the description carries the full burden and does so well: it discloses that the firmware gives no acknowledgement, that a return value of 1 only means the byte reached the channel, and that effect must be confirmed out-of-band via dpiChanged events. This is exactly the non-obvious behavioral trait an agent needs to avoid false success.

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?

Dense but front-loaded: the critical semantic (firmware byte, not DPI number) leads, followed by the mapping and the no-ack caveat. Every sentence earns its place, though the run-on structure of the final caveat is slightly harder to parse than ideal.

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?

No output schema and no annotations, but the description covers the important gaps for a mutation tool: what the argument means, the value encoding, and how to judge success given no firmware acknowledgement. Minor omissions are the device_id scoping (covered by schema) and any mention of persistence across reboot.

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 100%, so baseline would be 3, but the description goes far beyond: it explains the wire protocol (03 22 <level>), gives a concrete mapping table (800→21, 1200→32, etc.), and warns that other firmware families encode differently. The schema's own parameter description even defers to this table, making it load-bearing.

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 name plus description make clear this writes a firmware DPI-level byte for a device, and it explicitly disambiguates 'level' from an index or a DPI number. It never states the purpose as a standalone sentence ('set the mouse DPI'), relying partly on the name, but the encoding explanation is specific enough to identify the resource and operation.

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?

Usage is only implied: the reader infers you call it to change DPI, and there are no sibling tools that set DPI so no alternative routing is needed. The verification guidance (confirm via dpiChanged/cursor speed) is useful context but is about post-call validation, not when-to-use selection.

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