メインコンテンツへスキップ

​
概要

list_notes はノート探索の軽量な階層です。メタデータ（タイトル、参加者、日付、ソースタイプ）のみを返し、コンテンツを読まずにどのノートが存在するかを知る必要があるときに適したツールです。 query.keyword が指定されると、結果セットは recordingStartAt の降順ではなく、全文検索の関連度（同点の場合は createdAt の降順）で並べ替えられます。 主なユースケース:
  • 「フォルダ X にはどのノートがありますか?」
  • 「キーワード Y に一致するノートはどれですか?」（存在の確認のみ）
  • 日付範囲でフィルタリングして大きなワークスペースを絞り込む。
主な特長:
  • search_notes（深い、ドキュメントを返す）と get_note_transcript（生のトランスクリプト）を含む 3 階層モデル。
  • 一覧パスでの cursor ベースのページネーション。
  • 不完全なノートを自動的に除外します。録音が一度も開始されず、タイトルがデフォルトのプレースホルダのままのノートは、MCP レイヤーで除外されます。
トークン効率。 list_notes の 1 ページはノートあたり ~50 トークンを返します。search_notes 経由でドキュメントを読み込む（ノートあたり ~1,500 トークン）場合や、get_note_transcript 経由でトランスクリプトを読み込む（ノートあたり ~3,000–5,000 トークン）場合と比べて、これは手元に何があるかを見つける最も安価な方法です。

​
パラメータ

ParameterTypeRequiredDescription
query.keywordstringOptionalオプションのキーワード。指定すると全文検索の関連度で並べ替えます。
pagination.cursorstringOptional前回の nextCursor から得た cursor。
pagination.sizenumberOptional1 ページあたりの結果数（デフォルト 20、最大 100）。
filter.folderIdstringOptionalフォルダに限定（再帰的 — 子孫フォルダを含みます）。
filter.createdAtFromstringOptionalISO 8601 形式の日時。createdAt の下限（その値を含む）。
filter.createdAtTostringOptionalISO 8601 形式の日時。createdAt の上限（その値を含まない）。

​
query.keyword (optional)

一覧表示を関連度モードに切り替えます。ヒットは、ノートのタイトルと段落のコンテンツに対するサーバーの全文インデックスでスコアリングされます。キーワードが指定されると nextCursor は null になります（深い検索インデックスは安定した一覧 cursor を持ちません）。 キーワード検索には現在、ユーザースコープの API key が必要です。keyword を設定したチーム専用 API key は 400 Bad Request を返します。

​
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 を使用してください。

​
レスポンス形式

​
成功レスポンス

{
  "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（レガシーエイリアス）の両方に含みます。クライアントが好む方を選び、もう一方は無視してください。
フィールドの説明:
FieldTypeDescription
content[]arrayノート（推奨フィールド）。
content[].noteGuidstringノートの一意な識別子。search_notes、get_note_transcript などに渡します。
content[].titlestringノートのタイトル。
content[].webUrlstringTiro Web アプリ内のノートへの直接リンク。
content[].createdAtstringISO 8601 形式の作成タイムスタンプ。
content[].updatedAtstringISO 8601 形式の最終更新タイムスタンプ。
content[].recordingDurationSecondsnumber録音の長さ（秒）（録音以外のソースでは 0）。
content[].sourceTypestringlive-voice、recording、text、video、webpage、offline-mode、onboarding のいずれか。
content[].participants[]array参加者ごとの { name, email }。いずれも null の場合があります。
totalnumberバックエンドのフィルタ前の件数。
totalSizenumberMCP 側の不完全ノートフィルタ後の件数（total より小さくなることがあります）。
nextCursorstring | null次のページ用の cursor。これ以上結果がない場合やキーワード検索が有効な場合は null。
ページネーションのヒント。 total と totalSize は食い違うことがあります。total がカウントした不完全なノートは totalSize より前に除外されます。while (totalSize < total) でループせず、代わりに nextCursor でページをたどってください。

​
使用例

​
例 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=="
  }
}

​
どの階層を使うか

フォルダ・日付・キーワードの有無で、どのノートが存在するかを知る必要があるとき。メタデータのみを返し、ノートあたり ~50 トークンです。最も安価な探索ツールです。
トピックの背後にあるコンテキスト（決定事項、アクションアイテム、チームの結論）を理解する必要があるとき。一致したノートと、その主要ドキュメント（ワンページャー、カスタム）を返します。ノートあたり ~1,500 トークンです。LLM がユーザーの質問に答えるためにドキュメントの内容を必要とする場合は、list_notes から search_notes に切り替えてください。
会話から話された言葉そのものを引用する必要があるとき。タイムスタンプ付きのトランスクリプト全文を返します。会議 1 時間あたり ~3,000–5,000 トークンで、最終手段です。get_note_transcript をご覧ください。

​
よくあるエラー

​
チーム専用 API key でのキーワード検索

解決方法: キーワード検索にはユーザースコープの API key を使用してください。キーワードなしのチームフォルダ一覧は、チーム API key でも引き続き機能します。

​
無効な日時

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

​
トークン使用量

ModeTokens 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 を使ってください。