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

Far exceeds the destructiveHint/openWorldHint annotations: it discloses the irreversible cascade (no restore through MCP), that subjects leave active lists and schedules pause, that edits and Scan starts are refused with client_archived/site_archived, the scan_running refusal, and that no Scan allowance is spent. It also gives uncertain-result retry semantics via client.archivedAt.

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 paragraph is long but dense, with the action and cascade front-loaded and every clause carrying operational weight (refusals, confirmation, retry guidance). It is on the verbose edge, but little of it is wasted for a destructive cascade tool.

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?

Although an output schema exists, the description still clarifies the return fields' meaning (alreadyArchived and archivedSites are newly archived counts, not total inventory), and covers refusals, reversibility, and failure recovery. An agent has everything needed to call and recover correctly.

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 description coverage is 0%, so the description carries the param burden. It names clientId and shows its cross-tool role (used in list_sites_and_topics(clientId)), but adds no format or identifier semantics beyond what the schema's uuid pattern already supplies. It partially compensates but not richly.

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 (Archive), resource (Client), and the cascade scope (every Site and Topic under it by clientId). This clearly distinguishes it from archive_site and archive_topic, which operate on narrower resources.

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?

It prescribes prerequisites (read get_client and inspect all pages of list_sites_and_topics) and mandates explicit user confirmation of the cascade. It also states the when-not condition (refused with scan_running while a linked Scan is in progress) and routes retries through get_client readback.

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