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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: 20-snapshot retention with pruning, history only accruing after staged changes are enabled, empty history being a legitimate non-error state, and a 404 for unknown or cross-help-center articles. These are exactly the traps an agent would otherwise misreport as failures.

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 purpose sentence, then short Args/Returns/Errors blocks — no filler and easy to scan. Minor redundancy in re-stating the response_format default and enum already present in the schema.

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?

With no output schema, the description supplies the return shape (versions array with id, locale, title, created_at) and the failure mode (404). Combined with the retention and history-accrual caveats, an agent has everything needed to call this and interpret an empty result 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 100%, so article_id and response_format are already fully documented, and the description's Args block largely restates them (including the enum/default). It notably omits agent_key despite that being a required credential parameter, so no added meaning here.

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+resource ('List the archived previous versions of an article') and explains the material mechanism: every publish archives the version it replaced. It also implicitly separates itself from helpcenter_list_template_versions and points at helpcenter_restore_article_version as the consumer of the result.

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?

The stated purpose ('so a past wording can be restored') plus the handoff note 'Pass a version id to helpcenter_restore_article_version' gives a clear task context and next step. It doesn't explicitly say when not to use it (e.g., use helpcenter_get_article for current content), so it falls short of full when/when-not coverage.

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