jev_review

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

Annotations already declare readOnlyHint=true, so the non-mutating nature is captured externally. The description adds value by noting the advisory nature and that tests/host review are still required, which tells the agent the output is not authoritative. It does not describe any additional side effects, output format, or behavior around optional parameters like auto_accept, but there is 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?

The description is a single, tight sentence with two clauses: the core action and the critical advisory limitation. Every word earns its place, and the most important distinction ('Advisory') is front-loaded. There is no filler, repetition, or redundant schema echo.

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?

With 6 parameters, no output schema, and several similarly named sibling tools, the description is too thin. It does not explain what the review returns, how to interpret the advisory result, how auto_accept or review_at affect behavior, or when this tool is preferable to jev_evaluate or jev_verify. The core purpose is clear, but an agent would struggle to invoke it correctly in nuanced contexts.

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 50%, with descriptions only for diff, tests, and request. The tool description adds no parameter-level meaning whatsoever, leaving model, review_at, and auto_accept completely unexplained in both the schema and description. Since the description must compensate for this gap and does not, it falls below 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 uses a specific verb and resource: 'Assess a proposed diff.' The word 'Advisory' further clarifies that this is a review/opinion tool, which helps distinguish it from stricter verification tools like jev_verify or jev_gate. However, it does not explicitly name or contrast any sibling tool, so it stops short of full differentiation.

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 phrase 'Advisory; actual tests and host review remain required' provides useful context that this tool should not be treated as a final authority or a substitute for verification. It implies when not to rely on it, but it does not explicitly state when to use it versus alternatives like jev_verify or jev_gate, nor does it name sibling tools.

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