Server Quality Checklist

Tool Scores

• codex_job_consume_resultA
  3.8/5.0
  Behavior1/5

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

  The description richly discloses deletion semantics (validate-then-delete, delete-before-response, TTL retention), but annotations set destructiveHint=false while the tool explicitly deletes the stored record. This is an annotation contradiction, so per rubric the score is 1.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Front-loaded with a clear one-sentence summary, followed by dense but necessary edge-case details. Slightly verbose with references like #56, but each clause earns its place for a complex destructive-plus-read operation.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Covers deletion timing, validation, corruption handling, failed-removal retention, TTL, non-done jobs, cost (free), and relation to sibling tools. Output schema exists, so return values need no explanation.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%; job_id and workspace_root are fully documented in the schema. The description only cross-references codex_job_result for detail, adding no meaning beyond the schema. Baseline 3 applies.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  Specific verb+resource: 'Fetch a finished background Codex job's result and delete the stored record.' This clearly distinguishes it from sibling codex_job_result (fetch-only) and 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.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Explicitly states 'Use only when you no longer need to poll or re-read the job,' mentions codex_job_result for inspectable retained results, and notes non-done jobs are not deleted.

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

• codex_transferA
  4.4/5.0
  Behavior5/5

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

  Annotations only say readOnlyHint=false and idempotentHint=false; the description enriches these substantially: it creates a thread in $CODEX_HOME (hence not read-only), never edits the working tree, is not idempotent for active sessions (new thread per call), validates identifiers and fails as cli_contract_changed, and returns a POSIX resume_command. This fully explains the side effects and failure behavior beyond the structured hints.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is longer than minimal, but each paragraph earn its place: it front-loads the core purpose, then covers side effects, usage nuances, validation, and preflight. It is structured and readable, though slightly verbose compared to a two-sentence ideal. Still well-organized and not bloated.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a tool with moderate complexity (local file conversion, CLI interaction, side effects), the description covers everything an agent needs: what it does, the output (resume_command), non-idempotency, validation behavior, and a clear pointer to codex_status for prerequisites. The existing output schema covers return values, so no additional return description is needed.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100% and the schema descriptions for transcript_path and workspace_root already contain the key guidance (newest .jsonl, ambiguity ask user, workspace fallback). The main description largely reiterates this, adding little new meaning beyond what the schema provides. Baseline 3 is appropriate because the schema does the heavy lifting.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with a specific verb+resource: "Hand off the current Claude Code session to a resumable Codex thread." It clearly distinguishes this from siblings like codex_status (which confirms installation) and codex_consult/delegate (which perform codex queries/tasks), by focusing on session transfer and returning a resume_command.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives clear context on when to use it (hand off an active Claude session to Codex) and a practical preflight pointer: "codex_status (free) can confirm Codex is installed and authenticated beforehand." It also explains ambiguity handling (ask the user which transcript to transfer). It lacks an explicit when-not-to-use or direct comparison with alternatives like codex_consult, so it stops 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.

• codex_job_cancelA
  4.5/5.0
  Behavior5/5

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

  The description richly discloses behavior beyond the annotations: graceful shutdown, force-kill on overstay, teardown of the throwaway worktree, non-resumability of cancelled jobs, cleanup_warnings for leftover paths, idempotency, and 'Free — no model call'. These details add significant context that the annotations do not provide and do not contradict them.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a compact paragraph of four sentences, each adding concrete value. It front-loads the purpose, then details the shutdown process, idempotency, and cost, with zero filler or repetition.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a cancellation tool with side effects, the description covers the full lifecycle: graceful shutdown, force-kill, worktree cleanup, non-resumability, idempotency, and cost, plus a mention of the output field cleanup_warnings. With an output schema available, this is a complete picture for an agent to decide and invoke confidently.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema already has 100% coverage with descriptions for both job_id and workspace_root. The description does not add any additional param-specific meaning beyond what the schema states, so it meets the baseline of 3.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description starts with 'Cancel a running background Codex job', which is a specific verb (Cancel) and resource (Codex job) with scope (running background). This clearly distinguishes it from sibling tools like codex_job_status or codex_job_result, which check status or retrieve results.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  It clearly states the tool is for cancelling running jobs and mentions that already-terminal jobs are returned unchanged, making retries safe. However, it does not explicitly name alternatives (e.g., 'use codex_job_status to check status instead'), so it falls just short of a full 5.

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

