Doing things on an Android phone

Say what you want done. The phone works out how.

The phone is attached over USB. You do not need to know anything about how it is driven — no screen-reading, no tapping, no accessibility trees. That is the server's job, and a decision model inside it works out each step and tells you when the instruction is complete.

State the goal

Call run_task with the outcome you want, in plain language:

run_task("open the email app")
run_task("turn on aeroplane mode")
run_task("set an alarm for 7am")
run_task("send a text to Alice saying I'll be late")

That one call replaces a whole back-and-forth. The phone reads its own screen, decides what to do, does it, checks the result, and repeats until the goal is reached or it cannot get there — then reports back.

Phrase the goal as the outcome, not the steps. "open the email app", not "tap the Gmail icon". You are describing what should be true when it finishes.

Keep it short, and ask for one thing at a time. A goal that names the app and the thing you want, and no more, is the one that works:

run_task("open the Play Store")
run_task("search for YouTube")
run_task("open YouTube")

Three calls, each waiting for the one before it, beat a single request that spans them: "find YouTube in the app store and install it" asks the phone to hold a plan across several screens, and leaves you with one report to guess at instead of three you can read.

Multi-step work is fine — send the steps one at a time, and send the next once the one before has come back. When something fails you will know which step it was, and so will the person you are working for.

max_steps bounds how much it will try. Leave it alone unless the task is genuinely long.

Read the report

run_task returns what happened, and the two fields that matter most are at the top:

achieved is not one model's opinion. The work is only declared done when the chosen action says so and a separate question about the same screen agrees. If the two disagree the run carries on, because a wrong "done" ends everything and reports success that never happened.

A run that fails says so. It does not claim success for something it could not do. If achieved is false, reason says why — most often that it could not get there from the screen it reached, or that it was about to repeat itself.

If it comes back unfinished

Say so. achieved false with reason is the honest answer, and the report names the screen it stopped on and every action it took — which is what the person holding the phone needs in order to take it from there, and what you need in order to explain what happened.

Report it rather than trying the job again by hand. There is no set of smaller tools to reach for: the phone is driven by describing the outcome, and working out which control to touch from a screen is the server's job. An agent that starts choosing controls instead is doing that job with less of the information.

Things worth knowing

The phone is real and someone is holding it. Sending a message, deleting something or spending money has consequences. Say what you are about to do before you do it, and do not take an instruction further than it was given.

A locked phone cannot be worked around. If the run reports the phone is locked, ask the user to unlock it. A PIN cannot and should not be entered for them.

Non-ASCII text cannot always be typed as keystrokes. If a goal involves accented text, emoji or a non-Latin script and it fails, that is usually why — say so rather than retrying.

A goal the phone cannot do will be reported as such. If the user asks for something no phone can do, achieved will be false. Relay that; do not invent a success.

When something fails

Failures come back with a plain explanation and, where there is one, a concrete next step. Relay it rather than retrying blindly.

Two need the user's hands on the phone, so say so plainly instead of retrying:

• no Android device is attached — the cable is unplugged, or USB debugging has been switched off
• the phone has not authorised this computer — it is showing an Allow USB debugging? prompt that needs a physical tap

If run_task is not among your tools

The phone is driven through an MCP server, and this skill only describes how to ask it for things. If you have no run_task, the server is not mounted in this session: say so rather than improvising with other tools. README.md in the repository this skill came from has the setup — connecting the phone, the key, and mounting the server — and mounting usually needs a new session before the tools appear.

Full reference

references/tools-reference.md has every tool with its arguments, and the keys press_key accepts.