Ostler MCP tools and profiles

Explore Ostler's MCP tool profiles and parameters for navigation, quotations, evidence gaps, forms and optional memory.

Ostler exposes 32 MCP tools in five profiles. --tools auto|core|forms|research|all (or OSTLER_TOOLS) controls how many the agent sees. The default, auto, starts with the 16 core tools (4.9 KB of schema), adds the research tools after the first read or search, and adds the form and memory tools once a page shows form fields. The server sends tools/list_changed, the result names the new tools, and every tool stays callable even if a client never refreshes its list. The full set is about 9.7 KB of schema, roughly 2.7k tokens on every turn, and a test keeps it under 11 KB. Tool output is terse by default (verified fields are named once, no timings or fingerprints); --verbose brings the debug detail back.

Page-derived text in results (page content, titles, URLs, dialog text, the look legend) is wrapped in <page_content untrusted="true">. The server instructions tell the model not to follow it. See Security model.

Browse (profile: core)#

navigate#

Open a URL. Returns page state with interactive elements, so no separate snapshot call is needed.

It reports the HTTP status (Navigated (HTTP 404)) with a plain-language reason, labels PDFs, downloads and redirects to a sign-in page, and explains navigation errors. A CAPTCHA or "verify you are human" page produces a CHALLENGE: line at the top. On a search-results URL whose visible text matches fewer than about half of the query's words, it adds a Warning: results do not seem to match the query.

snapshot#

Read the page as text with element refs (e1, e2, …). Use delta to see only changes. Pass the ref of a heading to read just that section.

Long text is split into several lines with an explicit … [N more chars cut] marker. Text a person cannot see is left out and counted.

read#

Read a page for research (opens url if given). With query: only the best passages, ranked locally with BM25 and MMR, so a page costs a few hundred tokens instead of the whole text. Without: the start of the page. Only pages read this session can be cited.

The header names the page, its size, fetch time and content hash, and flags what a reader must know first: PAYWALL, CHANGED (the page differs from an earlier read; earlier citations from it are re-checked), the page's own paging text (showing 1-5 of 13), and ATTENTION when the page contains text aimed at an AI. A bot wall, robots.txt refusal, HTTP error or empty page is NOT READ and is recorded as a gap, never as a source.

click#

Click an element by ref. The result ends with a Result: line: navigated, popup opened as tab tN, page updated, or no visible change.

hover#

Move the pointer over an element by ref (opens menus and tooltips).

scroll#

Scroll an element into view (ref) or the page (direction). Reports the position as scrolled/max, so the agent knows when it has reached the end of an infinite list.

type#

Type into an element by ref, replacing its content.

press#

Press a key, for example Enter, Tab, Escape, Control+a.

wait_for#

Wait until text appears or disappears, or a CSS selector shows, or just pause for ms milliseconds (max 10000).

wait_for_human#

A CAPTCHA or verification wall is blocking the page: wait for the user to complete it in the browser window. Needs --headed. Ostler never solves these itself.

screenshot#

Capture a PNG of the page or one element.

look#

See where to click: a screenshot with every clickable element boxed and numbered by its ref, plus a legend saying what each does (type here, submits the form, error, …). Use the refs with click, type and fill_field.

Boxes come from DOM geometry and are coloured by role: green submits, blue inputs, purple links, red has an error. Elements hidden under a cookie banner, modal or sticky bar are left out and counted, so the agent closes the overlay first. It covers only the visible viewport. The overlay is removed afterwards. With --lean, screenshots omit images.

back#

Go back in history. Takes no parameters. At the start of a tab's history it says so instead of landing on about:blank.

Tabs and shared notes (profile: core)#

tabs#

Manage tabs. They share cookies and the context tool. Popups open as new tabs.

search_tools#

Find Ostler tools without listing them all: names, one-line descriptions or full input schemas for any tool, listed or not.

context#

Notes shared by every tab and later calls: get, set, delete, list. Keep short facts, not page dumps. Survives a browser restart.

