Skip to main content
Glama

Open a browser

writ_browser_use
Destructive

A REAL CLOUD BROWSER FOR A TASK ON A SITE: the user's signed-in account (a persona_id from writ_personas: the password stays sealed in Writ, and sessions never ask for a password), a click, form, submit or search inside an app, or a page a plain fetch cannot open (login wall, 403, CAPTCHA). Opens the browser and returns the first page; writ_browser_act drives it (Writ runs no model here). Recording is always on: writ_browser_save turns the session into a workflow that replays without a browser, writ_browser_cancel closes it (an open browser bills). The start answer carries the action vocabulary, the recording rules and, with a persona, the 2FA rules. NOT FOR: reading pages (writ_scrape). An API: writ_website_to_api opens this same browser, bound to a build.

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": {
      "url": "<url>"
    },
    "name": "writ_browser_use"
  }
}

Input Schema

NameRequiredDescriptionDefault
urlYes
goalNo
auth_modeNo
fresh_exitNo
persona_idNo
idempotency_keyNo
use_residentialNoResidential exit (bot walls, another country). Omitted: Writ's residential list decides. Pair with residential_country.
execution_targetNocloud | auto | local (the user's own desktop app).
residential_countryNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / idempotency_key
      Added value: +{
      +  "type": "string"
      +}
  2. Changed4 schema fields changed
    • addedInput schema / properties / auth_mode
      Added value: +{
      +  "enum": [
      +    "reuse",
      +    "fresh_login"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / fresh_exit
      Added value: +{
      +  "type": "boolean"
      +}
    • addedInput schema / properties / residential_country
      Added value: +{
      +  "type": "string"
      +}
    • changedInput schema / properties / use_residential / description
      Previous value: -"Open on the residential network (bot walls, CAPTCHAs)."New value: +"Residential exit (bot walls, another country). Omitted: Writ's residential list decides. Pair with residential_country."
  3. Changed9 schema fields changed
    • removedInput schema / properties / auth_mode
      Removed value: -{
      -  "description": "reuse verifies unknown saved authentication before adopting it; fresh_login starts without old cookies/storage while preserving the persona's device and network identity, the mode for recording a new login.",
      -  "enum": [
      -    "reuse",
      -    "fresh_login"
      -  ],
      -  "type": "string"
      -}
    • changedInput schema / properties / execution_target / description
      Previous value: -"Where the session runs: 'cloud' (managed cloud fleet), 'auto' (the user's own linked Writ desktop app when it is online, else cloud), or 'local' (only their own desktop app). On the user's own machine the session keeps their computer and IP and exposes nothing local to the cloud. No value means the account's default set in the Writ app. A 'local' run reports local_agent_offline when their app is closed; execution_target='cloud' re-runs it in the cloud, off the user's machine."New value: +"cloud | auto | local (the user's own desktop app)."
    • removedInput schema / properties / fresh_exit
      Removed value: -{
      -  "description": "Residential only: skips the persona's usual exit for this site and draws a new address, for after the site refused it (an IP rate limit, a sign-in rejected with correct credentials). Ignored on server-IP egress.",
      -  "type": "boolean"
      -}
    • removedInput schema / properties / goal / description
      Removed value: -"Optional label describing the task, for the run log. A label only: the tool performs no step from it, and every step is a writ_browser_act batch."
    • removedInput schema / properties / human_layer
      Removed value: -{
      -  "description": "Native keyboard input, distance-adaptive mouse paths and pre-click dwell for this session. Fresh login defaults to enabled; explicit false disables it. Native actionability checks remain active.",
      -  "type": "boolean"
      -}
    • removedInput schema / properties / persona_id / description
      Removed value: -"Saved identity to sign in with (writ_personas lists them). Required for sites behind a login with 2FA. A desktop persona ('device:…') opens the browser on its own desktop, which fills {{secret:username}} / {{secret:password}} / 2FA itself; its values never reach the caller."
    • removedInput schema / properties / residential_country
      Removed value: -{
      -  "description": "Two-letter ISO country the residential exit should be in (e.g. 'us', 'fr'), for a site that serves a different page per country or throttles foreign traffic. No value means an automatic exit. Ignored unless the session egresses residential.",
      -  "type": "string"
      -}
    • removedInput schema / properties / url / description
      Removed value: -"Starting URL to open (required)."
    • changedInput schema / properties / use_residential / description
      Previous value: -"Opens on the platform residential network (premium), for a site that blocks datacenter IPs or shows a bot wall / captcha. Default off (free)."New value: +"Open on the residential network (bot walls, CAPTCHAs)."
  4. First observed

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already flag destructive=true, openWorld=true and non-idempotent, but the description adds material context beyond them: recording is always on, an open browser bills money, sessions never prompt for a password because credentials stay sealed, and no model runs server-side. What it does not disclose is why the operation is destructive beyond billing, or how the caller should clean up on failure.

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?

Front-loaded with the core verb and the trigger conditions, then lifecycle and exclusions, so the reader hits the important parts first. The opening clause is a dense fragment and the parenthetical asides make some sentences hard to parse, but no sentence is filler.

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

Completeness3/5

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

For a 9-parameter, destructive, open-world tool with no output schema, the description covers the lifecycle and return shape ('returns the first page', 'start answer carries the action vocabulary') reasonably well. It still leaves several parameters and any failure/cleanup semantics unexplained, which is a real gap for a billing, stateful operation.

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

Parameters3/5

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

Schema description coverage is only 22% across 9 parameters, so the description has to compensate. It adds real meaning for persona_id (drawn from writ_personas, password sealed, no password prompts) and implicitly for auth_mode, but goal, fresh_exit, idempotency_key and execution_target are left undocumented in both places.

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 concrete verb and resource ('Opens the browser and returns the first page') and enumerates the triggering situations: signed-in persona account, click/form/submit/search inside an app, or a page a plain fetch cannot open. It explicitly names what it is not (writ_scrape for reading, writ_website_to_api for API builds), so an agent can separate it from its siblings without opening schemas.

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

Usage Guidelines5/5

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

Gives explicit when-to-use conditions (login wall, 403, CAPTCHA, interactive app actions) plus a dedicated NOT FOR clause routing to writ_scrape. It also maps the downstream lifecycle tools (writ_browser_act drives, writ_browser_save records, writ_browser_cancel closes), which is genuine alternative-selection guidance.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.