codex_start_task

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

Annotations only indicate readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds substantial behavioral detail: it mentions the TRUSTED_EXECUTOR_AUTO_ADVANCE mechanism, worker-owned DoD, error conditions for omitted/deprecated inputs, and the specific default completion policies. This goes well beyond the sparse annotations, though it does not describe the return value or potential side effects in detail.

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 dense paragraph but is not overly long relative to the complexity. It front-loads the core action ('Start a background Codex turn') and then packs constraints efficiently. No unnecessary filler; every sentence conveys a specific constraint or behavior. It could benefit from bullet points for readability, but the content is appropriately sized.

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?

Despite covering workstream logic and completion policies, the description leaves many parameters unexplained, including nested objects like research_program and research_contract, which are essential for RESEARCH workstreams. With only 13% schema description coverage and no output schema, an agent would lack sufficient context to correctly construct the full request. The description is inadequate for the tool's complexity.

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?

With schema description coverage at only 13%, the description compensates for the most critical parameters: it explains the next_workstream structure, the requirement for accepted_handoff_path/sha256 in EXECUTION_ONLY, and the behavior of completion_policy. However, it does not clarify many other parameters such as research_program, research_contract, expected_artifacts, or rva_fallback_policy, leaving a significant gap for a tool with 23 parameters.

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 tool's purpose: 'Start a background Codex turn.' It uses a specific verb ('Start') and resource ('background Codex turn'), and the details about workstream types and policies distinguish it from sibling tools like codex_send_followup or codex_abort, which serve different lifecycle stages. The purpose is unmistakable.

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 context on when different configurations apply (e.g., EXECUTION_ONLY vs RESEARCH) and clarifies error conditions, but it does not explicitly name alternative tools or conditions under which an agent should choose this over a sibling. The guidance is more about parameter requirements than tool selection, leaving the agent to infer alternatives from the tool name and sibling list.

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