codex_run

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

No annotations are provided, so the description carries the full burden. It discloses that the tool uses cached OpenAI auth and requires no API key, which is a useful behavioral detail. It also mentions that tasks can take longer than Gemini, setting expectations. However, it does not discuss side effects such as file modifications (sandbox behavior) or potential irreversible actions, but the sandbox parameter partially covers that. Since the sandbox parameter mentions approvals and workspace-write, the description provides decent transparency without contradicting anything.

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 efficient and front-loaded: it opens with the core purpose, then adds key differentiators (specialization and auth) in a compact form. The sentence about cached auth is useful, but the description could be slightly more structured by separating general purpose from usage notes. Overall, it is concise and clearly structured without wasted words.

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?

The tool has moderate complexity (5 params, one enum, no output schema), and the description plus schema provide enough for an agent to call it correctly. It covers the key operational aspects: what it does, how to specify the model, sandbox options, timeout, and working directory. There is no explicit mention of return format, but given no output schema, that is a minor gap. The description is sufficiently complete for a coding-task tool.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly, including the sandbox enum and the timeout's purpose. The description adds a bit of context by mentioning that Codex tasks can take longer than Gemini, which explains the timeout default, and that working_directory should be set to the project root so Codex can read/write files. This adds marginal value beyond the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states the verb 'Send' and the resource 'task to OpenAI Codex via the local codex CLI', and specifies the specialization in coding tasks, file operations, and technical analysis. It distinguishes from siblings like gemini_run, claude_run, and local_llm_run by naming the specific platform (Codex) and the local CLI mechanism.

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 that this tool is for coding tasks and specifically mentions it can take longer than Gemini, which hints at when to use it relative to siblings with faster models. However, there is no explicit guidance on when NOT to use it (e.g., for non-coding tasks) or direct comparison with alternatives like gemini_run or claude_run. The specializations are mentioned but not framed as usage conditions.

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