Comments are threads anchored to ranges of text. They render as chips beside
the page, survive the DOCX round trip, and are readable and writable from the
host.
Reading threads
Each thread carries its root comment, replies, the anchor it points at, and any
suggestions related to it:
Writing
Comment bodies are markdown. Every method returns the new comment’s ID, or
null when the target no longer exists.
Mentions are supported as an optional second argument on each of these.
Panel and selection
There is no built-in comments button — chips render inline, and the panel opens
wherever your own UI decides. See chrome.
One affordance is built in: selecting text in an editable document shows a
small insert-comment chip in the page margin, and clicking it starts a draft on
that selection — the same thing addCommentAtSelection does. It stays out of
the way of an in-progress draft, of read-only documents, and of selections that
already carry a thread.
A comment can be tied to the suggestions it discusses, which lets a reviewer
resolve the conversation and the edit in one action:
An agent reviewing a document should usually comment rather than rewrite.
The leave_comment tool is the agent-facing equivalent of the above:
The other anchor forms are { start_text, end_text } for a range too long to
quote in full, and { whole_block: true } for structural or empty content.
Replying to a thread is the same tool with no anchor:
leave_comment anchors to text the agent has actually read. Call a read tool
such as read_blocks_from_index first, or the anchor text will not resolve
to a range in the loaded context.
<comment-thread> elements in the HTML read tools
return, so an agent can see what has already been said. A new thread that
overlaps an existing unresolved one is rejected: the agent should reply to that
thread instead of repeating the point beside it. When the overlap is deliberate
and the point is genuinely different, list the overlapping IDs in
acknowledge_existing_thread_ids to confirm it read them.
For products where each thread is its own conversation with the model, the
comments controller runs an agent scoped to one thread:
getState(threadId) returns that thread’s run state, and subscribe()
publishes a map of every in-flight run, so a thread list can show per-thread
progress. 
