Tool reference

The twenty-nine tools your agent can use, and the four rules that decide what it can reach. Your agent reads each tool's exact arguments from the server, so they are not repeated here.

Four rules first

These decide more about what an agent can do than the tool list does.

An agent works only in tabs it opened. It opens one with create_tab. Tabs you opened yourself are never listed, read or touched, and there is no setting to change that. To have it look at a page you have open, give it the address.
Element refs expire when the page changes. read_page and find return refs for the agent to click or type into. After the tab moves to another page they answer STALE_REF, and an element that has disappeared answers ELEMENT_NOT_FOUND. Either way, read the page again.
Two tools are off until an admin turns them on. evaluate_js and upload_file answer POLICY_DISABLED until an admin of your organization turns them on from the Policy page. Even then, upload_file asks the person at the browser every time, naming the file and the site — so a pause there is waiting for them, not stuck.
Errors come back as ordinary results. Browser closed, tab not the agent's, ref expired — each returns a normal result marked isError: true, with a code and what to do next, so the agent can read it and recover.

A typical run

list_browsers — see which browsers it can use.
select_browser — pick one, by name.
create_tab — open a tab at a web address.
read_page — read the page, and get refs for what can be clicked.
click or type — act on one of those refs.
read_page again — see what changed.

Choosing a browser

`list_browsers`	The browsers you can drive, with state. Call this first.
`select_browser`	Pick the browser every later call goes to — by name, by id, or by a tag given to it in the dashboard.
`get_browser_status`	Which browser is picked, whether it is connected, and when it asks before visiting a site.

Tabs

`create_tab`	Open a tab and take ownership of it. The only way to get one.
`list_tabs`	The tabs the agent opened — never your own.
`close_tab`	Close a tab the agent opened.
`activate_tab`	Bring one of the agent's tabs to the front, where you can see it.

Moving around

`navigate`	Go to a web address in one of the agent's tabs.
`go_back` · `go_forward`	One history entry, and wait for the load.
`reload`	Reload and wait for the load.
`wait_for`	Wait for a selector, text, a navigation or network idle.

Reading

`read_page`	The content, as markdown or an accessibility tree, with refs for what is clickable.
`find`	Elements by CSS selector or visible text. Returns refs.
`get_page_info`	The current URL and title. Cheap.
`screenshot`	Capture the tab as an image.
`read_console`	Console output and browser log entries.
`read_network`	The requests the tab has made.

Acting

`click`	By ref, or by coordinates.
`type`	Text into an element, optionally submitting.
`press_key`	A key or a chord — `"Enter"`, `"Control+Shift+Tab"`.
`hover`	Move the pointer onto an element.
`drag`	Press, move, release. Real mouse events, not HTML5 drag-and-drop.
`scroll`	Scroll the tab, or bring an element into view.
`select_option`	Choose in a `<select>`.

Changing how the page is drawn

`set_viewport`	Lay the tab out at another size, or emulate a device.
`set_zoom`	Page zoom.

Switched off by default

`evaluate_js`	Run JavaScript in the page. An admin turns it on for the whole organization.
`upload_file`	Attach a file from the browser's computer to a form. An admin turns it on, and the person at the browser approves every upload.

What bounds all of them

Asking first. Unless the browser was set up with Allow everything, the first visit to a new site asks the person at the browser, and the tool waits for their answer.
Your organization's site lists. Sites an admin has blocked on the Policy page answer navigate and create_tab with BLOCKED_ORIGIN — including when a page redirects there.
A paused browser. Its owner paused it; every tool that uses it answers BROWSER_PAUSED until they resume it.
A browser shared with you to view only. Tools that change anything answer PERMISSION_DENIED.

Is something here wrong, or missing? Tell us.