Skip to main content
Glama

Aginx Browser

by net.aginx
OverviewDiscussionsAdmin

session_create

Create a persistent interactive browser session for multi-step interaction - clicking, typing, scrolling, reading state across page transitions. Use when the agent must INTERACT with a page (login flows, forms, pagination, click-through) rather than read it once. Returns session_id; persists 8 min idle. With persistent:true the login state survives idle eviction and server restarts - the same session_id revives logged-in.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
urlNoInitial URL to navigate to (optional)
widthNoInitial viewport width in CSS pixels. Pinned for the session's life (survives navigation) so element rects and media queries anchor to the same layout across every page of the visit.
heightNoInitial viewport height in CSS pixels.
mobileNoMobile device emulation (coarse pointer, no hover) for the initial viewport.
cookiesNoCookies to inject before navigation: `"name=value"` strings or CDP-style objects `{"name","value","domain",...}`. Lets the session start already logged-in. Round-trips with session_cookies.
storageNoWeb Storage to inject after the initial navigation lands: {"local_storage": {"k":"v"}, "session_storage": {"k":"v"}}. For login states that live in localStorage rather than the cookie jar. Round-trips with session_storage.
ttl_secsNoIdle time-to-live in seconds before the session is evicted (default: 480, clamped 60..3600). Raise it for long workflows.
keepaliveNoExempt the session from the idle reaper: it lives until session_close or server exit, so a workflow interrupted by long non-browser steps keeps its login state.
use_proxyNoRoute through proxy (default: false)
persistentNoPersist the login state (cookies + localStorage/sessionStorage + viewport + dialog policy) to the server's local store after every action. If the session idles out — or the whole server restarts — the next call with the same session_id revives it logged-in (storageState-style recovery, no re-login). Explicit session_close drops the snapshot.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changed
    • changedInput schema / properties / cookies / description
      Previous value: -"Cookies to inject before navigation ([\"name=value\", ...]). Lets the\nsession start already logged-in. Round-trips with session_cookies."New value: +"Cookies to inject before navigation: `\"name=value\"` strings or\nCDP-style objects `{\"name\",\"value\",\"domain\",...}`. Lets the session\nstart already logged-in. Round-trips with session_cookies."
    • addedInput schema / properties / height
      Added value: +{
+  "description": "Initial viewport height in CSS pixels.",
+  "format": "uint32",
+  "minimum": 0,
+  "type": [
+    "integer",
+    "null"
+  ]
+}
    • addedInput schema / properties / keepalive
      Added value: +{
+  "default": false,
+  "description": "Exempt the session from the idle reaper: it lives until\nsession_close or server exit, so a workflow interrupted by long\nnon-browser steps keeps its login state.",
+  "type": "boolean"
+}
    • addedInput schema / properties / mobile
      Added value: +{
+  "default": false,
+  "description": "Mobile device emulation (coarse pointer, no hover) for the initial\nviewport.",
+  "type": "boolean"
+}
    • addedInput schema / properties / persistent
      Added value: +{
+  "default": false,
+  "description": "Persist the login state (cookies + localStorage/sessionStorage +\nviewport + dialog policy) to the server's local store after every\naction. If the session idles out — or the whole server restarts —\nthe next call with the same session_id revives it logged-in\n(storageState-style recovery, no re-login). Explicit session_close\ndrops the snapshot.",
+  "type": "boolean"
+}
    • addedInput schema / properties / width
      Added value: +{
+  "description": "Initial viewport width in CSS pixels. Pinned for the session's life\n(survives navigation) so element rects and media queries anchor to\nthe same layout across every page of the visit.",
+  "format": "uint32",
+  "minimum": 0,
+  "type": [
+    "integer",
+    "null"
+  ]
+}
  2. Changed2 schema fields changed
    • addedInput schema / properties / storage
      Added value: +{
+  "description": "Web Storage to inject after the initial navigation lands:\n{\"local_storage\": {\"k\":\"v\"}, \"session_storage\": {\"k\":\"v\"}}. For login\nstates that live in localStorage rather than the cookie jar.\nRound-trips with session_storage."
+}
    • addedInput schema / properties / ttl_secs
      Added value: +{
+  "description": "Idle time-to-live in seconds before the session is evicted\n(default: 480, clamped 60..3600). Raise it for long workflows.",
+  "format": "uint64",
+  "minimum": 0,
+  "type": [
+    "integer",
+    "null"
+  ]
+}
  3. First observed

TDQS

A4.6/5.0
Behavior4/5

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

With no readOnly/destructive annotations, the description carries the burden of transparency. It explains the session lifecycle (idle eviction, keepalive, persistent revival) and the storage-side effects (snapshot of cookies and web storage). It doesn't explicitly warn that the session is a server resource needing cleanup, but the session_close sibling and the described lifetime make this reasonably clear.

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

Conciseness5/5

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

The description is dense but focused, with a clear main purpose sentence followed by a usage condition and parameter summaries. Minor redundancy between keepalive and persistent is acceptable given the complexity. No filler or irrelevant content is present.

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 10-parameter tool with no output schema, the description covers the operational context thoroughly: when to use it, how login state is handled, lifetime controls, persistence semantics, and recovery behavior. It even notes the return value (session_id) and round-trip relationships with sibling session_cookies/session_storage tools, making the tool's role in the broader set clear.

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

Parameters5/5

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

All 10 parameters have detailed schema descriptions that explain not only what each parameter does but why it matters (e.g., width pinned for consistent layout, persistent for storageState-style recovery). The tool description adds further context on login-state injection and round-trip storage, exceeding the baseline for high schema coverage.

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 description clearly states the tool creates a persistent interactive browser session for multi-step interaction, and explicitly contrasts it with read-once operations. It names concrete use cases (login flows, forms, pagination, click-through) and the resource produced (session_id), making the purpose unmistakable.

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 explicit guidance to use when the agent must interact with a page rather than read it once, which distinguishes it from read-only tools. It doesn't name specific alternatives like fetch or search, but the contrast is clear enough and the parameter explanations cover when to adjust TTL, keepalive, and persistence.

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

All Aginx Browser toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources