> ## 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.

# MCP ユースケース

> AI エージェント向けのステップバイステップなワークフロー：Tiro MCP ツールで会議を検索し、ドキュメントを生成します

Tiro MCP ツールは [Progressive Disclosure pattern](/ja/developers/mcp/mcp-overview)（段階的開示パターン）を中心に設計されています。まずメタデータを読み込み、詳細は必要なときだけ取得します。以下のワークフローでは、token の使用量を最小限に抑えながら、一般的なタスクのためにツールを連結する方法を紹介します。

<Tip>
  **Tiro MCP は初めてですか？** まず [Overview](/ja/developers/mcp/mcp-overview) でアーキテクチャを理解し、これらのワークフローを試す前に[クライアント](/ja/developers/mcp/setup)をセットアップしてください。
</Tip>

***

## 会議を見つけて話された内容を読む方法

Tiro のノート探索は **3 段階の段階的な流れ**になっています。まずは軽量な `list_notes` から始め、ドキュメントの内容が必要になったら `search_notes` に深め、一言一句の発言が必要なときだけ `get_note_transcript` に手を伸ばします。ほとんどのユーザーの質問は tier 1 または tier 2 で完結します。

### ステップバイステップ

<Steps>
  <Step title="候補ノートを一覧表示する（最も低コスト）">
    [`list_notes`](/ja/developers/mcp/tools/list-notes) を呼び出し、任意の `query.keyword` と `filter` で結果を絞り込みます。返されるのはメタデータのみです（ノートあたり約 50 token）。

    ```json theme={"system"}
    {
      "query": { "keyword": "product roadmap" },
      "filter": { "createdAtFrom": "2026-04-01T00:00:00Z" },
      "pagination": { "size": 20 }
    }
    ```

    特定のフォルダに範囲を限定するには `filter.folderId` を使い、フォルダを日付順に閲覧するには `query.keyword` を完全に省略します。
  </Step>

  <Step title="一致したノートのドキュメントを読む">
    どのノートが一致するかを確認するだけでなく、話された内容を**理解する**必要がある場合は、必須の `keyword` を指定して [`search_notes`](/ja/developers/mcp/tools/search-notes) を呼び出します。レスポンスには、一致した各ノートの主要なドキュメント（one-pager、custom）がインラインで含まれ、HTML が除去され、ドキュメントあたり 5KB に制限されます。

    ```json theme={"system"}
    {
      "keyword": "product roadmap",
      "filter": { "createdAtFrom": "2026-04-01T00:00:00Z" },
      "pagination": { "size": 10 }
    }
    ```

    最大 10 件の一致ノートをそのドキュメントとともに返します（ノートあたり約 1,500 token）。**ほとんどのクエリはここで完結します**。整理されたドキュメントには、通常チームの意思決定とアクションアイテムが含まれています。
  </Step>

  <Step title="単一の AI 要約を取得する（任意）">
    要約の概要が必要な場合は、`include: ["summary"]` を指定して [`get_note`](/ja/developers/mcp/tools/get-note) を呼び出します。

    ```json theme={"system"}
    {
      "noteGuid": "f8a2c1e4-9b3d-4e7f-a6c8-1d2e3f4a5b6c",
      "include": ["summary"]
    }
    ```

    主要な意思決定、アクションアイテム、ハイライトを返します（200〜800 token）。
  </Step>

  <Step title="完全なトランスクリプトを読み込む（最終手段）">
    **正確な引用**や特定の発言が必要なときだけ、[`get_note_transcript`](/ja/developers/mcp/tools/get-transcript) を呼び出します。タイムスタンプ付きの段落と、markdown に適したトランスクリプション文字列を返します（会議 1 時間あたり約 3,000〜5,000 token）。

    ```json theme={"system"}
    {
      "noteGuid": "f8a2c1e4-9b3d-4e7f-a6c8-1d2e3f4a5b6c"
    }
    ```
  </Step>
</Steps>

### Token の使用量

| Approach                                 | Tokens               | Speed |
| ---------------------------------------- | -------------------- | ----- |
| `list_notes` のみ（候補を見つける）                 | ノートあたり約 50           | 最速    |
| `list_notes` → `search_notes`（ドキュメントを読む） | ノートあたり約 1,500        | 速い    |
| `get_note_transcript` を直接読み込む            | 1 時間あたり約 3,000〜5,000 | 最も遅い  |
| **トランスクリプトとの比較での削減率**                    | **70〜80%**           | —     |

### よくある質問

<AccordionGroup>
  <Accordion title="list_notes と search_notes はどう使い分けますか？">
    フォルダ、日付、またはキーワードの有無で**どのノートが存在するかを知る**必要があるときは **`list_notes`** を使います。返されるのはメタデータのみです。

    あるトピックの背後にある**文脈を理解する**必要があるとき、つまりその意思決定、アクションアイテム、結論などを知りたいときは **`search_notes`** を使います。一致したノートとそのドキュメントをインラインで返します。キーワードは必須です。
  </Accordion>

  <Accordion title="list_notes が結果を返さない場合は？">
    より広い条件を試してください。

    * `query.keyword` を外すか短くする。
    * `filter.createdAtFrom` / `createdAtTo` の範囲を広げるか、外す。
    * ノートが [Tiro Dashboard](https://tiro.ooo) で「Completed」になっているか確認する。未完了のノートは自動的に除外されます。
  </Accordion>

  <Accordion title="search_notes のドキュメントと get_note_transcript ではどちらを優先すべきですか？">
    **`search_notes`** を優先してください。整理されたドキュメントは通常、生のトランスクリプトより 10 倍コンパクトで、チームの意思決定、アクションアイテム、結論を意図された構造で捉えています。直接引用のために一言一句の発言が必要なときだけ **`get_note_transcript`** を使ってください。
  </Accordion>

  <Accordion title="createdAtFrom / createdAtTo はどの日付形式を受け付けますか？">
    タイムゾーン付きの ISO 8601 datetime です：`2026-04-01T00:00:00Z`。`2026-04-01` のような日付のみの形式は受け付けられません。範囲は半開区間 `[from, to)` です。
  </Accordion>

  <Accordion title="workspace-scoped API key でキーワード検索を使えますか？">
    はい。`list_notes` と `search_notes` でのキーワード検索は、user-scoped と workspace-scoped のどちらの API key でも機能します。`workspaceGuid` を省略するとアクセス可能なすべてのワークスペースを検索します — workspace-scoped key は自動的に自身のワークスペースを検索します。特定のワークスペースを対象にするには、明示的な `workspaceGuid`（`list_workspaces` から取得）を渡してください。
  </Accordion>
</AccordionGroup>

***

## 会議ノートから構造化されたドキュメントを生成する方法

AI エージェントは、Tiro のテンプレートベースのドキュメントシステムを使って、任意の会議からアクションアイテム、意思決定、要点を抽出できます。各ドキュメントは、テンプレートで定義されたセクションに構造化されます。

### ステップバイステップ

<Steps>
  <Step title="利用可能なテンプレートを閲覧する">
    [`list_document_templates`](/ja/developers/mcp/tools/get-note) を呼び出して、利用可能なドキュメントの種類を確認します。

    ```json theme={"system"}
    {}
    ```

    「Meeting Minutes」「Action Items」「Decision Log」などのテンプレートを返します。それぞれに `id`、`title`、`description` が付いています。
  </Step>

  <Step title="対象の会議を見つける">
    [`list_notes`](/ja/developers/mcp/tools/list-notes) を呼び出し、キーワード（またはフォルダ、日付範囲）で会議を特定します。

    ```json theme={"system"}
    {
      "query": { "keyword": "sprint planning" }
    }
    ```
  </Step>

  <Step title="ドキュメントを取得する">
    `include: ["documents"]` を指定して [`get_note`](/ja/developers/mcp/tools/get-note) を呼び出すと、そのノートのために生成されたすべてのドキュメントを 1 回の呼び出しで取得できます。

    ```json theme={"system"}
    {
      "noteGuid": "f8a2c1e4-9b3d-4e7f-a6c8-1d2e3f4a5b6c",
      "include": ["documents"]
    }
    ```

    その会議について生成されたすべてのドキュメントを、構造化されたセクション（例：「Decisions」「Action Items」「Next Steps」）とともに返します。
  </Step>
</Steps>

### よくある質問

<AccordionGroup>
  <Accordion title="どのテンプレートを使えばよいか、どうやって知りますか？">
    まず [`list_document_templates`](/ja/developers/mcp/tools/get-note) を呼び出してください。各テンプレートには、その目的を説明する `description` フィールドが含まれています。ドキュメントをリクエストする前にセクション構造の全体を確認するには、特定の `templateId` を指定して [`get_document_template`](/ja/developers/mcp/tools/get-note) を使ってください。
  </Accordion>

  <Accordion title="ノートにまだドキュメントが存在しない場合は？">
    `get_note(include: ["documents"])` は空の配列を返します。ドキュメントはまず Tiro アプリから生成する必要があります。MCP server は既存のドキュメントへの読み取りアクセスを提供します。ノートの所有者に、Tiro 上でドキュメントを生成するよう依頼してください。
  </Accordion>
</AccordionGroup>

***

***

## AI エージェント開発者向けのヒント

### Token の最適化

* 必ず `list_notes`（ノートあたり約 50 token）から始め、ドキュメントの内容が必要なときだけ `search_notes`（ノートあたり約 1,500 token）に深め、一言一句の引用が必要なときだけ `get_note_transcript` に手を伸ばしてください。
* 結果の上限を設定するには `pagination.size` を使います。`list_notes` のデフォルトは `20`（最大 `100`）、`search_notes` のデフォルトは `10`（最大 `30`。各結果にドキュメントが含まれるため小さめです）。
* 要約とドキュメントには `MARKDOWN` 形式を優先してください。より構造化されていて、LLM が解析しやすくなります。

### エラーハンドリング

* `401` と `403` のレスポンスには `action_url` と `docs_url` フィールドが含まれます。これらを提示すれば、自身で解決できます
* `429` のレスポンスには `Retry-After` ヘッダーが含まれます。再試行する前にこれに従ってください
* 完全なエラーリファレンスは [Troubleshooting](/ja/developers/mcp/troubleshooting) をご覧ください

### 適切なツールの選び方

| User Intent               | Start With                                                     | Then                                                                           |
| ------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| 「トピック X の会議はどれですか？」       | [`list_notes`](/ja/developers/mcp/tools/list-notes)            | —（メタデータで十分）                                                                    |
| 「この会議では何が話されましたか？」        | [`search_notes`](/ja/developers/mcp/tools/search-notes)        | （ドキュメントがインライン。通常はこれで十分）                                                        |
| 「実際の発言を引用したい」             | [`list_notes`](/ja/developers/mcp/tools/list-notes)            | [`get_note_transcript`](/ja/developers/mcp/tools/get-transcript)               |
| 「アクションアイテムをください」          | [`list_notes`](/ja/developers/mcp/tools/list-notes)            | `include: ["documents"]` を指定した [`get_note`](/ja/developers/mcp/tools/get-note) |
| 「どのドキュメントテンプレートが利用できますか？」 | [`list_document_templates`](/ja/developers/mcp/tools/get-note) | [`get_document_template`](/ja/developers/mcp/tools/get-note)                   |
| 「認証されていますか？」              | [`auth_status`](/ja/developers/mcp/tools/auth-status)          | —                                                                              |

すべてのツールについては [Tool Reference](/ja/developers/mcp/tools/overview) をご覧ください。