Answer Codex

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

With no annotations, the description carries the full burden. It usefully discloses the two modes (approvals consume a decision; questions consume an answers map), which is real behavioral context, but it omits side effects, permission needs, or what happens after a decision is submitted.

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, front-loaded with the core purpose followed by the mode-specific input formats. Little waste, though the final sentence reads as an instruction rather than tool-contract 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?

No output schema and no annotations, so the description must stand alone. It covers the two request shapes and their inputs, but leaves return/blocking behavior largely to the wait_seconds schema and does not describe outcomes of the response.

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 only 25%, so the description is expected to compensate. It clarifies the answers map semantics ({question id: "answer"}) and restates the decision enum values, but leaves request_id and the mode-dependent usage of decision vs answers partially implicit.

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+resource: answer a request Codex is blocked on, and ties it to the pending_requests list. It distinguishes the two request types (approvals vs questions), making the tool's role clear, though it doesn't explicitly name how it differs from siblings like codex_steer or codex_wait.

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 one usage instruction ('Ask the user first when the request is something they should decide') and implies usage when a request is pending, but never states when to prefer this over codex_wait or codex_status, and offers no alternatives or exclusions.

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