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

# Knowledge & discovery

> Find the right tables, docs, and existing dashboards before writing a single line of SQL.

These five tools are how your agent orients itself. Use them before writing SQL — guessing a table name costs more than searching for it.

## Available tools

| Tool                   | Description                                                           |
| :--------------------- | :-------------------------------------------------------------------- |
| `search_schemas`       | Search Allium's table catalog, or fetch one table's full schema by ID |
| `search_docs`          | Semantic search across Allium's public documentation                  |
| `browse_docs`          | Navigate the documentation tree like a filesystem                     |
| `search_terminal`      | Search public Terminal dashboards built by Allium's analysts          |
| `get_terminal_results` | Fetch a Terminal chart's SQL or its latest precomputed rows           |

<Tip>
  Check `search_terminal` first for common topics. An analyst-built dashboard often already answers the question, and reading its SQL is cheaper and more reliable than writing your own.
</Tip>

## Search schemas

One tool covers both discovery and fetch-by-ID.

<Tabs>
  <Tab title="Discovery">
    Search by keywords, table names, tags, or a description of the data:

    ```json theme={null}
    {
      "name": "search_schemas",
      "arguments": {
        "query": "erc20 token transfers",
        "limit": 5
      }
    }
    ```

    Each hit returns the table ID, database, schema, table name, description, row count, tags, and score. Bodies are omitted by default so the payload stays small.
  </Tab>

  <Tab title="Fetch by ID">
    Once you know the table, fetch its full schema. `id` is the dotted `<database>.<schema>.<table>` form returned in a prior hit:

    ```json theme={null}
    {
      "name": "search_schemas",
      "arguments": {
        "id": "ethereum.raw.token_transfers"
      }
    }
    ```

    Fetch-by-ID bypasses search and always includes the full markdown body — column names, types, and descriptions.
  </Tab>
</Tabs>

| Parameter         | Default | Notes                                                                                                                                  |
| :---------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------- |
| `query`           | —       | Mutually exclusive with `id`                                                                                                           |
| `id`              | —       | Dotted table ID. Always returns full content                                                                                           |
| `include_content` | `false` | Full markdown body per hit. Use a `limit` of 1–3 when true                                                                             |
| `limit`           | `5`     | Max 20. Use 3–5 for discovery                                                                                                          |
| `search_mode`     | `basic` | `basic` is BM25 keyword ranking, sub-millisecond. `advanced` is hybrid vector + keyword with better recall on natural-language queries |

<Note>
  `advanced` search mode isn't enabled for every organization. If it returns an error, retry with `search_mode: "basic"` or contact [support@allium.so](mailto:support@allium.so).
</Note>

## Search and browse documentation

`search_docs` is semantic search over [docs.allium.so](https://docs.allium.so) — use it for data-model questions, API usage, and querying best practices.

```json theme={null}
{
  "name": "search_docs",
  "arguments": { "query": "how to query DEX trades" }
}
```

`browse_docs` walks the same content as a filesystem. Every directory has an `_index.md` listing its contents with descriptions.

```json theme={null}
{
  "name": "browse_docs",
  "arguments": { "path": "historical-data/_index.md" }
}
```

**How to navigate efficiently:**

1. Read `_index.md` at the root to see the top-level sections.
2. Read a section's `_index.md` (for example `historical-data/_index.md`).
3. Drill down through subdirectory index files.
4. Read the specific file for table schemas, SQL examples, or API specs.

| Path form                                      | Result                           |
| :--------------------------------------------- | :------------------------------- |
| `""` or `"."`                                  | Root directories and files       |
| `"api"`                                        | Contents of the `api/` directory |
| `"api/developer/prices/token-latest-price.md"` | That file's content              |

<Warning>
  Never read files blindly. Read the `_index.md` in a directory first — it tells you which file you actually want. For semantic lookup, use `search_docs` instead of guessing paths.
</Warning>

Realtime tool descriptions include a `docs_path` pointing at the exact file that documents their supported chains, edge cases, and response shape. Pass it straight to `browse_docs`.

## Terminal dashboards

[Terminal](https://app.allium.so/terminal) is Allium's library of public, analyst-built dashboards. Two tools read it, and **neither consumes Explorer Units** — they read existing definitions and precomputed results.

<Steps>
  <Step title="Find a dashboard">
    ```json theme={null}
    {
      "name": "search_terminal",
      "arguments": { "query": "stablecoin supply by chain", "limit": 5 }
    }
    ```

    Returns ranked hits with label, description, category, status, and URL. Set `include_content: true` with a small `limit` for the full rendered dashboard markdown. Never returns raw result rows or SQL.
  </Step>

  <Step title="List its charts">
    Call `get_terminal_results` with the `dashboard_id` and no `chart_id` to get the chart manifest.
  </Step>

  <Step title="Read a chart">
    ```json theme={null}
    {
      "name": "get_terminal_results",
      "arguments": {
        "dashboard_id": "<DASHBOARD_ID>",
        "chart_id": "<CHART_ID>",
        "mode": "both",
        "max_rows": 100
      }
    }
    ```

    `mode` is `queries` for SQL only, `results` for rows only, or `both`.
  </Step>
</Steps>

<Note>
  Terminal results are precomputed. Cite `result.queried_at` when you report values so the reader knows how fresh the numbers are, and link the reader to the Terminal dashboard itself — it carries context and visualizations the raw rows don't.
</Note>

## A typical discovery flow

<Steps>
  <Step title="Check Terminal">
    `search_terminal` — is this already built? If yes, `get_terminal_results` for the SQL and use it as your baseline.
  </Step>

  <Step title="Find the tables">
    `search_schemas` with a descriptive query, then fetch the top table by `id` for full column detail.
  </Step>

  <Step title="Check the data model">
    `search_docs` for the vertical's conventions — adjusted volume, decimals, re-org handling.
  </Step>

  <Step title="Load the SQL rules">
    `get_skill(name="sql-optimization")` before writing the query.
  </Step>
</Steps>

## Related resources

<CardGroup cols={2}>
  <Card title="SQL & queries" icon="database" href="/ai/mcp/tools-reference/sql-and-queries">
    Run the query once you've found the tables
  </Card>

  <Card title="Skills" icon="book-open" href="/ai/mcp/tools-reference/skills">
    Allium's own guidance on writing efficient SQL
  </Card>

  <Card title="Data Catalog" icon="database" href="/historical-data/overview">
    The human-readable version of the schema catalog
  </Card>

  <Card title="Terminal" icon="chart-line" href="https://app.allium.so/terminal">
    Browse the public dashboards yourself
  </Card>
</CardGroup>