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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds real value beyond that: the cascade behavior (widgets fall back to their next account, or show no posts if none exists) and the conditional confirm gate based on 7-day view activity. It stops short of stating whether removal is reversible or how to recover from it, which keeps it off a 5.

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?

Four short sentences, front-loaded with the core action and effect, then the safety workflow. Dense but every clause carries operational meaning; only minor tightening (e.g. the trailing 'ask the user first') could be merged with the prior sentence.

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 two-parameter destructive mutation with no output schema, the description covers the action, cascade consequences, the safety precondition, and the required pre-call lookup. 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 both parameters are already documented. The description nonetheless adds conditional meaning to confirm by tying it to the 'views in the last 7 days' condition, which is richer than the schema's own phrasing and directly shapes correct invocation.

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 ('Removes a social account') and immediately scopes it to SnapWidget accounts, distinguishing it from siblings like remove_review_source, delete_widget, and reconnect_account. It also describes the downstream effect on widgets, so the agent knows exactly what domain object is being acted on.

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?

Explicitly routes the agent to list_accounts to see affected widgets, instructs it to tell the user before removal, and gives a concrete precondition: confirm: true is required when widgets had views in the last 7 days, and the agent should ask the user first. This is rare, actionable when/when-not guidance.

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