confluence_list_pages

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

There are no annotations, so the description carries the full burden. It does disclose pagination behavior ('Use cursor from the previous response for the next page'), which is useful. It does not disclose return shape, whether body content is included, sort/limit semantics, or error behavior, but it is enough to convey the basic read/pagination behavior.

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?

Two compact sentences, with the core listing purpose and the pagination hint front-loaded. The wording is efficient, though the parameter names are paraphrased rather than exact, which slightly reduces clarity.

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 tool with nine parameters, zero schema coverage, no annotations, and no output schema, this description is too thin. It does not clarify output format, default sort/limit behavior, body_format semantics, or relationship to the many sibling list/get tools.

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 0%, so the description must compensate for nine undocumented parameters. It maps only some of them (space→space_ids, title→title, status→status, ID→ids, body format→body_format), and not always precisely. It adds no meaning for sort, limit, max_chars, or cursor beyond the cursor usage hint.

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 states a specific verb and resource ('List Confluence pages') and mentions the main filtering dimensions. It is distinguishable from single-page getters like get_page and from search. However, it refers to 'space' and 'ID' while the schema uses 'space_ids' and 'ids', which introduces mild imprecision.

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 implies a general listing use case and gives cursor instructions, but it never explains when to choose this over get_page, search, list_children, or list_descendants. With many sibling tools, explicit routing guidance would materially help, and none is present.

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