auth_oauth_login

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

With no annotations, the description carries the full behavioral burden. It discloses that a window opens, the user signs in, the redirect is intercepted, the code is exchanged, and the token is stored and auto-refreshed. It doesn't mention failure modes or interaction with existing profiles, but the main side effects are clear.

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?

Two dense sentences with no filler. The main action and prerequisite are front-loaded, and the flow details are compactly listed. Every clause adds relevant behavioral or setup information.

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?

The core OAuth flow is well explained, but there are gaps: no parameter-level guidance for `headed`/`timeout_s`, no comparison with sibling auth tools, and no description of the return value or success/error behavior. It is adequate for a simple call but not fully complete for an agent.

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. It explains the meaning of `name` (the profile) but gives no guidance on `headed` or `timeout_s` beyond the indirect mention of an 'opened window'. The two boolean/integer parameters remain effectively undocumented.

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 names the specific verb ('Run'), the resource ('OAuth authorization-code + PKCE flow for profile `name`'), and the protocol variant. This clearly separates it from sibling tools like auth_browser_login, which handles browser-based rather than OAuth flow.

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?

The description gives a clear prerequisite (configure oauth with grant_type, authorize_url, token_url, client_id, redirect_uri) and implies this is the OAuth path. However, it never explicitly says when to choose this over sibling auth tools or when not to use it.

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