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 already carry readOnlyHint=false and destructiveHint=true, so the write/destructive profile is covered. The description adds genuine value beyond annotations by disclosing the return format (path, not image bytes) and the no-API-key requirement. No contradiction with annotations — the file-writing behavior aligns with the non-read-only hint.

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 sentences with zero waste. The core action and output path are front-loaded, followed by the auth note and return-format clarification. 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 complex 22-parameter tool with no output schema, the description clarifies the return value and the execution mechanism, which is essential. The rich per-parameter schema descriptions cover the remaining configuration surface. Slightly more safety/limitation context would help given the destructive annotation, but the description is largely adequate.

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 all 22 parameters are documented in the input schema, setting the baseline at 3. The description adds marginal semantic value by tying output_path to the save behavior and clarifying the return, but it does not elaborate on individual parameters beyond what the schema already provides.

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?

States a specific verb ('Generate an image'), a concrete resource, and the output behavior (saves to output_path). It also clarifies the mechanism (Codex's built-in image_gen) and the return type (path, not bytes), making it clearly distinct from siblings like codex_exec, codex_apply, and the job/session tools.

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 useful context about how the tool runs (through the Codex session, no API key needed), but offers no explicit when-to-use vs. alternatives guidance and no exclusions. The purpose is self-evident relative to siblings, but the description relies on inference rather than stating usage boundaries.

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 signal read-only/non-destructive behavior; the description adds non-blocking/cost characteristics, cursor-based incremental reads, and the meaning of awaiting_answer. It could go slightly deeper on message retention or consumption behavior, but the key traits are disclosed.

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 tight sentences lead with purpose and examples, then move to usage and behavioral guidance. There is no repetition of schema/annotations and no filler.

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 tool with one optional parameter, it covers purpose, cost, non-blocking behavior, pagination, and a key return field. It does not fully describe the message envelope shape or when to use codex_job_logs instead, but the overall guidance 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 already documents job_id with 100% coverage, so the description does not need to compensate. It adds no parameter-level detail, and the baseline of 3 applies because the schema carries the semantic load.

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 concrete verbs ('Collect'/'Read') and a specific resource ('messages from Codex'), with examples of content types (questions, findings, warnings). This clearly distinguishes it from log/status/reply sibling tools.

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 gives clear context: the tool is cheap, non-blocking, and worth calling between other tools while a run is in flight. It also provides pagination guidance via next_cursor, though it does not explicitly contrast with siblings or state when not to use it.

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?

Annotations already indicate destructiveHint=true, but the description adds significant behavior beyond that: the preset is removed from a persistent file, and the operation fails rather than falsely succeeding if the name does not exist. This failure mode is critical for an agent to predict outcomes correctly.

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, front-loaded with the action, and contains no filler. The first sentence states scope and persistence; the second clarifies the error behavior, which earns its place by preventing a common false-success expectation.

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 delete tool, the description covers the essential context: what is deleted, the persistence effect, and failure behavior. Annotations already convey destructive intent, so an agent has everything it needs to invoke the tool correctly.

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 fully documents the single 'name' parameter. The description repeats the failure condition but does not add any new parameter-level meaning, matching the baseline of 3.

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 the specific verb 'Remove' and identifies the resource ('a preset') and the scope ('from this instance and from its presets file'). This distinguishes it from sibling tools like codex_preset_set, codex_preset_update, and codex_preset_list without needing to open them.

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 makes clear that the tool is for deleting a preset and that the preset must already exist, which is a clear context for use. It does not explicitly name siblings or say when not to use it, but no exclusions are needed for a straightforward delete operation.

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, so the safety profile is covered. The description adds that it shows full details and the file source, which is useful output context. No contradictions 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 two sentences, front-loaded with the core function ('Show the image presets'), and every phrase adds value. It is concise and well-structured.

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 zero-parameter, read-only list tool, the description fully covers what it returns (subject, style, constraints, reference art, file) and when to use it. No output schema exists, but the description provides sufficient 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?

The tool has zero parameters, so schema coverage is trivially 100%. With no parameters to document, the description doesn't need to add parameter semantics, and the baseline of 4 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 'Show the image presets this instance is configured with', listing specific fields (subject, style, constraints, reference art) and the source file. It explicitly distinguishes from codex_generate_image, which only names presets, making the purpose unambiguous and differentiating it from siblings.

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 usage guidance: 'use this to see what a preset actually contains before using or changing it'. It also contrasts with codex_generate_image, telling the agent when to use this tool instead. This is clear and actionable.

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 behavior beyond the annotations: it discloses that a bad file will cause the call to fail and that currently loaded presets are preserved. This gives the agent important safety information about failure modes, though it doesn't describe the success return value or side effects in detail.

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 sentences with no filler. The primary action is front-loaded, and the failure-safety behavior is added in a compact second sentence. Every word contributes value.

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 zero-parameter, no-output-schema tool, the description covers the essential context: what the tool does, when it is useful, and what happens on failure. It is complete enough for an agent to invoke it correctly, even if it omits a precise success response description.

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 tool has zero parameters, so there are no parameter semantics to document. The baseline of 4 applies because no parameter explanation is needed and the description focuses on the operation itself rather than inventing unnecessary parameter details.

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 ('re-read') and resource ('presets file from disk'), making the action immediately clear. It also distinguishes itself from sibling tools like codex_preset_set, codex_preset_update, and codex_preset_list by focusing on reloading from disk rather than mutating or listing presets.

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: after presets were edited outside the server, to apply changes without a restart. It does not explicitly name alternatives or exclusions, but the context is strong enough that an agent would not confuse it with the sibling preset 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?

The description adds material behavioral detail beyond the annotations: it persists to the presets file, survives restart, is usable immediately, and replaces same-name presets outright so fields can be removed. This replacement/removal behavior is exactly the kind of side effect an agent needs to know.

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 sentences with no filler: purpose first, then persistence and overwrite semantics. It does not repeat schema details and every sentence contributes critical selection or invocation information.

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 an 8-parameter tool with complete schema coverage and no output schema, the description covers purpose, file persistence, immediate usability, and replace-not-merge behavior. An agent has enough information to decide whether to call it and what to expect when it does.

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?

All eight parameters already have schema descriptions, so the baseline is 3. The description adds value by tying the two central parameters together—'name' is the handle used in later calls, and the 'subject' is the recurring content being preset—clarifying their relationship beyond the individual schema entries.

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—'Define a named preset for a subject drawn repeatedly'—and names the resource and purpose: to let later calls use the preset name instead of restating the subject. It also distinguishes this from update-style siblings by stating it 'Replaces a preset of the same name outright rather than merging.'

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 a clear use context: use this when a subject is drawn repeatedly and you want a reusable named preset. It also conveys when not to rely on it, since replacement is outright rather than a merge, implying partial updates are not performed here.

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=false, destructiveHint=false, so the mutation nature is known. The description adds crucial behavioral context beyond annotations: the null-to-clear semantics and the failure condition when the preset is missing. It does not contradict annotations. While it doesn't mention permissions or side effects, given the annotations, this is a solid disclosure.

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 core purpose and differentiation are front-loaded in the first sentence, followed by the null-clearing and failure notes in the second. Every word earns its place, and the structure is scannable for an agent.

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 8 parameters, all documented in the schema, the description covers the essential decision-making: when to use, null behavior, and failure mode. It doesn't mention the return value, but since there is no output schema, that might be expected. Still, the description is complete enough for correct invocation; a slightly richer mention of what happens after success (e.g., in-memory or persisted) would push it to 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 100%, so each parameter is documented in the schema. The description adds a global semantic: 'Pass null for a field to clear it' and 'leave the rest alone', which clarifies the behavior of omitted and null fields—valuable beyond what the schema individually states. This elevates it above the baseline for high-coverage schemas.

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 verb ('Change'), the resource ('existing preset'), and the scoping ('some fields... leave the rest alone'). It explicitly differentiates from the sibling codex_preset_set by naming it and describing the exact condition for choosing this tool over it. No ambiguity remains about what this tool does.

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 gives explicit when-to-use guidance: 'Use this rather than codex_preset_set when adjusting one thing', and explains the rationale ('restating a long subject just to tweak a style is how a subject drifts'). It also warns about a failure condition ('Fails if the preset does not exist') and clarifies that omitted fields remain unchanged. This fully directs an agent on when to invoke this tool vs 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 discloses useful timing semantics: answering promptly unblocks the run, late answers are still delivered at the next turn, and the call fails rather than posting orphaned answers. This goes beyond the annotations by explaining failure modes and delivery behavior.

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 focused sentences, with the core purpose first and each sentence adding necessary runtime context. No repetition of schema details or filler.

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 two-parameter tool with full schema coverage and annotations declaring side effects, the description covers invocation, timing, and failure behavior completely. No additional return-format details are necessary for correct use.

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%, and both required parameters already have clear descriptions in the schema. The description reinforces that message_id comes from codex_inbox and that text should be direct, but adds little parameter-level meaning beyond the schema.

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?

States the action and target clearly: 'Answer a question codex_inbox reported.' This is distinct from sibling tools by describing a blocking inbox exchange, not a general codex instruction.

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?

Clearly explains when to use it: a Codex run is blocked waiting for this answer, and it fails if no such question exists, which serves as a when-not. It does not explicitly name an alternative sibling for non-reply communication.

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.

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

Annotations already carry destructive and non-read-only hints. The description adds useful behavioral detail: delivery happens at next tool turn (non-interrupting) and omitting job_id broadcasts to all runs. This exceeds annotation baseline.

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, front-loaded with purpose, no filler. Every phrase contributes useful information.

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 two-parameter tool with no output schema, the description covers the message content, targeting, and delivery timing. It is complete enough for correct invocation, though it does not address edge cases like missing runs.

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 covers 100% of parameters. The description adds semantic nuance by explaining that omitting job_id reaches all runs and is intended for stop, which goes beyond the schema's phrasing.

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?

States a specific action (send a message to a running Codex agent) and enumerates use cases (correction, direction change, stop). It distinguishes itself from siblings by emphasizing unsolicited messages and delivery timing, so an agent can separate it from codex_reply or codex_job_cancel.

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?

Gives concrete scenarios (correction, direction change, stop) and parameter guidance (omit job_id to reach every run, especially for stop). It does not explicitly name alternative tools, but the context is clear enough for selection.

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