• codex_delegate_dry_runA
  4.6/5.0
  Behavior5/5

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

  Goes far beyond the readOnlyHint annotation: declares 'no model call, no spend, no worktree created', explains that returned tier/sandbox describe the previewed run (not the preview itself), and clarifies that deadline_advisory is a hint, not a refusal. Also notes the mirroring of zero-spend validation.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is dense but well-structured, opening with the core purpose and then layering usage, interpretation, and caveats. It is longer than simpler tools, but every sentence adds value given the tool's complexity; it is appropriately sized.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the complexity of the tool and the presence of an output schema, the description is exceptionally complete. It covers prerequisites, usage timing, behavioral nuances (no side effects, alignment with paid failures), and edge cases like deadline_advisory. Nothing essential is left unexplained.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  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. The description does not add parameter-specific detail beyond the schema; it contextualizes the overall behavior (e.g., prompt size, mirrored validation) but does not elaborate on individual parameter semantics.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's purpose: 'Preview what a codex_delegate/codex_delegate_async call would do' and details the previewed components (baseline, prompt size, workspace/isolation). It distinguishes itself from the actual delegate tools and explicitly links to the sibling codex_dry_run pattern.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Provides explicit when-to-use guidance: 'Use it before delegating to confirm scope and repo before committing to cost.' It also directly compares to codex_dry_run previewing codex_review_changes, giving a clear analogy. It notes that a failure here mirrors a paid-call failure, guiding the agent on how to interpret results.

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

