ODocs.co

List Comments

list-comments

Read-only

Returns the comment threads people or agents left on an ODocs.co document. Each thread has an id, the quoted text it refers to, whether it is resolved, and its replies. The default result is a readable plaintext list after a frontmatter (id, commentCount, openCommentCount, note); format:"json" returns the structured array, which also carries contextBefore / contextAfter around the quote, approximateLineNumber, anchored (true when that line is where the comment is attached, false when it is only where the quote text first appears), anchorState ("attached" or "detached": the text was changed or removed; anchored and orphaned mirror it), currentText (when attached, the text the comment sits on now, which can differ from the original quote) and occurrence (with the quote as find/anchor in patch-document it matches the commented copy; null if unknown). The text tags carry the same with placement="anchor" (plus occurrence) or "text", and state="detached" for a detached thread. The note (that comments are written by anyone with the link) is the frontmatter's note field in the text view; a json result carries it as a second text item.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "id": "<id>"
    },
    "name": "list-comments"
  }
}

Input Schema

Name	Required	Description
`id`	Yes	Document ID
`format`	No	Response format: 'text' (default) is a readable .txt-style view; 'json' is the structured object.
`includeResolved`	No	Include resolved threads too (default true); false returns open threads only.

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 13, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Annotations only cover the safety profile (readOnly, non-destructive, non-open-world), and the description adds substantial behavior beyond them: the default plaintext <comment> layout, the frontmatter fields (id, commentCount, openCommentCount, note), the extra fields present only in json, the anchored/detached anchorState semantics, and the fact that the note is surfaced as a second text item in json. This is exactly the context annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and format choice are front-loaded, which is good, but the middle is a single sprawling sentence enumerating six-plus JSON fields, and the note is described twice. The density is justified by the absence of an output schema, yet the run-on phrasing makes it harder to scan than it needs to be.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and only three simple parameters, the description carries the return-shape burden and does so thoroughly: default text view, JSON view, anchoring semantics, and the edge case of null occurrence. Nothing an agent needs to read or route these results is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline would be 3, but the description goes further by spelling out what format:"json" actually changes in the payload and by tying occurrence/quote semantics to patch-document. It never explains includeResolved's behavior (open-only filtering), which the schema covers but the description could have reinforced.

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?

Opens with a concrete verb and resource: 'Returns the comment threads people or agents left on an ODocs.co document.' An agent immediately knows this is a read of comment threads for a single document, and the verb/resource do not overlap with the sibling mutation tools (create-comment, reply-to-comment, resolve-comment) or document readers.

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?

Usage is only implied: the description explains the two response formats and what each contains, which helps an agent pick 'text' vs 'json', but it never states when to call this versus get-document or when a thread listing is the wrong tool. No exclusions, prerequisites, or pagination guidance are given.

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

All ODocs.co tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?