MCP tool reference

Every App Use app answers the same small tool vocabulary, so an agent learns it once and can drive anything that exposes an App Use surface. Each tool carries a risk level — read, write, or execute — and every write or execute tool routes through the app's consent gate before it touches the real UI.

App-level tools (app.*)

These are the per-app tools the SDK ships on every surface. An agent connected to one app calls them directly; through a hub it calls them via app.call.

Tool	What it does	Args (brief)	Risk
app.describe	Returns the app's full AppSpec — screens, elements and actions.	none	read
app.read_screen	Snapshot of the active screen: elements plus recent events, with secret values pre-redacted.	none	read
app.get_value	Reads one control's current value (secret controls return <redacted>).	the control key	read
app.poll_events	Returns app events since a cursor, for observing change over time.	optional since cursor	read
app.navigate	Switches the app to a named screen.	the target screen	read
app.highlight	Visually highlights a control without changing it.	the control key	read
app.focus	Moves keyboard focus to a control.	the control key	read
app.set_value	Writes a value into a control (text box, toggle, slider).	control key and value	write
app.invoke	Activates a control — clicks a button or runs its action.	the control key	execute
app.press_key	Sends a key press, optionally with modifiers.	key and optional modifiers	execute
app.click_link	Follows a link control.	the control key	execute
app.window.move	Moves the app window to a new position.	x and y	write
app.window.resize	Resizes the app window.	width and height	write
app.window.focus	Brings the app window to the front.	none	read
app.window.state	Sets the window to normal, minimized or maximized.	the target state	write
app.screenshot	Captures the app (or one control) as a PNG returned as MCP image content.	optional control key	read

App surfaces also ship a guides surface (app.guide.list, app.guide.get, app.guide.run_step) and, from SDK 0.3.0, an admin surface (token, audit and consent tools) gated on an admin-scoped bearer.

Hub-level tools (apps.*)

The hub is a single MCP server that brokers many apps to one agent. Every hub tool is a broker operation — lifecycle and routing the hub performs as a local daemon. A proxied side-effecting call still passes through the target app's own consent gate, so the hub never bypasses per-app approval.

Tool	What it does	Args (brief)	Risk
apps.list	Lists every known app — running and registered-but-stopped — with its status, launchability, operations and live instances.	optional health probe flag	broker
apps.launch	Spawns an app from its launch manifest; it self-registers once up.	the app id	broker
apps.stop	Stops a running instance's process.	an instance id or app id	broker
app.call	Proxies an app.* tool to a target instance using its registered bearer token.	target, tool name and arguments	broker
apps.move	Moves an instance's window — cooperative if supported, else native.	target, x and y	broker
apps.resize	Resizes an instance's window — cooperative, else native.	target, width and height	broker
apps.focus	Brings an instance's window to the front — cooperative, else native.	the target	broker
apps.tap	Hub-wide live merged feed of call, result and observe events across all apps (in-memory, resets on restart).	optional since and max	broker
apps.history	Durable cross-app, cross-restart timeline; available only when the hub runs with history enabled.	since, max, source, app, instance and time range	broker

A target is either an explicit instance id or an app id (resolved to the app's unique live instance). Discovery is simply app.call with app.describe; a typical flow is apps.list → describe → app.navigate → app.set_value → window controls.