Skip to main content
Glama

list_comments

Read-onlyIdempotent

Access and retrieve comments associated with a task ID. View comment history chronologically or by newest first, handling pagination and full data extraction.

Instructions

List comments newest first (limit default 10), with pagination. Compact fields: id for reply/after, author_name, created_at in UTC to the minute, entire ordinary body. Known automation prefixes get one-line summaries; include_auto=true restores their bodies. full=true restores non-capability REST fields. after accepts a comment UUID or RFC3339 timestamp and returns only newer comments (exclusive), paginated within that delta; unknown IDs are refused. order=asc gives chronological reading.

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": {
      "task_id": "<task_id>"
    },
    "name": "list_comments"
  }
}

Input Schema

NameRequiredDescriptionDefault
fullNoReturn complete comment objects (author_id, task_id, url, metadata, parent_comment_id, updated_at, uncut bodies) instead of the compact view.
pageNo1-based page number. Omit for the first page; use with `has_more`/`total_pages` in the response to read the rest of a thread.
afterNoExclusive comment UUID or RFC3339 timestamp; page/limit apply to the newer-comments delta. Unknown IDs are refused.
limitNoMax comments to return (default 10, newest first; ordinary bodies are complete).
orderNoSort direction: desc (default — NEWEST comments first, so limit=2 gives the LAST two comments) or asc (oldest first — chronological reading from the start of the thread). An invalid value is REFUSED by the API; an explicitly empty value is refused locally (at the API boundary it is indistinguishable from absent) — neither is silently treated as asc.
task_idYesTask ID.
include_autoNoReturn complete automation bodies in compact mode.
include_internalNoInclude internal (agent-only) comments.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.1

TDQS

A3.5/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral detail beyond that: automation prefixes are collapsed to one-line summaries unless include_auto=true, full=true restores non-capability REST fields, after is exclusive, and unknown IDs / invalid order values are refused rather than silently coerced. Missing: nothing about include_internal's default-on behavior or what the paginated response envelope contains.

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

Conciseness4/5

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

Front-loaded with the core behavior and each clause covers a distinct mode or edge case, so there is little waste. The semicolon-chained, parenthetical style makes it dense and slightly 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.

Completeness4/5

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

For an 8-parameter read tool with no output schema, the description covers the important complexity: compact vs full projection, automation stripping, delta pagination via after, ordering, and refusal behavior on bad input. Gaps are minor – include_internal is never mentioned and the response shape is only gestured at ('with pagination').

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

Parameters3/5

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

Schema description coverage is 100%, so every parameter is already documented and the baseline is 3. The description reinforces a few points (default limit 10, newest-first, after accepting UUID or RFC3339 and being exclusive, unknown IDs refused) but mostly restates schema content rather than adding new semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource plus scope: 'List comments newest first (limit default 10), with pagination.' It distinguishes the compact view from the full view and thin automation summaries, so an agent knows exactly what comes back. It never names the sibling it is not (list_doc_comments), so the task-vs-doc distinction is left to the task_id parameter.

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 context is implied rather than declared: 'order=asc gives chronological reading' and 'after ... returns only newer comments' tell an agent which mode fits which reading pattern. There is no explicit when-to-use/when-not or routing to alternatives such as list_doc_comments or get_task.

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