Install Device RPM

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is partly covered. The description adds the genuine behavioral fact that the operation is detached and hands back a job, which the annotations do not convey. It omits other behavioral traits the agent would want: files are copied to the device (side effects outside the RPM transaction), remote_dir is auto-created, and what happens to a partially-installed dependency set.

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 front-loaded sentence with no wasted words, so it is structurally efficient. It is arguably over-terse for an 8-parameter mutating tool, and the trailing 'use sailfish_build_status/cancel' reads like a boilerplate artifact rather than deliberate content, keeping it from a 5.

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?

For an 8-parameter, zero-required, mutating device operation with no output schema, the description covers only the async job handoff. It says nothing about failure modes, partial installs, what the job result contains, or that RPMs are physically copied to the target, leaving the agent under-informed about consequences.

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 88%, so the schema already documents device, wait, timeout, rpm_path vs rpm_paths, remote_dir, and remote_path with meaningful guidance (including the 'usb' alias convention). The description adds no parameter-level meaning beyond what the schema states, which is the baseline-3 case when the schema does the heavy lifting.

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?

States a specific verb+resource combination ('Start a detached RPM copy/install transaction') that distinguishes it from siblings like sailfish_build_rpm and sailfish_device_command_start. However, the routing pointer to sailfish_build_status/cancel is confusing for a device-install tool (that naming pattern belongs to the build family), which slightly muddies rather than sharpens the purpose.

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 word 'detached' implies the asynchronous usage mode and the follow-up tools (status/cancel) are named, so an agent can infer the workflow. But there is no explicit when-to-use vs when-not guidance, no note on when to prefer the synchronous 'wait' path, and no prerequisite/permission guidance for a tool that mutates a device.

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