Server Quality Checklist

Tool Scores

• codex_interruptA
  3.6/5.0
  Behavior3/5

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

  The description adds the nuance that the cancellation applies to an 'active' turn, which implies it may not have effect on non-active turns. However, the annotations already declare destructiveHint and idempotentHint, so the description does not need to restate those. It does not clarify what happens if no active turn exists or whether this is a request versus a guaranteed cancellation, but with annotations covering the safety profile, the additional context is moderate.

  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?

  The description is a single, focused sentence that directly conveys the tool's purpose without any filler. It is perfectly concise and well-structured for such a simple operation.

  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?

  Given the tool's simplicity, the presence of annotations (destructive, idempotent) and full schema descriptions, the description provides sufficient context for invocation. It does not mention return values or error scenarios, but with no output schema and a straightforward operation, this is not a critical gap. It covers the essential action and target.

  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?

  Both parameters have thorough descriptions in the schema (100% coverage), including meaning and default behavior for turnId. The tool description itself adds no further parameter semantics, so the baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states a specific action (request cancellation) on a specific resource (an active Codex turn), which distinguishes it from sibling tools like codex_start or codex_status. The verb 'request cancellation' is unambiguous and the phrase 'active Codex turn' scopes the operation appropriately.

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

  Usage Guidelines2/5

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

  No guidance is given on when to use this tool versus alternatives. It does not mention that it should be used to stop an ongoing turn, or that one might use codex_status first to check for an active turn. The description simply states what it does without any contextual 'when-to-use' or exclusionary language.

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

• codex_resolve_approvalA
  3.7/5.0
  Behavior3/5

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

  The annotations already mark the tool as destructive (destructiveHint: true) and non-idempotent (idempotentHint: false). The description adds the specific decision actions (accept, acceptForSession, decline, cancel) but does not disclose behavioral details such as whether accepting triggers command execution or whether cancellation is reversible. It does not contradict the annotations.

  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?

  The description is a single, information-dense sentence that efficiently lists all decision actions and the approval types. There is no redundancy or filler, making it highly concise and well-structured.

  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?

  For a simple two-parameter tool, the description covers the core purpose and decision spectrum adequately. However, it fails to mention how to obtain a requestKey or what happens after a decision (e.g., whether the command execution proceeds). The lack of an output schema means return values are unaddressed, but this is a minor gap given the simple nature of the tool.

  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?

  The schema description coverage is only 50%, with requestKey having a description and decision lacking one. The description repeats the enum values without explaining their semantic differences or the consequences of each choice. It adds no meaning beyond the schema for requestKey, merely referencing 'pending approval' without clarifying how to obtain or use the key.

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

  Purpose5/5

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

  The description uses explicit verbs (accept, decline, cancel) and names the resource (pending Codex command-execution or file-change approval), making the tool's purpose immediately clear. It also distinguishes this from sibling tools like codex_list_approvals by indicating this tool resolves rather than lists approvals.

  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 description implies the tool is used when a pending approval exists, but it does not explicitly state when to use this tool versus alternatives, nor does it mention prerequisites like obtaining a requestKey. There is no guidance on when to choose acceptForSession over accept, or when to cancel rather than decline.

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

• codex_read_threadA
  4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds a substantive behavioral detail: the bridge denies threads outside CODEX_ALLOWED_ROOTS, which is not visible in annotations. This informs the agent about potential authorization failures and scoping limits.

  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?

  The description is two concise sentences with no filler. The main purpose is front-loaded in the first sentence, and the second sentence provides a crucial constraint. Every word contributes to understanding the tool.

  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?

  Given the tool's simplicity, strong annotations, and full parameter schema coverage, the description is mostly complete. It does not describe the return value format, but with no output schema, that is a gap; however, the name and the includeTurns parameter reasonably convey what is returned. The authorization constraint adds essential context for operational use.

  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 100% for both parameters, so the structured schema already defines threadId and includeTurns. The description adds no additional meaning beyond what the schema provides, such as the distinction between compact and full turn views, which is already in the schema. Baseline 3 is appropriate when schema covers parameter semantics.

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

  Purpose5/5

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

  The description clearly states the action ('Read') and the resource ('a persisted authorized Codex thread'), immediately distinguishing it from sibling tools like codex_list_threads (list threads) or codex_status (status check). The scope is well-defined with the authorization constraint, making the tool's purpose unambiguous.

  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 description implies usage for reading a specific thread's contents, but it does not explicitly differentiate from alternatives like codex_status or codex_list_threads. The mention of CODEX_ALLOWED_ROOTS is a constraint on valid inputs rather than guidance on when to choose this tool over others. Use is implied rather than clearly instructed.

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

