shell_execute

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

With no annotations, the description carries the full burden. It usefully discloses that execution is device-side only ("never invokes a host shell"), that timeouts are device-side when supported, that root is achieved via su uid=0, and that output may be truncated — but it omits what happens if the device is not rooted, whether commands are destructive, and permission/error behavior. The return-field listing largely duplicates the output schema, so real added value is moderate.

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 dense, front-loaded sentences with no filler; the key constraint (host shell exclusion) lands early. The telegraphic phrasing ("optionally su uid=0", "real exit_code/stdout/stderr") is efficient but slightly opaque to a non-expert reader.

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 4-parameter, unannotated, high-risk arbitrary-execution tool, the description covers the execution model and output shape but leaves side-effect risk, root prerequisites, and per-parameter tuning undocumented. The existing output schema offsets the need to explain return values in detail.

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 compensate. It explains `root` semantics (su to uid 0) and gesture at `timeout` (device-side) and `max_output_bytes` (truncation), but gives no units, defaults, or guidance on choosing values, and `max_output_bytes` is never named directly.

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 uses a concrete verb+resource ("Run an arbitrary Android shell command") and adds the distinguishing scope detail "never invokes a host shell," which separates it from the adb/host-shell siblings. It doesn't name specific siblings like root_shell or shell_batch, so differentiation is implied rather than explicit.

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: "arbitrary" suggests this is the catch-all shell tool, and the host-shell note hints at when to prefer it over adb_command. There is no explicit when-to-use vs root_shell, shell_batch, or device_files, and no stated prerequisites for root mode.

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