---
title: "Add Comment"
description: "Add a comment to a media file."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.speakai.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Comment

Use the Speak AI MCP server tool `add_comment` to add a comment to a media file.

## What does it do?

Add a comment to a media file. Three kinds: on the whole file (no quote or range),
on words in the transcript (quote, or range plus expectedTranscriptRevision, exactly
as in `apply_label`), or a reply to a thread (parentId, with no span of its own).
Replies go one level deep, so parentId must be a thread's first comment. A reply
notifies the thread's starter in Speak, unless the starter wrote the reply.
mediaLabelId links the comment to a labelled span on this file. A 409 that says the
transcript changed means someone edited it after your revision was read: read the
transcript again (`get_transcript`) and retry with the new range or quote. Nothing
was saved. Requires the comments create permission (every member by default). The
change is recorded in your Speak Notifications under Comment (type comment).

## Parameters

`add_comment` takes 8 parameters, 2 of them required.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `mediaId` | string | Yes | Media id |
| `body` | string | Yes | Comment text (1 to 5000 characters) |
| `parentId` | string | No | commentId of the thread's first comment, to reply to it |
| `mediaLabelId` | string | No | mediaLabelId from `list_media_labels` to link the comment to |
| `range` | object | No | Exact word range. Needs expectedTranscriptRevision. Prefer quote unless you already hold word indices. Word indices count the words of `get_transcript`'s insight.transcript in order, from 0: for each sentence, the words of its entities[].text when it has entities, otherwise its text split on spaces; tokens that are only punctuation are not counted. |
| `expectedTranscriptRevision` | number | No | transcriptRevision the range was read at (returned by `get_transcript`, `list_media_labels` and `list_media_comments`). Required with range. Optional with quote: the quote is found in the current transcript, and a revision you pass makes the call fail with 409 if the transcript changed since you read it. |
| `quote` | string | No | Words copied from the transcript, used instead of range. Matching ignores case and leading or trailing punctuation, and must cover whole words in order. If the words appear more than once, pass occurrence. |
| `occurrence` | number | No | Which match of quote to use (1 = first) when the quote appears more than once |

## Behaviour

The Speak AI MCP server publishes these behaviour hints for `add_comment`.

- Can change data in your workspace.
- Does not delete or overwrite existing data.
- Repeating an identical call can have an extra effect.
- Stays inside Speak AI. Does not reach other systems.

## Related

- [Labels & comments](/mcp/tools/labels-comments/) lists the rest of the Labels &
  comments category.
- [Tool reference](/mcp/tools/) lists every Speak AI MCP server tool.
- [MCP server](/mcp/) covers setup, supported clients, and what agents can do once
  connected.

Source: https://docs.speakai.co/mcp/tools/labels-comments/add_comment/index.mdx