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

No annotations are provided, so the description carries the full behavioral burden. It discloses: returns summaries only (not images), defaults to pending status, is owner-scoped to your account, and that it flags changes against an approved baseline. This is reasonable behavioral clarity for a read/list operation, though it doesn't mention ordering, pagination, or maximum result count.

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, all dense with useful information: purpose, image-vs-summary distinction, default behavior, scoping. No wasted words. The parenthetical in the schema for replay_id is also well-structured. Slightly more than minimal but every sentence earns its place.

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 read-only list tool with full schema coverage, no output schema, and no required params, this description is adequate. It covers default behavior, scoping, image handling, and owner scope. Given the fairly simple contract (list candidates, filter by status/replay), the description provides enough context for correct invocation without needing to explain return values beyond what's implied.

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 schema already documents both parameters well. The description adds value by explaining the default ('pending') that matches the status enum default, and gives rich context for replay_id ('narrow to candidates from one specific replay run only... so you never touch pending candidates from other runs'). Baseline 3 is appropriate since schema covers the fields and description adds some supplementary context.

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 what the tool does: 'List AI Visual Review candidates' with specific context about flow-replay steps where pixel-diff flagged a change. It explicitly distinguishes from get_visual_review (returns summaries with image URLs/refs only, not the images themselves), and from resolve_visual_review (which is a sibling that handles resolution). This is a specific verb+resource+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 gives clear context for when to use this tool — it's the listing entry point for visual review candidates, defaulting to pending. Key guidance: use get_visual_review for actual images, and the replay_id parameter has explicit usage guidance ('Use this when you were asked to review a particular replay'). No explicit exclusions for alternatives like resolve_visual_review, but the distinction from get_visual_review is well made.

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