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.

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

The annotations already mark the tool as mutating, open-world, and destructive, so the bar is lower. The description adds useful behavioral context by explaining that Codex can read and edit files and run commands in the sandbox, and that long runs move to the background and return a job_id. It also discloses the return surface (final message, commands, thread_id), which goes beyond what annotations provide.

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 compact and front-loaded: it opens with the core purpose, then covers capabilities, return values, and backgrounding behavior in just a few sentences. Every clause earns its place and there is no filler or restating of the tool name.

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 complex 16-parameter tool with no output schema, the description supplies the essential missing pieces: what the agent can do, what it returns, and how continuation and backgrounding work. Sandbox modes, timeouts, and safety flags are left to the fully covered schema, which is a reasonable division. A short explicit caution about destructive potential would push this to 5, but the destructiveHint annotation already covers that.

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 the schema already documents all 16 parameters and the baseline is 3. The description adds little parameter-level meaning beyond framing the prompt as the input to the agent and mentioning the thread_id/job_id outputs. It does not need to compensate, but it also does not enrich individual parameter understanding.

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 states a specific action ('Start a new Codex agent session') against a clearly identified resource ('a prompt'), and immediately distinguishes the tool from siblings by naming its two output tokens: thread_id (for codex_resume) and job_id (for background runs). This gives an agent a clear mental model of codex_exec as the entry-point tool rather than resume, review, or apply.

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 clearly implies when to use the tool: for a brand-new session against a prompt. It also points to the follow-up tool by saying the returned thread_id can be passed to codex_resume, which helps an agent understand the workflow. It does not explicitly state when not to use it or name excluded siblings, so it falls just short of a 5.

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

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

The description usefully adds the key behavioral detail that the original session is left untouched, which is valuable and goes beyond the annotations. It does not disclose approval requirements, background execution, or the lifecycle of the new session, though the annotations already signal a non-read-only, potentially destructive operation.

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?

Two short sentences with no filler. The primary action is stated immediately, and the important safety trait 'leaving the original untouched' is front-loaded. Every word 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 complex 16-parameter mutation tool with no output schema and destructive annotations, the description is thin. It does not explain what is returned, how the forked session runs, or how the tool relates to codex_exec and codex_resume, though the rich schema and sibling list partially compensate.

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 the input schema fully documents all 16 parameters. The tool description adds no parameter-level meaning beyond what the schema already provides, so the baseline of 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 clearly states a specific action and resource: branch an existing Codex session into a new one while leaving the original untouched. This distinguishes it from related operations like resume or exec, though it never names or contrasts with any sibling tool.

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?

'Useful for trying a different approach from a shared starting point' gives a clear use case but no explicit when-to-use versus alternatives. The agent must infer that codex_fork is the right choice over codex_exec or codex_resume from context rather than being told.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, which are consistent with the description's write action. The description adds useful context beyond annotations: it explains that no API key is needed and that the return is the file path, not image bytes. It does not contradict the annotations, and it adds meaningful behavioral detail without being exhaustive.

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 concise (three sentences), front-loaded with the core action, and includes only high-value details (no API key, return path). There is no wasted wording or repetition, making it highly efficient for an agent to parse.

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 21 parameters and 2 required, the schema carries the full param documentation, so the description only needs to provide overarching context. It does that, and since there is no output schema, it correctly explains the return format. It could mention background execution or job_id behavior, but that is already in the timeout_seconds parameter description. The description is adequate given the schema richness, though a note on returning a job_id would push it higher.

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 every parameter has a documented description. The tool description does not add any parameter-specific information beyond that. Per the baseline guidance, when coverage is high, a score of 3 is appropriate. The description's mention of output_path and return path aligns with the schema but adds no new semantics.

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 states a specific action (generate an image), the mechanism (using the image_gen tool built into Codex), and the output (save to output_path). It also clarifies the return value (path, not bytes), which makes the tool's function unambiguous and distinguishes it from the non-image sibling tools like codex_exec or codex_review.

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 does not explicitly compare to siblings, but the clear purpose and the mention that no API key is needed (it runs through your Codex session) provide enough context for when to use it. There are no explicit exclusions or alternatives named, but the tool's focused role makes usage obvious, so it earns a 4 rather than a 5.

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

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

