comment_on_item
Post a comment on one artefact as the person the token acts as, in Markdown, under a first comment when answering; the people named and the followers are told and comment.created goes out.
Post a comment on one artefact of a project: project_id, artefact_type (epic, work-item, requirement, business-rule, use-case, raid-item, decision, data-entity or glossary-term), artefact_id, body in Markdown (turned into the same sanitised HTML the editor writes), an optional parent_id to answer the first comment of a thread, and internal to keep the comment from client guests, which needs comment:internal. Name people with @ and their full name to tell them; the artefact's followers are told either way, and the person the token acts as becomes a follower.
Comment when you have a question, a finding or a decision to record against the artefact: before you move a status, after you link a pull request, when a criterion cannot be verified. A comment is a claim on the record, so say what you did and why rather than what you plan. Editing, resolving and deleting comments stays with people: correct yourself with a new comment.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Fires one event
Delivered to every endpoint subscribed to it once the change is made.
Arguments
project_id*stringUUID of the project the artefact belongs to.
artefact_type*stringThe artefact's type.
epicwork-itemrequirementbusiness-ruleuse-caseraid-itemdecisiondata-entityglossary-termbaselinechange-requestartefact_id*stringUUID of the artefact to comment on.
body*stringThe comment, in Markdown; up to 20,000 characters.
internalbooleanoptionalKeep the comment from client guests; needs comment:internal. False by default.
parent_idstringoptionalUUID of the first comment of the thread to answer; omit for a new thread.
What it returns
{ "data": { "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><strong>Confirmed</strong> by CRM-BR-7: 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_FAILEDa missing or unknown type or id, an empty body or one over 20,000 characters, or a parent_id that is missing, a reply itself or on another artefact.
RESOURCE_NOT_FOUNDunknown project_id, or an artefact the token may not see.
FORBIDDENthe token holder's role on the project does not carry comment:create; a guest token on a project whose guests may not comment; internal without comment:internal.
TOKEN_MISSING_ABILITYtoken lacks comment:create.
How is this guide?
Last updated on