Read Codex output or wait for progress

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.