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

Annotations already declare openWorldHint=true, destructiveHint=false, and readOnlyHint=false; the description adds meaningful context beyond them — the link is bound to the signed-in Soclo account, the mailbox attaches only to that account, and no password or token ever reaches the assistant. What it omits is link lifetime/expiry and whether repeated calls mint new links (relevant given idempotentHint=false).

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 short sentences with no filler, and the security assurance is placed last as a reassurance rather than buried. The opening phrase 'A link the owner opens…' describes the artifact instead of leading with the action the tool takes, which slightly delays the point.

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?

For a one-parameter tool with annotations covering the safety profile, the description conveys the whole flow: mint a link, the owner opens it signed in, the mailbox binds to that account, no credentials touch the assistant. Only edge behaviors — link expiry and re-invocation semantics — are left unspecified.

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 carries the burden for the single `provider` parameter, and it does: it states the choice is between Gmail and Outlook, matching the enum. It adds no further semantics such as defaults or whether an existing connection changes provider, but the core meaning is covered.

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 artifact (a connect link) and the resource (the owner's own Gmail or Outlook mailbox), so an agent can tell this produces a URL rather than performing the connection itself. It does not explicitly contrast with siblings such as soclo_accounts_connect or soclo_leads_mailbox_status, so the differentiation is inferred rather than stated.

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 usage context is implied rather than spelled out: the owner must open the link in a browser while signed in to Soclo. There is no explicit 'use this when…' or 'do not use this instead of accounts_connect…' guidance, and no statement of what the agent should do with the returned link (hand it to the owner, do not attempt to fetch it).

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