Create an account connection link

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

The description adds critical behavioral context beyond the annotations: the tool does not complete the connection itself, the link is single-use, it expires in fifteen minutes, and it requires the user to authorize on the network's own screen. This fully discloses the tool's limitations and side effects.

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, no wasted words, and each sentence earns its place: the key constraint is front-loaded, the tool's output is described, and the mandatory follow-up action is stated. This is a model of concise, structured tool documentation.

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?

Given the annotations, a fully descriptive input schema, and an existing output schema, the description contains everything an agent needs to call this tool correctly. It covers the OAuth context, link expiry, user involvement, and verification via list_accounts, leaving no critical gaps.

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%, with both parameters already well-documented (social_network travels inside the token; id_organization is optional). The main description adds no parameter-specific meaning, but the baseline of 3 applies because the schema already carries the semantic load.

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 clearly states the tool's purpose: it returns a single-use account connection link for an OAuth flow, and it explicitly distinguishes this from directly connecting the account. It also references list_accounts as the verification tool, helping an agent tell this tool apart from its siblings.

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 explicit, actionable guidance: give the link to the user, ask them to open it, and do not claim the account is connected until list_accounts confirms it. This is exactly the kind of when-to-use and how-to-use instruction that helps an agent avoid a common failure mode.

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