Jev Browser

Navigate a browser with Jev

jev_navigate

Drives a headless browser to complete a task from a start URL, returning the final page, step trace, errors, and token cost. Supports secure password fills and cookie seeding.

Instructions

Give a task and a start URL; a Jev-driven agent navigates a real headless browser until the goal is met, the stuck gate fires, or a budget (steps/seconds) is exhausted. Returns the final page in a chosen format (text, markdown, html, or an aria snapshot), the full step trace with confidences, console/page/network errors captured along the way, token usage with estimated cost, and a final screenshot. The result also reports typing degradation explicitly (degraded, warnings with codes, typing_provider, typing_model), so a failed typing generator is visible instead of silently typing keyword soup. For logins: with JEV_BROWSER_PASSWORD_ORIGIN set in this server's environment, password_file or password_env fills native password fields on that origin only, without the value ever entering model context, traces, or screenshots; never put the password value itself in any argument or in the task. To start already logged in, seed a session cookie instead via cookie_file or cookie_env (same reference-based delivery and redaction).

Input Schema

TableJSON Schema

Name	Required	Description
`task`	Yes	What the agent should accomplish, in natural language.
`format`	No	Final page payload format: text (default, 8k chars), markdown (16k, via turndown), html (1MB, for app-side parsing), aria (16k, Playwright aria snapshot YAML).
`max_chars`	No	Override the format's default character cap (at most 1,000,000, the html format's default).
`max_steps`	No	Hard step cap. Default 24.
`start_url`	Yes	Where to start.
`cookie_env`	No	Seed cookies with values from JEV_COOKIE_* environment variables; naming a variable with that prefix is the operator's opt-in, any other name is rejected. Redacted like passwords.
`screenshot`	No	Final viewport JPEG. Default 'final'. Suppressed automatically after a password fill.
`cookie_file`	No	Seed cookies so the run starts behind a login, e.g. a session cookie captured elsewhere. Values arrive by reference and are redacted like passwords. Never put a cookie value itself in any argument.
`max_seconds`	No	Wall-clock cap in seconds. Default 180.
`allow_typing`	No	Whether the agent may type into fields. Uses the configured small model; when it fails, ordinary fields are left empty with a warning and search boxes fall back to a keyword heuristic. Default true.
`password_env`	No	Password fill: name of a JEV_PASSWORD_* environment variable visible to this server. Naming a variable with that prefix is the operator's opt-in; any other name is rejected. Requires JEV_BROWSER_PASSWORD_ORIGIN in this server's environment.
`password_file`	No	Password fill: absolute path inside the handoff directory (default ~/.jev-browser/handoff; override with JEV_BROWSER_HANDOFF_DIR) holding the password, written by your secret manager (e.g. op read --no-newline --out-file ...). The file is consumed and deleted at run start. Requires JEV_BROWSER_PASSWORD_ORIGIN in this server's environment. Never put the password value itself here.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.8.1Sep 30, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedInput schema / properties / max_chars / description

Previous value: -"Override the format's default character cap."New value: +"Override the format's default character cap (at most 1,000,000, the html format's default)."

changedInput schema / properties / max_chars / maximum

Previous value: -9007199254740991New value: +1000000

Changed4 schema fields changedv0.7.0Sep 26, 2026
- removedInput schema / additionalProperties
```
Removed value: -false
```
- removedInput schema / properties / cookie_env / items / additionalProperties
```
Removed value: -false
```
- removedInput schema / properties / cookie_file / items / additionalProperties
```
Removed value: -false
```
- addedInput schema / properties / max_chars / maximum
```
Added value: +9007199254740991
```

Changed2 schema fields changedv0.5.0Sep 23, 2026

addedInput schema / properties / cookie_env

Added value: +{
+  "description": "Seed cookies with values from JEV_COOKIE_* environment variables; naming a variable with that prefix is the operator's opt-in, any other name is rejected. Redacted like passwords.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "domain": {
+        "description": "Omit (recommended): host-only on the start URL's exact host. '.example.com' (leading dot) also matches subdomains.",
+        "maxLength": 256,
+        "type": "string"
+      },
+      "env": {
+        "description": "Name of a JEV_COOKIE_* environment variable visible to this server.",
+        "maxLength": 256,
+        "minLength": 1,
+        "type": "string"
+      },
+      "httpOnly": {
+        "description": "Defaults to true; set false only if the site's own scripts must read this cookie.",
+        "type": "boolean"
+      },
+      "name": {
+        "description": "Cookie name, e.g. session.",
+        "maxLength": 256,
+        "minLength": 1,
+        "type": "string"
+      },
+      "path": {
+        "description": "Defaults to '/'.",
+        "maxLength": 1024,
+        "type": "string"
+      },
+      "sameSite": {
+        "description": "Defaults to 'Lax'.",
+        "enum": [
+          "Strict",
+          "Lax",
+          "None"
+        ],
+        "type": "string"
+      },
+      "secure": {
+        "description": "Defaults to true on https start URLs. Forced true for __Host-/__Secure- names and sameSite \"None\"; secure: false cannot strip a forced flag.",
+        "type": "boolean"
+      }
+    },
+    "required": [
+      "name",
+      "env"
+    ],
+    "type": "object"
+  },
+  "minItems": 1,
+  "type": "array"
+}

