Skip to main content
Glama

browser_create_identity

Create a browser identity for a website the person must sign in to (or sign up on) themselves, and get back a link to give them. Opening the link shows a live browser on the site; when they have signed in they press 'I'm logged in, save session' and the identity becomes active, after which browser.open / browser.attach_identity work with it. Use browser.handoff instead for an identity that already exists and is active. For a plain username + password sign-in form WITHOUT captcha or 2FA, pass username, password and confirm_sign_in_stored=true and the platform signs in itself (admin or owner only): the answer is status 'active' on success, or the reason plus the human link when the site wanted more (a captcha, a code). When the site refuses the username or password, an identity created by this call is deleted again (status 'deleted'); one that already existed is left as it was. The password is kept encrypted in the workspace's secret store and used to sign in again when the session expires.

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": {
      "name": "<name>",
      "origin": "<origin>"
    },
    "name": "browser_create_identity"
  }
}

Input Schema

NameRequiredDescriptionDefault
urlNoThe first page the person lands on, e.g. a signup page. Must be on the same domain as origin. Omit to start on the origin.
nameYesName for the identity, unique in the workspace (e.g. 'stripe_main'). A pending identity of the same name is resumed.
originYesThe site the identity is for, an https address (e.g. https://dashboard.example.com).
passwordNoThe site's own password for username. Stored encrypted, never returned or logged. Or a `clip:` handle from clipboard.copy(source={identity_id}) of an identity on the SAME origin (another workspace's sign-in to the same site), so the password is never seen.
usernameNoThe site's own login (email or username). With password, the platform signs the identity in itself instead of waiting for a person. Admin or owner only.
in_workspaceNoRun this one call in this workspace id instead of the session's. Nothing is stored; other sessions are not affected.
confirm_sign_in_storedNoRequired true with username and password: the an admin or the owner of the workspace confirms that the platform stores this sign-in encrypted, types it into the site's login form in its own browser and keeps the session (the disclosure a person accepts in the sign-in window). Journalled. OMIT when not signing in.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / password / description
      Previous value: -"The site's own password for username. Stored encrypted, never returned or logged."New value: +"The site's own password for username. Stored encrypted, never returned or logged. Or a `clip:` handle from clipboard.copy(source={identity_id}) of an identity on the SAME origin (another workspace's sign-in to the same site), so the password is never seen."
  2. Changed3 schema fields changed
    • addedInput schema / properties / confirm_sign_in_stored
      Added value: +{
      +  "description": "Required true with username and password: the an admin or the owner of the workspace confirms that the platform stores this sign-in encrypted, types it into the site's login form in its own browser and keeps the session (the disclosure a person accepts in the sign-in window). Journalled. OMIT when not signing in.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / password
      Added value: +{
      +  "description": "The site's own password for username. Stored encrypted, never returned or logged.",
      +  "type": "string"
      +}
    • addedInput schema / properties / username
      Added value: +{
      +  "description": "The site's own login (email or username). With password, the platform signs the identity in itself instead of waiting for a person. Admin or owner only.",
      +  "type": "string"
      +}
  3. Added

TDQS

A4.8/5.0
Behavior5/5

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

Goes well past the annotations: it explains the pending-then-active lifecycle, the human confirmation step ('I'm logged in, save session'), the deletion of a just-created identity when the site rejects the credentials, and the encrypted secret-store persistence used to re-sign-in on session expiry. The one tension with destructiveHint=false — an identity gets deleted on credential refusal — is explicitly bounded ('one that already existed is left as it was'), so it reads as cleanup of this call's own side effect rather than a contradiction.

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?

The primary path is front-loaded in the first sentence and every clause carries information an agent needs. The middle sentence stacks many nested conditions into a single run-on, which costs readability but not correctness.

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?

For a 7-parameter creation tool with no output schema, the description covers the full lifecycle, the outcome vocabulary the agent should expect ('active', 'deleted', a reason plus human link), persistence, and the permission model. Nothing needed to call it correctly or interpret the result 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 already 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema cannot: username + password + confirm_sign_in_stored must be passed together, and only for forms without captcha or 2FA. It does not restate the url/origin relationship or the clip: handle mechanics, which stay in the schema only.

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 ('Create a browser identity') plus the concrete artifact returned ('a link to give them'), and explicitly separates it from browser.handoff and browser.attach_identity. An agent can tell which of the three identity tools to pick without opening a schema.

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 routing rules: use browser.handoff for an identity that already exists and is active, use this one for sites a person must sign in to themselves. It also names the sub-case that changes behavior (plain username/password form without captcha or 2FA) and the permission gate (admin or owner only).

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.