codex_request_async

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

Annotations already carry the safety profile (destructiveHint=true, readOnlyHint=false, idempotentHint=false), so the description only needs to add context beyond that. It adds the 'durable' background-job semantics and the poll/collect lifecycle, but says nothing about the immediate return payload, subprocess side effects, cost, or approval gates — meaningful but thin for a tool that launches an external CLI.

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, action first, with zero filler: the first states what the tool does and the second provides the follow-up protocol. For a tool whose 42 parameters are each thoroughly documented in the schema, this is appropriately sized and front-loaded.

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 destructive, open-world, async tool with no output schema, the description omits what the start call returns (job ID/receipt) and never frames the sync-versus-async decision. The schema and annotations carry most of the invocation correctness burden, but the tool-level description leaves the request lifecycle only partially specified.

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 3 applies and the tool description correctly adds no parameter-level detail. The schema's per-parameter prose is exceptionally rich (sandboxMode resume caveats, worktree ownership and tombstone rules, providerFlags refusal for remote callers), but that documentation lives in the schema, not in the tool description.

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 pairs a specific verb and resource — 'Start an OpenAI Codex CLI request' — with a clear operating mode, 'durable background job,' which implicitly separates it from the synchronous codex_request sibling. However, it never explicitly names that sibling or the other async provider variants, so differentiation is implied rather than stated.

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 post-invocation workflow guidance ('Poll with llm_job_status, collect with llm_job_result'), which is genuinely useful. But it gives no when-to-use versus the synchronous codex_request, no when-not-to-use, and no criteria for choosing among the eight async provider variants; selection guidance is largely implied by the word 'durable.'

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