memory_archive

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

With no annotations, the description carries the full burden and does well: it discloses reversibility, that originals/IDs/provenance remain in canonical storage, that archive/restore are dry-run by default, and that apply is gated on a preview revision, digest and a reason. It omits permissions/auth requirements, rate limits, and what restore actually changes.

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?

Five sentences, no filler, and the primary capabilities are front-loaded ahead of the apply prerequisites and exclusions. It is dense but every sentence earns its place; the packing of many clauses per sentence mildly hurts scanability.

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 12-parameter, five-action tool with no annotations and no output schema, the description covers the lifecycle model, defaults, apply gating, and scope exclusions adequately. What remains thin is the return shape for list/candidates and pagination behavior, which some agents will need to infer.

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 the schema already documents all 12 parameters including defaults and enums; baseline is 3. The description largely restates those defaults (inspect, dry-run true) rather than adding new syntax or semantics, though the apply-gating sentence usefully ties expectedRevision/expectedDigest/reason together. It does not add meaning beyond the structured fields for most parameters.

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 description names five specific verbs (inspect, list, candidates, archive, restore) over a specific resource (reversible archive state and retention/TTL candidates) scoped to an exact project. It also states what the tool is not — it 'does not enable automatic retention or perform forget' — which cleanly separates it from memory_governance_delete and memory_graph_purge. An agent can place it without opening the 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?

It gives explicit routing between its own actions: default action is inspect, archive/restore default to dry-run, apply requires preview revision, digest and a reason, and candidate listing is read-only and requires individual review. It carries a clear exclusion (no automatic retention, no forget). It does not name sibling alternatives by name, so it stops short of the top band.

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