> ## 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 Use Cases

> Step-by-step workflows for AI agents: search meetings and generate documents with Tiro MCP tools

Tiro MCP tools are designed around a [Progressive Disclosure pattern](/en/developers/mcp/mcp-overview) — load metadata first, details only when needed. The workflows below show how to chain tools for common tasks while keeping token usage minimal.

<Tip>
  **New to Tiro MCP?** Start with the [Overview](/en/developers/mcp/mcp-overview) to understand the architecture, then set up [your client](/en/developers/mcp/setup) before trying these workflows.
</Tip>

***

## How to Find a Meeting and Read What Was Discussed

Tiro's note-discovery surface is a **3-tier progression**: start lightweight with `list_notes`, deepen to `search_notes` when you need document content, and only reach for `get_note_transcript` when verbatim spoken words are required. Most user questions stop at tier 1 or tier 2.

### Step-by-step

<Steps>
  <Step title="List candidate notes (cheapest)">
    Call [`list_notes`](/en/developers/mcp/tools/list-notes) with an optional `query.keyword` and `filter` to narrow the result. Returns metadata only (\~50 tokens per note).

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

    Use `filter.folderId` to scope to a specific folder, or omit `query.keyword` entirely to browse a folder by date.
  </Step>

  <Step title="Read documents for matched notes">
    When you need to **understand** what was discussed (not just see which notes match), call [`search_notes`](/en/developers/mcp/tools/search-notes) with a required `keyword`. The response carries each matched note's primary documents (one-pager, custom) inline, HTML-stripped and capped at 5KB per document.

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

    Returns up to 10 matched notes with their documents (\~1,500 tokens per note). **Most queries end here** — the curated documents typically capture the team's decisions and action items.
  </Step>

  <Step title="Fetch a single AI summary (optional)">
    If you need a summary overview, call [`get_note`](/en/developers/mcp/tools/get-note) with `include: ["summary"]`.

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

    Returns key decisions, action items, and highlights (200–800 tokens).
  </Step>

  <Step title="Load the full transcript (last resort)">
    Only when you need **exact quotes** or specific spoken words, call [`get_note_transcript`](/en/developers/mcp/tools/get-transcript). Returns timestamped paragraphs and a markdown-friendly transcription string (\~3,000–5,000 tokens per hour of meeting).

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

### Token Usage

| Approach                                       | Tokens                 | Speed   |
| ---------------------------------------------- | ---------------------- | ------- |
| `list_notes` only (find candidates)            | \~50 per note          | Fastest |
| `list_notes` → `search_notes` (read documents) | \~1,500 per note       | Fast    |
| Direct `get_note_transcript` load              | \~3,000–5,000 per hour | Slowest |
| **Savings vs. transcript**                     | **70–80%**             | —       |

### Frequently Asked Questions

