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.

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

Annotations already declare readOnly/idempotent/no open world, so safety is covered; the description adds real value beyond them by listing terminal states (completed, failed, interrupted, connectionLost), warning that partial output can return before completion, and noting persisted per-turn model/effort may be unavailable with threadDefaults reported separately.

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?

Five packed sentences, front-loaded with the core read action and followed by polling, cursor, and streaming guidance. Dense but every sentence carries operational information; the final sentence about persisted model/effort is slightly tangential to invoking the tool.

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?

No output schema, so the description must convey return behavior, and it does: message chunks, cursors, partial versus completed output, terminal states. The main remaining gap is the limit parameter and the shape of returned content, which keeps it from being fully complete.

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%, so the description must carry parameter meaning. It explains waitMs (polling up to 20000), cursor (follow nextCursor for chunks), and turnId (specified turn), but says nothing about limit or what discussionId identifies, leaving part of the 5-parameter surface 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?

States a specific verb and resource: 'Read the latest or specified turn' of a discussion. It is clearly a read/retrieval tool, distinguishable from the write-oriented siblings (discussion_start, discussion_reply) and from models_list, though it never names a sibling explicitly.

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?

Gives actionable operating guidance: poll with waitMs up to 20000, follow nextCursor for more chunks, and during generation re-read without a cursor for updated text. It stops short of stating when to prefer this over alternatives or prerequisites (e.g., needing an existing discussionId from discussion_start).

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

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

Goes well beyond the annotations by disclosing async semantics ('Returns immediately'), the required prior state transition (finishing or cancelling the active turn), and inheritance rules for optional arguments. This is real behavioral context an agent cannot infer from readOnlyHint/openWorldHint/idempotentHint.

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?

Five short sentences, front-loaded with the action and the blocking prerequisite, then the argument-inheritance rule, then the return/next-step pointer. Telegraphic but every clause carries decision-relevant information.

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?

No output schema exists, and the description covers return behavior itself ('Returns immediately; use discussion_read'). Combined with the preconditions and inheritance rules, nothing an agent needs to invoke it correctly is missing.

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 coverage is 50% (model and effort documented, message and discussionId not), so the description must compensate. It adds genuine semantics the schema lacks: model and effort are re-selectable per reply, omitted choices inherit, and changing model without effort falls back to the new model default.

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?

States a specific verb ('Send a follow-up, objection or additional evidence') against a specific resource ('an existing discussion'), which cleanly separates it from discussion_start and discussion_read. An agent can classify the tool without opening the schema.

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?

Explicit prerequisite ('Finish or cancel the active turn first') and an explicit alternative for the follow-up read ('use discussion_read'). It doesn't spell out the reply-vs-discussion_start boundary, but 'existing discussion' makes that implicit and unambiguous.

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

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

Adds behavior annotations don't convey: it is asynchronous, returning discussionId and turnId immediately while output must be fetched via discussion_read. The adjective 'read-only' describes the Codex session but could be misread against readOnlyHint=false, since the call itself creates discussion state; that nuance is not spelled out, which keeps it below a 5.

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?

Four short sentences, front-loaded with the core action, followed by the ordering constraint and the return contract. Dense and free of filler; the only slight cost is that the workflow and return details are packed together without visual separation.

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?

With no output schema, the description usefully states the return shape and the read-back path, which is the key gap for an async tool. It omits practical limits (message size, cost/latency of a turn, lifecycle of the discussion) that an agent would benefit from, but the essential calling contract is present.

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 coverage is 75%, with cwd, model and effort already documented in the schema; the description mostly echoes those (absolute cwd, model from models_list). It adds light selection guidance for model/effort but leaves the required 'message' parameter (question plus relevant context) with no schema description and only a brief mention here.

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?

States a specific verb and resource ('Start an independent read-only Codex conversation') and immediately tells the agent how it differs from the reading sibling ('read output using discussion_read'). It is clear this opens a new discussion rather than continuing one (discussion_reply) without needing to open any schema.

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?

Gives an explicit prerequisite sequence ('Call models_list first, then select model and effort for the question complexity') and names the follow-up tool for retrieving results. It does not state when NOT to use it (e.g., when to continue an existing thread with discussion_reply instead), so it falls short of full alternative routing.

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

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

Goes beyond the readOnly/idempotent annotations by stating 'No inference is run' (no cost or side effects) and warning that 'catalog entries do not guarantee account/provider inference access' — a real interpretation caveat an agent would otherwise get wrong. It stops short of describing catalog size, staleness, or caching behavior.

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?

Three tight sentences with the action directive front-loaded and zero filler. Every sentence carries a distinct fact: what to do, what is returned, and what the result does not imply.

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?

With no output schema, the description compensates by enumerating the returned catalog fields, and it adds the no-inference and access-caveat facts. For a single-optional-parameter read-only tool, nothing an agent needs to call it correctly is missing.

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 100% and the single optional parameter includeHidden is fully documented in the schema. The description adds nothing about it, so the baseline 3 applies.

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?

States a specific verb and resource ('fetch the current Codex model catalog') and enumerates the payload (descriptions, default model, default effort, supported effort descriptions). Sibling tools are all discussion_* operations, so no differentiation is needed and none is confused.

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?

'Call first' gives an explicit sequencing directive that tells the agent to invoke this before model selection. It lacks an explicit 'do not use when' clause, but there is no competing sibling that would need an exclusion.

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