manage_session

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

Annotations only indicate readOnlyHint=false, so the description must carry behavioral context. It does: it explains that sessions belong to the server process, that close ends the browser and the session never survives, that status reads liveness first, and that contexts=2 gives independent cookie jars. These details go beyond the annotation and help the agent predict side effects.

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 long (about 8 sentences) and dense, but it is structured as a logical flow from core concept to operation list to parameter effects. It front-loads the key idea and uses consistent formatting for operation names. It is not wasteful, but the sheer length could overwhelm an agent; still, given the tool's complexity, the detail is mostly necessary.

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 17 parameters, multiple operations, and no output schema, the description is fairly complete. It covers session lifecycle, sharing, liveness checks, and some parameter semantics. It references an alternative workflow. However, it omits explanations for many parameters and the op/action distinction, leaving gaps for an agent to fully understand all use cases.

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 for all 17 parameters. It explains auth_state, contexts, device, viewport, locale, and timezone, but leaves many parameters (note, path, site, token, reason, context, session, expires_minutes, op, action) unexplained. Critically, it does not clarify whether 'op' or 'action' is the primary operation selector, which is a major ambiguity for correct invocation.

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 explicitly defines the tool as managing sessions, where one session equals one browser, and enumerates distinct operations (open, close, status, capabilities, budget, reset_budgets, handoff, export_handle, import_handle, lanes, profiles). It is specific and clearly distinguishes this tool from siblings by focusing on session lifecycle and configuration rather than page interactions.

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?

It provides context on when operations are automatic ('the first navigate of a conversation can open one for you') and explicitly references an alternative for session transfer ('see get_workflows(task='session-transfer')'). It does not, however, give explicit guidance on when NOT to use this tool in favor of other siblings, but the scope is clearly session management.

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