Integrations: oauth connect

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false), so the lower bar applies. The description usefully adds that the flow is browser-based and starts a local listener — behavior not derivable from the annotations — but omits that the call blocks until the callback or timeout, that the user must complete the login in the browser, and that it persists a new connection. Note that the browser-based external flow sits uneasily with openWorldHint=false, though the description is the accurate party here.

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?

A single front-loaded sentence with the parenthetical carrying the one non-obvious mechanic; nothing is repeated from the title or annotations. It is arguably too thin for a 6-parameter interactive tool, but nothing in it is wasted.

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 is the only place to explain the interactive, blocking nature of the call and its prerequisites, and it doesn't. Annotations cover safety, and the schema covers parameters, so an agent can call it, but it cannot predict that the call waits for user interaction or what state change results.

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% and every parameter (port, no_open, timeout, provider, user_connection, name) is documented in the schema itself. The description adds no parameter-level detail beyond implicitly motivating port (local listener) and no_open (browser opening), so the baseline 3 applies.

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 (Connect) plus the mechanism and scope (browser OAuth flow, local listener), so the agent knows this initiates an OAuth handshake rather than configuring or checking one. It does not differentiate from close siblings such as integrations_connect or integrations_oauth_configure, which likely connect by other means or set up credentials.

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?

No when-to-use guidance: nothing says when to prefer this over integrations_connect, integrations_oauth_configure, or integrations_oauth_callback_url, and no prerequisites are stated (e.g. that the OAuth app must be configured first). The only usage hint is implicit in the parameter documentation of the schema, not the description.

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