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

Annotations already cover the destructive/not-read-only profile, but the description adds substantial context beyond them: removal from list_sites_and_topics, pause of the scan schedule, the site_archived refusal for later edits and Scan starts, readability of saved details/reports, absence of any MCP restore path, and no scan allowance spent.

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 action, scope, and refusal condition are front-loaded in the first two clauses. Every sentence conveys a distinct operational fact (reachability, blocking error, irreversibility, idempotency, retry semantics) with no 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?

For an irreversible mutation with an output schema present, the description covers everything the agent needs: preconditions, failure modes, side effects, irreversibility, and post-failure verification via get_site(siteId).site.archivedAt. Return values are additionally noted (alreadyArchived:true) even though the output schema covers them.

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?

Only one parameter (siteId) with 0% schema coverage, and the description adds real meaning beyond the schema by specifying it must be a Site ID and that a Topic ID is rejected. It does not restate the UUID format, but the semantic constraint it adds is the more valuable part.

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?

Specific verb (archive) plus a precisely scoped resource: 'one brand Site by siteId', explicitly distinguishing it from archiving a Topic ('a Topic ID is refused'). This separates it cleanly from sibling tools archive_topic, archive_client, and archive_recommendation.

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 prerequisites ('Read get_site first', 'obtain explicit user confirmation first'), a hard blocking condition ('Refused with scan_running while a Scan is in progress; wait for it to finish'), and a recovery path after an uncertain result. The agent knows exactly when it can and cannot call this.

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