MCP tools
For AI agents: this page is Markdown at https://squiggle.sh/docs/reference/mcp.md. Every docs page is listed at https://squiggle.sh/llms.txt, and all of them are one file at https://squiggle.sh/llms-full.txt.
Every one of the ninety-seven tools the Squiggle MCP server gives your agent, grouped by job. Your agent reads each tool's full description from the server; this page is for you, to know what it can reach for.
To connect the server, see Connect your agent. For how the tools fit together, see What your agent can do.
Start here
| Tool | What it does |
|---|---|
status | What is connected, which app, which tools work right now and why not, the approvals in force (the mode, the environment and what this session approved), and, when another Squiggle process took your app’s port, a notice naming it. While the app shows a red box, appError has the error, the line it came from and the fix. When no app is connected, it still answers: ready is false, blockers says why (for example, the app is on the Expo development launcher, or its bundle has no Squiggle SDK) and target lists the apps on the simulator that run with Squiggle’s agent. If your agent moved to another simulator because the one it was driving shut down, target.movedFrom names the one it left. An app another Squiggle session is driving (one of another project, or of another checkout of this repository) is listed under target.others with heldBy naming that session and its port: your agent never takes it. In a Niteshift task, also the device provider. Needs no licence. |
target | List the running apps and switch to one, or to a booted simulator by its UDID when several are booted and no app is connected. A React web app in Squiggle’s window is listed as web:<origin>, and one in a browser you opened, connected through a bundler plugin, also says dialledIn: true. When your project’s .squiggle/config.jsonc names its app (apps.ios or bundleId) and that app is installed on a booted simulator but not running with Squiggle (not started, or started without it), it is listed under notRunning with the launch_app call that starts it. Your agent attaches only to your project’s app; another project’s app on the same simulator is listed but never picked on its own. An app another Squiggle session is driving carries heldBy, naming that session and its port, and switching to it is refused. |
incidents | What went wrong in the app while your agent’s Squiggle server watched it, from when it attached to the app: crashes, errors, stalls, slowdowns and CPU, GPU or memory spikes, each with its recording when one was saved. Every other tool’s result says when there is something new. Only the app your agent drives is listed (before it drives one, the apps your project’s .squiggle/config.jsonc names); otherApps counts what other apps reported. mute keeps a performance detector or component off the other tools’ results for the session, and unmute takes it back. |
briefs | Problems the app has already found (crashes, friction, slowdowns), each with a recording, a cause and a source line. |
drive_mode_briefing | The working rules for driving an app, for an agent to read before it starts. |
perf_mode_briefing | The working rules for performance work. |
Look at the screen
| Tool | What it does |
|---|---|
describe | What is on screen, controls first, each with a short reference to act on. Can return only what changed since the last look. |
find | Whether a selector matches one control, several or none, before acting. |
query | Search the live component graph. |
inspect | One component’s live props, hooks, state, context and on-screen frame. A control with no React component behind it, such as a native header button or an alert’s button, is refused with an answer that says so. |
renders | Which components re-render most, how fast and why: memo misses, render loops, what started each burst, and providers that recreate their value. With mounts: true, also what mounted and what each mount cost in ms. A selector limits the count to that component and what it renders; a control with no React component behind it is refused, as by inspect. |
logs | The app’s console output, a worklet’s console.log included, kept since the server attached to the app (the last 2,000 lines). level keeps that level and above, text keeps lines containing it, and since (the cursor of the last reply) returns only newer lines, or, as a duration such as 2m, the lines from that last stretch. A reply holds up to 100 lines; limit raises that to at most 500. |
assert | Check that something is true now: visible, a route, a value. |
wait_for | Wait until something becomes true: a screen, the app going quiet, or a control appearing (visible) or going away (notVisible), named the same way as for tap. Give a route and several quiet conditions together and every one must hold at once; visible, notVisible and appRunIdle wait on their own. If the app reloads or relaunches during the wait, for example after a deep link into a development build, the wait reconnects to it and keeps going within the same timeout. If the app never comes back, the answer says why, naming another Squiggle attached to the app when there is one. The time limit is timeoutMs, or timeout as the waitFor step names it. |
screenshot | An image of the screen, when nothing else will do. It works with no app connected, from the simulator your agent drives (or the only booted one). |
legibility | Score how easily an agent can drive the screen, and name the lines to fix, ranked by the points each edit adds. |
report_card | After building a feature: tour the screens the change touched, run the flows that cover them, and check their budgets, findings, legibility and interface. Green, or the line to fix for each row. Pass changedFiles (the files you changed; omit to use the branch’s git diff), full: true to check every screen, tour: false to skip the tour, and live: true to run the flows against your real backend instead of the stubs recorded on each flow’s last green run. A touched screen no saved flow covers fails the card. Takes minutes, since it runs real flows. Failing rows come first, at most 60; the full card is saved to the file the result names. |
Act on the app
| Tool | What it does |
|---|---|
tap | Tap a control by reference or selector; gesture double_tap or long_press for the others. A control still moving, such as a button riding up with the keyboard, is tapped where it stops, after a wait of up to 3 seconds. A control under a sheet that is still closing, such as the tap right after the one on its Close, is tapped once the sheet has gone, after a wait of up to 2 seconds; a control that stays covered is refused, and the answer names what covers it. A tap on one of your app’s controls that gets no reaction is sent once more when nothing on screen changed. If the second gets no reaction either, the answer is ok: false and says the tap did nothing, as a flow step fails. A control iOS draws and a tap in a browser tab are never failed this way. A tap on UI outside your app, such as a system sheet or Expo’s developer menu, is sent once: the answer is ok: false and says the tap did nothing when, for 2 seconds after it, that UI shows exactly what it showed before and your app doesn’t react. Any tap first waits, up to a second, for a sheet that is still sliding in or out, and heldForSheetMs in the answer says how long it waited. expectRoute names the screen the tap opens: the answer is ok: false unless the app reaches it within 5 seconds. approve gives the reason a tap the deny rail stops is safe, which counts in approvals mode agent. |
pinch | Two fingers about a control or point: scale (0.2–5, not 1) above 1 zooms in, below 1 zooms out. duration 100–5000 ms, default 400. |
hover | Move the pointer onto a control, or off it, so its hover card or outline shows. Runs the app’s hover handlers; no cursor moves. |
input_text | Type into a field, replacing what it held; submit presses Return after. A field still moving is waited on, as for tap. On an iOS simulator the on-screen keyboard opens when the field takes focus and stays up while it types, as it does for a person; device { hideKeyboard: true } puts it away, and device { softKeyboard: false } types as a hardware keyboard. Flows type as a hardware keyboard unless the device keeps softKeyboard: true. |
swipe | Swipe; the direction is where the finger goes. duration (50–5000 ms) slows the drag, hold (1–3000 ms) presses first. |
scroll | Scroll; the direction is where the content goes. |
drag | One touch from a selector or point along a path of 1–32 legs (to, duration 50–5000 ms, pause 0–5000 ms), lifting only at the end. hold (1–3000 ms) presses first. For a slow drag, a pan or a sheet pulled back and forth. |
scroll_until_visible | Scroll until a control appears, in one call. |
back | Go back a screen: an edge swipe in the simulator, history back in a web app. If that doesn’t change the screen, for example because a horizontal pager took the swipe, it taps the header’s back button. Your app can report its new route late, because it is busy or reports it only after the screen finishes animating out, so before it decides nothing changed it waits at least 900 ms after going back, 600 ms more once the screen stops moving, and longer while your app is busy, up to 5 seconds in all. The answer says whether the screen changed (navigated) and how (via: edge-swipe, history or nav-bar-button). navigated is unknown when your app doesn’t report its route and too few components go away to tell a new screen from, say, a spinner finishing; then the button isn’t tapped, so the app never goes back twice. |
launch_app | Launch or relaunch the app, past an Expo development launcher or an “Open in …?” alert, and return once its first screen is up. An app that is already running with Squiggle is left as it is unless you pass relaunch: "always", which relaunches it even when you name it with app to switch to it; clearState: true wipes the app’s data and relaunches it. With udid, it launches on that booted simulator, and your agent keeps driving that simulator until it switches again. With app, it launches that app; on its own, your project’s app: an iOS app, a macOS app, or a React web app in Squiggle’s window. With url (5173, localhost:5173 or a full URL), it opens that web app in Squiggle’s window, or uses the window already open on it. It never relaunches an app another project’s Squiggle session drives, even on a simulator you name: it stops with E_DEVICE_HELD, naming that session. |
device | Read or change the simulator settings in Studio’s device menus, and get every one back as the device now has it. Your agent’s taps and typing show the iOS on-screen keyboard as a person sees it; softKeyboard: false types as a hardware keyboard instead, and softKeyboard: true keeps the keyboard showing for flow runs too, after relaunches, until you change it, and softKeyboard: “default” forgets either, so your agent opens the keyboard again and flows type as a hardware keyboard. showKeyboard: true opens the on-screen keyboard for the running app and keeps it up while you type; hideKeyboard: true puts it away. appearance, increaseContrast, textSize, statusBar, location and permission change the simulator itself; button presses a hardware button and shake shakes the device. iOS closes the app to apply some permission changes, such as photos or microphone access; the tool opens it again and says so with relaunched: true. simulator, passed on its own, manages the Mac’s iOS simulators: action list reads the installed iOS versions, the device types and every simulator; create creates one (by default the newest iOS version’s current iPhone) and boots it unless boot: false; boot and shutdown take a udid, and shutdown refuses a simulator that Studio, another agent’s Squiggle server or a CLI run is driving. Your agent then picks the new simulator with target; a new simulator has no apps, so install your development build on it first. It doesn’t delete simulators. |
run_flow | Run a flow file and return its result. A failed runFlow, repeat, retry or branch step carries failedStep: the step inside it that failed, with its position, kind, selector and detail. A name no saved flow has, or inline YAML that isn’t a valid flow, is refused at once, before any wait for your app; an unknown name comes back as E_NO_FLOW with the closest names. fresh: true relaunches your app before the run, like squiggle flow --fresh, including an app that never connected (stuck on the Expo development launcher, or left behind by a failed run). When your agent works in a git worktree of the project, root names it (or the folder in it that holds .squiggle), so the worktree’s copy of the flow runs, not the one where the server started; root wins over SQUIGGLE_PROJECT_ROOT. In flow YAML passed inline, addMedia and runFlow paths start at that project folder, and a runFlow file can be a library flow’s name. With waitMs (up to 300000 ms) the flow runs in the background: the call returns the result if the run ends within waitMs, else its runId (0 returns at once); intent_wait reports progress and the result, and intent_stop stops it at its next step. While it runs, describe, find, screenshot, perf_profile and perf_heap work; tools that move the app, and every other run (run_flow, run_intent, intent_continue, crawl and replay_recording), are refused until it ends. record: true films the run; record: { fps, tailMs } also sets the frame rate (1 to 120: 60 by default, 30 in a browser tab; a simulator draws at most 60) or keeps filming up to 30000 ms after the last step. The video is saved in the project that owns your app. When root names a project that doesn’t own it, nothing is filmed, and the reply’s notice names the project to pass as root instead. An app no project owns isn’t filmed either; the notice says why. |
batch | Run several tools in one call, in order, stopping at the first step that fails unless stopOnError is false: tap, hover, input_text, swipe, scroll, drag, pinch, scroll_until_visible, back and device, and the looks and checks describe, find, assert, wait_for, inspect, renders and logs. Each step takes the tool’s own name and arguments. |
tap, hover, input_text, swipe, scroll, drag, pinch, scroll_until_visible, back, batch and tune return what changed on screen once it settles: the new route, what appeared, and whether motion stopped. Pass observe: false for a bare acknowledgement when the agent is about to act again straight away.
Run a journey as a program
| Tool | What it does |
|---|---|
intent_schema | The full grammar of an intent program. |
run_intent | Start a program that drives a whole journey. approvals: "ask" makes this run stricter than your approvals setting. |
intent_wait | Wait for a running program, or a run_flow started with waitMs, to reach its next escalation or its final report (timeoutMs, 120000 by default). Pass a progressToken and each step arrives as a progress notification while you wait. |
resume_intent | Answer a decision a program stopped for, or, in approvals mode agent, approve a blocked step with your reason (agentApprove). |
approve_action | Approve one step the deny rail blocked. Your client asks you first. remember: "session" also approves that control for the rest of the session. |
approvals | Set the approvals mode, or approve controls, for the rest of this session. Your client asks you first. |
steer | Add a note to a running program, which its next decision carries, and name controls it must not touch from then on. |
intent_stop | Stop a running program, or a run_flow started with waitMs (it stops at its next step). The app isn’t put back: what the run already did stays done. |
intent_continue | Pick up a program that died, without asking the model again for decisions already made. |
branch | From one point in a program (at), try several continuations (alternatives, each with its own goal) and rank which reached its goal. Blocks until every branch has run. With fromSlot: true, the prefix runs once and a save slot taken there is loaded before each branch instead of a relaunch and replay; the prefix must end on a known screen (a waitFor or assert on a route), and a branch whose slot won’t load replays instead. order: margin runs the alternative whose first tap most surely matches a control on the branch screen first; firstWin: true stops at the first branch that reaches its goal and lists the rest in notRun. |
agent_config | Read the deny rail, the learned popup handlers and the run limits. |
agent_stats | Model turns per journey, escalation and replay rates, and how often saved answers were reused. |
See Intent programs and Safety and approvals.
Remember the app
| Tool | What it does |
|---|---|
library_list | The saved flows the agent can replay, with or without an app running. A flow in a folder is listed by the name run_flow takes, such as auth/login. An entry whose last run healed a selector carries healMargin, its thinnest heal: a low value is the flow most likely to break next. |
library_save | Save a program that worked as a reusable flow. library_list and library_save take root, like run_flow, to use a worktree’s library. |
route | The shortest known path to a screen. |
predict | What a tap has led to before, without touching the app. With horizon (1–10), where the app has usually been that many taps on, each screen with the share of recorded paths that end there, and the share that ran out of recorded exits. |
what_if | What a flow did before under a condition, from the race, twin and fuzz runs already recorded; it never touches the app. Pass flow (by name), condition (repeat, back, slow, error, empty, truncated or offline) and, for repeat and back, step. Says “measured” and cites the runs, or “inconclusive” when nothing was recorded under that condition. With condition layout (no flow), it says what the screen the app shows does at another window width in points (width), text size (textSize, a content-size category) or tunable value (tunable and value): which controls move, which labels take more lines, the layout findings there, and the widths or values where the layout jumps. Leave out value to find where along its range a tunable changes the layout. It reads the screen once, and moves a named tunable and puts it back. Says “predicted” with how often the prediction has matched real runs so far, or “inconclusive” with the reason, for example on a web page or a release build. Use it to choose which runs to do, not as proof. |
interface | Each screen’s controls and where they lead. save: <name> stores a copy; against: <name> compares the live app with a stored copy and lists the saved flows the change puts at risk. A flow is at risk when a control it taps is gone or leads somewhere else, or when, on a changed screen, a selector that matched a control there would now match nothing, be refused by self-healing, or win by under 20 points (the reason gives the margin before and after). A project’s first squiggle up, flow run or run_flow stores one named first. |
affected_by_diff | Given changed files, which screens and saved flows they touch, before the app is built. |
crawl | Explore the app and map its screens. |
invariants | Standing checks the app should keep passing: flows with goals, inferred rules, performance limits. action: navigation checks the navigation your project declares for this app over its recorded screens, each answer proven, falsified (with the shortest path that breaks it) or inconclusive (with the screens to explore first). |
fixture | Save and restore a named starting point, such as a cart with three items: action is list, capture or restore, with name. Restoring puts back the screen as well as the data. It uses the same slots as squiggle save and squiggle load, so a slot saved in one loads in the other. Reports unsupported when the app registered no data source. |
deterministic_session | Pin the network, animations, clock and locale so two runs can be compared. The clock moves in a debug build of an app with the Squiggle SDK: its Date reads the instant you give and runs on from there, until the app relaunches (launch_app { relaunch: "always" }). |
tune | With no name, lists the values the app declared tunable with defineTunable, and their current values. With name and value, sets one within its declared range and step; with name and reset: true, puts back its default. The app refuses an undeclared name or an out-of-range value, and a set value is dropped on reload. An app built before tunables answers unsupported. |
bisect_state | Find which app state makes a flow fail. Takes a flow (name or yaml) and two save slots: green, which the flow passes from, and failing, which it fails from. It loads green with some of failing’s store values put in, runs the flow, and narrows to the smallest set of fields that still fails. Returns those fields, every field that differed, the number of loads it took, and a brief with the line that writes each field and the components that read it. A slot name the deny list matches is refused. When it finds the fields, it leaves the app on the green slot. |
Record and look at frames
| Tool | What it does |
|---|---|
record_start | Start recording the app, and keep recording across your other calls until record_stop. With video: true, film the screen to an .mp4 instead, the same video run_flow record: true makes, for steps you drive yourself. fps sets the frame rate, 1 to 120: 60 by default, 30 in a browser tab, and a simulator draws at most 60. tailMs (up to 30000 ms) keeps filming that long after you call record_stop. A video stops itself after 10 minutes; record_stop still returns it, marked stoppedBy: limit. For an app that belongs to another project, nothing is filmed unless you name the file with outPath; the reply names the project that owns it. |
record_stop | Stop and save the recording. For a video, returns the path to the .mp4, which filmstrip and motion read. |
replay_recording | Replay a recording with no app, and optionally check a flow against it. |
diff_runs | Compare two recordings: renders, screens, requests and timings. With journey (an intent program’s name: its runs that passed) or cohort (names, paths or patterns like login-*) instead of b, judge one recording against many: every number outside the range of all of them, and whether any took its route. |
motion | Whether a scroll, slide or animation in a recording is smooth: how far the content moved each frame, with stalls, dropped and repeated frames, judder, jumps and reversals listed by frame and time, and a verdict. Leave out areas such as the keyboard. When another part of the frame moves on its own, such as a looping banner, the reply carries independentMotion: that part’s area and the area of the part that moved furthest, to pass back as ignore or region, because the whole-frame reading mixes them and can miss a stall. A part that swings back and forth in place, such as a turning progress indicator, is named even when nothing else moves, with only its area to pass back as ignore; in a recording its swings count as stillness, not as reversals. Stillness longer than half a second is a pause between two motions unless the content then carries on at speed in the same direction. With no video named, it reads the newest recording made in this session; needs ffmpeg. With testID, it tracks that view on the running app at every frame the screen draws, for ms (default 1000, from 100 to 10000; a longer window is refused), around a tap or a scroll, with no recording; the view can be one the tap or scroll brings in, followed from the first frame it appears. It follows the view’s own position, so name what moves, not a list whose content scrolls inside it. On a live track, and on a recording Squiggle made, each problem says what the app was busy with: a long JavaScript task, garbage collection, which components rendered; for a recording, busyUnavailable says why when it can’t. With against, it compares with an earlier recording or report and says whether the motion regressed. With chart, it adds a picture of speed over time with the bad frames marked, saved in .squiggle/filmstrip so publish_evidence can attach it; without rsvg-convert installed, the chart comes back as the path to an SVG instead of an image. On a live track, against, region, ignore, axis, fromS and toS have no effect: they apply to recordings. |
filmstrip | A contact sheet of a video’s frames, or per-frame brightness to catch a one-frame flash. With no video named, it reads the newest recording made in this session and refuses if there is none, so it never shows an older run of another flow. A sheet holds 2 to 36 frames (tiles), in up to 36 columns, so one row is allowed. It stays within 8000 px per side, narrowing the tiles to fit, and refuses a grid that can’t fit. Each tile is labelled with the time of the frame it shows. A stretch where the screen held still adds no tile, and the sheet’s note says how many stretches had a frame; when the whole window held still, the one tile is the frame that was on screen. The reply gives the recording’s frame rate, followed by its average when it wrote no frames while the screen held still: 60.0 fps (variable rate, 29.3 frames/s on average), the same reading motion gives. In brightness mode, the first value is the frame already on screen as the window opens, and when the screen held still for part of the window, heldStill says from when to when, since the recording has no frames there. Each call writes its own sheet to .squiggle/filmstrip, so a second call never returns the first one’s image. Needs ffmpeg. |
Explain and share
| Tool | What it does |
|---|---|
explain | Why something happened, traced through the recorded causes. For a tap or gesture that never reached the app, it says so: handed off (with the step and the point) or refused (with the reason), and what to do next. |
verify_citations | Check every evidence link in a report still points at what it claims. |
publish_evidence | Attach a recording, screenshot or filmstrip to the pull request: in the description of a pull request you opened, in a comment on anyone else’s. Each round replaces the last. Needs prEvidence turned on, and takes only files in the project’s .squiggle folder. In a Niteshift task it posts nothing: it writes the files to a folder for the task to attach. |
perf_narrative_context | A session’s findings with their evidence resolved, for writing up what happened. |
Performance data
| Tool | What it does |
|---|---|
perf_insights | A session’s findings, worst first: the top 20 (limit lists up to 200), with repeats of one finding counted once, and the number of findings by detector and by severity. A reply stays under about 24 KB; omitted says how many entries it left out. Ask for one by its index to see all its detail, or narrow by detector or severity. |
propose_fix | Turn a finding into an edit plan. With tuning (an id, or latest), plan the edit a squiggle flow --tune or --matrix --repair chose instead: each tunable’s default line before and after, with what was measured. With rank: "saving", list up to five of your components whose memo misses and render storms cost the most render time, each with how many renders a fix removes, the time that would save (a prediction), its plan and, when your project owns the app, a prediction id. After the fix, measure: { prediction, after } with the new session records what it really saved. Never edits a file. |
perf_report | A summary of a session. Like perf_sql, it first waits for rows still being written, and opens with why when this server isn’t the one recording the app. |
perf_top | The newest value of each metric. |
perf_sql | Run a read-only SQL query. It first waits, up to 2 seconds, for rows this server is still writing; notRecording says why when another process, such as Studio, records the app instead. |
probe_read | Run a short read-only script against the data and return only its result. |
probe_read_capabilities | What probe_read scripts can call. |
perf_saved_query_list | The saved queries. |
perf_saved_query_save | Save a query. |
perf_saved_query_run | Run a saved query. |
perf_snapshot | Save a session as a baseline. |
perf_diff | Compare a session with a baseline. |
perf_profile | Take a CPU profile of the JS thread. It returns the functions in your app that took the most time, and apart from them the time Squiggle’s own code took. A profile across a reload carries on in the reloaded app. startup: true reads the newest launch’s startup profile instead, with no capture. React Native refuses it, saying the Tracing domain is unavailable, while the app has more than one host; status lists it under unavailable when it can tell ahead. |
perf_heap | Take a heap snapshot. |
perf_heapdiff | What grew between two heap snapshots. |
perf_crashes | Find and store crash reports, and list the newest 20 crashes of the app on its simulator, or a web page’s crashes. |
perf_symbolicate | Turn stack frames back into source lines. |
perf_export_trace | Export a session for Perfetto or chrome://tracing. |
perf_gc | Clean up now: the same pass as squiggle perf gc, with every size limit. |
See Performance. For what Squiggle measures on a React web app, see React web apps.
Product data
| Tool | What it does |
|---|---|
product_overview | The headline numbers. |
product_screens | Visits, time and exit rate per screen. With cost: true, what each screen costs real sessions (dropped frames and time to interactive, times the share that open it), the share over its budget, and whether that moved against the sessions before. |
product_usage | How often each named action ran, or its adoption. |
product_affinity | Actions people use together. |
product_friction | Rage taps, dead zones and confusion across sessions. withState: true adds the app state at each moment. |
product_heatmap | Where people touched each screen, and how they scrolled. include: ["intents"] adds what drags meant: dismiss, refresh, reorder or scrub, per screen, each with its evidence. |
product_state | What the app held on each screen, from its state samples: with no path, the feature paths; with path, that feature’s values per screen. Instead of that, coverage: true lists states real sessions reached that no flow or save slot did, each with a proposed slot (never saved by the tool); drift: true compares two releases (latest against the one before, or pick them with from and to); perf: true reads performance findings against the state in force when each happened. |
product_funnels | The saved funnels. |
product_funnel_eval | Evaluate a funnel. |
product_retention | Retention by cohort. |
product_releases | Each release and when it first appeared. |
product_users | Identified users, with an at-risk flag. |
product_sessions | Each session with its screens and actions. |
product_screens (without cost), product_friction, product_funnel_eval and product_retention also take whereState, such as zustand:useCart.items#len >= 3, to compare the sessions that reached a state with the rest. See Product analytics.