phone-gotchaslisted

# Phone Gotchas ## Overview You do not know the phone. You read it. `ocr()` returns the real accessibility tree with exact point coordinates, so stop recalling where a control lives and go look. This skill holds only what reading the screen **cannot** tell you: harness limits, coordinate traps, and safety gates. Pairs with the `phone` skill, which covers the helper API. ## Coordinates: never do pixel math | Source | Units | |---|---| | `ocr()`, `find_text()`, `wait_for_text()` | **points** — tap these directly | | `screenshot()` | **pixels**, 2-3x larger than points | | `screen_info()` | points, `{width, height, units}` | Reading a coordinate off a screenshot and tapping it means dividing by a scale you had to derive. Use `find_text()` instead. Only fall back to screenshot math for elements that carry no text (color swatches, symbol grids), and compute the scale as `image_width / screen_info()["width"]`. Never hardcode it. `ocr()` and `find_text()` return **compacted** results over MCP: actionable elements only, no `rect`. That is ~62% fewer tokens and the hits you get back are the ones worth tapping. `ocr(full=True)` returns the raw tree with rects — reach for it only when you need geometry, not to "see more". A screenshot costs about the same as a *full* `ocr()` (~1,500 tokens) because images are billed after resizing. Downscaling saves nothing. The only lever is taking fewer of them, and compact reads are legible enough that you usually can. ## Reading elements in