Interrupt a Codex turn

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

Beyond annotations, the description discloses important behavior: an accepted cancellation request is distinct from the final interrupted status, confirmation requires discussion_read, and completed older turns are returned without interrupting newer work. This gives useful async/state context for a mutation-style operation.

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 three tight sentences with the action front-loaded. Each sentence adds distinct value: the action, the async confirmation behavior, and the older-turn edge case.

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?

The behavioral nuances are well covered, but with 0% schema parameter coverage and no output schema, the description should do more to explain the required identifiers and what an accepted response looks like. It is usable but leaves meaningful gaps for invocation.

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?

Schema description coverage is 0%, and the description only refers to 'the specified turn' without explaining discussionId, turnId formats, or how the two parameters relate. It gives partial meaning to turnId but leaves the required discussionId undocumented.

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 states a specific verb and resource: request interruption of exactly the specified turn. It also distinguishes the confirmation path by naming discussion_read, so an agent can tell what this tool does relative to its siblings.

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?

Usage is implied by 'Request interruption of exactly the specified turn,' and the description says to confirm with discussion_read. However, it does not explicitly state when to use this versus alternatives or when cancellation should not be requested.

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