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

No annotations are provided, so the description carries the full burden. It transparently discloses that it walks all pages server-side (so the caller never handles offsets), that it caps at 20 pages (5000 cases) and exposes capReached, and that the default compact form is used to avoid output limit issues. This goes beyond simple read/write safety and gives critical operational details.

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 dense but well-structured: it front-loads the core scope and pagination behavior, then addresses output format and limitations, and ends with a clear routing to an alternative. Every sentence adds information, and the length is justified given the operational complexity.

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's complexity (pagination, output limits, return format) and the lack of an output schema, the description covers all essential aspects: the default compact output, the cap, the capReached flag. It also provides usage context via the sibling alternative. Nothing critical is missing for an agent to call this correctly.

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 100%, so the schema already documents each parameter. The description adds value by explaining the purpose of the compact parameter (default true, set false only for narrow sections) and explicitly mentions capReached as an output signal, which ties to the page cap. It doesn't add much for suiteId/sectionId beyond scoping, but the compact guidance is useful.

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 ('List EVERY case') and resource ('TestRail project/suite/section'), and clearly distinguishes it from the sibling testrail_find_cases by noting the difference in scope (all cases vs. checking existence of one). The emphasis on server-side pagination and the default compact format further clarify its purpose relative to other case-listing 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 explicitly says when to use this tool (when you need to list all cases) and when not to (if you only need to know whether one specific case exists, use testrail_find_cases instead, calling it 'far cheaper'). It also provides guidance on the compact parameter, advising to avoid full form unless the section is narrow.

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