• codex_statusA
  4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds transparency by detailing the exact data returned (latest diff, streamed events, etc.) beyond the annotation flags. It does not mention potential large responses from includeTurns, but that is covered in the schema parameter description.

  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?

  The description is a single, well-structured sentence that front-loads the main action ('Read a thread snapshot') and then lists all data components in a logical sequence. No filler or redundant content.

  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 no output schema, the description adequately enumerates the key return categories (thread snapshot, turn state, approvals, etc.). It does not cover edge cases or polling behavior, but given the read-only annotation and schema parameters, it provides sufficient context for an agent to understand the tool's purpose and outputs.

  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?

  The description does not elaborate on any parameters, but the input schema already provides descriptions for 3 of 4 parameters (threadId, includeTurns, afterSequence). The only undocumented parameter, maxEvents, is self-explanatory. The description's phrase 'recent streamed events' loosely implies event-related parameters but adds minimal value beyond the schema.

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

  Purpose5/5

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

  The description clearly states the tool reads a thread snapshot, current turn state, pending approvals, latest agent message, latest diff, and recent streamed events. It uses a specific verb ('Read') and resource, and the enumerated components distinguish it from sibling tools like codex_read_thread or codex_list_approvals.

  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 description implicitly conveys this is for getting a composite status view, but it does not explicitly state when to use this tool versus alternatives such as codex_read_thread or codex_list_approvals. No exclusions or alternative recommendations are given.

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

• codex_steerA
  4/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint false, destructiveHint true, and idempotentHint false, so the agent knows this modifies state. The description adds context about the 'currently active turn' and the safety mechanism of expectedTurnId to avoid steering the wrong turn. Still, it does not explain failure modes or what happens if no active turn exists, so it provides only moderate additional transparency beyond the annotations.

  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?

  The description is two sentences long, front-loaded with the core action, and every word earns its place. It avoids repetition and includes both the primary function and an important usage hint without excess.

  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?

  Given the tool's simplicity and the presence of detailed annotations, the description is adequate. It covers the key behavior and the critical safety parameter. A minor gap is that it does not explain return behavior or error conditions (e.g., what happens if no active turn exists), but since there is no output schema and the context is straightforward, this is not a significant omission.

  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 coverage is 100%, so the baseline is 3. The description adds meaning for expectedTurnId by explaining its purpose ('prevent steering the wrong turn'), which goes slightly beyond the schema. However, it offers no additional context for prompt or threadId beyond the existing schema descriptions. Overall, the added value is marginal, so a 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool appends guidance to the currently active turn, using the specific verb 'append' and resource 'guidance to active turn'. It also distinguishes itself from creating another turn, differentiating it from siblings like codex_send. The mention of expectedTurnId to prevent steering the wrong turn further clarifies its unique role.

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

  Usage Guidelines4/5

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

  The description implies when to use this tool: when you want to add guidance to an ongoing turn rather than starting a new one. The phrase 'without creating another turn' provides an exclusion, and the instruction to supply expectedTurnId when available gives practical guidance. However, it does not explicitly name alternative tools, so it falls short of a 5.

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

• codex_sendA
  4.1/5.0
  Behavior3/5

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

  Annotations already indicate destructive and open-world behavior, so the description doesn't need to repeat those. However, it adds only a state constraint ('no turn active') without explaining what 'authorized' means, potential side effects like command execution, or how approval flow (given sibling codex_resolve_approval) interacts. Neutral but somewhat thin.

  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, no fluff, front-loaded with action and usage. Every word earns its place and is highly scannable.

  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?

  While purpose and usage are clear, the tool has 8 parameters and no output schema. The description doesn't explain what the function returns, how to handle approval requests, or what distinguishes an 'authorized thread'. Sibling tools like codex_wait and codex_resolve_approval imply a larger workflow, but this description alone leaves some gaps for an agent to infer.

  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 100%, so the schema fully documents all 8 parameters. The description adds no parameter-level detail beyond what the schema already provides, which is acceptable given the baseline of 3.

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

  Purpose5/5

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

  The description uses specific verbs ('Resume', 'start a new turn') with a clear resource ('Codex thread'), and differentiates itself from the sibling tool codex_steer by explicitly stating its scope. It clearly states what the tool does and when it applies.

  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?

  The description explicitly states when to use this tool ('only when no turn is active') and names the alternative for the opposite case ('use codex_steer for an in-flight turn'). This is exactly the kind of direct usage guidance needed.

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

• codex_list_approvalsA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnly and non-destructive behavior. The description adds context that unsupported request types remain visible and specifies which types this release resolves, going beyond annotations. No contradiction.

  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 concise sentences: the first states the primary action, the second adds scope clarification. No waste, information is front-loaded.

  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?

  For a simple list tool with good annotations and full schema coverage, the description covers the operation and adds useful context about supported versus unsupported request types. It does not specify the return format, but no output schema exists, so the description is adequate.

  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?

  The only parameter, threadId, is fully documented in the schema as 'Optional authorized thread filter.' The description adds no further parameter semantics, so the schema carries the weight.

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

  Purpose5/5

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

  The description uses a specific verb ('List') and resource ('pending app-server requests'), clearly distinguishing it from siblings like codex_resolve_approval and codex_list_threads. The title corroborates this.

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

  Usage Guidelines4/5

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

  It clearly provides the context for when to use the tool (listing pending approvals). However, it does not explicitly mention alternatives or exclusions, so it does not achieve a 5.

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

