Skip to main content
Glama

codex_events

Read-onlyIdempotent

Replay Codex task progress events or wait up to 25s for new ones, paging fragmented output by cursor. Coalesce state for up to 50 tasks with the outcome view.

Instructions

Replay progress or wait up to 25s. Drain has_more. For fragments, keep after and use event_seq/next_event_offset until complete. Page requests with requests_cursor. outcome coalesces state for task_ids (max 50); return cursors unchanged on the next poll. Detailed replay uses after separately.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "codex_events"
  }
}

Input Schema

NameRequiredDescriptionDefault
viewNoDetail or compact supervision viewdefault
afterNo
limitNo
cursorsNo
task_idNoTask id
task_idsNo
event_seqNo
event_offsetNo
tasks_offsetNo
wait_secondsNo
requests_limitNo
requests_cursorNoPending-request cursor
include_descendantsNo

Output Schema

NameRequiredDescriptionDefault
okYes
result_versionYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.3

TDQS

B3.3/5.0
Behavior4/5

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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), so the description's addition of the 25s long-poll blocking window, has_more draining, fragment reassembly via event_seq/event_offset, and outcome coalescing across up to 50 task_ids is meaningful latency and state-machine context. Gaps remain: it does not say what happens on timeout or whether a partial replay is resumable beyond the cursor advice.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is short and front-loads the core action, and every clause carries information. But the telegraphic fragments ("Drain has_more.", "Page requests with requests_cursor.") are compressed past readability, and the final sentence about `after` is tacked on rather than ordered with the other cursor rules.

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

Completeness4/5

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

With an output schema present, return values need not be explained, and annotations carry the safety profile; the description correctly concentrates on polling, paging, and coalescing semantics. It is still incomplete for a 13-parameter tool, leaving several paging/scope parameters and the view enum values unexplained.

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

Parameters3/5

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

Schema description coverage is low (23%) across 13 parameters, so the description has to compensate, and it only partially does: it explains `after`, `event_seq`/offset chaining, `requests_cursor`, `cursors`, and the 50-item cap on `task_ids`. It is silent on `limit`, `requests_limit`, `tasks_offset`, `include_descendants`, and `task_id`, and it names `next_event_offset` where the schema says `event_offset`, which risks a wrong argument.

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

Purpose3/5

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

The description opens with "Replay progress or wait up to 25s," which implies event/progress retrieval but never states the resource plainly (task events). It distinguishes modes (replay, wait, outcome coalescing, request paging) but does not contrast with siblings such as codex_status, codex_history, or codex_get, so an agent must infer when this is the right entry point.

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?

There is real operational guidance: drain while has_more, keep `after` for fragments, reuse cursors unchanged on the next poll, and use `after` separately for detailed replay. However, all of it is intra-tool mechanics; nothing says when to choose this over polling siblings or which situation calls for view=outcome versus a full replay.

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