agent-browser

Use for: loading a web page in a real Chromium browser and reading it. Returns the page title, final URL and a clean text extract (up to 8000 chars). Don't use when: you only need raw HTML or an API response — a plain HTTP fetch is cheaper. Errors are structured: NAV_TIMEOUT, NAV_FAILED, INVALID_URL.

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "string",
      "minLength": 1,
      "description": "Session ID. Reuse the same ID to keep cookies, login state and page position across calls; a new ID starts a fresh browser."
    },
    "url": {
      "type": "string",
      "description": "Absolute http(s) URL to load."
    },
    "wait_for": {
      "type": "string",
      "description": "Optional CSS selector to wait for after load (max 10s)."
    }
  },
  "required": [
    "session_id",
    "url"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    },
    "url": {
      "type": "string"
    },
    "text": {
      "type": "string"
    },
    "session_id": {
      "type": "string"
    }
  },
  "required": [
    "title",
    "url",
    "text",
    "session_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Use for: pulling repeated elements (prices, titles, links) from the page a session is on, via a CSS selector, or the full page text when no selector is given. Returns one string per matched element. Don't use when: the page has not been loaded yet — call browser_navigate first.

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "string",
      "minLength": 1,
      "description": "Session ID. Reuse the same ID to keep cookies, login state and page position across calls; a new ID starts a fresh browser."
    },
    "selector": {
      "type": "string",
      "description": "CSS selector to extract. Omit for full page text."
    },
    "attribute": {
      "type": "string",
      "description": "Attribute to read instead of text, e.g. href or src."
    }
  },
  "required": [
    "session_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "count": {
      "type": "number"
    }
  },
  "required": [
    "results",
    "count"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Use for: understanding page structure cheaply and deterministically — returns the accessibility tree (roles, names, states) as compact YAML instead of pixels or raw HTML. This is the lowest-token way to decide what to click or fill next. Don't use when: you need visual layout or images — use browser_screenshot.

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "string",
      "minLength": 1,
      "description": "Session ID. Reuse the same ID to keep cookies, login state and page position across calls; a new ID starts a fresh browser."
    }
  },
  "required": [
    "session_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "snapshot": {
      "type": "string"
    },
    "url": {
      "type": "string"
    }
  },
  "required": [
    "snapshot",
    "url"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Use for: interacting with the page — click, fill, type, select, submit, press. Returns the resulting page title, URL and text so you can verify the action landed. Don't use when: the target element is not on the current page — navigate or snapshot first. This tool can change remote state (it can submit forms).

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "string",
      "minLength": 1,
      "description": "Session ID. Reuse the same ID to keep cookies, login state and page position across calls; a new ID starts a fresh browser."
    },
    "action": {
      "type": "string",
      "enum": [
        "click",
        "fill",
        "type",
        "select",
        "submit",
        "press"
      ],
      "description": "The interaction to perform on the target element."
    },
    "selector": {
      "type": "string",
      "description": "CSS selector of the target element."
    },
    "value": {
      "type": "string",
      "description": "Value for fill/type/select, or key name for press (default Enter)."
    }
  },
  "required": [
    "session_id",
    "action",
    "selector"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean"
    },
    "title": {
      "type": "string"
    },
    "url": {
      "type": "string"
    },
    "text": {
      "type": "string"
    }
  },
  "required": [
    "success",
    "title",
    "url",
    "text"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Use for: visual verification — layout, images, charts, CAPTCHA presence, or evidence of page state. Returns a PNG image (JPEG if the PNG exceeds 2.5MB). Don't use when: you only need the page's content or structure — browser_extract and browser_snapshot are far cheaper in tokens.

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "string",
      "minLength": 1,
      "description": "Session ID. Reuse the same ID to keep cookies, login state and page position across calls; a new ID starts a fresh browser."
    },
    "full_page": {
      "type": "boolean",
      "description": "Capture the full scrollable page instead of the viewport."
    }
  },
  "required": [
    "session_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "bytes": {
      "type": "number"
    },
    "mime_type": {
      "type": "string"
    },
    "url": {
      "type": "string"
    }
  },
  "required": [
    "bytes",
    "mime_type",
    "url"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Use for: ending a session and freeing its browser. Sessions also expire automatically after 10 idle minutes. Free on every door — closing is never charged.

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "string",
      "minLength": 1,
      "description": "Session ID. Reuse the same ID to keep cookies, login state and page position across calls; a new ID starts a fresh browser."
    }
  },
  "required": [
    "session_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "closed": {
      "type": "boolean"
    },
    "session_id": {
      "type": "string"
    }
  },
  "required": [
    "closed",
    "session_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}