The description goes well beyond the annotations by revealing the exact kill mechanism (SIGTERM, then SIGKILL after a grace period) and the return semantics ('Reports honestly whether this call is what cancelled it'). This is valuable behavioral context that the destructiveHint annotation alone does not provide, and nothing contradicts the 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?

Two sentences convey purpose, mechanism, and outcome without waste. The core action is front-loaded, and each sentence earns its place by adding essential operational detail.

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 single-parameter destructive tool with no output schema, this description is complete: it explains what is cancelled, how (signal sequence), when the tool is appropriate, and what result to expect. An agent has enough context to call it correctly and interpret the outcome.

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 job_id parameter already has a full description including signal behavior. The tool description repeats this rather than adding new parameter-level meaning, so the baseline of 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 states an unambiguous action ('Stop a run that is still going') with a specific resource and even details the shutdown sequence (SIGTERM then SIGKILL). It clearly differentiates from siblings like codex_job_status and codex_job_logs by focusing on cancellation rather than inspection.

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 'Stop a run that is still going' conveys the primary use case: cancel an active background job. It does not explicitly name alternatives or say when not to use it, but the context is clear enough for an agent to route to this tool instead of job_status or job_logs.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=falsecars, so safety is covered. The description adds meaningful behavioral detail beyond that: it explains cursor-based pagination semantics and the incremental-read pattern ('Pass the returned next_cursor back as "since"'), which is valuable for correct use.

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?

Three short sentences, each earning its place: the first states the core purpose, the second teaches cursor resumption, and the third explains filtering. No filler or redundancy.

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 read-only paginated log tool, the description covers what the agent needs: how to page, how to continue from a cursor, and how to filter. The annotations cover safety, and the schema covers parameters. The absence of an output schema is mitigated by mentioning JSONL events and next_cursor.

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%, so the baseline is 3. The description adds value by clarifying that 'since' is a cursor returned by a previous call and that 'types' can reduce noise, going slightly beyond the schema's bare definitions.

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 states a specific action and resource: 'Page through the JSONL events of a background run.' This clearly positions the tool as an event-log reader and distinguishes it from siblings like codex_job_status and codex_job_cancel, which cover status and cancellation rather than raw event streams.

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 provides concrete usage context: paginate with next_cursor, resume with 'since' for new data, and reduce volume via 'types'. It does not explicitly name alternatives or state when not to use the tool, but the event-log framing makes its intended role clear against the sibling tools.

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

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

Annotations already establish read-only, non-destructive behavior. The description adds useful behavioral detail about what the status check returns: running state, exit code, elapsed time, and event count. It does not contradict annotations and supplements them with meaningful output expectations.

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 focused sentence that front-loads the core action and then lists the returned status details. Every clause adds useful information, with no redundant or filler text.

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 simplicity, one required parameter, and no output schema, the description adequately covers input, behavior, and return contents. It tells the agent what data the call will provide, which is sufficient for correct invocation.

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 schema covers the single parameter job_id with a clear description ('Job id returned by a tool call that went to the background'), and schema coverage is 100%. The tool description does not add additional parameter-level meaning beyond this, so the baseline score of 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 clearly states the tool's purpose: 'Report the state of a run that moved to the background' and lists the concrete details it reports (still running, exit code, elapsed time, event count). This distinguishes it from sibling tools like codex_job_logs and codex_job_cancel, which serve different purposes.

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?

