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

With no annotations, the description carries the full burden and does so richly: it discloses soft-archive recoverability, the precise 409 conflict semantics with error code, open_in_sessions count and suggested_action, side effects under force (unlinks every session, notifies other sessions), and the invariant that a 2xx always means the archive happened. This is exactly the behavioral context an agent needs.

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-loads the core action and the failure/recovery flow in a logical order. Some redundancy: the force/409 behavior is restated in the closing 'no-op never wears a success status' paragraph and duplicates the force parameter's schema description, though the emphasized lines still earn most of their space.

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?

No output schema and no annotations, so the description must cover the full behavioral profile — and it does cover errors, side effects, and the force contract well. It falls short only on the uninstrumented document_id/authorization parameters and on clarifying the 'saved document' vs session-document distinction.

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?

Coverage is 50%. The description reinforces the force flow (which the schema already documents) and adds meaning to from_session via 'unlinks every session,' but says nothing about document_id or authorization, leaving two of four parameters undocumented in both schema and description.

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 precise verb+resource ('Soft-archive a saved document') and immediately distinguishes it from deletion semantics by noting the doc 'leaves the Files view but is recoverable server-side.' This differentiates it clearly from destructive siblings like delete_attachment and routes to unarchive_document conceptually.

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?

Gives strong operational guidance on the force flow — when the call fails (409), why, and how to re-call with force=true — but never names or contrasts an explicit alternative sibling (e.g., unarchive_document, close_session_document) or states when NOT to use this tool.

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