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

Annotations only declare readOnlyHint=false and openWorldHint=true; the description goes far beyond them, disclosing data egress ("Everything passed in prompt, context and target_files is sent to OpenAI"), cost (spends the user's own Codex usage), the read-only default sandbox, the server-level sandbox ceiling that can refuse a call, and the read-only-context limitation. It also prescribes user-facing behavior (tell the user when you delegate). No contradiction 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?

Purpose and routing are front-loaded, then cost/privacy, then sandbox, which is the right order. It is a single very dense block with minor redundancy (the prompt/context/target_files data-egress point and the "Codex cannot see this conversation" point are made twice in different framings).

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 18-parameter, open-world, mutating delegation tool with no output schema, the description covers the gaps the schema cannot: cost, data egress, permission ceiling, defaults, and user communication. It never explains how to collect results from a background run (codex_job_status/codex_job_result), but the mode parameter's schema text covers the job_id return.

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 meaning on top by explaining that everything in prompt, context and target_files leaves the machine, and that sandbox escalation to workspace-write depends on a server ceiling that must be stated in the server's instructions. It does not touch mode/background vs blocking behavior or how jobs are retrieved, leaving the rest to 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 a specific verb and resource ("Delegate a task to the local Codex CLI (OpenAI's coding agent)") plus the two knobs it exposes, model and reasoning effort. It is clearly distinguishable from siblings like codex_recommend (advice only) and codex_follow_up (continuation), which are named with different roles.

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?

Explicitly says when to use it (user asks for Codex, second opinion from a different model family, investigation that would flood the conversation) and when not to ("do not delegate what you can answer directly"). It also gives an ordered prerequisite: if no model was named, call codex_recommend first and present the suggestion in the same message.

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 openWorldHint=true, and the description adds useful context beyond them: it explicitly guarantees that this tool never installs or repairs anything, warns that extended triggers a slow networked config.load report, and notes caching behavior through refresh in the schema. This is exactly the kind of extra behavioral detail that annotations alone cannot convey.

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, front-loaded with the purpose, then the usage triggers, then the behavioral constraint and the opt-in cost. No sentence is wasted.

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 diagnostic tool with no output schema, the definition covers what is checked, when to run it, and the safety stance. The return format is only loosely described (exact fix steps, codex doctor --json report), which is a minor gap but not enough to block 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?

Schema coverage is 100%, so all three parameters are documented in the schema. The description only implicitly explains the effect of extended (slow networked config.load report); refresh and working_dir add nothing beyond the schema, so the baseline of 3 applies.

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 and resource: checks whether the local Codex CLI is installed, recent enough, signed in, and able to load configuration. It also covers the failure path (report fix steps), and it is clearly distinguishable from siblings such as codex_delegate, which actually uses the CLI or relies on it.

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?

Explicit triggers are given: run it when any other tool reports the CLI is unavailable, or before relying on delegation for the first time. It also sets a clear boundary, saying it only inspects the installation and never installs or repairs anything, so the agent knows this is not a repair tool.

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 flag openWorldHint and readOnlyHint=false; the description adds genuinely non-structured behavior: Codex retains prior context, the call leaves the local machine for OpenAI, and it consumes the user's Codex usage quota. It stops short of saying whether the call blocks or hands back a job handle.

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 tight sentences: mechanism first, then the context-retention insight that explains why the prompt can be short, then the cost warning. Nothing is padded.

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 10 parameters, no output schema, and an open-world external dependency, the description should say what comes back — a result, a job id for codex_job_status, or a streamed block (the output_schema parameter implies JSON returns but this isn't stated). Cost and context are covered; return and blocking behavior are not.

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 90%, so parameters like thread_id, model, sandbox and output_schema are already documented. The description only reinforces thread_id's provenance and adds nothing about the optional overrides — baseline 3 applies.

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 and resource — send a follow-up message to a previous delegation — and pins it to a thread_id, which immediately separates it from codex_delegate (new task) and the codex_job_* tools (polling). An agent can pick it without opening the schema.

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?

Makes the precondition explicit: you must already have a thread_id from a prior delegation, and only the new instruction needs sending. It does not say when to abandon the thread and start a fresh codex_delegate instead, so there is no exclusion guidance.

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 destructiveHint=true and readOnlyHint=false, clearly indicating a destructive operation. The description adds 'running' as a state constraint, which is useful. However, it omits key behavioral details like whether the job is killed immediately or gracefully, whether it can be undone, or what happens to any partial results. With annotations covering the safety profile, a 3 is 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?

The description is a single, efficient sentence with no wasted words. It is front-loaded with the action, though it is extremely terse, which might leave some ambiguity.

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 parameter, no output schema) and the annotations covering destructiveness, the description is minimally adequate but lacks important context about side effects, job state requirements, and the return value or confirmation. It should do more to help an agent understand when and how to use it safely.

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 single parameter job_id is fully documented in the schema, including that it comes from codex_delegate. The description adds no additional parameter meaning beyond what the schema provides, making the baseline 3 correct.

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 (Terminate) and resource (running background delegation), which is clearer than the title. However, it does not distinguish itself from siblings like codex_job_status or codex_job_result, so it falls short of a 5.

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?

