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 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. Needs no licence.
`target`	List the running apps and switch to one.
`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 and context.
`renders`	Which components re-render most, how fast and why: memo misses, render loops, what started each burst, and providers that recreate their value.
`assert`	Check that something is true now: visible, a route, a value.
`wait_for`	Wait until something becomes true.
`screenshot`	An image of the screen, when nothing else will do.
`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.
`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.
`swipe`	Swipe; the direction is where the finger goes.
`scroll`	Scroll; the direction is where the content goes.
`scroll_until_visible`	Scroll until a control appears, in one call.
`back`	Go back a screen.
`launch_app`	Launch or relaunch the app.
`run_flow`	Run a flow file and return its result.
`batch`	Run several of these tools in one call.

tap, hover, input_text, swipe, scroll, 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.
`intent_wait`	Wait for a running program to finish or stop.
`resume_intent`	Answer a decision a program stopped for.
`approve_action`	Approve one step the deny rail blocked. Your client asks you first.
`steer`	Add a hint a running program must follow.
`intent_stop`	Stop a running program.
`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. 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.
`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 “unknown” when nothing was recorded under that condition.
`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). The first squiggle up 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.
`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.
`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.
`record_stop`	Stop and save the recording.
`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.
`filmstrip`	A contact sheet of a video’s frames, or per-frame brightness to catch a one-frame flash. Needs ffmpeg.

Explain and share

Tool	What it does
`explain`	Why something happened, traced through the recorded causes.
`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. Needs prEvidence turned on.
`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.
`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. Never edits a file.
`perf_report`	A summary of a session.
`perf_top`	The newest value of each metric.
`perf_sql`	Run a read-only SQL query.
`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.
`perf_heap`	Take a heap snapshot.
`perf_heapdiff`	What grew between two heap snapshots.
`perf_crashes`	Find and store native crash reports.
`perf_symbolicate`	Turn stack frames back into source lines.
`perf_export_trace`	Export a session for Perfetto or chrome://tracing.
`perf_gc`	Clean up old performance data now.

See Performance.

Product data

Tool	What it does
`product_overview`	The headline numbers.
`product_screens`	Visits, time and exit rate per screen.
`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, 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.