Apply a Codex diff

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

Annotations already carry destructiveHint=true and readOnlyHint=false, so the description's 'Modifies files on disk' mostly echoes structured metadata. It does add useful operational context ('as a git apply' and 'local working tree'), but it does not disclose possible failure modes like apply conflicts, dirty working trees, or whether changes are staged.

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 two short sentences with no filler. The core action and target are front-loaded, and the side-effect note is kept to one clause. 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 mutating tool with no output schema, the description gives the core operation but is thin on surrounding context. It does not mention what happens after apply, how failures or timeouts are surfaced, whether a missing diff is an error, or how an agent should verify the result. Structured fields cover parameters and safety, but an agent still lacks enough operational context to call this confidently.

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 all parameters (cwd, task_id, timeout_seconds) are already documented in the input schema. The description does not add extra meaning beyond 'latest diff' aligning with task_id, so it stays at the baseline rather than adding new parameter-level insight.

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 names a specific action ('Apply'), a specific resource ('the latest diff produced by a Codex task'), and a specific target ('the local working tree... as a git apply'). It clearly distinguishes this from sibling tools like codex_exec or codex_review by focusing on applying an existing diff rather than creating or reviewing one.

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 context by indicating this applies a task's latest diff to the local tree, but it never explicitly says when to use this tool versus alternatives. With siblings like codex_exec, codex_resume, and codex_review available, an agent gets no direct guidance on sequencing, such as 'use after codex_exec' or 'consider codex_review before applying.'

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