Tools
Reference for the seven tools the Aesops MCP server exposes — search, metadata, queries, and brand chart colors.
All tools are read-only. Query tools (query_dataset_rows,
aggregate_dataset, distinct_dataset_values) take a slug — a dataset's
slug or id, same as GET /datasets/{slug} —
and run against that dataset's latest active revision, so results always
match what the REST API and web app would show. They also require
authentication unless the dataset is currently
keyless; every other tool below is fully public.
search_datasets
Search/browse the catalog by free-text query and/or filters. Returns a page of dataset summaries.
| Param | Type | Notes |
|---|---|---|
query | string | Free-text search over dataset name and metadata |
license | string[] | e.g. mit, cc-by-4.0 |
category | string[] | e.g. finance, housing |
tags | string[] | Closed vocabulary — call list_facets to discover valid values |
min_size / max_size | number | File size in bytes |
min_rows / max_rows | number | Row count |
page / page_size | number | Default 1 / 20, page_size capped at 100 |
list_facets
No input. Lists the license, category, and tag values currently in use
across the catalog, plus dataset counts per category — call this before
search_datasets to discover valid filter values.
get_dataset
Full detail for one dataset: description, license, row/column counts, per-column schema (dtype, null/unique stats, sample values), and linked discussion threads.
| Param | Type | Notes |
|---|---|---|
slug | string | Dataset slug or id |
query_dataset_rows
Fetch real rows, optionally filtered and sorted. Rows are capped at 100 per
call regardless of limit; the response includes the true total matched
count.
| Param | Type | Notes |
|---|---|---|
slug | string | Dataset slug or id |
filters | Filter[] | AND-combined — see Filters below |
columns | string[] | Subset of columns to return; omit for all |
orderBy | { column, direction? } | Combine with limit: 1 for a single endpoint row (earliest/latest, highest/lowest) |
limit | number | Default 20, hard-capped at 100 |
aggregate_dataset
Group by one or two columns and compute a metric per group. Omit groupBy
for a single grand-total row.
| Param | Type | Notes |
|---|---|---|
slug | string | Dataset slug or id |
groupBy | string | string[] | Up to 2 columns for a two-dimensional breakdown |
datePart | 'year' | 'month' | 'month_year' | 'quarter' | Extract a date part from the groupBy column(s) first |
metric | { column?, fn } | fn: count / sum / avg / min / max / median. column required unless fn is count |
rowFilters | Filter[] | Filter rows before grouping |
limit | number | Default 20, hard-capped at 5000 |
distinct_dataset_values
List the unique values of one column with their counts — useful for discovering what values exist before filtering.
| Param | Type | Notes |
|---|---|---|
slug | string | Dataset slug or id |
column | string | Exact column name |
limit | number | Default 50, hard-capped at 200 |
get_chart_colors
Returns the Aesops brand chart color palette as hex strings — the same
aeschart 6-slot categorical series (teal, peach, rust, sage, orange,
brown) documented in the Python SDK's brand colors page,
so a chart built from Aesops data can match the platform's own look.
| Param | Type | Notes |
|---|---|---|
theme | 'light' | 'dark' | Omit to get both |
Filters
filters / rowFilters on the query tools above are arrays of:
{ column: string, op: FilterOp, value?: string }FilterOp is one of eq, neq, contains, gt, gte, lt, lte,
in, is_null, is_not_null. value is required unless op is
is_null or is_not_null — those test for a blank/missing cell and take
no value. For in, pass a comma-separated string (e.g. "Nairobi,Mombasa").
Numbers are passed as strings, e.g. "180".