Create isolated browser session

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the mutating nature is clear. The description adds valuable behavior: sessions have isolated cookies/storage/pages, contextSettings are validated, geolocation is the only supported permission, and the response returns sessionId, initial pageId, and normalized effective settings. It could mention lifecycle/cleanup implications, but overall it gives meaningful transparency beyond the structured fields.

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

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

The description is dense but well-organized, with the core action and key behavior front-loaded. Every sentence adds value, particularly around isolation, permissions, and return values. It is slightly long due to the contextSettings enumeration and redundancy with the schema, but no sentence is wasted.

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

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

For a tool with nested schema, zero schema descriptions, and many siblings, this description is comprehensive. It explains the session-creation semantics, isolation requirements, permission constraints, supported settings, restoration via stateId, and the deterministic initial pageId in the response. It is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It names the contextSettings fields in prose (viewport, scale, locale, timezone, color scheme, reduced motion, user agent, geolocation) and explains stateId's restore purpose. However, it does not explain the 'name' or 'metadata' parameters, and the mapping between 'scale' and deviceScaleFactor is not explicit. Still, it covers the critical parameter semantics well.

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

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

The description states a specific verb and resource: 'Create a new isolated browser session with its own cookies, storage, pages, and optional validated contextSettings.' It clearly distinguishes the tool from siblings like browser_session_get/list/close and browser_page_create by emphasizing isolation and session creation. This is unambiguous and context-rich.

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

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

The description gives explicit when-to-use guidance: 'Create a separate session whenever a task involves a different user, account, role, authentication state, device profile, accessibility preference, permission profile, or independent parallel workflow.' It also states a clear exclusion: 'never reuse one session for identities or context settings that must remain isolated,' plus the special-case use of stateId for restoring saved state. This is strong usage direction.

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