There is no guidance on when to use this tool versus alternatives, or when not to use it. The description gives no context about the conditions under which cancellation is appropriate, such as whether the job must be running or what happens if it has already completed.

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 openWorldHint=false, so the safety profile is covered. The description adds a meaningful behavioral constraint: it errors when the job is still running, telling the agent this is a post-completion read with a specific failure mode. It does not discuss output truncation or pagination, so 4.

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, zero waste, and the completion precondition is front-loaded. The error condition follows immediately after the main action, keeping the most important routing information prominent.

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 read tool with full schema coverage and annotations covering safety, the description supplies the necessary completion precondition and output scope. No output schema exists, so describing the return as 'full output' is appropriately complete.

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% and the only parameter 'job_id' is documented as 'returned by codex_delegate'. The description adds no additional syntax, format, or constraint beyond the schema, so the baseline of 3 applies.

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 ('Return') and resource ('full output of a finished background delegation'), and the error condition distinguishes it from a status check. It does not explicitly name sibling codex_job_status as the alternative, so it falls short of a 5.

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?

Implies use only after completion via 'finished background delegation' and 'Errors if the job is still running'. However, it does not explicitly tell the agent to call codex_job_status first or name alternatives, so usage is inferable but not spelled out.

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 openWorldHint=false, so the safety profile is covered. The description adds that it reports state plus recent activity and that omitting job_id enumerates all jobs, but says nothing about pagination, log volume, or failure modes for unknown job ids.

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, front-loaded with the core purpose and with the no-arg listing behavior second; 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 zero-required-param, read-only status tool with no output schema, the description covers what is queried (state and activity) and the two calling modes. It is nearly complete, with only return-shape hints and error handling left unspecified.

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% and both parameters are already documented in the schema; the description's note about omitting job_id restates that documentation rather than adding format or constraint detail.

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 (report) plus resource (state and recent activity of a background delegation) and scopes it to delegations started with mode=background, which links it to codex_delegate and separates it from codex_job_result.

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 one concrete usage rule — call with no job_id to list every known job — but never says when to prefer this over codex_job_result, codex_follow_up, or codex_job_cancel, so the sibling routing is left 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?

Beyond the readOnlyHint and openWorldHint annotations, the description discloses that the tool executes no model call and applies a documented matrix reconciled against the installed catalog. This adds meaningful context about how the recommendation is derived (deterministically, not by running a model) without conflicting with 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?

The two-sentence description is compact and front-loaded: it immediately states the input ('Given a task description') and the output ('recommend which Codex model and reasoning effort'). The second sentence clarifies a key behavioral trait without waste. 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 simple tool with 3 parameters (1 required) and no output schema, the description is adequately complete. It specifies the recommendation output (model and effort) but does not detail the exact return structure (e.g., object or string). Given the low complexity and clear sibling context (codex_delegate, list_codex_models), this is sufficient.

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 three parameters are fully described in the input schema (100% coverage), so the description adds no parameter-specific detail beyond the schema. With full schema coverage, the baseline of 3 is appropriate; the description does not compensate with extra parameter guidance.

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: 'recommend which Codex model and reasoning effort to delegate it with.' It also notes 'Runs no model call,' which clearly differentiates this advisory tool from execution tools like codex_delegate. The purpose is unambiguous and distinct 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 implies usage ('Given a task description... recommend') but does not explicitly say when to use this tool versus alternatives like codex_delegate or list_codex_models. The phrase 'Runs no model call' hints it is not for execution, but there is no explicit 'Use this before delegating' or 'For execution, use codex_delegate.' Guidance is implied, not stated.

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 openWorldHint=false; the description adds real context beyond them by naming the data source, saying it 'reads local files only and runs no Codex process', and bounding what the result can contain. It stops short of stating behaviour when the log is absent or empty, or how much data a large window returns.

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 the core action and payload, with the scope caveats following immediately. Every clause (source file, windowing, reported fields, local-only, no quota) carries distinct 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?

With only two fully-documented optional parameters and no output schema, the description does the right extra work by listing the reported fields, which stands in for a return-value spec. The remaining gap is edge-case behaviour (empty or missing log, size of output for long windows) for a tool the agent will likely call with defaults.

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 both parameters (including the enum and its default) are already fully documented in the schema. The description's 'over a window' and 'per group' merely gesture at the same two parameters without adding syntax, bounds or examples, so baseline 3 applies.

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 and resource ('Summarise this server's local usage log (CODEX_SUBAGENT_USAGE_LOG)') and enumerates exactly what the summary contains: process counts, outcomes, commands, durations and reported tokens. That combination is unmistakable against every sibling, none of which summarise usage history.

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 a clear usage context (summarising the local log over a window) and an explicit exclusion ('It never reports quota, credits or remaining allowance'), which steers an agent away from asking it about allowance. It does not name an alternative tool for quota-style questions, so it falls short of full when/when-not routing.

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 mark the tool read-only, and the description adds useful behavioral context: it reads from the installed Codex CLI and has a 'warned static fallback' if the catalog cannot be read. This goes beyond the annotation in a meaningful way, though caching behavior is left to the schema.

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, each earning its place: the core purpose, the fallback behavior, and the usage guidance. It is front-loaded with the essential information and contains 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 listing tool, the description covers the key context: what is listed, where it is read from, the fallback behavior, and when to call it. It does not describe the return format, but no output schema exists and the purpose makes the return shape largely predictable.

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 fully documents both parameters. The description does not add parameter-level meaning beyond the schema, which makes the baseline 3 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 names a specific action ('List'), a precise resource ('Codex models available on this machine'), and additional detail ('reasoning-effort levels each one supports'). It also distinguishes itself from a sibling by pointing to codex_delegate, so an agent can tell why this tool exists.

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 context: 'Call this before codex_delegate when choosing a model explicitly.' It clearly states when the tool should be used, though it does not name alternatives to avoid or describe 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.