list_comments
The conversation on one artefact, oldest first, each comment with its author, its audience, the people it names, the thread it answers and whether the thread is resolved; the open comments only for a guest token.
Return the comments on one artefact, oldest first: each with its author's name, the words as sanitised HTML, whether it is internal, the ids of the people it names, the first comment it answers when a reply, and whether and by whom the thread was resolved. Read it before you act on an artefact: the questions, the answers and the decisions taken in the margin are here, and a thread marked resolved tells you the question is settled.
The artefact is named by artefact_type (epic, work-item, requirement, business-rule, use-case, raid-item, decision, data-entity or glossary-term) and artefact_id. A guest token reads the open comments only, and only on the agreed record.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same actions as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Annotations
It reads and never changes anything.
Arguments
artefact_type*stringThe artefact's type.
epicwork-itemrequirementbusiness-ruleuse-caseraid-itemdecisiondata-entityglossary-termbaselinechange-requestartefact_id*stringUUID of the artefact whose comments to list.
What it returns
{ "data": [ { "id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a81", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "artefact_type": "work-item", "artefact_id": "0f9e8d7c-6b5a-4c3d-8e2f-1a0b9c8d7e6f", "parent_id": null, "author_id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f", "author_name": "Jane Doe", "body": "<p>Does the voucher apply before or after the loyalty discount? @Sam Lee</p>", "internal": false, "mentions": ["d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70"], "resolved": false, "resolved_at": null, "resolved_by": null, "edited_at": null, "created_at": "2026-10-28T09:20:00+00:00", "updated_at": "2026-10-28T09:20:00+00:00" }, { "id": "f6a7b8c9-d0e1-4f2a-9b3c-4d5e6f7a8b92", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "artefact_type": "work-item", "artefact_id": "0f9e8d7c-6b5a-4c3d-8e2f-1a0b9c8d7e6f", "parent_id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a81", "author_id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70", "author_name": "Sam Lee", "body": "<p>After it: CRM-BR-7 says the voucher comes last.</p>", "internal": false, "mentions": [], "resolved": false, "resolved_at": null, "resolved_by": null, "edited_at": null, "created_at": "2026-10-28T10:05:00+00:00", "updated_at": "2026-10-28T10:05:00+00:00" } ]}How it fails
VALIDATION_FAILEDartefact_type is not one of the nine; the response lists them.
RESOURCE_NOT_FOUNDunknown artefact_id, an artefact of a project outside the token's scope or the person's visibility, or an artefact a guest token may not read.
FORBIDDENthe token holder's role on the project does not carry comment:view-any.
TOKEN_MISSING_ABILITYtoken lacks comment:view-any.
How is this guide?
Last updated on