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

Annotations only say this is not read-only and not destructive; the description goes far beyond, spelling out exactly what is suspended (scheduled invites/messages held and resumed in place, inbox/acceptance checks and recurring reads skipped, end-of-day report skipped, no alerts) and what still works (Reconnect, diagnosis). It is also clear that direct requests are refused rather than queued, so the agent knows this is a reversible hold, not a deletion.

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?

Front-loaded with the action and the paused parameter, and every sentence carries distinct information (effects, exceptions, routing advice). It is a single dense paragraph of roughly 120 words, so mildly heavier than necessary but without filler.

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 covers the mutating effect, the scope of what changes, the exceptions, the alternative tool for blocked accounts, and where current state is visible. Nothing an agent needs to invoke it correctly is missing.

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%, so the baseline is 3, and the schema already explains paused and reason. The description still adds operational meaning for the paused flag beyond 'true = put on hold' by describing the resulting account behavior, which helps the agent choose the right value.

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 (pause/resume) on a specific resource (one LinkedIn account) and encodes the two modes as paused:true/false in the first clause. It is clearly distinguishable from li_pause_campaign and li_hold_sending, which operate on campaigns and sending rather than a whole account.

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 when-to-use case ('an outage already known about — e.g. the account's proxy is down') and an explicit when-NOT-to-use case ('NOT the fix for a blocked account (that needs Reconnect)'), naming the alternative. It also points at li_list_accounts as the way to read current state.

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