list_notes

概要

list_notes はタイトル、参加者、日付、ソースタイプなどのメタデータのみを返します。ノートの内容を読まずに一覧だけ確認したいときに使ってください。 query.keyword が指定されると、結果セットは recordingStartAt の降順ではなく、全文検索の関連度（同点の場合は createdAt の降順）で並べ替えられます。 使うとき

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

主な特長:

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

workspace-scoped key で呼び出すと、個人フォルダのノートはエラーにならずに結果から外れます（システムAPIキーが読み取るノートの範囲）。

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

パラメータ

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	末尾が `Z` の ISO 8601 UTC 日時。`createdAt` の下限（その値を含む）。
`filter.createdAtTo`	string	Optional	末尾が `Z` の ISO 8601 UTC 日時。`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) の範囲フィルタです。どちらも末尾が Z の ISO 8601 UTC 日時を受け付けます（例: 2026-04-01T00:00:00Z）。日付範囲は、カーソルページネーションと検索結果件数の制限より前に適用されます。範囲外の新しいノートを飛ばすためにページを繰り返し取得する必要はありません。年・月・日の条件は、ユーザーのタイムゾーンの境界を UTC に変換してください。たとえば韓国標準時の 2025 年 7〜8 月は、createdAtFrom: "2025-06-30T15:00:00Z"、createdAtTo: "2025-08-31T15:00:00Z" です。

pagination (optional)

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

レスポンス形式

成功レスポンス

{
  "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=="
}

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

フィールドの説明:

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`。
`degraded`	boolean	`query.keyword` が指定されたものの、検索インデックスを利用できずキーワードが無視された場合は `true`。
`hint`	string	レスポンスの解釈方法や再試行方法を示す案内文。

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

検索インデックスを利用できない場合

query.keyword を指定したレスポンスに degraded: true が含まれる場合、検索インデックスを利用できない状態です。このときキーワードは適用されず、content と notes にはキーワードの検索結果ではなく、最近のノートが含まれます。

degraded: true のレスポンスを通常の検索結果や「一致するノートなし」と解釈しないでください。hint をユーザーまたは LLM に表示し、時間を置いて検索を再試行してください。

使用例

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

リクエスト:

{
  "filter": {
    "folderId": "455765"
  }
}

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

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

リクエスト:

{
  "filter": {
    "createdAtFrom": "2026-04-01T00:00:00Z",
    "createdAtTo": "2026-05-01T00:00:00Z"
  },
  "pagination": {
    "size": 50
  }
}

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

リクエスト:

{
  "query": {
    "keyword": "OKR"
  },
  "pagination": {
    "size": 30
  }
}

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

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

最初のページ:

{
  "pagination": { "size": 50 }
}

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

{
  "pagination": {
    "size": 50,
    "cursor": "eyJvZmZzZXQiOjUwfQ=="
  }
}

どの階層を使うか

Use list_notes when…

フォルダ・日付・キーワードの有無で、どのノートが存在するかを知る必要があるとき。メタデータのみを返し、ノートあたり ~50 トークンです。最も安価な探索ツールです。

Use search_notes when…

トピックの背後にあるコンテキスト（決定事項、アクションアイテム、チームの結論）を理解する必要があるとき。一致したノートと、その主要ドキュメント（ワンページャー、カスタム）を返します。ノートあたり ~1,500 トークンです。LLM がユーザーの質問に答えるためにドキュメントの内容を必要とする場合は、list_notes から search_notes に切り替えてください。

Use get_note_transcript when…

会話から話された言葉そのものを引用する必要があるとき。タイムスタンプ付きのトランスクリプト全文を返します。会議 1 時間あたり ~3,000–5,000 トークンで、最終手段です。get_note_transcript をご覧ください。

よくあるエラー

無効な日時

createdAtFrom／createdAtTo は ISO 8601 日時形式である必要があります。無効な形式は、カスタムエラーコードではなく MCP 標準の validation エラー（zod パラメータ検証の失敗）で拒否されます。 解決方法: 末尾が Z の ISO 8601 UTC 日時を使用してください（例: 2026-04-01T00:00:00Z）。

トークン使用量

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

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

ホーム

はじめに

API

音声ファイル

Webhook

MCP

CLI

開発者リソース

概要

パラメータ

query.keyword (optional)

workspaceGuid (optional)

filter.folderId (optional)

filter.createdAtFrom / filter.createdAtTo (optional)

レスポンス形式

成功レスポンス

検索インデックスを利用できない場合

使用例

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

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

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

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

どの階層を使うか

よくあるエラー

無効な日時

トークン使用量

​概要

​パラメータ

​query.keyword (optional)

​workspaceGuid (optional)

​filter.folderId (optional)

​filter.createdAtFrom / filter.createdAtTo (optional)

​pagination (optional)

​レスポンス形式

​成功レスポンス

​検索インデックスを利用できない場合

​使用例

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

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

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

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

​どの階層を使うか

​よくあるエラー

​無効な日時

​トークン使用量

概要

パラメータ

query.keyword (optional)

workspaceGuid (optional)

filter.folderId (optional)

filter.createdAtFrom / filter.createdAtTo (optional)

pagination (optional)

レスポンス形式

成功レスポンス

検索インデックスを利用できない場合

使用例

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

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

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

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

どの階層を使うか

よくあるエラー

無効な日時

トークン使用量