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

# Tools Reference

> Every tool the Blockworks MCP server exposes, what each one is for, and which to reach for first.

The MCP server exposes five tools: one that retrieves documents, and two catalog-and-read pairs over the
Blockworks data models. Your assistant picks between them on its own, but knowing what they do tells you how to
phrase a request, and explains why one question comes back in seconds while another takes minutes.

## All tools

| Tool                 | Purpose                                                                                   |
| -------------------- | ----------------------------------------------------------------------------------------- |
| `search_documents`   | Search research, news, and curated sources for documents relevant to a question           |
| `tabular_catalog`    | List the tabular models, or describe one in full: columns, filters, sort options          |
| `tabular_data`       | Read rows from one tabular model, filtered, sorted, and paginated                         |
| `timeseries_catalog` | List the timeseries models, or describe one in full: metrics, granularities, series rules |
| `timeseries_data`    | Read points from one timeseries model over a time window                                  |

<Note>
  Whatever your client lists is authoritative. If a name here does not match what you see, use the one your client
  shows and let us know.
</Note>

## Discover, then read

The four dataset tools are two pairs, and each pair is meant to be used in order. A catalog call returns the exact
model slug, the exact field names, and the operators or granularities that model accepts; the read call then
rejects anything that does not match the catalog exactly. That is the same discover-then-query model the REST
[Data API](/getting-started/concepts/catalog) uses, backed by the same catalog.

```mermaid theme={null}
flowchart LR
    Q["Your question"] --> S["search_documents"]
    Q --> TC["tabular_catalog"]
    Q --> SC["timeseries_catalog"]
    TC --> TD["tabular_data"]
    SC --> SD["timeseries_data"]
    TD -. "row id becomes a series key" .-> SD
```

In practice you rarely drive the two steps separately. You ask the question and the assistant runs the catalog
lookup first on its own. Asking the discovery question explicitly is useful when you want to know what is available
before committing to an analysis.

## By category

<CardGroup cols={3}>
  <Card title="Document search" icon="search" href="/mcp/tools/search">
    `search_documents` searches research, news, and curated sources, returning documents with their content,
    links, and publication dates.
  </Card>

  <Card title="Tabular datasets" icon="table" href="/mcp/tools/datasets">
    `tabular_catalog` and `tabular_data` browse the row-and-column models, then read rows with filters, sorting,
    and pagination.
  </Card>

  <Card title="Timeseries" icon="chart-area" href="/mcp/tools/timeseries">
    `timeseries_catalog` and `timeseries_data` find a metric series, then pull its points at a granularity over a
    window.
  </Card>
</CardGroup>

## Where to start

* **Qualitative and research questions: `search_documents`.** What a protocol does, what changed in a launch,
  how an event played out, what has been published on a theme. The answer comes back as documents the assistant
  can read and cite.
* **Anything true right now: the tabular pair.** A price, a ranking, a TVL figure, a funding round, an unlock
  schedule. `tabular_catalog` resolves the model and its columns, then `tabular_data` returns the matching rows.
* **Anything that changes over time: the timeseries pair.** A named metric, at a specific granularity, over an
  exact window. `timeseries_catalog` tells the assistant what exists and `timeseries_data` fetches the points.

The split between the two pairs is the same one the REST API draws; see
[Tabular vs Timeseries](/getting-started/concepts/tabular-vs-timeseries) for the full model.

<Note>
  The catalogs list only the models Blockworks publishes to the public API. Within that list, which models you can
  actually read follows your API key's entitlements, so a listed model can still return an access error.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="What to ask" icon="messages" href="/mcp/prompts">
    Prompt patterns grouped by use case.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/mcp/troubleshooting">
    Missing tools, auth loops, and empty results.
  </Card>
</CardGroup>