Skip to main content
Glama

codex_start

Destructive

Starts a persistent Codex conversation and immediately returns a task ID; then poll codex_events and handle pending requests until the turn completes.

Instructions

Start a persistent Codex conversation and return promptly with a task id. Poll codex_events and handle pending_requests until the turn finishes.

Input Schema

NameRequiredDescriptionDefault
nameNo
modelNo
accessNowrite
effortNo
imagesNo
promptYes
skillsNo
workdirNoAbsolute project directory chosen by the main agent
project_idNoSelected project; use instead of workdir
request_idNoKey for identical retries
operation_idNoAlias of request_id
service_tierNo
approval_modeNoNative Codex reviewer; approve_for_me uses auto_review without disabling sandboxinginherit
context_filesNo
output_schemaNo
collaboration_modeNodefault

Output Schema

NameRequiredDescriptionDefault
okYes
result_versionYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.3

TDQS

B3.4/5.0
Behavior4/5

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

Annotations already declare the safety profile (non-read-only, destructive, open-world), so the description's job is to add context, and it does: the call is non-blocking, it creates a persistent conversation, and completion requires a polling loop that may surface pending requests needing responses. It stops short of warning about what the destructive/write behavior can affect or how request_id retries interact with the declared non-idempotency.

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?

Two sentences, both load-bearing: the first defines the operation and its return contract, the second defines the follow-up loop. The return behavior is front-loaded and there is no redundant restatement of the name or annotations.

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

Completeness2/5

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

For a destructive, open-world, 16-parameter launcher, the description omits the mechanics an agent actually needs: what access/approval semantics do, how to choose workdir vs. project_id, and what side effects the turn can have on the workspace. An output schema exists so return-shape detail is excusable, but the input-side gaps are substantial.

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

Parameters2/5

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

With 16 parameters and only 31% schema description coverage, the description needs to carry meaning for most inputs, and it explains none of them. Workdir vs. project_id, the read/write access enum, approval_mode, and effort/model selection are all left entirely to schema or unstated.

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

Purpose4/5

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

States a specific verb and resource ('Start a persistent Codex conversation') and adds the key differentiator that it returns immediately with a task id rather than blocking. It names codex_events as the follow-up surface, so the async model is legible, but it never contrasts itself with nearby siblings like codex_send, codex_delegate, or codex_resume.

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

Usage Guidelines3/5

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

The second sentence gives real operational guidance: poll codex_events and handle pending_requests until the turn finishes, which tells the agent how to drive the turn to completion. However, there is no guidance on when to choose this over the other conversation-entry siblings, nor any prerequisite or exclusion criteria.

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