--- name: android-mcp-android-screen-triage description: Investigate an unknown or broken Android screen through Android-MCP without changing app state. Capture the snapshot, identify what is on screen, what the user can act on, what is stuck or unreachable, and what blocks progress, then report with evidence. Use when the user asks what is on the phone, why a screen is stuck, why a button cannot be reached, what a dialog or error means, or wants a read-only look at the current state of an Android device. --- # Triage an Android screen Triage answers three questions: **what is on screen, what can the user act on, and what is blocking progress?** It is a read-only look. The goal is an accurate picture of the current state, not a fix. Do not tap through the app to see what happens next; that is a test, and a different job. ## 1. Confirm which device you are looking at Before reading anything, make sure the right device is connected. Call `ListDevices` and state the serial and whether it is physical or an emulator. If more than one device is attached, ask the user which one. Do not guess. Only call `ConnectDevice` or disconnect if the user asks; switching the active device changes the session, so wait for the user's explicit yes first. ## 2. Take the snapshot and read it in layers Call `Snapshot` once. Default settings give the interactive elements with labels and coordinates. Only add `use_vision` when the labels alone do not explain the screen, for example a custom-drawn view, a game, or an image-heavy page. Use `use_annotation=false` if you want a clean screenshot to show the user. Read the result in this order: 1. **Foreground context:** which app and which screen. A system dialog, permission prompt or lock screen changes everything else you conclude. 2. **Blocking layer:** modal dialogs, error text, progress spinners, "Try again" or "Not responding" messages. These sit above everything underneath them, so anything behind them is not reachable until they are cleared. 3. **Actionable elements:** buttons, fields, toggles and links that are enabled. Note which are disabled or greyed out. A disabled "Continue" button is a finding; say why it is likely disabled if the labels show it (an empty required field, an unchecked terms box). 4. **Content:** the visible text and data the user is probably looking at. If the element list is empty or very short while the screen is clearly busy, you are probably in the busy-screen case (below). Say so rather than inventing elements. ## 3. Find what is unreachable Users often ask "why can't I press X". Check the common causes: - **Covered by an overlay:** a dialog, bottom sheet, keyboard or floating bar sits on top. Compare the element's coordinates with the overlay's bounds. - **Off screen:** the element is in a list or scroll view and its coordinates lie outside the visible area. Scrolling is a state change in a sense, so do not do it here; just report that it is off screen and where. - **Disabled:** the element is present but not enabled. Report it as present and disabled, not missing. - **Behind a permission or login gate:** the app is asking for something before it will show the content. - **Keyboard open:** a focused text field has pushed content up or hidden the submit button. Report which of these you can see evidence for. If you cannot tell, say "cause not visible in the snapshot". ## 4. Check the screen is not just loading A spinner, skeleton placeholder or "Loading" text means the state may resolve on its own. Do not diagnose a stuck screen from a single snapshot. Take a second `Snapshot` after a short pause (the `Wait` tool is fine for a pause, since it does not change app state) and compare. Only call the screen stuck if the two snapshots match and the progress indicator is still there. ## 5. Check notifications for context, read only If the user's question involves a message, an alert or a failed background action, call `Notification` to open the shade and read it. Pulling the shade down is a visible change to the device, so do not do this unless the question is about notifications or the user is clearly fine with it. Close it afterwards with `Press` (back), which is a state change; mention it to the user. ## Common patterns and traps - **The dialog is the screen.** A permission, update or "rate this app" prompt often covers the whole view. Report the dialog as the blocker before describing the content behind it. - **Disabled is not missing.** Many screens render a disabled button that looks like the rest. Check its state before concluding the feature is absent. - **Busy screens return thin data.** When uiautomator cannot settle on a video, animation or running timer, the element list is short or empty. Use `use_vision` for a screenshot, and say the element list is incomplete. Click by coordinates still works, but triage does not click. - **Stale snapshots.** A snapshot is a moment in time. If the user has been interacting, the screen may already differ. Take a fresh snapshot before reporting the current state. - **Text-only identification is fragile.** Labels can be localised or truncated. Give the exact text you saw and the element type, not a paraphrase presented as fact. - **Notifications can contain private content.** Do not quote message bodies or codes in the report unless the user asked for them. - **Emulator versus device.** An emulator may show a default home screen or a first-run wizard that a real phone would not. Say which kind of device this is when it affects the reading. ## Output ``` Device: , , Android Screen: / Blocking: Actionable now: Unreachable: - Loading: Evidence: Not established: