Tools reference
Argent exposes its capabilities to the coding agent as MCP tools. You rarely call these by hand, but knowing what exists tells you what you can ask for.
Run argent tools to list them from the terminal, argent tools describe <name> for the full schema of one, and argent run <name> to invoke one directly.
Devices and apps
| Tool | Description |
|---|---|
list-devices | List iOS simulators, Android emulators and devices, Chromium apps, Vega (Fire TV) devices, and HarmonyOS phones and emulators |
boot-device | Boot a simulator, emulator, Vega Virtual Device, or HarmonyOS emulator, or spawn an Electron app |
launch-app | Open an app by bundle id (iOS) or package name (Android) |
restart-app | Terminate then relaunch an app |
terminate-app (SDK only) | Stop an app without relaunching it |
reinstall-app | Install or reinstall an app, clearing app data and runtime permissions |
open-url | Open a URL or URL scheme on the device |
settings-permissions | Grant, deny, or reset a runtime permission without navigating the Settings UI |
rotate | Set the device orientation to portrait or either landscape |
fold | Fold or unfold a foldable iOS simulator or Android emulator to a posture or a hinge angle |
shake | Shake the device |
button | Press a hardware button: home, back, power, volume, app switch, action button |
tv-remote | Press a TV remote or D-pad button on Apple TV, Android TV, or Vega |
stop-simulator-server | Stop the transport session for one device and free its resources |
stop-all-simulator-servers | Stop every service a device owns: simulator servers, native devtools, TV daemons |
stop-metro | Stop the Metro bundler listening on a given port |
launch-app and restart-app accept launchArgs, a list of arguments that Argent passes to the app process at launch. For example, ["-FeatureFlag", "YES"] overrides a UserDefaults value. launchArgs works on Apple simulators and physical iPhones. Other targets ignore it. If the app already runs, launch-app terminates it first, so that the app gets the arguments. On a physical iPhone, the app sees -- before the arguments. UserDefaults overrides still apply.
reinstall-app uninstalls the app first, so Argent checks the app at appPath before the uninstall. The tool fails and keeps the installed app when one of these checks fails:
appPathdoes not exist, or it is not a.appdirectory (iOS), an.apkfile (Android), a.vpkgfile (Vega) or a.hapfile (HarmonyOS).bundleIddoes not match the bundle id in the.app, the package name in the.apkor the bundle name in the.hap. On a remote simulator, Argent does not compare the bundle id.
Argent drives a foldable iOS simulator, for example the iPhone Duo, and a foldable Android emulator, for example a Pixel Fold or a generic foldable AVD. list-devices marks a foldable device and a foldable AVD with foldable: true. fold moves the hinge to a posture (closed, half-open or open) or to an angle from 0 to 180 degrees.
- Closed, the cover panel shows the UI. Half-open and open, the inner panel shows the UI. The panel that shows the UI is the active panel.
- All tools use the active panel. This is also true after a fold made outside Argent.
- The coordinates and the screenshot size change with the panel.
foldreturns when the device accepts input again.
On an iOS simulator:
- A video keeps the size of the panel where the recording started. Argent keeps the proportions of the other panel and adds black bars.
- A fold between two angles that are not 0 or 180 can keep the current panel. To change panels, fold to
closedoropen. - Unfolded, the UI is landscape.
rotatesets the orientation of the device, not of the UI.Portraitgives a landscape UI. - If Argent cannot find the active panel, it uses the cover panel. The tool result then has a warning.
On an Android emulator:
- The result gives
deviceState(CLOSED,HALF_OPENEDorOPENED) and the matchingposture. - Argent dismisses a lock screen that the fold to closed shows, if it has no PIN or password.
- The result has a warning if the screen is off or the lock screen shows after the fold.
- On a generic foldable profile, closed shows only the left part of the display, and
describeframes do not match taps. Use a Pixel Fold profile to test the cover panel. - A physical device and an emulator without a hinge reject the call.
Argent supports physical iPhones; physical iPads are not supported yet. list-devices shows a physical device as an iOS entry with kind device. The state is connected only while the device is attached by USB cable; Argent controls physical devices over the cable and does not use Wi-Fi. The state is paired when the device is paired but not reachable now. Argent never selects a physical device automatically: name its udid. A paired device cannot be driven until it is connected by cable again. See Physical iOS devices for the requirements, the signing model, and the app-scoped interaction contract.
Inspecting the screen
| Tool | Description |
|---|---|
screenshot | Capture the device screen |
describe | Get the accessibility / DOM element tree for the current screen |
screenshot-diff | Compare two PNG screenshots and return a visual-diff summary |
await-screen-idle | Block until the screen has rendered content and stopped changing |
await-ui-element | Block until a UI element reaches an expected state, instead of polling in a loop |
ui-tree (SDK only) | Get the raw accessibility tree as nested JSON, iOS simulator and Android |
foreground-app (SDK only) | Get the app in front, iOS simulator and Android |
Interacting
| Tool | Description |
|---|---|
gesture-tap | Tap at normalized coordinates |
gesture-swipe | Smooth swipe or drag between two points |
gesture-scroll | Scroll a Chromium app by dispatching mouse-wheel events |
gesture-drag | Press, move, and release the mouse in a Chromium app |
gesture-pinch | Pinch to zoom around a center point |
gesture-rotate | Two-finger circular arc that rotates on-screen content |
gesture-custom | Send an arbitrary sequence of touch events for complex gestures |
keyboard | Type text or press special keys |
paste | Put text on the device clipboard and paste it (sim/emu only) |
fill (SDK only) | Set the text of the focused text field |
run-sequence | Execute several interaction steps in a single call |
screen-recording-start | Start recording the screen to an h264 mp4 |
screen-recording-stop | Stop the recording and retrieve the video |
gesture-tap, gesture-swipe, gesture-scroll, gesture-drag, and gesture-custom require position coordinates from 0 to 1, inclusive, not pixels. Argent rejects coordinates outside this range before sending input and names the invalid coordinate. This also applies to calls in run-sequence and e2e steps. The deltaX and deltaY scroll distances can be negative or greater than 1.
Through the MCP server, an interaction tool and await-ui-element return a screenshot and the element tree after the screen stops changing. These limits apply:
- Argent waits at most 15 seconds for the screenshot and the element tree together. If a capture takes longer, the result does not include it.
- Argent does not send a capture call again after a timeout.
Call screenshot or describe to read the screen again.
JavaScript runtime debugging
| Tool | Description |
|---|---|
debugger-connect | Connect to the JS runtime CDP debugger |
debugger-status | Report connection status and diagnostics |
debugger-evaluate | Execute JavaScript in the app's runtime: Hermes on device, V8 on Chromium |
debugger-component-tree | Fetch the current screen as a compact React component text tree |
debugger-inspect-element | Inspect the React component hierarchy at a screen coordinate |
debugger-log-registry | Summarize console logs captured from the app |
debugger-reload-metro | Restart the Metro bundle without restarting the native process |
view-network-logs | Retrieve captured HTTP requests from the running app |
view-network-request-details | Get full details of one request by its requestId |
Native devtools
| Tool | Description |
|---|---|
native-devtools-status | Check whether native devtools are connected and injection is prepared |
native-describe-screen | Read the app's native accessibility screen description |
native-full-hierarchy | Get the complete UIKit view tree |
native-find-views | Search views by class, accessibility id, label, tag, or nativeID |
native-view-at-point | Inspect the deepest visible view at a native window point |
native-user-interactable-view-at-point | Inspect the deepest view at a point that would receive touch input |
native-network-logs | Retrieve requests captured at the native NSURLProtocol level |
Chromium and Electron
| Tool | Description |
|---|---|
chromium-tabs | List, switch, open, and close tabs or BrowserWindows |
chromium-cookies | Read and write cookies, including HttpOnly ones |
chromium-storage | Read and write localStorage and sessionStorage of the active page |
Profiling
| Tool | Description |
|---|---|
react-profiler-start | Start CPU profiling and React commit capture on the connected Hermes runtime |
react-profiler-stop | Stop profiling and collect the CPU profile and commit tree |
react-profiler-status | Check the profiler session state without side effects |
react-profiler-analyze | Analyze stored profiling data into a markdown performance report |
react-profiler-renders | Collect component render counts and durations from the live fiber tree |
react-profiler-fiber-tree | Inspect the React fiber tree as JSON |
react-profiler-cpu-summary | Return the top Hermes CPU hotspots by self-time |
react-profiler-component-source | Find a component's source file, line, and memoization status |
native-profiler-start | Start native profiling: Instruments on iOS, Perfetto on Android |
native-profiler-stop | Stop native profiling and export the trace |
native-profiler-analyze | Analyze an exported native trace into a markdown report |
profiler-combined-report | Cross-correlate React Profiler and native profiler data |
profiler-load | Restore a previously captured session from disk so query tools can use it |
profiler-commit-query | Query React commit data for iterative render investigation |
profiler-cpu-query | Query Hermes CPU profile data with targeted modes |
profiler-stack-query | Query native trace data for iterative native investigation |
While a profiler that react-profiler-start or native-profiler-start started records on a device, interaction tools on that device return no automatic screenshot or element tree. The tool-server sets profiling: true on the tool-call response, and the MCP server returns a note in place of the capture. An explicit describe call returns its tree and no note. Call screenshot or describe to see the screen. Through the MCP server, an interaction tool still waits until the screen stops changing before it returns, so a screenshot or describe called next shows the screen after the interaction. The skip ends when the profiler stops, when the 10-minute recording cap ends the capture, when the app reloads its JavaScript during a React profile, or when the profiler session ends. On an Android emulator or device, Argent also sets the simulator-server of the device to on-demand screenshots while a profiler records. On an emulator, a screenshot then takes one frame in about 100 ms. On a physical device, a screenshot takes about 150 ms to 200 ms. It starts the screen capture for a short time. Interaction tools do not start the screen capture. When the last profiler on the device stops, Argent sets the simulator-server back to the default mode. An older simulator-server ignores the setting and keeps the default mode.
When two or more devices use one Metro, react-profiler-start takes the logicalDeviceId of Metro, not the device id. Interaction tools take the device id. Thus Argent finds the device of the React profile:
- The app writes a marker line to the device log.
- Argent reads the logs of the connected Android devices and the booted iOS simulators.
- The device whose log contains the marker is the device of the React profile.
When Argent finds no device, interaction tools on the device keep the automatic screenshot and element tree. react-profiler-start then returns a note. Argent cannot read the log of a physical iPhone or of a device from a provider.
E2E
The old flow-* names, for example flow-execute, still call these tools. See Record and replay e2e tests.
| Tool | Description |
|---|---|
e2e-start-recording | Start recording a new e2e test, resetting .argent/e2e/<name>.yaml |
e2e-add-step | Execute a tool call and record it as a step in the open recording |
e2e-add-echo | Record an echo step that prints a message during replay |
e2e-add-script | Run a local .mjs file and add it to the open recording |
e2e-finish-recording | Finish the recording and write the e2e test to disk |
e2e-execute | Run a saved e2e test |
e2e-read-prerequisite | Read the execution prerequisite of an e2e test without running it |
Design variants
Staged through Argent Lens so you can compare proposals against the running app. These tools require the argent-lens flag and macOS. The flag is off by default, so argent tools omits them until you enable it.
| Tool | Description |
|---|---|
propose_variant | Stage one design variant for one on-screen element |
await_user_selection | Block until you pick among the staged variants |
Workspace and maintenance
| Tool | Description |
|---|---|
gather-workspace-data | Fetch a structured snapshot of the app project's workspace |
update-argent | Apply a pending Argent update |
dismiss-update | Silence update reminders for a number of hours |
Footnotes
Argent marks the tools that only read state with the MCP readOnlyHint annotation. Examples are screenshot, describe, debugger-component-tree, list-devices and the profiler query tools. In plan mode, Claude Code runs these tools without a permission prompt. Tools that change the device, the app or files, and debugger-evaluate, do not have the annotation.
terminate-app, ui-tree, foreground-app and fill are hidden from MCP. Call them with the Argent SDK, which exports the UiTree, ForegroundApp and FillResult result types.
terminate-app works on iOS and tvOS simulators, Android emulators and devices, and Vega Virtual Devices. On an iOS simulator it succeeds with terminated: false when the app is not running or not installed. Android and Vega always report terminated: true. Physical iPhones are not supported yet.
In ui-tree, fields a platform cannot report yet are listed in unsupportedFields. A node is hidden when no part of it is on screen inside its ancestors. On iOS, while a system alert shows, roots holds the system app first and the app it covers second. On Android, roots holds one root per window, topmost first. A system dialog, such as a runtime permission prompt or a crash dialog, sets alertVisible, and every node of the app it covers is covered. When Android hides the app's window under the dialog, foregroundApp is unset. foreground-app returns the same foregroundApp and alertVisible without reading the tree, plus the app's name on iOS.