List every Android device and emulator currently visible to adb, with model, Android version and screen geometry.

Call this first in any session: other tools need a serial when more than one device is attached, and this is where devices in a bad state (unauthorized, offline) surface.

Args:

• detailed (boolean): also query each device for Android version, SDK level, screen size, density and rotation. Costs one extra adb round trip per device (default: true)

• response_format ('markdown' | 'json'): output format (default: 'markdown')

Returns: { "count": number, "devices": [ { "serial": string, // e.g. "R3CN70XXXXX" or "192.168.0.12:5555" "state": string, // "device" = ready; "unauthorized" / "offline" = not usable "wireless": boolean, // connected over TCP/IP rather than USB "model": string, "androidVersion": string, // when detailed=true, e.g. "14" "sdkLevel": number, // when detailed=true, e.g. 34 "screenSize": string, // when detailed=true, e.g. "1080x2340" "density": string, // when detailed=true, e.g. "420" "rotation": number // when detailed=true, degrees: 0/90/180/270 } ] }

Examples:

• Use when: starting work and you need a serial for the other tools

• Use when: an install failed and you want to check the device is still authorized

• Don't use when: you already have a serial and just want app logs (use android_logcat)

Error Handling:

• Returns an empty device list rather than an error when nothing is plugged in

• Devices in state 'unauthorized' need the on-screen "Allow USB debugging?" prompt accepted

Switch a USB-connected device to wireless adb, or reconnect to one that was paired before.

Wireless adb is what makes it practical to keep iterating on a phone that is not tethered to the machine. The device and the host must be on the same network.

Two modes:

1. No 'host' given — requires a USB device. Reads the device's Wi-Fi address, runs 'adb tcpip', then connects. After this succeeds the USB cable can be unplugged.

2. 'host' given — reconnects directly to a known address, no USB needed.

Args:

• host (string, optional): device IP, with or without port, e.g. "192.168.0.12" or "192.168.0.12:5555"

• port (number): TCP port to use (default: 5555)

• serial (string, optional): USB serial to promote to wireless, when several devices are attached

Returns: { "serial": string, "host": string, "port": number, "alreadyConnected": boolean }

Examples:

• Use when: you want to unplug the cable and keep building to the device

• Use when: the wireless connection dropped after the phone slept and you need it back

• Don't use when: you only need to know what is connected (use android_list_devices)

Error Handling:

• "no usable IPv4 address" means the device is not on Wi-Fi; connect it to the same network as this machine

• A device that has rebooted loses TCP/IP mode entirely and must be re-promoted over USB

Run a Gradle assemble for an Android project and, when asked, install the APK and start it on a device — the full edit-run loop in one call.

Handles the toolchain details that normally break automated builds:

• picks a JDK Gradle can actually run on (Android Studio's bundled JBR when present), instead of trusting the ambient JAVA_HOME

• refuses to start, with an explanation, when the JDK is newer than the Gradle wrapper supports

• condenses a failed build's log down to the compiler errors instead of returning thousands of progress lines

The first build of a project downloads the Gradle distribution and dependencies and can take several minutes.

Args:

• project_path (string): absolute path to the Gradle root (contains gradlew)

• module (string): module producing the APK (default: 'app')

• variant ('debug' | 'release'): build variant (default: 'debug')

• clean (boolean): run the 'clean' task first (default: false)

• install (boolean): install the APK after a successful build (default: false)

• launch (boolean): start the app after installing; implies install (default: false)

• serial (string, optional): target device when installing

• timeout_ms (number): build timeout (default: 900000)

• response_format ('markdown' | 'json')

Returns: { "success": boolean, "task": string, // e.g. "assembleDebug" "durationMs": number, "apkPath": string, // present on success "packageName": string, // resolved from applicationId / namespace / manifest "gradleVersion": string, "javaMajor": number, // JDK major version used "installed": boolean, "launched": boolean, "output": string, // build tail on success, error summary on failure "hint": string // present when the failure is recognised }

Examples:

• Use when: "build and run this app on my phone" -> project_path=..., install=true, launch=true

• Use when: verifying a code change compiles -> project_path=..., install=false

• Don't use when: the APK is already built and you only want it installed (use android_install)

Error Handling:

• "Unsupported class file major version" is caught before the build starts and reported as a JDK/Gradle mismatch with the fix

• "SDK location not found" means local.properties or ANDROID_HOME is missing

• Install failures report the adb failure code (e.g. INSTALL_FAILED_UPDATE_INCOMPATIBLE) with the usual remedy

Run a Gradle project's tests and report which ones failed.

This is the verification half of the loop: after changing code, prove the change works rather than assuming it. Failure output is condensed the same way android_build condenses it — you get the failing test names, not the whole Gradle log.

Two kinds of test:

• 'unit' runs testDebugUnitTest on the JVM. Fast, no device needed.

• 'instrumented' runs connectedDebugAndroidTest on a connected device or emulator. Slower, and requires a device.

Args:

• project_path (string): absolute path to the Gradle root (contains gradlew)

• module (string): module whose tests to run (default: 'app')

• kind ('unit' | 'instrumented'): which test task to run (default: 'unit')

• tests (string, optional): Gradle --tests filter, e.g. "com.example.MyTest" or ".LoginTest."

• timeout_ms (number): timeout (default: 900000)

• force (boolean): skip the JDK/Gradle compatibility pre-check (default: false)

• response_format ('markdown' | 'json')

Returns: { "success": boolean, "task": string, // e.g. ":app:testDebugUnitTest" "durationMs": number, "failures": string[], // failing test names, when parseable "output": string, // condensed failure summary, or the tail on success "hint": string // present when the failure is a known one }

Examples:

• Use when: you changed logic and want to know it still passes -> kind="unit"

• Use when: narrowing to one failing test -> tests="com.example.CalcTest"

• Use when: the behaviour only shows on a device -> kind="instrumented"

• Don't use when: you only need the app compiled (use android_build)

Error Handling:

• "instrumented" with no device connected fails at the device check, before Gradle starts

• A project with no test sources reports success with an up-to-date task rather than a failure

Wipe an app's data and cache while leaving it installed — the equivalent of "Clear storage" in system settings.

Use this to get back to a first-run state without uninstalling. It is less disruptive than android_uninstall (the app and its install stay put) but it still destroys everything the app has stored: databases, preferences, cached files, and any signed-in session.

Args:

• package_name (string, optional): application id to clear

• project_path (string, optional): Gradle root; the package is resolved from it when package_name is omitted

• module (string): module to read the package from (default: 'app')

• serial (string, optional): target device

Returns: { "cleared": boolean, "packageName": string, "serial": string }

Examples:

• Use when: testing onboarding or a first-run migration repeatedly

• Use when: a corrupt local database is masking the bug you are chasing

• Don't use when: you need the app gone entirely (use android_uninstall)

Error Handling:

• Reports when the package is not installed

• The app is force-stopped as a side effect; relaunch it with android_launch

Install an APK onto a device, replacing any existing copy.

Args:

• apk_path (string, optional): absolute path to the APK. Omit to use the last build output of project_path.

• project_path (string, optional): Gradle root, used to locate the APK when apk_path is omitted

• module (string): module that produced the APK (default: 'app')

• variant ('debug' | 'release'): which build output to install (default: 'debug')

• serial (string, optional): target device

• grant_permissions (boolean): grant all runtime permissions at install time (default: false)

Returns: { "installed": boolean, "apkPath": string, "serial": string }

Examples:

• Use when: an APK was built earlier and you want it on the device -> project_path=...

• Use when: installing a downloaded APK -> apk_path=...

• Don't use when: you also need to compile first (use android_build with install=true)

Error Handling:

• INSTALL_FAILED_UPDATE_INCOMPATIBLE: the installed copy was signed with a different key; uninstall it first

• INSTALL_FAILED_VERSION_DOWNGRADE: the device has a newer versionCode; uninstall or bump the version

• INSTALL_FAILED_INSUFFICIENT_STORAGE: free space on the device

Start an installed app's launcher activity, optionally force-stopping it first.

Args:

• package_name (string, optional): application id, e.g. "com.example.myapp"

• project_path (string, optional): Gradle root; the package is resolved from it when package_name is omitted

• module (string): module to read the package from (default: 'app')

• serial (string, optional): target device

• force_stop (boolean): kill the app before starting, guaranteeing a cold start (default: false)

Returns: { "launched": boolean, "packageName": string, "serial": string }

Examples:

• Use when: bringing an app to the foreground before taking a screenshot

• Use when: you need a cold start to reproduce a launch-time bug -> force_stop=true

• Don't use when: the app is not installed yet (use android_install)

Error Handling:

• Reports when the package is not installed, rather than silently doing nothing

• An app with no launcher activity cannot be started this way

Remove an app from the device. This deletes the app's data and cannot be undone.

Args:

• package_name (string, optional): application id to remove

• project_path (string, optional): Gradle root; the package is resolved from it when package_name is omitted

• module (string): module to read the package from (default: 'app')

• serial (string, optional): target device

• keep_data (boolean): keep app data and cache directories (adb uninstall -k) (default: false)

Returns: { "uninstalled": boolean, "packageName": string, "serial": string }

Examples:

• Use when: an install fails with INSTALL_FAILED_UPDATE_INCOMPATIBLE and the old copy must go

• Use when: testing a first-run experience from a clean state

• Don't use when: you only want to clear state; force-stopping or clearing data is less destructive

Error Handling:

• Reports when the package was not installed to begin with

Capture the device screen as a PNG.

By default the image is returned inline so it can be looked at directly. Screenshots are large — a phone screen is typically 0.5–2 MB, and a tablet more — so when you only need the file (for a report, or to diff later), pass output_path and set include_image=false to keep it out of the conversation.

To read UI text or find something to tap, android_dump_ui is far cheaper than a screenshot and gives exact coordinates.

Args:

• serial (string, optional): target device

• output_path (string, optional): absolute path to also write the PNG to

• include_image (boolean): return the image inline (default: true)

Returns: Inline image plus: { "bytes": number, "outputPath": string, "serial": string }

Examples:

• Use when: confirming a layout change actually rendered as intended

• Use when: the app crashed and you want to see what is on screen

• Don't use when: you need the text of a view or somewhere to tap (use android_dump_ui)

Error Handling:

• A black or empty image usually means a secure window (FLAG_SECURE) or a locked screen

Read logcat from the device, filtered down to what is actually relevant.

Returns a snapshot of the existing buffer and exits; it does not stream. Filter by package to see only your app's output — this is usually what you want after a crash, because the unfiltered buffer is mostly unrelated system noise.

Args:

• serial (string, optional): target device

• package_name (string, optional): show only lines from this app's process

• tag (string, optional): show only this log tag

• priority ('V'|'D'|'I'|'W'|'E'|'F'): minimum level (default: 'V', or 'E' when crashes_only is set)

• crashes_only (boolean): read the crash buffer — fatal exceptions and ANRs. This buffer survives the process, so it works after the app has died (default: false)

• lines (number): how many lines to return, 1-2000 (default: 200). Normally the most recent N; with crashes_only it is the first N of the crash, since that is where the exception and the top frames are

• clear_only (boolean): wipe the buffer and return immediately without reading (default: false)

• response_format ('markdown' | 'json')

Returns: { "lines": string[], "count": number, "truncated": boolean, "serial": string, "pid": number, "diagnosis": string }

'diagnosis' is present when a crash matches a known Android failure mode.

Examples:

• Use when: the app crashed and you need the stack trace -> crashes_only=true, package_name="com.example.app"

• Use when: watching your own Log.d output -> tag="MyTag"

• Use when: reproducing a bug cleanly -> clear_only=true, reproduce it, then call again to read

• Don't use when: you want to see the screen (use android_screenshot)

Error Handling:

• Filtering by package uses the process id, which requires the app to be running. After a crash there is no process, so combine package_name with crashes_only — that path filters the crash buffer by name instead

Dump the current screen's view hierarchy as text, with tap coordinates for every element.

This is the cheap way for an agent to see what is on screen. It gives exact text, resource ids and content descriptions, plus a centre point for each node that can be passed straight to android_tap — no guessing at pixel positions from a screenshot.

By default only meaningful nodes are returned (anything with text, a content description, a resource id, or that is clickable). Layout containers are dropped.

Args:

• serial (string, optional): target device

• include_all (boolean): return every node including empty containers (default: false)

• filter (string, optional): case-insensitive substring; keeps only nodes whose text, id or description matches

• response_format ('markdown' | 'json')

Returns: { "count": number, "nodes": [ { "index": number, "class": string, // e.g. "android.widget.Button" "text": string, "desc": string, // content-description "id": string, // resource-id "clickable": boolean, "center": [number, number], // pass to android_tap "bounds": string // "[left,top][right,bottom]" } ] }

Examples:

• Use when: you need to press a button and must know where it is -> filter="submit"

• Use when: verifying a screen shows the expected text after a change

• Use when: a screenshot is ambiguous and you want the literal string values

• Don't use when: you need to see rendering, colour or layout quality (use android_screenshot)

Error Handling:

• "could not get idle state" means the UI is still animating; wait briefly and retry

• WebView content is often opaque to uiautomator; a screenshot may be the only option there

Run an arbitrary command on the device via adb shell, for anything the dedicated tools do not cover.

Arguments are passed as an array and are not interpreted by a host shell, so quoting is not a concern. Note that the device's shell still applies its own semantics to things like redirection.

Prefer a dedicated tool when one exists — they parse output and explain failures. Reach for this for one-off inspection: dumpsys, pm, settings, getprop and similar.

Args:

• command (string[]): command and arguments, e.g. ["dumpsys", "battery"]

• serial (string, optional): target device

• timeout_ms (number): command timeout (default: 30000)

Returns: { "stdout": string, "command": string, "serial": string }

Examples:

• Use when: reading battery state -> command=["dumpsys", "battery"]

• Use when: listing installed packages -> command=["pm", "list", "packages", "-3"]

• Use when: checking a system setting -> command=["settings", "get", "global", "window_animation_scale"]

• Don't use when: a dedicated tool covers it (android_logcat, android_dump_ui, android_tap)

Error Handling:

• The device shell's own error text is returned verbatim

• Commands needing root fail on production builds; there is no workaround on a locked device

Tap at a screen coordinate.

Get coordinates from android_dump_ui, which returns a ready-to-use centre point for every element. Coordinates are in device pixels and depend on the current rotation, so re-read the UI after rotating.

Args:

• x (number): horizontal position in pixels

• y (number): vertical position in pixels

• serial (string, optional): target device

• long_press (boolean): hold instead of tapping (default: false)

• duration_ms (number): hold duration when long_press is set (default: 600)

Returns: { "tapped": [number, number], "longPress": boolean, "serial": string }

Examples:

• Use when: android_dump_ui reported a button at (540, 1683) -> x=540, y=1683

• Use when: opening a context menu -> long_press=true

• Don't use when: you do not know where the element is (call android_dump_ui first)

Error Handling:

• Coordinates outside the screen are silently ignored by Android; verify with android_dump_ui afterwards

Swipe between two points. Used for scrolling, dismissing, and drag gestures.

To scroll a list down (revealing content further down), swipe from a lower y to a higher one — the finger moves up.

Args:

• x1, y1 (number): start point in pixels

• x2, y2 (number): end point in pixels

• duration_ms (number): gesture duration; longer is a drag, shorter is a fling (default: 300)

• serial (string, optional): target device

Returns: { "from": [number, number], "to": [number, number], "durationMs": number, "serial": string }

Examples:

• Use when: scrolling a list down -> x1=540, y1=1600, x2=540, y2=600

• Use when: dragging an item -> duration_ms=1000

• Don't use when: a single tap is enough (use android_tap)

Error Handling:

• A swipe that is too fast to register is the usual cause of "nothing happened"; raise duration_ms

Type text into the focused input field.

Two limitations come from Android's 'input text' command itself, not from this tool. Both are rejected up front with an explanation rather than silently mangling the text:

• ASCII only. Korean, Japanese, Chinese, emoji and accented letters cannot be injected at all. Use an IME that accepts adb broadcasts (ADBKeyBoard is the usual one), or set the value directly in the app under test.

• The literal sequence '%s' cannot be typed. Spaces are transmitted as '%s', and Android's decoder has no escape for a real one — even '%%s' decodes to '% '.

Tap the field first (android_tap) so it has focus.

Args:

• text (string): ASCII text to type

• serial (string, optional): target device

• submit (boolean): press Enter afterwards (default: false)

Returns: { "typed": string, "submitted": boolean, "serial": string }

Examples:

• Use when: filling a login form -> text="user@example.com"

• Use when: entering a search term and running it -> text="pizza", submit=true

• Don't use when: the text contains non-ASCII characters (see the limitation above)

Error Handling:

• Rejects non-ASCII input, and text containing a literal '%s', with an explanation instead of mangling it

• Text going nowhere means no field has focus; tap the field first

• Text appended to existing content means the field was not empty; clear it first

Send a key event — Back, Home, Enter, arrows, volume and so on.

Args:

• key (string): key name without the KEYCODE_ prefix. One of: BACK, HOME, MENU, APP_SWITCH, ENTER, TAB, DEL, FORWARD_DEL, ESCAPE, DPAD_UP, DPAD_DOWN, DPAD_LEFT, DPAD_RIGHT, DPAD_CENTER, VOLUME_UP, VOLUME_DOWN, WAKEUP, SLEEP, POWER, CAMERA, SEARCH, MEDIA_PLAY_PAUSE, MEDIA_NEXT, MEDIA_PREVIOUS, PAGE_UP, PAGE_DOWN, MOVE_HOME, MOVE_END

• serial (string, optional): target device

• repeat (number): how many times to send it, 1-20 (default: 1)

Returns: { "key": string, "repeat": number, "serial": string }

Examples:

• Use when: navigating back out of a screen -> key="BACK"

• Use when: dismissing to the launcher before a cold start -> key="HOME"

• Use when: submitting a form without tapping -> key="ENTER"

• Use when: the screen is off and you need to see it -> key="WAKEUP" (POWER toggles, so it can turn the screen back off)

• Don't use when: typing characters (use android_input_text)

Error Handling:

• An unrecognised key name is rejected with the list of supported keys

Force the display into a specific orientation, or hand control back to the accelerometer.

Setting a fixed rotation turns auto-rotate off first; otherwise the sensor immediately overrides it. Use 'auto' to restore normal behaviour.

Rotating is the fastest way to check a layout in both orientations. Note that an app locking its own orientation in the manifest wins over this — the display will not turn.

Args:

• orientation ('portrait' | 'landscape' | 'portrait_reverse' | 'landscape_reverse' | 'auto')

• serial (string, optional): target device

Returns: { "requested": string, "rotationDegrees": number, "serial": string }

Examples:

• Use when: checking a tablet layout in landscape -> orientation="landscape"

• Use when: restoring the device after testing -> orientation="auto"

• Don't use when: the app declares a fixed screenOrientation; change the manifest instead

Error Handling:

• If the reported rotation does not change, the foreground app is locking its orientation

Check that the Android toolchain is usable and report exactly what is wrong when it is not.

Verifies adb, the SDK, the JDK, and connected devices; with a project path it also checks that project's Gradle wrapper against the JDK that would be used to build it — the mismatch that produces 'Unsupported class file major version'.

Run this first when a build or device command fails for a reason that is not obviously in the app's own code.

Args:

• project_path (string, optional): Gradle root to include in the checks

• module (string): module to inspect (default: 'app')

• response_format ('markdown' | 'json')

Returns: { "healthy": boolean, "checks": [ { "name": string, "status": "ok"|"warn"|"fail", "detail": string, "fix": string } ], "toolchain": { "adb": string, "sdkRoot": string, "javaHome": string, "javaMajor": number } }

Examples:

• Use when: a build fails and you do not yet know whether the cause is the project or the environment

• Use when: adb commands fail and you want to know if the device is authorized

• Use when: setting up on a new machine and want to confirm everything resolves

Error Handling:

• Reports missing adb as a failed check with installation guidance, rather than throwing

Search a curated set of Android development failure modes whose symptoms point nowhere near their causes.

These are problems where the obvious interpretation is wrong: a build that fails on a JDK version rather than the code, a service killed by vendor power management rather than a bug, keystrokes ignored because they are synthetic, a GridLayout that collapses because of how weights resolve. Each entry gives the symptom, the actual cause, and the fix.

Consult this when something fails in a way that does not make sense, before spending time bisecting the app's own code.

Args:

• error_text (string, optional): observed error output; returns entries whose known signatures match it

• topic ('build'|'device'|'service'|'input'|'layout'|'packaging', optional): filter by area

• search (string, optional): case-insensitive substring match across title, symptom, cause and fix

• response_format ('markdown' | 'json')

Returns: { "count": number, "pitfalls": [ { "id": string, "topic": string, "title": string, "symptom": string, "cause": string, "fix": string } ] }

Examples:

• Use when: a build failed with unfamiliar output -> error_text=""

• Use when: a background service keeps dying -> topic="service"

• Use when: planning tablet support and you want the known traps first -> topic="layout"

• Don't use when: the error is plainly in the app's own code

Error Handling:

• Returns an empty list when nothing matches; that means the problem is not a known environment trap