Skip to main content
Two tools cover tabular data, and they are meant to be used in order: the assistant discovers what exists, then reads it. Tabular models are row-and-column datasets (assets, exchanges, funding rounds, funds, ETF holdings) that answer what is true right now. For metrics observed over time, use the timeseries tools; for questions whose answer is written down rather than computed, start with search_documents. These tools are a thin layer over the REST Data API: the same models, the same field names, the same filter operators. Anything documented for filtering and pagination applies here too.

​
The workflow

1

The assistant discovers what is queryable

tabular_catalog with no arguments returns one compact entry per model: slug, name, description, access, and columnCount. Passing search narrows that list by a case-insensitive substring match on the name, slug, and description.Passing a model slug instead returns that one model in full, including every column:You can trigger this step explicitly:
2

The assistant reads the rows

With a model identified, tabular_data reads it. Its arguments map onto the catalog exactly:

​
Filters

A filter is an object of the form {field, operator, values}, and multiple filters combine with AND. A column only accepts the operators its catalog entry lists: Values are written as strings and coerced to the column’s type. Filters on a time column accept YYYY-MM-DD, RFC3339, or unix seconds. The full operator reference, including which operators each column type supports, is on Filtering & Pagination.

​
What comes back

tabular_data returns one page of rows plus the totals for the whole filtered set: Because totalRows describes the whole filtered set, it is how you tell a complete answer from a first page. If a result looks short, check it before concluding the data is thin.
The MCP tools cap a read more tightly than the REST API does, because every row returned is spent from the assistant’s context window: 25 rows by default and 200 at most, against the REST API’s 100 and 1000. A larger pageSize is clamped to 200 rather than rejected. To answer a question about a large model, filter and sort rather than paging through it.

​
Best practices

  • Name the entity precisely. “Uniswap v4” and “Uniswap” resolve to different rows.
  • Say what to rank on. “Sorted by 30-day TVL change” removes a guess that a bare “top protocols” leaves open.
  • State the filter you mean. “Above $1B in TVL” becomes a server-side filter; “the big ones” does not.
  • Ask what is available first when you are scoping work: “what tabular datasets cover DeFi protocols?” tells you what is queryable before you commit to a specific prompt.
Tabular models are also where series keys come from. If you want a metric over time for a named asset, the assistant reads the identifier out of the matching tabular model first, then hands it to timeseries_data as a series key.

​
When to use something else

tabular_catalog lists only the models Blockworks publishes to the public API. Within that list, reading a model still depends on your key’s entitlements, so “that data is not available” may be an entitlements boundary rather than a gap in coverage.