codex_review

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

No annotations are provided, so the description correctly carries the full burden of behavioral disclosure and largely succeeds: it discloses the execution timeout and its default, the uncommitted-review behavior, that an external CLI is invoked, and the return shape (output, exit code, summary). It slightly under-discloses what 'review output' actually contains and how failures surface, but the core behavior is transparent.

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 tightly organized: a one-line purpose statement, a clean Args list, and a Returns note. Every sentence carries information and there is no fluff or repetition. The format is front-loaded and scannable for an agent parsing the definition.

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 moderately complex tool (5 params, external CLI, side-effect-free review) the definition is complete: purpose, all parameters, timeout semantics, and return format are covered. The Returns section effectively substitutes for the output schema by describing the JSON string contents. Minor omissions such as error/exit-code interpretation and whether network access to Codex is required keep it from a 5.

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 0%, so the description is fully responsible for parameter documentation, and it compensates excellently. The Args block documents all five parameters with meaningful semantics: working_directory (root dir), instructions (focus areas, e.g. security, memory leaks), model (override), timeout (seconds, default 300), and uncommitted (staged and unstaged changes). Only the default=true for uncommitted is arguably non-obvious, but it is still declared.

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 opening sentence states a specific verb ('reviews'), a resource ('git repository'), and a method ('using OpenAI Codex CLI'). This clearly separates it from codex_run/antigravity_run (execution tools), and naming the backend distinguishes it from antigravity_review. However, it never mentions the antigravity_review sibling, so an agent cannot tell them apart purely from this text without inferencing.

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?

Usage context is implied rather than stated: it reviews code, so an agent will infer 'use this when a code review is wanted.' But there is no explicit when-to-use/when-not-to-use guidance or mention of alternatives like antigravity_review. The description leaves selection among review siblings to the agent's own judgment.

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