Codex Control Plane MCP

Overview Schema Source Related Servers Discussions Admin

codex_list_active_chats

List active chats from tracked, hook, transcript, or cached evidence for operator inspection. After obtaining IDs, use codex_get_turn_status or codex_get_operation_status to check specific statuses.

Instructions

List chats that look active from tracked, hook, transcript, or cached evidence. Use this for operator inspection, not for creating retries. Next call codex_get_turn_status or codex_get_operation_status when ids are available.

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_list_active_chats"
  }
}

Input Schema

Name	Required	Description	Default
`project_id`	No
`include_waiting_for_user`	No
`include_waiting_for_approval`	No
`include_running`	No
`active_window_minutes`	No
`include_evidence`	No
`title_max_chars`	No

Output Schema

Name	Required	Description	Default
`ok`	Yes
`error`	No
`agentGuidance`	No
`agentGuidanceText`	No
`recoveryAttemptState`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedJun 19, 2026
- addedOutput schema / properties / agentGuidance
```
Added value: +{
+  "additionalProperties": true,
+  "type": "object"
+}
```
- addedOutput schema / properties / agentGuidanceText
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / recoveryAttemptState
```
Added value: +{
+  "additionalProperties": true,
+  "type": "object"
+}
```
First observedv0.1.2Jun 18, 2026

TDQS

A3.7/5.0

Behavior3/5

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

No annotations provided, so description carries the burden. It mentions the evidence sources (tracked, hook, transcript, cached) but does not disclose if the operation is read-only or any side effects. The behavior is implied to be non-destructive, but not explicitly stated, leaving room for ambiguity.

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: first describes purpose, second provides usage guidance. No unnecessary words. Highly efficient.

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

Completeness3/5

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

Given the complexity (7 parameters, output schema exists), the description covers core purpose and usage but lacks details on how activity is determined, pagination, sorting, or result set behavior. It's minimal but passes the threshold for basic understanding.

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?

Schema description coverage is 0%, and the description does not explain any parameters. Parameters like 'include_waiting_for_user', 'active_window_minutes', and 'title_max_chars' have self-explanatory names but could benefit from annotation. The description adds no value beyond the schema, which is insufficient for a tool with 7 parameters.

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?

Description clearly states it lists chats that look active based on various evidence sources, and specifies use for operator inspection. However, it does not explicitly differentiate from sibling tools like codex_list_project_chats or codex_search_chats, missing a chance to clarify when to choose this over alternatives.

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

Usage Guidelines5/5

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

Explicitly states when to use ('operator inspection'), when not to ('not for creating retries'), and provides next-step suggestions ('Next call codex_get_turn_status or codex_get_operation_status when ids are available'). This is clear, actionable guidance.

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

Deploy Server