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

# list_notes

> フィルタとオプションのキーワードでノートを一覧表示 — 軽量なメタデータのみ

## 概要

`list_notes` はノート探索の軽量な階層です。メタデータ（タイトル、参加者、日付、ソースタイプ）のみを返し、コンテンツを読まずに**どのノートが存在するかを知る**必要があるときに適したツールです。

`query.keyword` が指定されると、結果セットは `recordingStartAt` の降順ではなく、全文検索の関連度（同点の場合は `createdAt` の降順）で並べ替えられます。

**主なユースケース:**

* 「フォルダ X にはどのノートがありますか?」
* 「キーワード Y に一致するノートはどれですか?」（存在の確認のみ）
* 日付範囲でフィルタリングして大きなワークスペースを絞り込む。

**主な特長:**

* [`search_notes`](./search-notes)（深い、ドキュメントを返す）と [`get_note_transcript`](./get-transcript)（生のトランスクリプト）を含む 3 階層モデル。
* 一覧パスでの cursor ベースのページネーション。
* 不完全なノートを自動的に除外します。録音が一度も開始されず、タイトルがデフォルトのプレースホルダのままのノートは、MCP レイヤーで除外されます。

<Tip>
  **トークン効率。** `list_notes` の 1 ページはノートあたり \~50 トークンを返します。`search_notes` 経由でドキュメントを読み込む（ノートあたり \~1,500 トークン）場合や、`get_note_transcript` 経由でトランスクリプトを読み込む（ノートあたり \~3,000–5,000 トークン）場合と比べて、これは手元に何があるかを見つける最も安価な方法です。
</Tip>

## パラメータ

| Parameter              | Type   | Required | Description                                                                                                         |
| ---------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `query.keyword`        | string | Optional | オプションのキーワード。指定すると全文検索の関連度で並べ替えます。                                                                                   |
| `workspaceGuid`        | string | Optional | 特定のワークスペースを対象にします（`list_workspaces` から取得）。省略するとアクセス可能なすべてのワークスペースを検索します。workspace-scoped key は自動的に自身のワークスペースを検索します。 |
| `pagination.cursor`    | string | Optional | 前回の `nextCursor` から得た cursor。                                                                                       |
| `pagination.size`      | number | Optional | 1 ページあたりの結果数（デフォルト `20`、最大 `100`）。                                                                                  |
| `filter.folderId`      | string | Optional | フォルダに限定（再帰的 — 子孫フォルダを含みます）。                                                                                         |
| `filter.createdAtFrom` | string | Optional | ISO 8601 形式の日時。`createdAt` の下限（その値を含む）。                                                                             |
| `filter.createdAtTo`   | string | Optional | ISO 8601 形式の日時。`createdAt` の上限（その値を含まない）。                                                                           |

### query.keyword (optional)

一覧表示を関連度モードに切り替えます。ヒットは、ノートのタイトルと段落のコンテンツに対するサーバーの全文インデックスでスコアリングされます。キーワードが指定されると `nextCursor` は `null` になります（深い検索インデックスは安定した一覧 cursor を持ちません）。

キーワード検索は user-scoped と workspace-scoped のどちらの API key でも機能します。`workspaceGuid` を省略するとアクセス可能なすべてのワークスペースを検索します（workspace-scoped key は自動的に自身のワークスペースを検索します）。特定のワークスペースを対象にするには明示的な `workspaceGuid` を渡してください。

### workspaceGuid (optional)

特定のワークスペースを対象にします。利用可能な GUID は `list_workspaces` から取得してください。省略するとアクセス可能なすべてのワークスペースを検索します。workspace-scoped key は自動的に自身のワークスペースを検索します。

### filter.folderId (optional)

指定すると、一覧表示はフォルダとそのすべての子孫に再帰的に限定されます。フォルダへのアクセスはサーバー側で認可されます。アクセス権のない folderId を渡すと `404` を返します。

### filter.createdAtFrom / filter.createdAtTo (optional)

`createdAt` に対する半開区間 `[from, to)` の範囲フィルタです。どちらもタイムゾーン付きの ISO 8601 形式の日時を受け付けます（例: `2026-04-01T00:00:00Z`）。

### pagination (optional)

`{ cursor, size }`。デフォルト `size: 20`、最大 `100`。ページをたどるには、前回のレスポンスの `nextCursor` を使用してください。

## レスポンス形式

### 成功レスポンス

```json theme={"system"}
{
  "content": [
    {
      "noteGuid": "abc-123-def",
      "title": "OKR Q2 Planning",
      "webUrl": "https://platform.tiro.ooo/notes/abc-123-def",
      "createdAt": "2026-04-15T10:00:00Z",
      "updatedAt": "2026-04-15T11:30:00Z",
      "recordingDurationSeconds": 3625,
      "sourceType": "live-voice",
      "participants": [
        { "name": "Alice Kim", "email": "alice@example.com" },
        { "name": "Bob Park", "email": null }
      ]
    }
  ],
  "notes": [],
  "total": 137,
  "totalSize": 1,
  "nextCursor": "eyJvZmZzZXQiOjUwfQ=="
}
```

<Note>
  レスポンスは各ノートを `content`（推奨）と `notes`（レガシーエイリアス）の両方に含みます。クライアントが好む方を選び、もう一方は無視してください。
</Note>

**フィールドの説明:**

