add_comment

Add a Markdown comment or a nested reply using parentId. Top-level comments have depth zero; replies support at most three nested levels. Mention with @email, @[Name](user:UUID), or mentionIds. Reuse idempotencyKey on retries.

Workflow

Access and behavior

Write or Administrator OAuth consent and a member/administrator team role are required. Tools are listed and callable only when the current grant and role permit them. Body is nonempty and at most 10,000 characters. Supports @email, user:UUID links and mentionIds. Root depth is zero; a fourth reply level returns 400 COMMENT_DEPTH_LIMIT. Comments advance board activity but do not produce activity-table rows.

Arguments

Argument	Required	Type or meaning
`taskId`	Yes	Task UUID, not its human identifier such as ENG-1.
`parentId`	No	Same-task parent comment UUID. When posting, omit it to create a top-level comment. When listing, use root for top-level comments or omit it to include every level.
`body`	Yes	string
`mentionIds`	No	array
`idempotencyKey`	No	One logical mutation key, reused unchanged on retries. MCP forwards it as the REST Idempotency-Key header.

Complete input schema

{
  "type": "object",
  "properties": {
    "taskId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "parentId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "body": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10000
    },
    "mentionIds": {
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      }
    },
    "idempotencyKey": {
      "type": "string",
      "minLength": 8,
      "maxLength": 128
    }
  },
  "required": ["taskId", "body"],
  "additionalProperties": false
}

Example call

The client initializes the MCP connection before sending this JSON-RPC call. Example records are fictional.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "add_comment",
    "arguments": {
      "taskId": "22222222-2222-4222-8222-222222222222",
      "parentId": "33333333-3333-4333-8333-333333333333",
      "body": "The isolated restore passed.",
      "idempotencyKey": "restore-check-reply-001"
    }
  }
}

Example result

Mill returns this object in structuredContent and normally a JSON text content block (large responses may shorten the text block). A tool failure sets isError; never treat an error as a completed mutation.

{
  "comment": {
    "id": "88888888-8888-4888-8888-888888888888",
    "taskId": "22222222-2222-4222-8222-222222222222",
    "parentId": "33333333-3333-4333-8333-333333333333",
    "replyCount": 0,
    "authorId": "66666666-6666-4666-8666-666666666666",
    "authorKind": "human",
    "authorName": "Alex Morgan",
    "body": "The isolated restore passed.",
    "version": 1,
    "createdAt": "2027-01-18T09:30:00.000Z",
    "updatedAt": "2027-01-18T09:30:00.000Z"
  }
}

HTTP operation · Connect an MCP client · Request conventions

Connect a client

MCP reference

API Reference

add_comment

Workflow

Access and behavior

Arguments

Example call

Example result

​Workflow

​Access and behavior

​Arguments

​Example call

​Example result

​Related reference

Workflow

Access and behavior

Arguments

Example call

Example result

Related reference