Research (profile: research)#

Built around one contract: an answer can only contain what was read and verified. See the Cookbook for the workflow.

cite#

Check a quote against a page read this session. VERIFIED returns the page's exact words and a #:~:text= link a person can open to check them. NOT READ (the page was never read), NOT VERIFIED (with the closest text on the page) and TOO SHORT are errors: do not use that claim. Markdown on either side is ignored, so **1887** and [Marta Ilves](/m) still verify.

evidence#

What the agent has read and may state: verified citations, citations made stale by a changed page, pages read but not cited, and the gaps (paywall, bot wall, robots.txt, HTTP error, empty page). Call it before answering. Takes no parameters.

search#

Web search through SearXNG (OSTLER_SEARXNG_URL) or Brave (OSTLER_SEARCH_PROVIDER=brave and OSTLER_BRAVE_API_KEY). Returns titles, URLs and snippets; a snippet is not evidence until the page is read.

open_many#

Read up to 10 URLs in a scratch tab; the agent's current tab is untouched. The domain policy is checked before robots.txt is fetched, robots.txt (RFC 9309) is obeyed, requests to one host are spaced, and the call has a time budget. Each page's outcome is reported.

extract#

Structured data from the current page: tables as rows, or lists of repeated cards with pagination hints and a completeness verdict (PARTIAL: 5 of 13 when the page states a total it does not show).

links#

Links on the current page with anchor text and context, optionally filtered.

run#

Run a short Rhai script for multi-page jobs. Loops, filtering and counting happen outside the context; only the script's printed lines and final value come back, inside the untrusted fence. In the script, tool("read", #{url: u, query: "price"}) runs any Ostler tool and returns its text; grep(text, word), lines(text) and print(x) help. No files, network, modules or eval; at most 60 tool calls; every call keeps the profile, allowlist, robots.txt and submit-gate rules, and run cannot call run. See ADR-0019.

Forms (profile: forms)#

form_inspect#

List the page's forms as typed fields (label, kind, required, options, errors) plus submit controls and what memory knows about this form.

form_fill#

A value written {{fact:KEY}} is replaced by the saved fact with that key, so the value never has to pass through the agent. An unknown key fails the call.

Fill many fields at once from {label | name | ref: value}. Handles selects, radios, checkbox groups, dates, files, comboboxes and dependent dropdowns, and verifies each field by reading it back. auto: "required" or "all" fills the rest from memory.

The report names each field OK, or says UNMATCHED (no field matches the key), ambiguous (several match equally well, so use the ref), or a read-back mismatch. It lists fields still empty and required, and says unsettled (a count) when the page was still busy at the end of the fill. File fields are refused unless --upload-dir allows the directory.

form_submit#

Click the form's submit or next control and report whether it was accepted, advanced to another step, or failed validation.

Result: Submitted, Advanced (next step), NOT ACCEPTED with the page's own messages, or Nothing changed when the form stays put and says nothing. Just before clicking it re-reads the fields it verified and reports any the page cleared or rewrote (CHANGED BEFORE SUBMIT).

fill_field#

Set one field by ref (any kind, including custom widgets).

Memory (profile: all)#

These need memory enabled (--memory local, a Qdrant URL, or --memory ephemeral). See Memory and privacy.

memory_remember#

Save a fact about the user for future forms (for example email, company). Secrets are refused.

memory_recall#

Semantic search over saved facts.

memory_list#

List all saved facts. Takes no parameters.

memory_forget#

Delete a saved fact by key.

stats#

Session cost and latency counters: calls, milliseconds, estimated tokens, browser memory. Takes no parameters.

Design notes#

• Observation is part of the action. navigate returns the interactive elements; clicks and typing return only what changed. observe: none opts out but still records a baseline.
• Actions are never replayed after a navigation. Calls that change the page report that the page changed instead of re-running.
• A crashed Chrome is relaunched and the agent is told. Open tabs and page state are lost.

View this page’s source on GitHub