| Field                                | Type           | Description                                                                          |
| ------------------------------------ | -------------- | ------------------------------------------------------------------------------------ |
| `content[]`                          | array          | ノート（推奨フィールド）。                                                                        |
| `content[].noteGuid`                 | string         | ノートの一意な識別子。`search_notes`、`get_note_transcript` などに渡します。                             |
| `content[].title`                    | string         | ノートのタイトル。                                                                            |
| `content[].webUrl`                   | string         | Tiro Web アプリ内のノートへの直接リンク。                                                            |
| `content[].createdAt`                | string         | ISO 8601 形式の作成タイムスタンプ。                                                               |
| `content[].updatedAt`                | string         | ISO 8601 形式の最終更新タイムスタンプ。                                                             |
| `content[].recordingDurationSeconds` | number         | 録音の長さ（秒）（録音以外のソースでは `0`）。                                                            |
| `content[].sourceType`               | string         | `live-voice`、`recording`、`text`、`video`、`webpage`、`offline-mode`、`onboarding` のいずれか。 |
| `content[].participants[]`           | array          | 参加者ごとの `{ name, email }`。いずれも `null` の場合があります。                                       |
| `total`                              | number         | バックエンドのフィルタ前の件数。                                                                     |
| `totalSize`                          | number         | MCP 側の不完全ノートフィルタ後の件数（`total` より小さくなることがあります）。                                        |
| `nextCursor`                         | string \| null | 次のページ用の cursor。これ以上結果がない場合やキーワード検索が有効な場合は `null`。                                    |

<Warning>
  **ページネーションのヒント。** `total` と `totalSize` は食い違うことがあります。`total` がカウントした不完全なノートは `totalSize` より前に除外されます。`while (totalSize < total)` でループせず、代わりに `nextCursor` でページをたどってください。
</Warning>

## 使用例

### 例 1: 特定のフォルダ内のノート

**リクエスト:**

```json theme={"system"}
{
  "filter": {
    "folderId": "455765"
  }
}
```

フォルダ `455765` とその子孫にある、最新の完全なノート 20 件を返します。

### 例 2: 日付範囲による最近のノート

**リクエスト:**

```json theme={"system"}
{
  "filter": {
    "createdAtFrom": "2026-04-01T00:00:00Z",
    "createdAtTo": "2026-05-01T00:00:00Z"
  },
  "pagination": {
    "size": 50
  }
}
```

### 例 3: キーワードによる一覧（関連度順）

**リクエスト:**

```json theme={"system"}
{
  "query": {
    "keyword": "OKR"
  },
  "pagination": {
    "size": 30
  }
}
```

タイトルまたは段落が `OKR` に一致するノートを、関連度順で返します。レスポンスの `nextCursor` は `null` です。さらに必要な場合は、同じキーワードとより大きい `size` で再度呼び出してください。

### 例 4: ページネーションによる閲覧

**最初のページ:**

```json theme={"system"}
{
  "pagination": { "size": 50 }
}
```

**次のページ（前回のレスポンスの `nextCursor` を使用）:**

```json theme={"system"}
{
  "pagination": {
    "size": 50,
    "cursor": "eyJvZmZzZXQiOjUwfQ=="
  }
}
```

## どの階層を使うか

<AccordionGroup>
  <Accordion title="Use list_notes when…">
    フォルダ・日付・キーワードの有無で、**どのノートが存在するかを知る**必要があるとき。メタデータのみを返し、ノートあたり \~50 トークンです。最も安価な探索ツールです。
  </Accordion>

  <Accordion title="Use search_notes when…">
    **トピックの背後にあるコンテキスト**（決定事項、アクションアイテム、チームの結論）を理解する必要があるとき。一致したノートと、その主要ドキュメント（ワンページャー、カスタム）を返します。ノートあたり \~1,500 トークンです。

    LLM がユーザーの質問に答えるためにドキュメントの内容を必要とする場合は、`list_notes` から [`search_notes`](./search-notes) に切り替えてください。
  </Accordion>

  <Accordion title="Use get_note_transcript when…">
    会話から**話された言葉そのものを引用する**必要があるとき。タイムスタンプ付きのトランスクリプト全文を返します。会議 1 時間あたり \~3,000–5,000 トークンで、最終手段です。

    [`get_note_transcript`](./get-transcript) をご覧ください。
  </Accordion>
</AccordionGroup>

## よくあるエラー

### 無効な日時

<Error>
  ```json theme={"system"}
  {
    "error": "Invalid createdAtFrom format. Expected ISO 8601 datetime.",
    "code": "INVALID_DATE_FORMAT",
    "statusCode": 400
  }
  ```
</Error>

**解決方法:** タイムゾーン付きの ISO 8601 形式の日時を使用してください（例: `2026-04-01T00:00:00Z`）。

## トークン使用量

| Mode                              | Tokens per note          |
| --------------------------------- | ------------------------ |
| `list_notes`（メタデータのみ）             | \~50                     |
| `search_notes`（ドキュメント付き）          | \~1,500                  |
| `get_note_transcript`（トランスクリプト全文） | 会議 1 時間あたり \~3,000–5,000 |

<Tip>
  **探索の流れ。** まず `list_notes` で対象の noteGuid を見つけてください。ドキュメントの内容が必要なときにのみ `search_notes` に切り替えます。言葉そのものの引用が必要なときにのみ `get_note_transcript` を使ってください。
</Tip>