sign_in

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

Discloses behavior the annotations cannot: a separate Chrome window opens and auto-closes, only one sign-in exists at a time, a new sign-in replaces the previous one, the session is harness-scoped and auto-renewed for up to 14 days, and pending calls do not open a second window. The readOnlyHint/idempotentHint annotations are consistent with the described in-place, repeatable flow — the tool orchestrates a browser sign-in rather than mutating MCP-managed data.

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-loaded with purpose and trigger, then mechanics, then the retry protocol — a sensible order with no filler. It is fairly dense in a single block and could be broken up, but essentially every sentence supplies a fact the agent needs to call it correctly.

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 3-parameter, no-output-schema tool this covers the full lifecycle: trigger, what the user sees, session lifetime, timeout behavior, and the exact follow-up when sign_in_pending comes back. An agent can execute the whole flow from the description alone.

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 coverage is already 100%, so the schema carries the parameter definitions. The description still adds meaning by connecting wait_seconds to the pending/retry cycle and by summarizing the url default (sign in where the MCP already works) in narrative form that reinforces the schema wording.

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 ("Signs the user in to their Constructor") plus the default target URL and the override condition. Nothing in the sibling list of file/app/deploy tools overlaps with this auth flow, and the description makes that uniqueness explicit.

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 two explicit triggering conditions: "Call it when the user asks to sign in, or when a tool returns needs_auth" and adds a ordering prerequisite ("after telling the user a sign-in window is about to open"). It also documents the retry loop when sign_in_pending is returned, so the agent knows exactly what to do after the call, not just when to make it.

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