Get a link to connect a social account

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

Annotations only declare readOnlyHint/openWorldHint/idempotentHint. The description adds vital behavioral context: the tool cannot complete the connection itself, requires a signed-in human to click through an OAuth popup, and warns agents not to claim the account is connected until the user confirms. This prevents a critical misuse and goes well beyond the structured annotations.

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?

The description is five sentences, each serving a distinct purpose: tool's core action, deep-link behavior, provider constraint, human-interaction caveat, and capability statement. Critical information is front-loaded and every sentence earns its place without unnecessary fluff.

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 tool's simplicity (one enum parameter, no output schema, strong annotations), the description fully covers what it does, what it returns (a link), how it must be used (relay to user), and its side-effect-free nature. It even covers the caveat about not claiming connection until user confirmation, making it complete for practical use.

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?

With schema description coverage at 0%, the description compensates by explicitly enumerating valid provider values: 'provider must be one of: instagram|twitter|tiktok|facebook|pinterest|youtube|linkedin|reddit|threads.' It also adds the semantic role 'for the chosen provider', clarifying that the provider selects which social network to connect. This is adequate for a single enum parameter.

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 opens with 'Return a link the user opens in a browser to connect a social account via OAuth', immediately stating the exact verb, resource, and mechanism. It further specifies the deep-link behavior and distinguishes it from sibling tools like build_in_public_connect_link, which serves a different connection purpose.

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 clear usage context: it must be used when a human is required to complete OAuth, and explicitly instructs agents to 'relay this link to the user and do not claim the account is connected until they confirm'. It stops short of naming alternative tools or exclusion conditions, so it lacks full 'when-not-to-use' guidance beyond the human-interaction caveat.

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