• codex_job_listA
  4.6/5.0
  Behavior5/5

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

  Even with readOnlyHint=true, the description goes far beyond annotations. It details truncation semantics (truncated:true, truncation_hint, rows dropped not paged), TTL expiry (default 24h), per-workspace soft cap with eviction, that running jobs are never evicted, and that sync-originated records are included. These operational traits are critical for correct agent behavior and are entirely additional to the annotation's read-only signal.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is lengthy but dense with operational caveats that are genuinely useful. It is front-loaded with the core purpose and 'Free — no model call,' then flows into return fields, limit/status semantics, and eviction policy. Every sentence provides value; the length is justified by the tool's subtle list behavior. Slightly long, but not padded.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The description covers purpose, use case, return fields, truncation behavior, TTL, soft cap, eviction, running-job protection, and sync-originated records. The output schema exists to handle return structure, so the description need not list fields. This is a complete picture for an agent deciding whether and how to invoke the tool, including all lifecycle gotchas.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema already covers all 3 parameters (100% coverage). The description reinforces the limit/status behavior, particularly that they narrow independently and that omitting limit does not cap results. It also adds 'omitted rows are dropped, not paged' which goes beyond the schema. However, workspace_root is only explained in the schema, and the description overlaps with the schema's own limit description. Given the high schema coverage, the description adds meaningful but not essential semantic detail.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's function: 'List the background jobs known for this workspace, newest first.' It specifies the verb (list), resource (background jobs), and scope (workspace). It also distinguishes itself from sibling tools by noting it returns job metadata (id, kind, status, expiry) and even references codex_job_status for result_ok semantics. This is a precise, non-tautological purpose statement.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives an explicit use case: 'Use to recover job_ids lost across context compaction or interruption.' It also warns that the list is not permanent storage, telling agents to read results promptly. However, it does not explicitly state when not to use this tool (e.g., for fetching a single job's result), though the reference to codex_job_status provides a pointer. The guidance is clear but lacks explicit exclusions.

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

• codex_job_resultA
  4.6/5.0
  Behavior5/5

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

  Annotations already mark the tool readOnlyHint=true and openWorldHint=false, and the description reinforces this with 'WITHOUT deleting the record.' It adds substantial behavioral context beyond annotations: error envelopes for various job states, the job_result_incompatible limitation, the envelope shape matching the job kind, and the 'free' nature with no model call. No contradiction present.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is front-loaded with the core purpose and then organized into applicability, usage, error behavior, alternatives, cost, and parameter notes. While longer than a trivial tool's description, every sentence carries operational value; a small amount of repetition (e.g., meta.job_id mentioned twice) keeps it from a perfect score.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's moderate complexity and the presence of an output schema, the description is fully complete. It covers prerequisites, error scenarios, the relationship to sibling tools, the optional detail parameter, and cost implications, giving an agent everything needed to invoke the tool correctly without needing to infer behavior.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so baseline is 3. The description mostly restates schema-provided parameter details (e.g., detail='summary' vs 'full') and adds no genuinely new parameter semantics. It mentions meta.job_id is set, which relates to input provenance but not a distinct parameter detail, so it does not raise the score above baseline.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with 'Fetch a finished background Codex job's result WITHOUT deleting the record,' which states a specific verb, resource, and key qualifier (non-destructive). This clearly distinguishes it from codex_job_consume_result, and the subsequent enumeration of supported job types removes ambiguity about scope.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explicitly says 'Use when codex_job_status reports result_available=true' and identifies codex_job_consume_result as the alternative when deletion is desired. It also names sibling tools and clarifies when this tool should not be used (e.g., errors for still-running/cancelled/timed-out/failed jobs), providing strong decision guidance.

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

• codex_job_statusA
  4.6/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint=true, so the bar is lower, but the description still adds substantial context: return fields, the nuanced meaning of result_ok, cross-release incompatibility, and the growing poll_after_ms backoff. It also explicitly notes the tool is free and performs no model call. 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.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is longer than a minimal two-sentence snippet, but it is well-structured with front-loaded purpose, then grouped paragraphs for result semantics and polling behavior. Every sentence contributes unique, non-redundant detail, though a slightly more condensed version could improve scannability.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's complexity, the description is complete: it covers when to use, what fields are returned, the semantics of result_ok, cross-release pitfalls, and retention behavior. An output schema exists, so return-value details are not required. The description leaves no critical gap for an agent to invoke and interpret the call correctly.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, and both parameters (job_id and workspace_root) have thorough descriptions in the schema itself. The tool description adds no additional parameter-level semantics beyond the schema's coverage, so it stays at the baseline of 3.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with a specific verb and resource: 'Check a background job's lifecycle state without fetching the full result.' It clearly distinguishes itself from siblings like codex_job_result (which fetches the result) and from the async/sync job-launching tools. This is a textbook example of purpose clarity.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  It explicitly states when to use the tool: 'Use after any *_async call ... or any sync consult/review/delegate (whose meta.job_id names its record).' It also gives forward guidance: 'when it is true, call codex_job_result,' and provides operational guidance on polling ('Honor poll_after_ms between polls'). This covers both timing and relationship to alternatives with actionability.

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

• codex_dry_runA
  4.7/5.0
  Behavior5/5

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

  The description discloses multiple non-obvious behaviors beyond the annotations: no model call or spend, best-effort redaction, `would_call_model` semantics, unvalidated overrides, and the conditional nature of `deadline_advisory`. It also explains that the result echoes effective model/reasoning_effort overrides unvalidated. This gives the agent a realistic expectation of what the dry run can and cannot confirm, which is especially important given the readOnlyHint annotation.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single dense paragraph that stays on point and front-loads the core purpose. Every sentence adds unique value — purpose, cost, usage timing, caveats, output fields, and async alternative — without filler or repetition. It is appropriately sized for a tool with this complexity and does not waste tokens on restating the title or obvious schema facts.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's complexity and the presence of an output schema, the description still covers the critical behavioral nuances: output fields that matter (`coverage`, `deadline_advisory`), redaction limitations, and the distinction between this dry-run tool and its async counterpart. It addresses both positives and negatives (what the tool does and what it does not do), making it complete enough for an agent to invoke it correctly without ambiguity.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema already provides 100% parameter coverage with detailed descriptions for each field, so the schema carries most of the parameter-semantics burden. The description adds marginal value by advising the agent to pass the same `extra_context` and `untracked` policy as the paid review, and by noting that model/reasoning_effort are unvalidated. However, this is mostly reinforcement of existing schema information rather than new parameter-level meaning, so a baseline 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with 'Preview what a codex_review_changes call would send — scope, diff size, redactions, truncation,' which states a specific verb, resource, and output scope. It explicitly distinguishes itself from the paid review tool by adding 'Free — no model call, no spend,' and it references tool-specific output fields like `would_call_model` and `deadline_advisory`. This clearly differentiates it from siblings like `codex_review_changes` and the async variants.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives explicit when-to-use guidance: 'Use it before a review to inspect the scope and the reported redactions.' It instructs the agent to pass matching parameters ('Pass the same extra_context and untracked policy') and explicitly names the async sibling (`codex_review_changes_async`) as the counterpart when `deadline_advisory` is non-null. The redaction best-effort caveat also tells the agent not to treat the preview as a security guarantee, which is a non-obvious usage constraint.

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

• codex_modelsA
  4.7/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint=true, but the description adds significant behavioral context: reads from cache with fallback, 'source' field indicates provenance, fallback lacks effort data, and backend validation may reject listed values or accept unlisted ones. It also notes the payload is the same as a resource, going far beyond the annotation.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Each sentence adds a distinct piece of information: purpose, cost, source, validation caveats, payload equivalence, and caching instability. The description is front-loaded with the main action and is compact despite the detail.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a zero-parameter read-only tool with an output schema, the description fully explains what the tool returns, how it obtains data, its reliability, and its relationship to other resources. There are no obvious gaps.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Zero parameters means no schema to elaborate. The description still explains the output meaning (model slugs and reasoning-effort sets) and the source field, which is helpful even though the output schema is present.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  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 Codex model slugs...' with the additional clarification of the reasoning-effort data. It clearly distinguishes this from sibling tools by focusing on model discovery and the 'codex://models resource' equivalence.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides clear context on when to use (advisory discovery) and explicitly warns against certain uses ('do not cache it by the capabilities fingerprint'). It does not name alternative tools explicitly, so it misses the full 'when not / alternatives' bar.

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

• codex_statusA
  4.7/5.0
  Behavior5/5

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

  The description extensively discloses behavior beyond the readOnlyHint annotation: it is 'Free — no model call', fetches live data via a read-only call, and explains the meaning of each status ('blocked', 'limited', 'unknown', etc.) and edge cases like stale cache or different CODEX_HOME. This is consistent with the annotations and adds significant context.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is long but well-structured: it opens with the core purpose, then provides usage timing, then walks through the complex rate_limit and blocked semantics. Every sentence adds value, and the front-loaded structure ensures the most important information is immediately visible.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's complexity (multiple quota windows, stale vs live data, spend control), the description is thorough. It covers null windows, conservative available semantics, retry behavior for unknown, when to surface blocked to the user, and freshness indicators. An output schema exists, but the description still provides complete situational context.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The tool has zero parameters, so the baseline is 4. The description does not need to explain parameters, but it does explain what the tool reports (e.g., rate_limit block, spend_control_reached), which is helpful for understanding the output.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's purpose: 'Check that the `codex` CLI is installed, authenticated, and a supported version, and report the resolved defaults.' It uses a specific verb ('check') and resource ('codex CLI'), and makes the tool's role distinct from sibling tools like codex_delegate or codex_dry_run by focusing on readiness and quota status.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives explicit usage timing: 'Run it before your first paid call in a session to confirm setup, and again whenever a run fails with a setup error.' It also provides decision guidance for quota states (e.g., 'prefer to defer non-urgent Codex calls'). It does not explicitly mention when not to use the tool or name alternative tools, so it falls 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.

• codex_capabilitiesA
  4.8/5.0
  Behavior5/5

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

  Beyond the readOnlyHint annotation, the description adds materially valuable behavioral facts: 'Free — no model call', cacheability by fingerprint, and the exact trade-offs of each detail mode. It also clarifies that include_schemas is an opt-in fallback to codex:// resources, giving the agent a precise mental model of the tool's side effects and cost profile.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is long but every sentence earns its place. It front-loads the core purpose and free/no-model-call behavior, then systematically walks through each detail mode and include_schemas. The structure is logical and avoids redundant restatement of the schema.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a capability-listing tool with an output schema, the description completes the picture: it explains caching, mode differences, fallback behavior, and cost implications. There is no significant missing context that would prevent an agent from selecting or invoking the tool correctly.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Even with 100% schema description coverage, the prose enriches both parameters significantly. It explains that detail='full' restates data the agent already holds, detail='contracts' omits tool_details to avoid re-paying for inventory, and include_schemas works in any detail mode. These are semantic insights the schema alone does not convey.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description immediately states it lists this server's tools, tiers, and result fingerprint. The phrase 'List this server's tools, tiers, and the result fingerprint' is a specific verb+resource pairing that distinguishes it from sibling tools like codex_status, which likely reports status rather than capability inventory.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives clear usage context: it is free, makes no model call, and supports caching via the fingerprint, which signals when to use it. It also explains when to use include_schemas (resource-blind clients) and warns that detail='full' restates information the agent already holds. However, it does not explicitly name any alternative sibling tools or state a strict when-not-to-use scenario.

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

• codex_delegateA
  4.8/5.0
  Behavior5/5

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

  Goes far beyond annotations by disclosing paid quota consumption, the model call sending task content to OpenAI, inability of sandbox commands to access network, loading of AGENTS.md/skills, timeout termination with no recoverable partial output, and detach/recovery options. 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.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is long but well-structured with bolded key points and clear paragraph breaks (PAID, NO NETWORK, Progress & recovery). Every sentence adds relevant operational detail, and the most critical facts are front-loaded. Slight redundancy in explaining async vs sync, but density is high.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's complexity (paid, network-isolated, with sync/async variants and job recovery), the description covers cost, security, sandbox limitations, timeout behavior, recovery paths, and prerequisites like needing a git repo with at least one commit. The output schema exists, so return format doesn't need explanation. Extremely complete.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, so baseline is 3. Description adds meaningful context beyond schema: workspace_root must be absolute and falls back to server cwd if omitted, timeout_seconds is clamped 10-600s and out-of-range values are coerced, and idempotency_key lifecycle details. This extra guidance justifies a 4.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a specific verb+resource+scope: delegates a coding task to Codex in an isolated git worktree and returns an unapplied reviewable diff. It clearly distinguishes from siblings like codex_delegate_async (background) and codex_delegate_dry_run (free check).

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Explicitly tells when to use alternatives: use codex_delegate_dry_run or codex_status when only checking scope/readiness, and prefer codex_delegate_async for substantial multi-file tasks that may exceed the deadline. It also states the self-contained/no-network constraint, guiding appropriate task selection.

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

• codex_delegate_asyncA
  4.9/5.0
  Behavior5/5

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

  Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false), the description exposes critical behavioral traits: it spends paid quota on every call, runs in a throwaway worktree with a non-applied diff, commits to the spend even if never polled, blocks network egress for sandbox commands, and sends the raw task and read file contents to OpenAI. It also discloses skill auto-loading and best-effort secret redaction, which is significant context not captured in 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.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Though lengthy, the description is tightly organized with bolded section cues (PAID, NO NETWORK) and every sentence carries essential operational, cost, privacy, or lifecycle information. The core purpose is front-loaded in the first sentence, and the structure makes the long form scannable. Given the high-stakes paid async nature and the need to disclose privacy limitations, the length is justified and not wasteful.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  With an output schema present, the description does not need to detail the return values; it covers everything else needed for correct invocation: cost, async behavior, prerequisites, error-prone network constraints, privacy boundaries, deadlines, and the post-job polling/consumption/cancellation flow. The tool's complexity is high, and this description fully equips an agent to use it safely and effectively.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema already provides 100% coverage with detailed descriptions for all six parameters, so the baseline is 3. The description goes beyond the schema by reinforcing that `workspace_root` must be absolute and, more importantly, warns that the `task` is sent raw to OpenAI and that secret redaction does not cover it. This adds security-relevant meaning to the task parameter that the schema does not express.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with a precise statement: 'Delegate a coding task to Codex in the background and get a `job_id` back immediately (does not block on the run).' This clearly identifies the action, the resource, and the async behavior, and it distinguishes this tool from the synchronous `codex_delegate` sibling. The paid/quota warning and the contrast with `codex_delegate_dry_run` further disambiguate its purpose.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives explicit when-to-use guidance: prefer this for substantial multi-file tasks that may exceed the 300s synchronous deadline, and use free dry-run/status checks first for scope/readiness. It also names the follow-up lifecycle tools (`codex_job_status`, `codex_job_result`, `codex_job_cancel`) and states the git-repo prerequisite and `workspace_root` requirement, making tool selection and invocation unambiguous.

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

