dump_ui

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

The readOnlyHint annotation already declares this as a safe read operation. The description adds the caveat 'when supported by the device,' which is useful, but it does not describe what happens on unsupported devices or any other behavioral details. The annotation lowers the burden, so a mid-range score is appropriate.

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 a single, front-loaded sentence that directly states the output and condition. Every word earns its place with no redundancy or filler.

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 simple read-only tool with a clear output format ('XML hierarchy') and a single optional parameter, the description is nearly complete. The only gap is lack of detail about unsupported-device errors, but the 'when supported' clause covers the main caveat adequately.

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% with a single well-described parameter (device_serial). The description itself does not add parameter-level detail, but the schema fully carries that responsibility, so the baseline of 3 applies.

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 clearly states the tool's function: 'Return the current Android UI Automator hierarchy as XML' with a specific scope ('when supported by the device'). This distinguishes it from sibling tools like screenshot (visual capture) and get_current_activity (activity name).

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?

No explicit guidance is given about when to use this tool versus alternatives. The description mentions a device-support condition but does not state when to prefer dump_ui over screenshot or wait_for_ui_node, nor any exclusions.

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