addedInput schema / properties / cookie_file

Added value: +{
+  "description": "Seed cookies so the run starts behind a login, e.g. a session cookie captured elsewhere. Values arrive by reference and are redacted like passwords. Never put a cookie value itself in any argument.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "domain": {
+        "description": "Omit (recommended): host-only on the start URL's exact host. '.example.com' (leading dot) also matches subdomains.",
+        "maxLength": 256,
+        "type": "string"
+      },
+      "file": {
+        "description": "Path inside the handoff directory (default ~/.jev-browser/handoff; override with JEV_BROWSER_HANDOFF_DIR) holding this cookie's value, written by your secret manager. The file is consumed and deleted at run start.",
+        "maxLength": 4096,
+        "minLength": 1,
+        "type": "string"
+      },
+      "httpOnly": {
+        "description": "Defaults to true; set false only if the site's own scripts must read this cookie.",
+        "type": "boolean"
+      },
+      "name": {
+        "description": "Cookie name, e.g. session.",
+        "maxLength": 256,
+        "minLength": 1,
+        "type": "string"
+      },
+      "path": {
+        "description": "Defaults to '/'.",
+        "maxLength": 1024,
+        "type": "string"
+      },
+      "sameSite": {
+        "description": "Defaults to 'Lax'.",
+        "enum": [
+          "Strict",
+          "Lax",
+          "None"
+        ],
+        "type": "string"
+      },
+      "secure": {
+        "description": "Defaults to true on https start URLs. Forced true for __Host-/__Secure- names and sameSite \"None\"; secure: false cannot strip a forced flag.",
+        "type": "boolean"
+      }
+    },
+    "required": [
+      "name",
+      "file"
+    ],
+    "type": "object"
+  },
+  "minItems": 1,
+  "type": "array"
+}

Changed4 schema fields changedv0.4.1Sep 22, 2026

changedInput schema / properties / allow_typing / description

Previous value: -"Whether the agent may type into fields (uses the configured small model, or a keyword fallback). Default true."New value: +"Whether the agent may type into fields. Uses the configured small model; when it fails, ordinary fields are left empty with a warning and search boxes fall back to a keyword heuristic. Default true."

addedInput schema / properties / password_env

Added value: +{
+  "description": "Password fill: name of a JEV_PASSWORD_* environment variable visible to this server. Naming a variable with that prefix is the operator's opt-in; any other name is rejected. Requires JEV_BROWSER_PASSWORD_ORIGIN in this server's environment.",
+  "maxLength": 256,
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / password_file

Added value: +{
+  "description": "Password fill: absolute path inside the handoff directory (default ~/.jev-browser/handoff; override with JEV_BROWSER_HANDOFF_DIR) holding the password, written by your secret manager (e.g. op read --no-newline --out-file ...). The file is consumed and deleted at run start. Requires JEV_BROWSER_PASSWORD_ORIGIN in this server's environment. Never put the password value itself here.",
+  "maxLength": 4096,
+  "minLength": 1,
+  "type": "string"
+}

changedInput schema / properties / screenshot / description

Previous value: -"Final viewport JPEG. Default 'final'."New value: +"Final viewport JPEG. Default 'final'. Suppressed automatically after a password fill."

First observedv0.2.0Sep 18, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the entire behavioral burden and does so richly: termination conditions, that password values never enter model context/traces/screenshots, the JEV_BROWSER_PASSWORD_ORIGIN origin restriction, reference-based delivery with redaction, and that handoff files are consumed and deleted at run start. It also discloses failure modes (typing degradation reported explicitly rather than silently emitting 'keyword soup') and the auto-suppression of screenshots after a password fill.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense paragraphs are front-loaded with the purpose and return payload, then the security/authentication details. Given 12 parameters and a security-sensitive surface, the length is justified, though the login paragraph could be tightened slightly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description must describe returns — and it enumerates the final page payload, step trace with confidences, console/page/network errors, token usage with estimated cost, final screenshot, and typing-degradation fields. For a tool of this complexity it leaves nothing essential unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is already 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the intent behind the security-relevant parameters — never placing the password value in an argument, the env-prefix opt-in model, and the equivalence of password_* and cookie_* reference delivery. It does not document the budget or format parameters, which the schema already handles well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence names a specific verb and resource ('a Jev-driven agent navigates a real headless browser') and states the exact termination conditions (goal met, stuck gate, budget exhausted). An agent knows precisely what this tool does without opening the schema. There are no siblings, but the scope is still unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear conditional guidance for the two authentication paths: use password_file/password_env for native password fields, or seed a session cookie via cookie_file/cookie_env 'to start already logged in'. It also frames when typing degradation matters. It stops short of stating when not to use the tool at all, so it is clear context rather than full when/when-not routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools

jev_navigateA