• codex_review_changesA
  4.9/5.0
  Behavior5/5

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

  Beyond the annotations, the description discloses extensive behavioral context: it spends Codex quota, sends the diff and possibly other repo files to OpenAI, has best-effort redaction with raw extra_context, auto-loads AGENTS.md and skills, ignores isolation flags, blocks up to a deadline, loses partial output on timeout, and supports recovery via job_id. It also explains review_status/coverage semantics. 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.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Although long, every paragraph earns its place: cost/alternatives, scope, result semantics, static-review limitation, data egress, and progress/recovery. It is front-loaded with the core purpose and paid warning, and uses clear section labels and bolded terms for scannability. The length is justified by the tool's complexity and security implications.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's complexity, the output schema covers return values, so the description correctly focuses on usage context, cost, egress, limitations, and recovery. It leaves no practical gap: the agent knows when to use it, what it costs, what data leaves the environment, what the limitations are, and how to handle long-running or timed-out calls via the async/job family.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  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 meaningful cross-parameter context beyond the schema, such as 'extra_context ... cuts false positives', 'untracked files ... NOT reviewed by default', 'pass workspace_root (absolute) for the right repo', and the distinction that timeout_seconds bounds the run, not necessarily the inline wait. It does not walk through every parameter, but the schema already does that.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with a specific verb+resource: 'Ask Codex (a different model) to review your git changes for an independent second opinion.' It distinguishes itself from siblings by explicitly naming codex_dry_run/codex_status as free alternatives and codex_review_changes_async for long-running reviews. The paid nature is boldly stated in the first line.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  It provides explicit when-to-use guidance: use codex_dry_run or codex_status first if only checking scope/readiness, prefer codex_review_changes_async for multi-file/whole-branch reviews that may exceed the timeout, and treat results as unvalidated claims because this is STATIC review, not a verify mode. It also tells the agent to pass workspace_root for the correct repo and use extra_context to cut false positives.

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

