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

Goes well past the annotations: it explains what does NOT change (scheduled times preserved, drafts stay drafts), what happens to Pins whose slot arrives during the pause (they fail and stay failed after resume), that the schedule does not shift forward, and that other Tailwind accounts on the same Pinterest account are affected. That coverage is strong, though there's no mention of return shape (an output schema exists) or whether the pause can be scoped in duration.

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 primary intent, then consequences, then alternatives, then the account-selection rule — a sensible ordering. It is a dense block of ~8 sentences and some clauses (the 'failed Pin has lost its slot' explanation) could be trimmed, but nearly every sentence carries decision-relevant information.

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 single-parameter, destructive, idempotent account-wide toggle with an output schema, the description covers the side effects, the post-resume state, the cross-account blast radius, and the idempotency edge case. An agent has what it needs to act and to explain consequences to the user.

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% for the sole accountId parameter, so the schema carries the definition. The description still adds non-schema meaning by describing how to resolve an ambiguous accountId via list_accounts and the requirement to ask the user — a real semantic rule the schema does not express.

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 first sentence gives a specific verb and scope — 'pauses publishing for the whole account' — and explicitly frames it as an account-wide switch rather than an edit. It names sibling tools (update_post, unschedule_post, schedule_post, resume_publishing) so an agent can separate it from adjacent operations without opening any schema.

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 the triggering user intent directly ('when the user wants to stop every scheduled Pin... for a while') and contrasts it against the alternative single-Pin tools. It also resolves the disambiguation case: if accountId is unclear and list_accounts returns multiple, ask the user rather than guessing.

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