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

Annotations only flag destructiveHint/idempotentHint without saying what is at stake; the description fills that in with consequences: the connection is kept, nothing new can be scheduled, and posts due during the pause fail per-account with the reason surfaced in get_post. It also discloses that disconnect would delete Shager's keys (and on some networks cancel access) and that only the owner can reconnect — rich context beyond the annotations, and consistent with destructiveHint=true.

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 state semantics, then preconditions, then the exclusion. Three dense sentences with no filler, though the disconnect rationale is slightly verbose for information that mostly serves to say 'do not do this.'

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?

No output schema exists, and the description compensates by explaining what happens to in-flight scheduling and where failure reasons appear. Preconditions, side effects, and the agent/human boundary are all covered; only the sourcing of channel_id is left implicit.

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 only 33% (only workspace_id is documented), so the description carries more burden than usual. It meaningfully expands the status enum by explaining what PAUSED and ACTIVE actually do, but it never says where channel_id comes from (presumably list_channels) and uses 'account' throughout while the field is named channel_id, leaving a small mapping gap.

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?

Names a specific verb (pause/resume) and resource (account), and disambiguates from the adjacent operations an agent might confuse it with: reconnecting (create_connect_link), retrying (retry_failed_accounts), and disconnecting (which is explicitly out of scope). An agent can tell exactly which state transition this tool performs.

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?

States when to use each status value, the preconditions for resuming (working connection, plan allowance), and an explicit exclusion: disconnecting is not offered to agents and must be done by the human on the Accounts page. It also routes to create_connect_link for the NEEDS_RECONNECT case rather than leaving the agent to guess.

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