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

Annotations already declare readOnlyHint/idempotentHint, so the safety profile is covered; the description adds default ordering ('newest first'), pagination contract ('totalPages', 'hasMore', 'nextPage'), and default page size with max. It stops short of discussing the size/cost of walking the whole wiki unpaged, which would matter for get_full_corpus-style large traversals.

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?

Four tight sentences, front-loaded with the differentiator (tag browsing vs keyword) followed by behavior, sorting, and pagination. No filler, and each sentence covers a distinct decision an agent must make.

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 exists, yet the description still discloses the response envelope (totalPages, hasMore, nextPage) and confirms row parity with search_wiki. For a zero-required-parameter list tool with full schema coverage, nothing needed to call it correctly is missing.

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 coverage is already 100%, so the baseline is 3; the description adds value by explaining tagPath semantics (matches the branch and everything beneath it) and the title-vs-updatedAt sort intent beyond the enum labels. Defaults for page and pageSize are repeated from the schema rather than extended.

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 specific verb (browse/list) and resource (reference wiki pages), and clearly distinguishes itself from keyword search by contrasting 'browse by tag path rather than by keyword'. It also names the sibling search_wiki as the equivalent-row alternative, so an agent can separate it from get_pages, get_page, and search_wiki without reading schemas.

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 (browse a branch by tag path), a when-not-to-use alternative (keyword search via search_wiki), and an operating mode for omitting tagPath ('omit it to walk the whole wiki'). It even specifies an alternate sort choice (title for A–Z pass), covering the decision points an agent needs.

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