PRD Review

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

The description discloses that the tool is a write operation (each call reruns review and persists a new version), consistent with readOnlyHint=false. It adds that it is a 'small LLM call,' which gives cost context. This goes beyond the annotations, which only provide hints without detail.

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 front-loaded with the core purpose and criteria in the first sentence. It then provides behavioral details and parameter guidance. While it is dense, nearly every sentence earns its place; a slight reduction in wordiness would improve conciseness.

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 no output schema, the description adequately explains the return structure (section, severity, suggested fix, evidence quote, score 0-100) and mentions persisting as a new version (linking to list_artifact_versions). It fully covers the tool's purpose, usage, parameters, and behavior.

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%. The description adds meaning by explaining that target_id comes from specific list tools, that target_type enum corresponds to artifact kinds, and that rubric_id can be omitted to use the default. This adds value beyond the schema descriptions.

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 the tool's role as an agent-as-critic over draft artifacts (feature spec, experiment plan, page) with specific criteria (problem/hypothesis, success metric, evidence, risks, plan) and output structure (findings and score). This distinguishes it from sibling tools which do not perform reviews.

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 advises using the tool before sending a draft for sign-off and instructs the agent to resolve target_id via other tools (pm_meta, list_features, etc.). It also notes that each call persists a new version. It lacks explicit when-not-to-use or alternative tools, but the advice is clear enough.

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