device_job

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

With no annotations, the description carries the full burden and does supply real behavioral facts: persistent handles, bounded stdout/stderr, incremental byte offsets, PID-reuse checks, and timeout=0 semantics. It omits mutation consequences (what cancel/cleanup destroy), privilege/root behavior, and any pagination details, leaving meaningful gaps for a lifecycle tool.

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 description is front-loaded with the action list and use cases, then adds behavioral constraints, with minimal wasted wording. The telegraphic style is dense but efficient for an agent.

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-value explanation is not required. For a complex 11-parameter multi-action tool with no annotations, the description covers lifecycle and some behavior but leaves privilege, mutation effects, and most parameter meaning unspecified.

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% across 11 parameters, so the description must compensate. It does clarify the action value set, offset/stream/limit semantics via 'incremental byte offsets' and 'bounded stdout/stderr', and timeout=0 behavior, but leaves root, label, command, job_id, encoding, and max_output_mb undocumented in both schema and 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 names the resource (background device processes) and enumerates the concrete actions (list/start/status/output/cancel/cleanup), giving a clear verb+resource picture. It also lists target workloads (logcat, instrumentation, perfetto, tcpdump), though it never explicitly distinguishes itself from siblings like shell_execute or adb_command.

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 gives when-to-use hints via the workload list ('Use for logcat, instrumentation, perfetto, tcpdump if installed') and mentions timeout=0 for indefinite work. However, it offers no when-not guidance and no explicit routing to alternatives such as adb_command or shell_execute, so the agent must infer which tool to pick.

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