create_connect_session

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

Annotations already declare openWorldHint, non-idempotent, non-destructive. The description adds real context beyond them: the session is short-lived, the URL is secure and meant to be handed to the user, and the browser/OAuth steps happen outside the agent. It does not state how long the session lives or that repeat calls mint new 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?

Three sentences, front-loaded with what the tool produces, then the follow-up action, then the guardrail. No filler or repetition of schema text.

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 still tells the agent that a connection URL is the payload to relay and how to track progress afterwards — enough to call it correctly. Missing only edge-case detail such as what to do if the session expires or the user never opens the URL.

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 100%, so platform/auto_start/workspace_id/debug are already documented; baseline 3 applies. The description adds only indirect meaning ('a social account' implies platform) and never touches auto_start, workspace_id, or debug.

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 — 'Create a short-lived posterly dashboard handoff session for connecting a social account' — and the scope (per-account handoff, short-lived) separates it from siblings like connect_account and get_signup_session 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.

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

Gives an explicit follow-up workflow ('send the URL to the user, then poll list_accounts with view=connect_session to narrate progress') and a clear prohibition against asking for passwords/OAuth codes. It stops short of naming when a caller should prefer connect_account or get_signup_session instead.

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