Tools reference

All tools operate on the current session, so create_browser_session must run first. Tools fall into three groups: session (create, close), read (read_page, collect_data), and act (fill, type_text, click, press_key, scroll, set_clipboard). The act tools are backed by POST /v1/session/{id}/act, so anything an agent does here is reproducible over REST.

Session

create_browser_session

Start a cloud browser and get a link the user can watch. Call this first, everything else needs a live session, and surface live_view_url to the user right away.

Argument	Type	Default	Notes
`full_browser`	boolean	`true`	The whole Chrome window (tabs, omnibox), interactive, off a warm pool. `false` gives the lighter JPEG page-screencast
`persistent`	boolean	`true`	Keep the session alive between calls

Returns

{
  "ok": true,
  "session_id": "sess_1a1188dd7e0545cc8c74910b6ab7eb68",
  "live_view_url": "https://api.tilion.dev/v1/session/sess_1a11.../vnc/vnc_lite.html?token=...",
  "full_browser": true,
  "note": "Browser is live and persists between calls. Show live_view_url to the user."
}

The session keeps cookies and logins across later calls. Do not open a new one per page. The live_view_url token expires after about five minutes. The session itself lives longer, so call create_browser_session again for a fresh link if the old one stops loading.

close_browser_session

Shut the browser down and stop the meter. Call it when the job is finished.

Returns

{ "ok": true, "closed": "sess_1a1188dd7e0545cc8c74910b6ab7eb68" }

Read

read_page

Navigate the session to url and return the page as clean markdown. The live view follows along. Use this for a single page.

Argument	Type	Default	Notes
`url`	string	required	Where to navigate

Returns

{
  "ok": true,
  "status": "ok",
  "reason": null,
  "url": "https://example.com/",
  "title": "Example Domain",
  "markdown": "Example Domain\nThis domain is for use in illustrative examples..."
}

A terminal status of no_data means the source was blocked, empty, or behind a login. Report that honestly; never invent records to fill the gap.

collect_data

Describe a dataset in plain English and get structured records back. It plans the job and runs the whole thing, including pagination.

Argument	Type	Default	Notes
`prompt`	string	required	The goal, e.g. “the top 50 products with name, price, and rating”

The call returns ok, a status (ok, or a terminal no_data when the source was blocked, empty, or behind a login), and the collected rows as structured JSON. Never invent rows to fill a no_data result. Prefer one collect_data call over looping read_page yourself. It is faster, costs less, and it will not miss paginated results.

Act

The act tools drive the page the session is currently on. They target elements by CSS selector or, for click, by visible text. If a selector does not match, the tool returns ok: false with error: "Element not found: ...", so check the result before moving on.

Failure

{ "ok": false, "action": "fill", "error": "Element not found: 'input#username'" }

Text you pass to fill, type_text, and set_clipboard, such as passwords and tokens, is never logged or echoed back. The tools return only success or failure.

fill

Clear an input and set its value in one call. Best for form fields.

Argument	Type	Default	Notes
`selector`	string	required	CSS selector for the input
`value`	string	required	Value to set. Not echoed back

Returns

{ "ok": true, "action": "fill" }

type_text

Type into a selector, or into the currently focused element if no selector is given. Use it for login and search boxes, and when a field reacts to individual keystrokes rather than a set value.

Argument	Type	Default	Notes
`text`	string	required	Text to type. Not echoed back
`selector`	string	focused element	CSS selector to type into

Returns

{ "ok": true, "action": "type_text" }

click

Click an element by CSS selector, or by visible text.

Argument	Type	Default	Notes
`selector`	string	—	CSS selector to click
`text`	string	—	Visible text to click, e.g. `"Sign in"`

Pass exactly one of the two. text is handy when an element has no stable selector.

Returns

{ "ok": true, "action": "click" }

press_key

Send a key or combo to the page.

Argument	Type	Default	Notes
`key`	string	required	e.g. `"Enter"`, `"Tab"`, `"Escape"`, `"Control+V"`

Escape is the escape hatch for a modal or popup that has trapped the page.

scroll

Scroll the page vertically.

Argument	Type	Default	Notes
`pixels`	number	required	Pixels to scroll. Positive is down, negative is up

set_clipboard

Put text on the session clipboard so a human can paste it in the live view, for example a password they would rather paste than have the agent type.

Argument	Type	Default	Notes
`text`	string	required	Text to place on the clipboard. Not echoed back

A worked flow: log in, then read

Create a session, drive the login form, and read a page that is now behind auth. Because the session persists, the later read_page is authenticated.

create_browser_session()                          → show live_view_url to the user
read_page("https://example.com/login")            → land on the form
fill("input[name=email]", "you@example.com")
fill("input[name=password]", "•••••••••")          → not logged or echoed
click(text="Sign in")
read_page("https://example.com/account")          → now authenticated
close_browser_session()

When a step should be done by the human, not the agent, hand it off: call set_clipboard with the value and ask the user to paste it in the live view, or just ask them to type it there directly.

MCP overview covers connecting a client and the session model.
Sessions and Fetch are the REST equivalents of the read tools.
For AI agents lists the invariants to encode.

Get started

MCP

Sessions

Fetch & jobs

Content

Agent & tasks

Live view & recordings

Account

Reference

Tools reference

Session

create_browser_session

close_browser_session

Read

read_page

collect_data

Act

fill

type_text

click

press_key

scroll

set_clipboard

A worked flow: log in, then read

​Session

​create_browser_session

​close_browser_session

​Read

​read_page

​collect_data

​Act

​fill

​type_text

​click

​press_key

​scroll

​set_clipboard

​A worked flow: log in, then read

​Related

Session

create_browser_session

close_browser_session

Read

read_page

collect_data

Act

fill

type_text

click

press_key

scroll

set_clipboard

A worked flow: log in, then read

Related