list_pages

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

No annotations provided, so the description carries the full burden. It discloses that the output is one-line descriptions and describes filtering behavior. However, it lacks details on pagination, maximum results, or any side effects, which are important for a read operation.

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 concise with a clear summary sentence followed by parameter docstrings. No wasted words, and the most important information is front-loaded.

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?

Given the tool has 3 parameters, an output schema exists (so return values need not be explained), and the description covers purpose and parameters well. It is missing potential usage limits or ordering, but these are not critical for a simple list tool. Overall adequate for its complexity.

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?

The schema has 0% coverage, meaning no parameter descriptions. The description adds significant value by explaining each parameter: page_type (with reference to list_types), tags (with reference to list_tags), and match (with examples of 'and' and 'or'). This fully compensates for the schema gap.

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 clearly states it lists pages with one-line descriptions, optionally filtered. It specifies the verb and resource, and implicitly distinguishes from siblings like search_wiki and read_page. However, it could be more explicit about the scope compared to sibling tools.

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 provides parameter explanations with references to list_types and list_tags, implying when to use those tools. However, it does not explicitly state when to use this tool over alternatives like search_wiki or find_page, leaving some ambiguity for the agent.

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