describe
Retrieve the current screen's accessibility/DOM element tree, including roles, labels, and tap coordinates. Use it to locate UI elements, inspect system dialogs, and guide automated interactions on any attached device.
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. |