review_history

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

With zero annotations, the description carries the full disclosure burden and meets it richly: it reveals that results contain immutable responding-model snapshots, that pagination is bounded via next_cursor, and that a session_id query returns session state (in_progress/completed/failed with timestamps) so failed or timed-out reviews are visible even without a review row. These are precisely the non-obvious behaviors an agent needs to interpret results correctly.

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?

Three sentences, front-loaded with the core purpose, then layered details about pagination and the session-state edge case. Every sentence earns its place; the only minor deduction is that the session-state clarification could arguably have been tightened, but overall it's efficient and well-ordered.

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 retrieval tool with zero required parameters and no output schema, the description is complete: it covers purpose, query modes, pagination mechanics, result composition (snapshots), and the edge case of failed reviews being visible via session state. An agent has everything needed to invoke it correctly and interpret the response.

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 100%, so the baseline is 3. The description adds marginal value by explaining what session_id returns (session state) and characterizing next_cursor as bounded, but it doesn't substantially deepen per-parameter semantics beyond the schema's own descriptions. It meets but does not exceed the baseline.

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 opens with a specific verb-resource pair ('Look up past review results') that clearly differentiates this read-only retrieval tool from its creation-oriented siblings (review_precommit, review_plan, review_code, review_status). It also names the two query dimensions (session_id, last_n), leaving no ambiguity about scope.

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 explains the two query modes and what each returns, giving the agent concrete trigger conditions. It doesn't explicitly state 'use this when you need historical results, not when creating a review', but the contrast with sibling tools that all imply creation makes the usage context clear. Lacks explicit when-not guidance, hence not a 5.

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