• codex_consultA
  5/5.0
  Behavior5/5

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

  The description extensively discloses behavior beyond annotations: it runs in a read-only sandbox, never edits files, sends question and extra_context to OpenAI, auto-loads AGENTS.md and skills, has best-effort redaction that does not cover raw inputs, and terminates with unrecoverable partial output on timeout. It also details progress streaming and recovery via meta.job_id, far exceeding what the annotations convey.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is long but exceptionally well-structured, with bolded headers (PAID, Data egress, Progress & recovery) and front-loaded critical warnings. Every sentence carries essential information, and the organization makes complex caveats navigable rather than rambling.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's complexity—9 parameters, multiple sibling alternatives, external API calls, sandbox constraints, and timeout/recovery behavior—the description is thoroughly complete. It covers prerequisites (free status check), alternatives (async variant), side effects (data egress), error/edge cases (deadline expiry, partial output), and points to output envelope/meta.job_id for result recovery. The existence of an output schema further reduces the need to describe return values.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Although the schema already covers all 9 parameters at 100%, the description adds substantial meaning: it explains workspace_root fallback behavior, timeout_seconds clamping to 10-600s and server default, reasoning_effort overrides and advisory values, extra_context being untrusted, and idempotency_key dedup semantics with conflict refusals. This goes well beyond the schema's baseline.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with a specific verb and resource: 'Ask Codex (a different model) for a read-only second opinion or answer.' It clearly distinguishes itself from siblings by noting this is a synchronous paid consult, contrasting with codex_consult_async and codex_dry_run, and stating it is a static review rather than a verify mode.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides explicit guidance: run codex_status (free) first to confirm CLI installation/authentication, use codex_consult_async for long-running or high-reasoning-effort consults, pass workspace_root for repo-grounded questions, and omit it for pure Q&A. It also advises treating findings as unvalidated claims to verify manually, which is key usage context.

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

