Who is browsing right now: the identity, the exit, the profile and the tabs.

Ask whenever you need to know which person the browser currently is, or from where its traffic leaves. The seed is what you would pass to session_start to become this person again, so this is also how you record a session that is worth repeating.

It starts nothing. If no browser is running yet it says so, because until one is running there is no identity to report.

Start a browsing session as a particular person, and say who that is.

Call this when you want to control WHO is browsing: a fresh stranger, the same person as last time, or a saved profile that is already logged in somewhere. Calling it closes whatever browser is open and starts another, so anything not saved in a profile is gone.

You do not have to call it at all. The first tool that needs a page starts a session on its own; session_status then tells you who that turned out to be.

There is only ONE browser. Two identities are visited in turn, never at the same time, so a task that needs both accounts live at once cannot be done here and is worth saying so rather than half-starting.

seed the browser identity. Same seed, same fingerprint, every time. Leave it out and one is drawn, and the answer tells you which, so you can ask for it again later. profile a directory that keeps cookies and logins between sessions. A profile also KEEPS ITS SEED: the first session on a new one stores the identity inside it, and every session after reuses it, so a login does not come back wearing different hardware. Pass "" to insist on no profile at all, which is how you get sessions a site cannot link to each other. A relative path is resolved against the server's own directory, so the answer reports the full path it used. proxy where the traffic goes out, as http://user:pass@host:port or socks5://host:port. Pass "" to insist on going out from this machine's own address. A profile does NOT pin its exit the way it pins its seed: timezone, locale and geography come from the exit, so the same login arriving from another country is as visible as one arriving on different hardware. You are warned when a profile's exit changes, but only when YOU change it - a provider that rotates its own addresses behind one host and port looks identical here.

Open a new tab and make it the active one. Returns its page id.

Tabs persist across calls and across clients, so this is how you keep one page while working on another rather than navigating back and forth.

Every open tab: id, title, url, and which one is active.

Use it before session_select_page: the id alone does not tell you which tab you are switching to.

Switch the active tab. Every other browser_* tool acts on it.

Take the id from session_list_pages or from session_new_page.

Close a tab, or the active one when page_id is left out.

Go to a url in the active tab, opening one if none exists.

wait_until is "domcontentloaded" by default, which returns as soon as the markup is parsed. Use "load" when the page needs its images and stylesheets, or "networkidle" for a single-page app that fetches its content after load.

The visible text of an element, with the markup gone.

The cheapest way to read a page. Narrow the selector when you know where the answer is; use browser_read_html instead when the structure matters, or browser_snapshot when you need something to click.

Long text is cut at max_chars (6000 by default) and the cut is marked in what comes back, so text that ends without that marker is the whole thing.

Title, url, and the interactive elements that are actually visible.

Each element carries a selector when one can reach it: pass that string to browser_click or browser_type VERBATIM. It is built to match exactly one element, which the obvious selector often does not - measured across 958 elements on real pages, 88% could be addressed but only 48% unambiguously, and Playwright acts on the first match, so a caller aiming at the third of five identical links would silently hit the first.

Elements with no selector carry at, the centre coordinates, for browser_click_at.

Not the accessibility tree: on a real sign-up page a single country <select> contributes about two hundred <option> nodes, which fill the character cap before the form the caller was looking for appears at all.

The page's HTML, cleaned down to what is worth reading.

Use this when the STRUCTURE matters - a form and its labels, a table, what a control is wired to. browser_snapshot gives a flat inventory of things to click; this keeps the markup and the relationships inside it.

mode="form" keeps the interactive surface and the text explaining it, mode="text" returns the prose alone, mode="full" keeps the structure with the noise and the attribute soup removed.

Unlike browser_read_text this is NOT capped: it returns the whole reduced page, which on a large one is tens of thousands of characters. That is deliberate, because cutting markup in the middle leaves tags that no longer mean anything - but it means the answer can be long. Reach for browser_snapshot when you only need something to click, or browser_read_text when you only need the words.

One screenshot of the active tab, on demand.

The whole browser window as a person at the machine sees it: tab strip, address bar, the page and the pointer, from a live capture kept running on the active tab. For watching the work, not for acting on it: the picture is window pixels, so do not feed its coordinates to browser_click_at; use browser_take_screenshot for that.

Click the first element matching a CSS selector.

Scrolls it into view and waits for it to be clickable. When no selector can describe the target, use browser_click_at with coordinates from browser_snapshot.

Click (or press-and-hold) a raw viewport coordinate instead of a selector - for targets a selector cannot reliably reach: a slider track, a canvas-drawn captcha, or a precise point inside a wider element. Moves the pointer there first (no teleport), then down, then up, holding first if hold_seconds is set. Returns a screenshot taken right after release.

hold_seconds needs invisible-playwright 0.9.0 or newer to mean anything. In every earlier version the wait it is built on returned instantly, so the press and the release happened in the same frame and the hold never happened - on the one tool that exists for sliders and press-and-hold challenges. The floor in pyproject.toml is set accordingly.

Coordinates are relative to the VIEWPORT, not to the page, so the ones in a snapshot go stale the moment anything scrolls: a click, a keypress, a lazy image loading in above the fold. Nothing raises when that happens - the click simply lands on whatever is at that spot now. Take a fresh snapshot after anything that could have moved the page, and prefer browser_click with the element's selector whenever it has one.

Fill a field, replacing whatever it holds.

This sets the value rather than typing key by key, so it will not fire the per-keystroke handlers an autocomplete needs. For those, click the field and use browser_press_key.

Choose an option in a dropdown (<select>), by its visible label or by its value.

Use this rather than clicking the dropdown and pressing arrow keys: a click plus arrows cannot tell you which row it landed on, and setting the value through browser_evaluate changes it without the page seeing a real interaction.

Press a key on whatever has focus: "Enter", "Tab", "Escape", "ArrowDown", "Control+a", or a single character.

READ from the page with JavaScript and get the result as JSON.

For what the other tools cannot see: a computed style, a value held in a framework's state, the length of a list.

Acting on the page is refused, and the refusal names the tool to use. Assigning to value, checked or selected, or calling click(), dispatchEvent(), submit() or requestSubmit(), changes the page without a real keystroke or pointer, and a page can tell. Use browser_click, browser_type or browser_select_option instead; they do the same thing through the pointer and the keyboard. Reading any of those properties is fine.

The refusal catches the obvious spellings, not every possible one. A script that slips past it is still the wrong way to do the thing: report it in your answer rather than using it.