# Comments

Read and add comments on a project.

These tools work on a project’s comments, not on the comments left on files. The Soontra app does not show a project’s comment thread at present, so a comment written here is read by other connected apps and scripts, not on the project’s own screen.

### soontra_comments_list

A project's comment thread (author identity is withheld by design).

Scope: `read` · Read-only

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `project_id` | string (uuid) | yes |  |
| `limit` | integer | no | 1 to 50 |

Returns: The project's `comments` (`id`, `body`, `parent_comment_id`, `created_at`, `updated_at`) and their `count`.

- `limit` defaults to 10, maximum 50; newest first, with no paging.

- Author names and ids are never included.

### soontra_comments_create

Comment on a project. Plain text; @mentions by name via mentions_by_name.

Scope: `write` · Writes

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `project_id` | string (uuid) | yes |  |
| `body` | string | yes | 1 to 5000 characters |
| `parent_id` | string (uuid) | no |  |
| `mentions_by_name` | string[] | no | up to 20 items |
| `idempotency_key` | string | no | Unique key for this logical mutation. Reuse only to retry the exact same payload. 1-128 chars: A-Z a-z 0-9 _ . : - |

Returns: The new `comment` with `id`, `body`, `parent_comment_id`, `created_at` and `updated_at`.

- `body` is up to 5,000 characters of plain text.

- Up to 20 names in `mentions_by_name`.

- `parent_id` makes the comment a reply.