• codex_list_threadsA
  4.2/5.0
  Behavior4/5

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

  Annotations already cover read-only and idempotent safety, so the description adds value by revealing the filtering behavior based on CODEX_ALLOWED_ROOTS and the 'persisted' qualifier. This goes beyond what annotations provide and gives important behavioral context for an agent.

  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?

  The description is two concise sentences. The first sentence states the primary action and scope, and the second clarifies a key behavioral constraint. No unnecessary words or repetition.

  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?

  For a simple listing tool with no output schema, the description covers the essential purpose and a key constraint. Combined with the schema and annotations, it provides sufficient context to use the tool, though it could mention pagination or return format explicitly.

  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?

  The description does not elaborate on any parameters. However, schema descriptions cover 3 of 4 parameters (cwd, cursor, searchTerm), and the remaining limit parameter has min/max constraints. With 75% schema coverage, the description's lack of parameter details is acceptable but not outstanding.

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

  Purpose5/5

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

  The description uses a specific verb ('List') with a clear resource ('persisted Codex threads') and a scoping constraint (working directories inside CODEX_ALLOWED_ROOTS). This clearly distinguishes it from sibling tools like codex_read_thread (which reads a single thread) and codex_list_approvals.

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

  Usage Guidelines4/5

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

  The description implies usage by stating the tool lists threads and filters by allowed roots. It gives clear context (listing function) but does not explicitly name alternative tools or exclusions. The mention that results outside allowed roots are filtered provides actionable guidance about when this tool is appropriate.

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

• codex_startA
  4.2/5.0
  Behavior4/5

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

  The description adds behavioral context beyond annotations: it returns threadId, turnId, and an event cursor, and clarifies that the turn begins immediately in an allowed local repository. Annotations already mark it as destructive and open-world, so no contradiction exists. It doesn't elaborate on approval or sandbox behavior, but those are covered by schema and annotations.

  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 concise sentences convey purpose, behavior, and return value without repetition. Every clause earns its place: it names the resource, the immediate action, the allowed scope, and the downstream tools that consume the return values.

  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?

  Given no output schema, the description appropriately explains the return values. It also contextualizes the tool as a starting point for a thread lifecycle. It doesn't explicitly state that execution is asynchronous or that the returned IDs are needed for later calls, but those are strongly implied by the mention of the event cursor. The tool's complexity is well handled overall.

  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 100%, so the schema documents all parameters well. The description only adds 'allowed local repository' context that aligns with cwd, and mentions the return cursor, but doesn't add new details about parameters like model, effort, sandboxMode, etc. This meets the baseline for high schema coverage.

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

  Purpose5/5

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

  The description clearly states the action ('Start a new Codex app-server thread'), the resource ('Codex app-server thread'), and the immediate behavior ('begin a turn in an allowed local repository'). It also distinguishes this from sibling tools by explicitly returning an event cursor for codex_wait or codex_status, signaling this is the entry point for new threads.

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

  Usage Guidelines4/5

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

  It explains what this tool does and implies its role relative to siblings by referencing post-start tools (codex_wait, codex_status). It doesn't explicitly say when not to use it or name alternatives for existing threads, but the context of 'new' thread is clear. The return cursor guidance helps the agent know how to follow up.

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

• codex_waitA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint and idempotentHint, so behavioral disclosure of safety is covered. The description adds valuable context about long-polling semantics, terminal states, timeout behavior, and the eventCursor continuation mechanism, which goes beyond annotations.

  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?

  The description is two sentences, front-loaded with the action and outcome, and every phrase adds value. No wasted words.

  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?

  For a simple polling tool, the description covers purpose, terminal conditions, timeout, and continuation with eventCursor. There is no output schema, but the description gives enough hint about the return value. It could mention what events contain or how to handle approval requests, but those may be covered by sibling tools like codex_resolve_approval.

  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 coverage is 50%: threadId and afterSequence are described, while maxEvents and timeoutMs are not. The description mentions 'timeout' and 'eventCursor', providing partial meaning for timeoutMs and afterSequence, but does not fully compensate for the undocumented parameters. Parameter names are mostly self-explanatory, but a clearer mapping would help.

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

  Purpose5/5

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

  The description clearly states the tool's function with a specific verb ('Long-poll') and a specific resource ('an active turn'), listing all terminal states: completes, fails, requests approval, interrupted, or timeout. This distinguishes it from siblings like codex_status (which likely polls status) and codex_read_thread (which reads a thread).

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

  Usage Guidelines4/5

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

  The description implies when to use this tool: after an active turn exists, to wait for completion or interruption, and to continue using the returned eventCursor. It does not explicitly name alternatives or exclusions, but the context is clear enough that an agent can infer it should be used instead of codex_status for blocking waits.

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