scout_login

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

With no annotations, the description carries the full burden and does: it discloses that the window closes on its own, that an SSO round trip is followed rather than treated as completion, that closing the window saves nothing, that the agent must never type credentials, and that the call can return with the window still open. It also flags the desktop/display prerequisite that would otherwise cause a silent failure.

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?

Purpose and the when-to-use trigger are front-loaded, then the user-facing instruction, then the save/return semantics, then the display caveat. It is dense but nearly every sentence carries operational information; the only mild cost is length, which makes the critical 'never type credentials' and 'closing saves nothing' points harder to scan.

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?

There is no output schema, so the description must explain what the call returns, and it does ('Returns once signed in and saved, or after waitSeconds with the window still open'). Combined with the desktop caveat and the credential-handling rule, nothing an agent needs in order to call this safely is missing.

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 100%, so 3 is the baseline, but the description adds real meaning beyond the schema: role is the key scout_attach consumes, successUrl is only relevant 'when the user says how to tell', and waitSeconds governs whether the call returns with the window still open. url and browser are left to the schema, which already covers them 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 ('Open a visible browser window for the USER to sign in to the app as a role, and save that sign-in') and ties the artifact to a named consumer, scout_attach { role }. That linkage alone separates it from every other sibling in the list.

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 gives an explicit trigger ('when an attach is refused because no sign-in is saved for the role, or the saved one has expired') and an explicit fallback for the no-display case (run `scenescout login <url> --role <name>` where the window is visible). It also names the retry pattern: call again with the same role to keep waiting.

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