previewapk_push_apk

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

With no annotations, the description carries the full burden and does a fair job: it discloses that the APK is installed and relaunched with no reboot when hot-swapping, and that the response contains parsed app info with swapped=true. It omits failure modes (invalid/mismatched APK), what happens to existing app state on a hot-swap, and any permission or device-precondition detail beyond 'hold the wheel'.

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 tight sentences, front-loaded with the action, then the two conditional behaviors, then the return signal. Every clause carries information and nothing is repeated from the name or schema.

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 a mutating tool with no annotations and no output schema, the description covers the important branch-dependent behavior and even names the return field (swapped), which is genuinely useful. It is slightly short on error/precondition handling and leaves the device parameter unexplained, but the core picture is complete.

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 only 50%: 'path' is documented as a local .apk path and the description's 'from this machine' reinforces that, but 'device' has no schema description. The description only refers to 'the device' and 'hold the wheel', which hints at a currently-attached device but never explains how the device argument is identified or supplied.

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 first sentence gives a specific verb and resource — upload an APK from this machine to the device — which no sibling tool does. The follow-on sentences further disambiguate it by describing the two device states under which the upload behaves differently, so an agent can place it precisely among the previewapk_* tools.

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 two concrete conditions for use: device OFF makes the APK the attached app (then call previewapk_start), and device RUNNING with the wheel held triggers a live hot-swap. That is real routing guidance including a follow-up call, but it stops short of stating exclusions or contrasting this with alternatives such as previewapk_relaunch.

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