BrowserPair

Start browser task

browser_run

Start a browser task in the user's own Chrome profile. It starts on allowed_domains and may use every tool; other sites are added when the task needs them (or the user is asked, as their BrowserPair Permissions say). It does not act by itself: continue with task_state, task_subgoal or task_respond. Every call starts a new task (and uses one task credit once the browser accepts it) unless idempotency_key repeats an earlier identical request, which returns that task with replayed: true.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "goal": "<goal>",
      "browser_id": "<browser_id>",
      "allowed_domains": "<allowed_domains>"
    },
    "name": "browser_run"
  }
}

Input Schema

Name	Required	Description
`goal`	Yes	The user's request in their own words, as the task's goal.
`browser_id`	Yes	A browser id from browser_list.
`capabilities`	No	Optional. Every task holds every capability; the user's Permissions decide which sensitive steps wait for their approval.
`confirmations`	No	Capabilities that must always pause for the user's approval in Chrome, even when their settings would not ask. Usually omit.
`allowed_domains`	Yes	Hostnames the task starts on (subdomains included), e.g. ["github.com"]. Name the sites the request is about.
`idempotency_key`	No	Reuse only to retry the exact same request after a lost response; omit to start a new task.
`max_side_effects`	No	Hard cap on page-changing steps in this task: every click, fill, select, key press, upload and submit counts as one, so a form with four fields and a submit needs at least 5. Omit it (no cap) unless the user explicitly asked for a limit; it is not a number of submissions.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 7, 2026
- removedInput schema / $schema
```
Removed value: -"https://json-schema.org/draft/2020-12/schema"
```

Changed2 schema fields changedOct 24, 2026

changedInput schema / properties / allowed_domains / description

Previous value: -"Hostnames the task may visit (subdomains included), e.g. [\"github.com\"]. Name every site the request needs."New value: +"Hostnames the task starts on (subdomains included), e.g. [\"github.com\"]. Name the sites the request is about."

changedInput schema / properties / capabilities / description

Previous value: -"What the task may do on those sites. Omit for ordinary low-risk browsing; add fill, select, click, state_change and so on when the request needs them."New value: +"Optional. Every task holds every capability; the user's Permissions decide which sensitive steps wait for their approval."

First observedOct 20, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Goes well beyond the annotations by disclosing the credit cost ('uses one task credit once the browser accepts it'), the domain-expansion and user-approval policy tied to BrowserPair Permissions, and the replay behavior ('returns that task with replayed: true'). These are operational traits an agent cannot get from readOnlyHint/openWorldHint alone, and none contradict the declared hints.

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?

Three sentences, front-loaded with the action and then the sequencing rule, then the idempotency/cost caveat. Dense but each clause carries information; the parenthetical '(or the user is asked, as their BrowserPair Permissions say)' is slightly convoluted phrasing that could be tightened.

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

Completeness4/5

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

For a 7-parameter task-creating tool with no output schema, it covers the essentials an agent needs: cost, domain scoping, follow-up call pattern, and idempotency. Minor gaps remain, such as not stating what the initial response contains besides the task, but nothing critical is missing.

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 coverage is 100%, so the baseline is 3, but the description adds real meaning: allowed_domains is a starting set rather than a hard boundary, and idempotency_key maps to a distinct replay return path. The capability-within-permissions nuance is left mainly to the schema, so it stops short of 5.

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?

States a specific verb and resource ('Start a browser task in the user's own Chrome profile') and immediately scopes it as a task-creation call rather than an acting call. The line 'It does not act by itself: continue with task_state, task_subgoal or task_respond' separates it cleanly from the sibling task_* tools.

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?

Explicitly routes the agent to the follow-up tools (task_state, task_subgoal, task_respond) and explains that allowed_domains is only the starting set, with other sites added at runtime. It also warns that every call starts a new task unless idempotency_key repeats an identical request, which is the key misuse risk. It does not explicitly say to call browser_list first, though the browser_id schema field does.

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

All BrowserPair tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?