<AccordionGroup>
  <Accordion title="When do I use list_notes vs search_notes?">
    Use **`list_notes`** when you need to **know which notes exist** — by folder, by date, or by keyword presence. Returns metadata only.

    Use **`search_notes`** when you need to **understand the context** behind a topic — its decisions, action items, or conclusions. Returns matched notes with their documents inline. Keyword is required.
  </Accordion>

  <Accordion title="What if list_notes returns no results?">
    Try broader criteria:

    * Drop or shorten the `query.keyword`.
    * Widen the `filter.createdAtFrom` / `createdAtTo` range or remove it.
    * Verify the note is "Completed" in your [Tiro Dashboard](https://tiro.ooo) — incomplete notes are excluded automatically.
  </Accordion>

  <Accordion title="Should I prefer search_notes documents or get_note_transcript?">
    Prefer **`search_notes`**. Curated documents are typically 10× more compact than the raw transcript and capture the team's decisions, action items, and conclusions in their intended structure. Use **`get_note_transcript`** only when you need verbatim spoken words for a direct quote.
  </Accordion>

  <Accordion title="What date format do createdAtFrom / createdAtTo accept?">
    ISO 8601 datetime with timezone: `2026-04-01T00:00:00Z`. Date-only formats like `2026-04-01` are not accepted. The range is half-open `[from, to)`.
  </Accordion>

  <Accordion title="Can I use a workspace-scoped API key for keyword search?">
    Yes. Keyword search on `list_notes` and `search_notes` works for both user-scoped and workspace-scoped API keys. Omit `workspaceGuid` to search across all workspaces you can access — a workspace-scoped key automatically searches its own workspace; pass an explicit `workspaceGuid` (from `list_workspaces`) to target a specific workspace.
  </Accordion>
</AccordionGroup>

***

## How to Generate Structured Documents from Meeting Notes

AI agents can extract action items, decisions, and key takeaways from any meeting using Tiro's template-based document system. Each document is structured into sections defined by a template.

### Step-by-step

<Steps>
  <Step title="Browse available templates">
    Call [`list_document_templates`](/en/developers/mcp/tools/get-note) to see what document types are available.

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

    Returns templates like "Meeting Minutes", "Action Items", "Decision Log" — each with an `id`, `title`, and `description`.
  </Step>

  <Step title="Find the target meeting">
    Call [`list_notes`](/en/developers/mcp/tools/list-notes) to locate the meeting by keyword (or folder, or date range).

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

  <Step title="Retrieve the documents">
    Call [`get_note`](/en/developers/mcp/tools/get-note) with `include: ["documents"]` to fetch all generated documents for the note in one call.

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

    Returns all generated documents with their structured sections (e.g., "Decisions", "Action Items", "Next Steps") for the meeting.
  </Step>
</Steps>

### Frequently Asked Questions

<AccordionGroup>
  <Accordion title="How do I know which template to use?">
    Call [`list_document_templates`](/en/developers/mcp/tools/get-note) first. Each template includes a `description` field explaining its purpose. Use [`get_document_template`](/en/developers/mcp/tools/get-note) with a specific `templateId` to see the full section structure before requesting documents.
  </Accordion>

  <Accordion title="What if no document exists yet for a note?">
    `get_note(include: ["documents"])` returns an empty array. Documents must be generated from the Tiro app first — the MCP server provides read access to existing documents. Ask the note owner to generate the document in Tiro.
  </Accordion>
</AccordionGroup>

***

***

## Tips for AI Agent Developers

### Token Optimization

* Always start with `list_notes` (\~50 tokens per note); deepen to `search_notes` (\~1,500 tokens per note) only when document content is needed; reach for `get_note_transcript` only when verbatim quoting is required.
* Use `pagination.size` to bound results: `list_notes` defaults to `20` (max `100`); `search_notes` defaults to `10` (max `30` — smaller because each result includes documents).
* Prefer `MARKDOWN` format on summaries and documents — more structured and easier for LLMs to parse.

### Error Handling

* `401` and `403` responses include `action_url` and `docs_url` fields — surface these to you for self-service resolution
* `429` responses include a `Retry-After` header — respect it before retrying
* See [Troubleshooting](/en/developers/mcp/troubleshooting) for a full error reference

### Choosing the Right Tool

| User Intent                              | Start With                                                     | Then                                                                          |
| ---------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| "Which meetings do I have on topic X?"   | [`list_notes`](/en/developers/mcp/tools/list-notes)            | — (metadata is enough)                                                        |
| "What was discussed in this meeting?"    | [`search_notes`](/en/developers/mcp/tools/search-notes)        | (documents inline; usually enough)                                            |
| "Quote what they actually said"          | [`list_notes`](/en/developers/mcp/tools/list-notes)            | [`get_note_transcript`](/en/developers/mcp/tools/get-transcript)              |
| "Give me the action items"               | [`list_notes`](/en/developers/mcp/tools/list-notes)            | [`get_note`](/en/developers/mcp/tools/get-note) with `include: ["documents"]` |
| "What document templates are available?" | [`list_document_templates`](/en/developers/mcp/tools/get-note) | [`get_document_template`](/en/developers/mcp/tools/get-note)                  |
| "Am I authenticated?"                    | [`auth_status`](/en/developers/mcp/tools/auth-status)          | —                                                                             |

Browse the full [Tool Reference](/en/developers/mcp/tools/overview) for the complete tool surface.