• codex_consult_asyncA
  5/5.0
  Behavior5/5

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

  Beyond the annotations, the description discloses that the call is paid, consumes Codex quota, has no dry-run preview, runs to completion even if never polled, has a configurable deadline, never edits files, and sends raw unredacted `question`/`extra_context` to OpenAI. It also explains workspace-root resolution, AGENTS.md auto-loading, and skill discovery—far exceeding the annotation-provided hints.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is dense but front-loaded: the first sentence states the core purpose and immediate return value, followed by a clear PAID warning, a comparison to the sync sibling, job lifecycle steps, and data-egress caveats. Every sentence provides operationally relevant detail without fluff.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's complexity, the description fully covers purpose, usage guidance, pricing, side effects, job lifecycle, parameter caveats, workspace behavior, and data egress. The presence of an output schema makes the lack of explicit return-value explanation acceptable; the description is complete for an agent to select and invoke safely.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Although the schema already covers all parameters at 100%, the description adds meaningful semantic nuance: `extra_context` is labeled UNTRUSTED and not redacted, `workspace_root` fallback triggers `meta.workspace_warning`, and `idempotency_key` replays results with no new spend only when key and args match. These details go well beyond the field descriptions.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with a specific verb+resource: 'Ask Codex for a read-only second opinion in the background' and states the immediate return of a `job_id`. It clearly distinguishes from the synchronous sibling `codex_consult` by noting it is 'detached' and better for long-running, high-reasoning_effort or broad repo-grounded consults.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explicitly says to prefer this tool over `codex_consult` when the sync deadline may be exceeded, warns that sync runs lose partial work, and instructs running `codex_status` first because there is no dry-run. It also names the exact lifecycle tools: `codex_job_status`, `codex_job_result`, `codex_job_consume_result`, and `codex_job_cancel`.

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

