describe
Get the current screen's accessibility tree with element roles, labels, and tap coordinates. Inspect foreground apps or system dialogs across iOS, Android, Chromium, and TV to identify actionable UI controls.
Instructions
Get the accessibility / DOM element tree for the current screen.
On iOS, uses the AXRuntime accessibility service to inspect whatever is currently visible — including
system dialogs, permission prompts, and any foreground app content. On a physical iOS device the tree
covers only the app registered by launch-app. On Android, runs uiautomator dump.
On Chromium, walks the renderer's DOM via Chrome DevTools Protocol — every visible element with its ARIA
role, accessible name, and bounding rect (normalized to 0–1).
On Vega (Fire TV), reads the on-device automation toolkit (getPageSource); each element carries
[focused]/[selected] so you can see where the D-pad cursor is, then move it with the tv-remote tool
(Vega is remote-driven, not touch). If describe returns an empty tree on Vega, relaunch the foreground
app (the toolkit attaches at launch) and try again.
When a system dialog is visible, describe returns the dialog's interactive elements (buttons, text)
with tap coordinates. When no dialog is present, it returns the foreground app's accessible elements.
On a physical iOS device, launch-app com.apple.springboard first to read system dialogs.
Returns { description, source } where description is a text rendering of the UI tree — one
line per element with its role, label/value/id, interactivity flags, and frame. Frame coordinates
are normalized [0,1] fractions of the screen / window width/height (not pixels) — the same space as
gesture-tap / gesture-swipe / gesture-pinch.
To tap an element use the centre of its frame: tap_x = frame.x + frame.width / 2,
tap_y = frame.y + frame.height / 2. The same formula appears in the response header so it
can be applied to a line in isolation.
The tree carries no z-order or occlusion information: an element listed at a point may be covered
by an overlay (e.g. a toolbar over list rows), so check a screenshot when a tap lands unexpectedly.
For app-scoped inspection with full UIKit properties (accessibilityIdentifier, viewClassName), use native-describe-screen with an explicit bundleId instead (iOS simulator only). For React Native apps, debugger-component-tree returns React component names with tap coordinates.
On a TV target (Apple TV / Android TV — a list-devices entry with runtimeKind 'tv') this returns
the focus-driven view instead: the currently FOCUSED element and the list of FOCUSABLE elements,
since a TV UI has no tap coordinates. Move the highlight with tv-remote (up/down/left/right/select/
back/menu/home), then call describe again to confirm where focus landed.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| udid | Yes | Target device id from `list-devices` (iOS UDID, Android serial, Vega serial, or Chromium id). | |
| bundleId | No | Optional app bundle ID. Used as a target hint on iOS when the AX-service returns no elements and the describe tool falls back to native-devtools inspection. If omitted, the fallback auto-detects the frontmost connected app. Ignored on Android / Chromium, and on a physical iOS device. |