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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial context beyond them: the link carries no credentials, only works in a browser signed in to ShortSync, and never expires. It also discloses the post-condition (the account appears in list_platform_connections once approved) and that some platforms demand a handle/server/Page/channel first.

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 critical facts (what it returns, that the user must act, that the link is safe and non-expiring) are front-loaded in the first three sentences. The final clause about `action` and `steps` is slightly rambling but still earns its place since no output schema exists.

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 carries the return-value burden and does so: `url`, `action` (first connect vs reconnect) and `steps` (per-platform prompts) are all explained. For a read-only, two-parameter tool, an agent has everything needed to call it and to tell the user what happens next.

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 coverage is 100%, and both parameters carry their own descriptions including a full 17-value platform enum, so the schema does the heavy lifting and baseline 3 applies. The description does add value by tying the platform/workspace choice to the 'needs_reconnect' health state and by explaining the returned `action` and `steps` fields, but it gives no syntax or selection guidance for the parameters themselves.

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 and resource ('Returns a link the user opens to connect a social platform to a workspace') and scopes it to two cases: first connect and reconnect. It is clearly distinguished from the sibling list_platform_connections, which is named as the discovery/status tool rather than the action tool.

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?

Gives an explicit trigger ('connect a social platform... or reconnect one whose health is needs_reconnect in list_platform_connections') and names the sibling that surfaces that condition. It also sets the expectation that the agent cannot complete the flow alone ('Connecting always needs the user') and states the verification step afterwards.

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