session_dialog

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

No annotations exist, so the description carries the full burden, and it does most of the work: it discloses that dialogs are left open and block the page, that sibling tools return 409 with a specific message shape, that beforeunload from your own navigation is auto-accepted, and what failure codes mean (409 no dialog open, 409 session not open → call profile_start, 404 unknown identity). The only gap is it doesn't say whether the answered state is persisted or what happens on concurrent sessions.

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?

Front-loads the core action in the first sentence, follows with the blocking context that justifies its existence, then structured Args / Returns / Fails blocks. Every sentence adds distinct operational information — none is filler.

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?

With no output schema, the description supplies the return shape ({ok, action, type, message}); with no annotations, it supplies blocking semantics and error behavior; with no schema descriptions, it defines all three parameters. Prerequisites (profile_start) and failure codes are covered, so an agent has everything needed to call it 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 fully, and it does: 'name' is defined as the identity name exactly as profiles_list reports it; 'action' is constrained to 'accept' (OK/Leave) or 'dismiss' (Cancel/Stay); 'prompt_text' is scoped to prompt() dialogs and its default behavior (accept default value when omitted) is spelled out.

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?

States a specific verb and resource ('Answer the JavaScript dialog ... open on the session's page') and enumerates the dialog types it handles (alert, confirm, prompt, beforeunload). It also distinguishes itself from the other session_* tools by explaining that they fail while a dialog is open, making selection unambiguous.

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?

Explicitly says when to call it ('while one is open the page is blocked and the other session_* tools fail with 409 ... Call this to answer it, then retry'). It also names the exception — beforeunload triggered by your own session_goto or click is auto-accepted and never appears here — which prevents a whole class of wrong calls.

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