List pending review work items in the Invariance queue, with pagination support for browsing large sets of findings or runs awaiting adjudication.
List reviews (work items requesting agent/human adjudication of a finding or run) in the queue, paginated.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No | opaque pagination token from previous response next_cursor; pass through unchanged |
Changes observed during successful MCP inspections.
v0.3.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotated readOnlyHint already signals that this is a safe read operation, so the description only needs to add contextual behavior. It adds 'in the queue' and 'paginated', but does not disclose ordering, default limit, or whether all review statuses are included. No contradiction with annotations.
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?
A single sentence that front-loads the verb and resource, defines the domain term, and states the pagination behavior. There is no filler and every clause contributes useful information.
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 simple paginated list tool with read-only annotations, the description is nearly sufficient: it names the resource, scope, and pagination, and the schema covers cursor mechanics. It does not describe the item shape or sort order, but with no output schema these are minor gaps for an agent selecting and invoking the call.
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 description adds the pagination context that connects limit and cursor, but it does not explain limit's default behavior or enumerate expected values. The cursor parameter is already well documented in the schema, so the agent can invoke the tool, though the description does not meaningfully compensate for the incomplete parameter coverage.
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 identifies a specific action ('List'), the resource ('reviews'), and the semantic scope ('work items requesting agent/human adjudication of a finding or run'), which clearly separates this from related tools like invariance_review_get or invariance_finding_list. The parenthetical definition removes ambiguity about what counts as a review.
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?
It makes the intended use clear: retrieve the queue of review work items, with pagination. It does not explicitly name exclusions or alternatives such as invariance_review_get for a single review, but the queue/list framing gives sufficient context for an agent to select it over mutation tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.