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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds meaningful behavioral context beyond that: archived items are 'soft-deleted' and restorable, and it names the specific restore operations for nodes, fields, views, and records. This gives the agent useful recovery-oriented context without contradicting the annotations.

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 description is front-loaded with the core purpose and remains focused, with the second paragraph adding restore semantics and scoping rules. It is slightly dense and the phrase 'node_create's counterpart nodes_create_change_request restore op' is a bit awkward, but every sentence contributes useful information. There is little wasted wording.

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?

The rich input schema covers parameter meanings, including baseId requirements, pagination, and targetSpaceId usage, so the description does not need to repeat all of that. Combined with the description's explanation of soft-deletion, restore paths, and scope behavior, an agent has enough context to call this tool correctly. There is no output schema, but the description's core 'list items' promise is sufficient for this kind of read-only listing tool.

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 the baseline is 3. The description does add a small amount of semantic value by explaining that nodes and bases are space-wide while fields, views, and records need a baseId, but this mostly overlaps with the schema's own parameter descriptions. It does not substantially clarify limit, cursor, playbook, or targetSpaceId beyond what the schema already says.

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 opens with a specific verb and resource: 'List archived (soft-deleted) items — the Trash view'. It clearly distinguishes this from ordinary listing tools by emphasizing soft-deletion and recoverability, and the scope enum clarifies exactly what kinds of items are covered.

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 description gives clear context for when this tool applies: showing trash/archived content that can be restored. It also provides concrete scoping rules—'fields, views and records scopes need a baseId; nodes and bases are space-wide'—which helps an agent decide which parameters to supply. It does not explicitly name an alternative list tool to use instead, so it stops short of a 5.

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