Preview a review (free)

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

The description discloses multiple non-obvious behaviors beyond the annotations: no model call or spend, best-effort redaction, `would_call_model` semantics, unvalidated overrides, and the conditional nature of `deadline_advisory`. It also explains that the result echoes effective model/reasoning_effort overrides unvalidated. This gives the agent a realistic expectation of what the dry run can and cannot confirm, which is especially important given the readOnlyHint annotation.

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 dense paragraph that stays on point and front-loads the core purpose. Every sentence adds unique value — purpose, cost, usage timing, caveats, output fields, and async alternative — without filler or repetition. It is appropriately sized for a tool with this complexity and does not waste tokens on restating the title or obvious schema facts.

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 the tool's complexity and the presence of an output schema, the description still covers the critical behavioral nuances: output fields that matter (`coverage`, `deadline_advisory`), redaction limitations, and the distinction between this dry-run tool and its async counterpart. It addresses both positives and negatives (what the tool does and what it does not do), making it complete enough for an agent to invoke it correctly without ambiguity.

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 input schema already provides 100% parameter coverage with detailed descriptions for each field, so the schema carries most of the parameter-semantics burden. The description adds marginal value by advising the agent to pass the same `extra_context` and `untracked` policy as the paid review, and by noting that model/reasoning_effort are unvalidated. However, this is mostly reinforcement of existing schema information rather than new parameter-level meaning, so a baseline 3 is appropriate.

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 'Preview what a codex_review_changes call would send — scope, diff size, redactions, truncation,' which states a specific verb, resource, and output scope. It explicitly distinguishes itself from the paid review tool by adding 'Free — no model call, no spend,' and it references tool-specific output fields like `would_call_model` and `deadline_advisory`. This clearly differentiates it from siblings like `codex_review_changes` and the async variants.

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 explicit when-to-use guidance: 'Use it before a review to inspect the scope and the reported redactions.' It instructs the agent to pass matching parameters ('Pass the same extra_context and untracked policy') and explicitly names the async sibling (`codex_review_changes_async`) as the counterpart when `deadline_advisory` is non-null. The redaction best-effort caveat also tells the agent not to treat the preview as a security guarantee, which is a non-obvious usage constraint.

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