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

Annotations already declare the safe read profile, but the description goes well beyond them: it explains current_version_id semantics, the distinction between pending_version and held_version, that link_ids are only surfaced here, that legacy links survive visibility changes, and that notices must be relayed once to the user.

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 core routing information is front-loaded, but the body is long and drifts into link/notice workflows that are only tangentially about listing pages, and the trailing keyword dump adds bulk without helping invocation. A capable agent gets what it needs, but several sentences could be trimmed.

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 carries the burden of explaining return fields (title, proposal_id, version state, current_version_id, pending/held flags, notices) and does so thoroughly, so an agent knows what to expect and how to act on each field.

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 both parameters are already documented, including the three-way folder_id semantics that the description merely restates. The description adds no syntax or format detail about the query parameter beyond the schema, so baseline 3 applies.

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 opening sentence states a specific verb and resource ('List pages in the current workspace') and enumerates the returned fields, which lets an agent distinguish it from list_versions, list_folders, and list_feedback. It also preempts naming confusion by explaining that a proposal_id is not a version_id.

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 explicit when-to-use ('find existing pages rather than asking the user to copy IDs'), parameter-selection guidance for folder_id (omit / ID / null), and names alternatives with conditions — list_versions for earlier versions or rollback, preview_version/get_version for the current version.

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