---
title: Comments
description: Optional. Comments on research pages. 2 tools.
group: comments
tools: [comments.list, comments.comment]
source: [packages/agents/src/tools/features.ts]
generated: true
---

> Roadstar docs for agents. Every page, as markdown: https://docs.roadstar.app/llms.txt

Optional research tools: comments on [research pages](/tools/pages/). What an agent writes shows as Roadstar.

## How to use it

What `find_tools` sends with these tools, word for word:

> Comments on pages. What an agent writes shows as Roadstar, like an @roadstar reply.

## Tools

| Tool | What it does | Owner's yes |
| --- | --- | --- |
| [comments.list](#list) | A page's comments | No |
| [comments.comment](#comment) | Comment on a page, or reply to a comment | No |

## list

`comments.list` · A page's comments.

**Owner's yes:** No. Nothing of the owner's changes.

| Input | Type | Required | Limits |
| --- | --- | --- | --- |
| `pageId` | id | yes |  |

Returns:

```ts
CommentWindowResult
```

## comment

`comments.comment` · Comment on a page, or reply to a comment.

**Owner's yes:** No. It makes something new.\
**Your work:** listed on Home.

| Input | Type | Required | Limits |
| --- | --- | --- | --- |
| `pageId` | id | yes |  |
| `text` | text | yes | 1–10,000 characters |
| `parentId` | id | no |  |

Returns:

```ts
{
  commentId: string;
}
```

## Types

Named types in the results above.

```ts
type CommentWindowResult = {
  comments: PublicCommentPage;
}

type PublicCommentPage = {
  items: PublicCommentItem[];
  nextCursor: string | null;
}

type PublicCommentItem = {
  assistant?: CommentAssistant | null;
  author: PublicCommentAuthor;
  bodyMarkdown: string | null;
  canEdit: boolean;
  canRemove: boolean;
  canReport: boolean;
  children: PublicCommentPage | null;
  createdAt: string;
  directReplyCount: number;
  editedAt: string | null;
  id: string;
  isLiked: boolean;
  likeCount: number;
  parentId: string | null;
  removedAt: string | null;
}

type CommentAssistant = AssistantRequest | AssistantReply | AssistantNote | AssistantAnswer

type PublicCommentAuthor = {
  image: string | null;
  name: string;
  username: string | null;
}

type AssistantRequest = {
  kind: "request";
  status: "done" | "failed" | "working";
  steps: string[];
}

type AssistantReply = {
  full: {
    contents: string;
    markdown: string;
  } | null;
  kind: "reply";
  looked: string[];
  sources: AssistantSource[];
  tag: "holds_up" | "out_of_date" | "disputed" | "no_source" | null;
}

type AssistantNote = {
  kind: "note";
  to: string;
  state: "changed" | "done" | "sent" | "waiting" | "kept";
}

type AssistantAnswer = {
  kind: "answer";
  by: string;
  outcome: "changed" | "done" | "kept";
}

type AssistantSource = {
  date: string | null;
  pageSource: number | null;
  quote: string | null;
  title: string;
  url: string | null;
}
```