It provides clear context by explaining that the tool applies to backgrounded runs rather than active or cancellable jobs. It does not explicitly name alternatives or exclusion conditions, but the domain context from the sibling tools makes the intended use reasonably clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavior beyond annotations by stating sessions are 'read straight from disk,' clarifying the source and implying no remote calls or state changes. This is useful context for an agent deciding whether invocation is safe and appropriate.

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?

Two compact sentences, with the core action and return fields front-loaded and the usage guidance in the second sentence. No filler words and no redundancy with the schema.

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 simple, read-only list tool with three optional and fully documented parametershol, the description covers what the tool returns composites and why to use it. No output schema exists, but the description names the key return fields, making the tool safely callable without needing more context.

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 the schema already documents all three parameters. The description adds little beyond the schema, except that the returned data includes fields like working directory, which maps to the cwd filter. Baseline 3 is appropriate since the schema carries the full parameter burden.

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 states a specific verb and resource: 'List recorded Codex sessions' and enumerates the returned fields (id, name, working directory, last update). It clearly differentiates itself from session-consuming tools like codex_resume and codex_fork by positioning itself as the way to discover a session_id.

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?

Provides explicit usage guidance: 'Use it to find a session_id for codex_resume or codex_fork.' This names the dependent siblings and the exact purpose, leaving no ambiguity about when to select this tool over alternatives.

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

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

The description adds meaningful behavioral context by noting the session includes 'full history' and that no re-explanation is needed, which characterizes stateful continuation beyond what annotations provide. Annotations already signal destructive and open-world behavior, so the tool's mutation risk is covered even though the description does not elaborate on side effects.

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 tight sentences with no filler. The core action and selection mechanism are front-loaded, and the alternative-tool guidance is condensed into the second sentence.

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?

Despite having 17 parameters and no output schema, the description plus the fully documented schema and annotations provide enough context for correct invocation. The main gap is that it does not describe the return/background-job behavior, but the schema and sibling tools like codex_job_status cover much of that workflow.

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 the baseline is 3 and the schema already documents all 17 parameters. The description reinforces the role of session_id and last=true, but it does not add semantic details beyond what the parameter descriptions already specify.

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 names the verb 'Continue', the resource 'previous Codex session', and the two selection modes (session_id or last=true). It also explicitly differentiates itself from codex_exec, so an agent can quickly tell when to pick this tool.

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?

It says directly to 'use this instead of codex_exec to follow up on earlier work without re-explaining the context'. This gives a concrete condition for using the tool and names the relevant alternative, leaving little to inference.

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

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

The description does not disclose important behavioral traits: a Codex review can run commands under a configurable sandbox, write to the workspace, and continue in the background after the inline timeout, but none of that appears here. The annotations do signal readOnlyHint=false and openWorldHint=true, but the description itself adds no behavioral context beyond the basic review action.

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?

Two sentences with no filler; the main purpose and default behavior are front-loaded, and optional customization comes second. This is appropriately concise given that the schema already carries the detailed parameter documentation.

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 18 parameters, no output schema, and asynchronous behavior implied by timeout_seconds and job_id, the short description is thin: it does not tell the agent what to expect back (inline result vs. job_id) or how the review interacts with sandbox and background execution. The rich parameter schema partially compensates, making this minimally viable but with clear gaps.

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 the baseline is 3 even without parameter info in the description. The description usefully summarizes the main review targets (uncommitted, base, commit) and the prompt parameter, but those map closely to the already-detailed schema fields and add grouping rather than genuinely new semantics.

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 a specific action ('Run a Codex code review') and clearly names the input scopes: uncommitted changes (default), a diff against a base branch, or a specific commit. This makes its purpose distinct from siblings like codex_exec and codex_apply even though no sibling is explicitly named.

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?

It clearly explains when to use the tool by describing the three review scopes and marking uncommitted changes as the default, so an agent knows what will happen if no target is specified. It also mentions optional custom instructions. However, it does not give explicit when-not-to-use guidance or name alternatives like codex_exec for broader tasks.

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