• codex_review_changes_asyncA
  5/5.0
  Behavior5/5

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

  The description richly discloses behaviors beyond the annotations: it clearly states this is a PAID operation that spends Codex quota, explains the diff-gathering job has zero spend on bad base/commit, details data egress (sending redacted diff plus unredacted extra_context to OpenAI), and notes redaction is best-effort. This complements annotations like readOnlyHint=false (because it creates a job and spends quota) without contradiction.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is long but every sentence serves a purpose; it is front-loaded with the key purpose and cost warning, then logically organized into usage guidance, job lifecycle, and data-egress details. Despite the length, it is appropriately sized for a tool with this many caveats.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's complexity, the description is comprehensive: it covers cost, scope semantics, error behavior, egress, job management, and configuration fallback. With an output schema present, it does not need to describe return values, and it fully instructs how to consume results via other tools.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, but the description adds valuable semantics: it explicitly instructs to pass workspace_root (absolute), reveals that bad base/commit yields zero spend, that bad scope is rejected by MCP validation, and flags that untracked files with the 'include' policy send contents to OpenAI. This goes well beyond the schema's property descriptions.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's function: 'Review your git changes in the background; get a job_id back immediately.' It distinguishes itself from the synchronous sibling codex_review_changes by emphasizing the detached/background nature and immediate job_id return.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Explicit guidance is provided: use codex_dry_run or codex_status first for free readiness checks, and prefer this async tool for multi-file or whole-branch reviews that may exceed the 300s sync deadline. It also explains the job lifecycle (poll, read, consume, cancel), making the intended usage clear.

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