Server definition
- Hash
- sha256:5d74cc5e99192ddd9e3f6a93186434ead444c45f660cda22653ad4c043e5f3a1
- What it is
- What a remote MCP server returned when asked what it offers: 6 tools
The blob, as servednamed by its sha256
{
"instructions": "Global food & agriculture statistics from the UN FAOSTAT bulk-download corpus, served from a local SQLite mirror (the public REST API is auth-gated). Workflow: faostat_list_domains to find a domain code → faostat_resolve_codes to turn commodity/country/metric names into the integer codes the cube needs → faostat_query_observations for the data. Aggregate regions (World, continents) are excluded by default so sums are not double-counted — set include_aggregates=true for roll-ups. Large results spill to a DataCanvas table; query it with faostat_dataframe_query (discover table/column names via faostat_dataframe_describe). faostat_commodity_profile bundles producers + trend + trade for one commodity in a single call. Every observation carries a data-quality flag — commonly A=Official, B=time-series break, E=Estimated, I=Imputed, M=Missing (value cannot exist), T=Unofficial, X=from an international organization, plus others FAOSTAT defines per domain — honor it, and treat any unrecognized flag as informational (never assume official).",
"tools": [
{
"description": "Assemble a global profile for one commodity in a single call: top-producing countries, the annual production trend, and trade flows (top exporters and importers). Accepts a commodity name, resolves it to item codes, then queries the production (QCL) and trade (TCL) domains and merges the results. Each ranking is a per-country sum across the resolved items, taken at that country's own latest year with data and grouped by unit so incomparable quantities are never added. The trend is returned inline as year/value points. Country-level only (aggregates excluded). The production domain (QCL) is required. When the trade domain (TCL) is not indexed locally, returns a production-only profile with a notice naming the gap rather than failing. When the merged observation set is too large to inline, it spills to a DataCanvas table (canvas_id + table_name) — call faostat_dataframe_describe for its columns, then faostat_dataframe_query for deeper SQL.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"canvas_id": {
"description": "Canvas ID to stage onto, as returned by a prior faostat_query_observations / faostat_commodity_profile call — exactly 10 characters of letters, digits, hyphens, and underscores. Omit to stage onto this session’s canvas, created on the first spill and reused by every later call, so tables staged earlier in the session sit alongside this one.",
"pattern": "^[A-Za-z0-9_-]{10}$",
"type": "string"
},
"item_query": {
"description": "Commodity name to profile (e.g. \"maize\", \"wheat\", \"coffee green\"). Matched by relevance; the 5 best-matching items are folded into one profile, so a broad name such as \"milk\" is narrowed — the response discloses how many items matched in total.",
"minLength": 1,
"type": "string"
},
"top_n": {
"default": 10,
"description": "Number of top producers / exporters / importers to return. Max 50.",
"maximum": 50,
"minimum": 1,
"type": "integer"
},
"year_end": {
"description": "Inclusive end year for the trend (e.g. 2022).",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"year_start": {
"description": "Inclusive start year for the trend (e.g. 1990).",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
}
},
"required": [
"item_query"
],
"type": "object"
},
"name": "faostat_commodity_profile",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"item_query",
"resolved_items",
"top_producers",
"top_exporters",
"top_importers",
"production_trend",
"trend_points",
"spilled",
"truncated",
"resolvedItemCodes",
"resolvedItemMatches",
"itemsTruncated"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"canvas_id": {
"description": "Canvas ID this call staged onto. When spilled it holds table_name — pass both to faostat_dataframe_describe (table_name as name) for the columns and types, then canvas_id to faostat_dataframe_query for SQL. Also present when the merged set fit inline and no table was staged; faostat_dataframe_describe with this canvas_id then lists any tables already staged on it. Absent when the canvas is disabled or staging failed.",
"type": "string"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `no_match`: The item query resolved to no commodity code. `domain_not_indexed`: The production domain (QCL) is not in the local mirror selection (FAOSTAT_DOMAINS), so there is no production data to profile. `index_not_ready`: The production domain (QCL) is selected, but its mirror is cold — its initial sync has never completed. `invalid_year_range`: year_start is greater than year_end — a self-contradictory range that can never match. The bounds reach the production, trade, and merged canvas-stream queries alike, so every one of them would return nothing. `canvas_not_found`: DataCanvas is enabled and canvas_id does not resolve to a live canvas — unknown, expired, or owned by another tenant. `query_timeout`: The profile's mirror reads (commodity resolution, rankings, trend, staging stream) — time queued behind other calls plus execution — ran past the 45-second per-call ceiling. Other values are possible when a failure originates below the handler.",
"examples": [
"no_match",
"domain_not_indexed",
"index_not_ready",
"invalid_year_range",
"canvas_not_found",
"query_timeout"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"item_query": {
"description": "The commodity query echoed back.",
"type": "string"
},
"itemsTruncated": {
"description": "True when the commodity name matched more items than the profile folded in — the profile then covers only the most relevant few.",
"type": "boolean"
},
"notice": {
"description": "States where the observation set went — the canvas table it was staged on (with the describe-then-query pointer), fit inline, a staging failure, or a disabled canvas — plus a trade domain (TCL) that was not indexed, item-resolution truncation, mixed units in the rankings, or other partial-result context.",
"type": "string"
},
"production_trend": {
"description": "The annual production series for the resolved commodity, summed over countries and items per year and ordered oldest-first. Aggregated in SQL over the complete filtered match, so it is not affected by the canvas staging cap.",
"items": {
"additionalProperties": false,
"description": "One annual trend point.",
"properties": {
"flags": {
"description": "Distinct data-quality flags across the summed observations, comma-separated and sorted — commonly A=Official, B=time-series break, E=Estimated, I=Imputed, M=Missing (value cannot exist), T=Unofficial, X=from an international organization, plus others FAOSTAT defines per domain; treat any unrecognized flag as informational, never assume official. Null when no summed observation carried a flag. More than one flag means the total mixes data qualities.",
"type": [
"string",
"null"
]
},
"observations": {
"description": "Observations summed into value — read it alongside value, since a change in coverage moves the total independently of production.",
"type": "number"
},
"unit": {
"description": "Unit of measure for value; null when unspecified. Points are grouped by unit, so a year can appear once per unit rather than summing incomparable quantities.",
"type": [
"string",
"null"
]
},
"value": {
"description": "Production summed across every country and resolved item reporting that year.",
"type": "number"
},
"year": {
"description": "Observation year.",
"type": "number"
}
},
"required": [
"year",
"value",
"observations",
"unit",
"flags"
],
"type": "object"
},
"type": "array"
},
"resolvedItemCodes": {
"description": "Item codes the commodity query resolved to.",
"items": {
"type": "number"
},
"type": "array"
},
"resolvedItemMatches": {
"description": "Total items the commodity query matched in QCL, before the 5-item profile cap.",
"type": "number"
},
"resolved_items": {
"description": "Commodities the query resolved to (the profile aggregates across all of them).",
"items": {
"additionalProperties": false,
"description": "One resolved commodity.",
"properties": {
"code": {
"description": "Resolved item code.",
"type": "number"
},
"name": {
"description": "Resolved item name.",
"type": "string"
}
},
"required": [
"code",
"name"
],
"type": "object"
},
"type": "array"
},
"spilled": {
"description": "True when the merged observation set was staged on a canvas table.",
"type": "boolean"
},
"staged_row_count": {
"description": "Rows actually staged on the merged canvas table (present when spilled). Equals the 50,000-row cap when truncated.",
"type": "number"
},
"table_name": {
"description": "Canvas table holding the staged observations — production plus trade when the trade domain (TCL) is indexed, production only when it is not (present when spilled). The notice names which of the two the table holds. Pass it as name to faostat_dataframe_describe for its columns (a domain column tags each row QCL or TCL), then reference it in faostat_dataframe_query SQL.",
"type": "string"
},
"top_exporters": {
"description": "Top exporters by summed export quantity (empty when trade is not indexed).",
"items": {
"additionalProperties": false,
"description": "One top-exporting country.",
"properties": {
"area": {
"description": "Country name.",
"type": "string"
},
"area_code": {
"description": "Country code.",
"type": "number"
},
"flags": {
"description": "Distinct data-quality flags across the summed observations, comma-separated and sorted — commonly A=Official, B=time-series break, E=Estimated, I=Imputed, M=Missing (value cannot exist), T=Unofficial, X=from an international organization, plus others FAOSTAT defines per domain; treat any unrecognized flag as informational, never assume official. Null when no summed observation carried a flag. More than one flag means the total mixes data qualities.",
"type": [
"string",
"null"
]
},
"observations": {
"description": "Observations summed into value — one per resolved item reporting that year.",
"type": "number"
},
"unit": {
"description": "Unit of measure for value; null when unspecified. Rows are grouped by unit, so values in different units are never summed together — a country can appear once per unit.",
"type": [
"string",
"null"
]
},
"value": {
"description": "Export quantity summed across the resolved items for this country, in its latest reporting year.",
"type": "number"
},
"year": {
"description": "This country's own latest year with data, computed per country — a country whose series ends earlier still ranks, at its own last reported year.",
"type": "number"
}
},
"required": [
"area_code",
"area",
"value",
"observations",
"unit",
"year",
"flags"
],
"type": "object"
},
"type": "array"
},
"top_importers": {
"description": "Top importers by summed import quantity (empty when trade is not indexed).",
"items": {
"additionalProperties": false,
"description": "One top-importing country.",
"properties": {
"area": {
"description": "Country name.",
"type": "string"
},
"area_code": {
"description": "Country code.",
"type": "number"
},
"flags": {
"description": "Distinct data-quality flags across the summed observations, comma-separated and sorted — commonly A=Official, B=time-series break, E=Estimated, I=Imputed, M=Missing (value cannot exist), T=Unofficial, X=from an international organization, plus others FAOSTAT defines per domain; treat any unrecognized flag as informational, never assume official. Null when no summed observation carried a flag. More than one flag means the total mixes data qualities.",
"type": [
"string",
"null"
]
},
"observations": {
"description": "Observations summed into value — one per resolved item reporting that year.",
"type": "number"
},
"unit": {
"description": "Unit of measure for value; null when unspecified. Rows are grouped by unit, so values in different units are never summed together — a country can appear once per unit.",
"type": [
"string",
"null"
]
},
"value": {
"description": "Import quantity summed across the resolved items for this country, in its latest reporting year.",
"type": "number"
},
"year": {
"description": "This country's own latest year with data, computed per country — a country whose series ends earlier still ranks, at its own last reported year.",
"type": "number"
}
},
"required": [
"area_code",
"area",
"value",
"observations",
"unit",
"year",
"flags"
],
"type": "object"
},
"type": "array"
},
"top_producers": {
"description": "Top producers by summed production (countries only).",
"items": {
"additionalProperties": false,
"description": "One top-producing country.",
"properties": {
"area": {
"description": "Country name.",
"type": "string"
},
"area_code": {
"description": "Country code.",
"type": "number"
},
"flags": {
"description": "Distinct data-quality flags across the summed observations, comma-separated and sorted — commonly A=Official, B=time-series break, E=Estimated, I=Imputed, M=Missing (value cannot exist), T=Unofficial, X=from an international organization, plus others FAOSTAT defines per domain; treat any unrecognized flag as informational, never assume official. Null when no summed observation carried a flag. More than one flag means the total mixes data qualities.",
"type": [
"string",
"null"
]
},
"observations": {
"description": "Observations summed into value — one per resolved item reporting that year.",
"type": "number"
},
"unit": {
"description": "Unit of measure for value; null when unspecified. Rows are grouped by unit, so values in different units are never summed together — a country can appear once per unit.",
"type": [
"string",
"null"
]
},
"value": {
"description": "Production summed across the resolved items for this country, in its latest reporting year.",
"type": "number"
},
"year": {
"description": "This country's own latest year with data, computed per country — a country whose series ends earlier still ranks, at its own last reported year.",
"type": "number"
}
},
"required": [
"area_code",
"area",
"value",
"observations",
"unit",
"year",
"flags"
],
"type": "object"
},
"type": "array"
},
"trend_points": {
"description": "Total production observations aggregated into production_trend. Exact — the aggregation runs over the complete filtered match, not a capped page.",
"type": "number"
},
"truncated": {
"description": "True when the STAGED CANVAS TABLE hit the 50,000-row staging cap and is therefore a PREFIX of the merged observation set — re-query faostat_query_observations partitioned by year to stage the rest. The rankings and production_trend above are SQL aggregates over the complete match and stay exact either way.",
"type": "boolean"
}
},
"type": "object"
}
},
{
"description": "List the canvas tables (faostat_xxxxxxxx) staged by faostat_query_observations and faostat_commodity_profile, each with its source tool, the query parameters that produced it, creation/expiry timestamps, row count, and column schema. Call this before faostat_dataframe_query to discover the exact table and column names to reference in SQL. Tables are listed newest-first and paged: pass `name` to describe one table outright, or page with `offset` + `limit` — when the response reports `truncated`, pass the returned `nextOffset` to fetch the rest.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"canvas_id": {
"description": "Optional canvas ID as returned by a prior faostat_query_observations / faostat_commodity_profile call — exactly 10 characters of letters, digits, hyphens, and underscores. Omit to list the tables staged in this session (the common case).",
"pattern": "^[A-Za-z0-9_-]{10}$",
"type": "string"
},
"limit": {
"default": 20,
"description": "Maximum staged tables to return on this page (max 100). Each entry carries a full column schema, so the default keeps a discovery call small.",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"name": {
"description": "Optional table name (faostat_xxxxxxxx) to describe a single staged table. Takes precedence over `offset` / `limit`, which are ignored for a name lookup (always single-page).",
"type": "string"
},
"offset": {
"default": 0,
"description": "Zero-based pagination offset into the staged tables (newest first). When the response reports truncated, pass the returned nextOffset here to fetch the next page. Ignored for `name` lookups.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"name": "faostat_dataframe_describe",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"tables",
"totalMatches",
"truncated"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `canvas_disabled`: The DataCanvas service is not configured for this deployment. `canvas_not_found`: An explicit canvas_id does not resolve to a live canvas — unknown, expired, or owned by another tenant. `missing_table`: A name filter was supplied but no staged table on the resolved canvas matches it. Other values are possible when a failure originates below the handler.",
"examples": [
"canvas_disabled",
"canvas_not_found",
"missing_table"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"nextOffset": {
"description": "Offset to pass on the next call to fetch the following page. Present only when truncated is true; absent on the last page and for `name` lookups.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"notice": {
"description": "Guidance when nothing is staged yet or more pages remain.",
"type": "string"
},
"tables": {
"description": "Active staged tables for this session, newest first — one page of them. Empty when none are staged.",
"items": {
"additionalProperties": false,
"description": "Provenance and schema for one staged table.",
"properties": {
"column_schema": {
"description": "Resolved column schema for the staged table.",
"items": {
"additionalProperties": false,
"description": "One column declaration.",
"properties": {
"name": {
"description": "Column name.",
"type": "string"
},
"type": {
"description": "Canvas column type (VARCHAR, BIGINT, DOUBLE, …).",
"type": "string"
}
},
"required": [
"name",
"type"
],
"type": "object"
},
"type": "array"
},
"created_at": {
"description": "ISO 8601 creation timestamp.",
"type": "string"
},
"expires_at": {
"description": "ISO 8601 expiry timestamp. Sliding TTL touched on every staged-table op.",
"type": "string"
},
"name": {
"description": "Canvas table name (faostat_xxxxxxxx).",
"type": "string"
},
"query_params": {
"additionalProperties": {},
"description": "Input parameters the source tool was called with.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"row_count": {
"description": "Rows staged in the table.",
"type": "number"
},
"source_tool": {
"description": "Tool that staged this table.",
"type": "string"
},
"truncated": {
"description": "True when the staging cap was hit and the table holds fewer rows than the full result.",
"type": "boolean"
}
},
"required": [
"name",
"source_tool",
"query_params",
"created_at",
"expires_at",
"row_count",
"truncated",
"column_schema"
],
"type": "object"
},
"type": "array"
},
"totalMatches": {
"description": "Staged tables on the resolved canvas, before the page limit is applied.",
"type": "number"
},
"truncated": {
"description": "True when more staged tables remain beyond the returned page — fetch them with nextOffset. Always false for a single-table `name` lookup, which is never paged.",
"type": "boolean"
}
},
"type": "object"
}
},
{
"description": "Run a single-statement SELECT against the canvas tables staged by faostat_query_observations and faostat_commodity_profile (table names look like faostat_xxxxxxxx). Use this for cross-country and cross-item aggregation, GROUP BY rankings, joins, and time-series analysis over the full result set the inline preview only sampled. Standard DuckDB SQL — joins, aggregates, window functions, CTEs all work. Read-only: writes, DDL, DROP, COPY, PRAGMA, ATTACH, and external-file table functions are rejected; system catalogs (information_schema, sqlite_master, duckdb_*) are denied — list staged tables via faostat_dataframe_describe. Every row carries its data-quality `flag` — commonly A=Official, B=time-series break, E=Estimated, I=Imputed, M=Missing (value cannot exist), T=Unofficial, X=from an international organization, plus others FAOSTAT defines per domain — keep it in projections, treat any unrecognized flag as informational, and never assume it is official.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"canvas_id": {
"description": "Optional canvas ID as returned by a prior faostat_query_observations / faostat_commodity_profile call — exactly 10 characters of letters, digits, hyphens, and underscores. Omit to query the tables staged in this session (the common case).",
"pattern": "^[A-Za-z0-9_-]{10}$",
"type": "string"
},
"row_limit": {
"default": 1000,
"description": "Hard cap on rows in the response. Default 1000, max 10000.",
"maximum": 10000,
"minimum": 1,
"type": "integer"
},
"sql": {
"description": "Single-statement read-only SELECT against staged faostat_<id> tables. Columns: area_code, area, item_code, item, element_code, element, year, unit, value, flag — plus domain (QCL or TCL) on tables staged by faostat_commodity_profile.",
"minLength": 1,
"type": "string"
}
},
"required": [
"sql"
],
"type": "object"
},
"name": "faostat_dataframe_query",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"columns",
"row_count",
"rows",
"truncated"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"columns": {
"description": "Column names in projection order.",
"items": {
"type": "string"
},
"type": "array"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `canvas_disabled`: The DataCanvas service is not configured for this deployment. `canvas_not_found`: An explicit canvas_id does not resolve to a live canvas — unknown, expired, or owned by another tenant. `missing_table`: The SQL references a faostat_<id> table that has expired or was never staged. `system_catalog_access`: The SQL references a denied system catalog (information_schema, sqlite_master, duckdb_*). `invalid_sql`: The SQL has a syntax or execution error, or is not a single read-only SELECT. Other values are possible when a failure originates below the handler.",
"examples": [
"canvas_disabled",
"canvas_not_found",
"missing_table",
"system_catalog_access",
"invalid_sql"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"notice": {
"description": "Guidance when the query returned no rows or when results were capped.",
"type": "string"
},
"row_count": {
"description": "Rows returned in this response — the materialized count, equal to rows.length. When truncated is true this is NOT the full result total (this path computes no exact total); page or aggregate to reach the rest.",
"type": "number"
},
"rows": {
"description": "Materialized result rows, bounded by row_limit.",
"items": {
"additionalProperties": {},
"propertyNames": {
"type": "string"
},
"type": "object"
},
"type": "array"
},
"truncated": {
"description": "True when row_limit capped the result and more rows exist than were returned. To reach them: page with ORDER BY + SQL LIMIT/OFFSET, raise row_limit (max 10000), or aggregate with GROUP BY.",
"type": "boolean"
}
},
"type": "object"
}
},
{
"description": "Discover FAOSTAT statistical domains (production, trade, food balances, food security, land use, agri-emissions, prices, value) with their codes, descriptions, last-update date, upstream row count, and local index status. Every query keys on a domain code from here. The `indexed` flag tells you which domains are queryable right now; un-indexed domains exist in the catalog but must be added to FAOSTAT_DOMAINS and re-synced before faostat_query_observations can read them. The catalog runs to ~69 domains with long descriptions, so responses are paged: narrow with `topic` / `indexed_only`, pass `code` to fetch one domain outright, or page with `offset` + `limit` — when the response reports `truncated`, pass the returned `nextOffset` to fetch the rest.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"code": {
"description": "Exact domain code lookup (e.g. \"RL\"), case-insensitive. Returns that one domain's full record on a single page. Takes precedence over `topic` / `indexed_only` when provided.",
"type": "string"
},
"indexed_only": {
"default": false,
"description": "When true, return only domains indexed in the local mirror (queryable now).",
"type": "boolean"
},
"limit": {
"default": 20,
"description": "Maximum domains to return on this page (max 200 — above the catalog size, so raise it to fetch everything at once). Domain descriptions are long; the default keeps a browse call small.",
"maximum": 200,
"minimum": 1,
"type": "integer"
},
"offset": {
"default": 0,
"description": "Zero-based pagination offset into the matching domains (code-sorted). When the response reports truncated, pass the returned nextOffset here to fetch the next page. Ignored for exact-code lookups (always single-page).",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"topic": {
"description": "Case-insensitive substring filter over domain code, name, and topic (e.g. \"trade\", \"emissions\", \"QCL\"). Omit to list the full catalog.",
"type": "string"
}
},
"type": "object"
},
"name": "faostat_list_domains",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"domains",
"totalCount",
"totalMatches",
"truncated",
"indexedCount"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"domains": {
"description": "Matching domains, sorted by code.",
"items": {
"additionalProperties": false,
"description": "One FAOSTAT domain with catalog metadata and local mirror status.",
"properties": {
"code": {
"description": "Domain code — the key for every query (e.g. \"QCL\").",
"type": "string"
},
"description": {
"description": "Domain description, when provided.",
"type": "string"
},
"file_size_in_bytes": {
"description": "Compressed ZIP size in bytes, parsed from the manifest size string.",
"type": "number"
},
"index_ready": {
"description": "True when the local mirror for this domain has completed an initial sync.",
"type": "boolean"
},
"indexed": {
"description": "True when this domain is in the local mirror selection (FAOSTAT_DOMAINS).",
"type": "boolean"
},
"indexed_last_sync": {
"description": "ISO 8601 timestamp of the last completed local sync (when synced).",
"type": "string"
},
"indexed_row_count": {
"description": "Rows in the local mirror for this domain (present when indexed and synced).",
"type": "number"
},
"last_update": {
"description": "Upstream last-update date (ISO 8601) from the manifest.",
"type": "string"
},
"name": {
"description": "Human-readable domain name.",
"type": "string"
},
"topic": {
"description": "FAOSTAT topic grouping, when provided.",
"type": "string"
},
"upstream_row_count": {
"description": "Row count reported by the manifest for the full domain.",
"type": "number"
}
},
"required": [
"code",
"name",
"last_update",
"indexed",
"index_ready"
],
"type": "object"
},
"type": "array"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode.",
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"indexedCount": {
"description": "Domains currently indexed in the local mirror.",
"type": "number"
},
"nextOffset": {
"description": "Offset to pass on the next call to fetch the following page. Present only when truncated is true; absent on the last page and for exact-code lookups.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"notice": {
"description": "Guidance when a filter matched nothing, more pages remain, or no domains are indexed yet.",
"type": "string"
},
"totalCount": {
"description": "Total domains in the FAOSTAT catalog, independent of any filter.",
"type": "number"
},
"totalMatches": {
"description": "Domains matching the current filters, before the page limit is applied.",
"type": "number"
},
"truncated": {
"description": "True when more matches remain beyond the returned page — fetch them with nextOffset.",
"type": "boolean"
}
},
"type": "object"
}
},
{
"description": "Query a FAOSTAT domain's data cube by area(s), item(s), element(s), and year range, returning observations (area, item, element, year, value, unit, and the data-quality flag). Resolve codes first with faostat_resolve_codes — the cube is unqueryable without them. Aggregate regions (World, continents, economic groupings) are EXCLUDED by default so a naive SUM does not double-count a region with its member countries; set include_aggregates=true to get the regional roll-ups, or pass explicit area_codes to query exactly what you name. Small result sets return inline; large ones spill to a DataCanvas table (returned canvas_id + table_name) — call faostat_dataframe_describe for its columns, then faostat_dataframe_query for GROUP BY / ranking / time-series analysis. Every row carries its flag — commonly A=Official, B=time-series break, E=Estimated, I=Imputed, M=Missing (value cannot exist), T=Unofficial, X=from an international organization, plus others FAOSTAT defines per domain — so honor it, treat any unrecognized flag as informational, and never assume an estimated, imputed, or unrecognized value is official.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"area_codes": {
"description": "Area codes from faostat_resolve_codes. When set, aggregates are NOT auto-excluded — the codes are honored verbatim.",
"items": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"type": "array"
},
"canvas_id": {
"description": "Canvas ID to stage onto, as returned by a prior faostat_query_observations / faostat_commodity_profile call — exactly 10 characters of letters, digits, hyphens, and underscores. Omit to stage onto this session’s canvas, created on the first spill and reused by every later call, so tables staged earlier in the session sit alongside this one.",
"pattern": "^[A-Za-z0-9_-]{10}$",
"type": "string"
},
"domain": {
"description": "FAOSTAT domain code (e.g. \"QCL\"). Must be indexed locally.",
"minLength": 1,
"type": "string"
},
"element_codes": {
"description": "Element codes from faostat_resolve_codes (e.g. 5510 Production).",
"items": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"type": "array"
},
"include_aggregates": {
"default": false,
"description": "When false (default), exclude aggregate-region rows (codes ≥ 5000 plus a few curated sub-threshold roll-ups such as China=351) so sums are not double-counted. Set true for World/continent/grouping roll-ups. Ignored when explicit area_codes are passed.",
"type": "boolean"
},
"item_codes": {
"description": "Item codes from faostat_resolve_codes.",
"items": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"type": "array"
},
"limit": {
"default": 200,
"description": "Max observations returned inline — also the preview size when the result stages to a canvas table. Rows past it are never dropped silently: a match larger than limit stages in full to a DataCanvas table (canvas_id + table_name), and when no table is staged the notice reports how many matched so you can raise limit or narrow the filters. Max 1000.",
"maximum": 1000,
"minimum": 1,
"type": "integer"
},
"year_end": {
"description": "Inclusive end year (e.g. 2022).",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"year_start": {
"description": "Inclusive start year (e.g. 2000).",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
}
},
"required": [
"domain"
],
"type": "object"
},
"name": "faostat_query_observations",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"domain",
"observations",
"spilled",
"truncated",
"totalCount"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"canvas_id": {
"description": "Canvas ID holding the staged table (present when spilled) — pass it with table_name to faostat_dataframe_describe for the columns and types, then to faostat_dataframe_query for SQL.",
"type": "string"
},
"domain": {
"description": "The domain code echoed back.",
"type": "string"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `domain_not_indexed`: The domain is not in the local mirror selection (FAOSTAT_DOMAINS) — whether a valid FAOSTAT code or not. `index_not_ready`: The domain mirror is cold — its initial sync has never completed. `canvas_disabled`: The result is too large to inline but DataCanvas is off, so it cannot be staged for SQL. `canvas_not_found`: The result is large enough to stage and canvas_id does not resolve to a live canvas — unknown, expired, or owned by another tenant. A result that fits inline stages nothing and never consults canvas_id. `invalid_year_range`: year_start is greater than year_end — a self-contradictory range that can never match. `query_timeout`: The call's mirror reads — time queued behind other calls plus execution — ran past the 45-second per-call ceiling. Other values are possible when a failure originates below the handler.",
"examples": [
"domain_not_indexed",
"index_not_ready",
"canvas_disabled",
"canvas_not_found",
"invalid_year_range",
"query_timeout"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"notice": {
"description": "Guidance on empty results, aggregate exclusion, or how to reach the spilled set.",
"type": "string"
},
"observations": {
"description": "Inline observations (preview when the full set spilled to a canvas table).",
"items": {
"additionalProperties": false,
"description": "One observation. The flag is load-bearing — never drop or ignore it.",
"properties": {
"area": {
"description": "Area name.",
"type": "string"
},
"area_code": {
"description": "Area code.",
"type": "number"
},
"element": {
"description": "Element (metric) name.",
"type": "string"
},
"element_code": {
"description": "Element code.",
"type": "number"
},
"flag": {
"description": "Data-quality flag — commonly A=Official, B=time-series break, E=Estimated, I=Imputed, M=Missing (value cannot exist), T=Unofficial, X=from an international organization, plus others FAOSTAT defines per domain; treat any unrecognized flag as informational, never assume official. Null when unflagged.",
"type": [
"string",
"null"
]
},
"item": {
"description": "Item name.",
"type": "string"
},
"item_code": {
"description": "Item code.",
"type": "number"
},
"unit": {
"description": "Unit of measure; null when unspecified.",
"type": [
"string",
"null"
]
},
"value": {
"description": "Observed value; null when the cell is empty.",
"type": [
"number",
"null"
]
},
"year": {
"description": "Observation year.",
"type": "number"
}
},
"required": [
"area_code",
"area",
"item_code",
"item",
"element_code",
"element",
"year",
"value",
"unit",
"flag"
],
"type": "object"
},
"type": "array"
},
"spilled": {
"description": "True when the full result was staged on a DataCanvas table.",
"type": "boolean"
},
"staged_row_count": {
"description": "Rows actually staged on the canvas table (present when spilled). Equals the full match count unless truncated, in which case it is the 50,000-row cap.",
"type": "number"
},
"table_name": {
"description": "Canvas table holding the staged result set (present when spilled; a PREFIX of the match when truncated) — pass it as name to faostat_dataframe_describe, then reference it in faostat_dataframe_query SQL.",
"type": "string"
},
"totalCount": {
"description": "Observations matched. Exact when the result was returned inline or fully staged. A floor — more matched — in two cases, both named by the notice: the match exceeded the 50,000-row staging cap (truncated is then true), or staging failed and the response fell back to an inline page.",
"type": "number"
},
"truncated": {
"description": "True when the staged table hit the 50,000-row staging cap — the staged set is a PREFIX of the match, not the complete result. Partition the query by year or code ranges to capture the rest.",
"type": "boolean"
}
},
"type": "object"
}
},
{
"description": "Resolve human terms to the opaque integer codes faostat_query_observations needs, within a dimension: areas (countries/regions), items (commodities), or elements (metrics like production, yield, import quantity). Pass `query` for fuzzy full-text matching (\"maize\" → item 56), `name_contains` for a substring filter, or `code` for an exact-code lookup; omit all three to list the whole dimension. Item and element results are scoped to the requested domain — only codes present in that domain's cube are returned, so a resolved code is always queryable there (areas are shared across domains). Page large listings with `offset` + `limit`: when the response reports `truncated`, pass the returned `nextOffset` to fetch the next page. Every area match is flagged `country` or `aggregate` — aggregates (World, continents, economic groupings — codes ≥ 5000 plus a few curated sub-threshold roll-ups such as China=351, which sums mainland + Taiwan + Hong Kong + Macao) double-count if summed with their member countries, so resolve before querying and exclude aggregates unless you want the regional roll-up.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"code": {
"description": "Exact code lookup. Takes precedence over `query`/`name_contains` when provided.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"dimension": {
"description": "Which dimension to resolve: \"area\" (countries/regions), \"item\" (commodities), or \"element\" (metrics).",
"enum": [
"area",
"item",
"element"
],
"type": "string"
},
"domain": {
"description": "FAOSTAT domain code (e.g. \"QCL\"). Item and element resolution is scoped to the codes present in this domain's data; area code lists are shared across all indexed domains.",
"minLength": 1,
"type": "string"
},
"limit": {
"default": 50,
"description": "Maximum matches to return (max 200).",
"maximum": 200,
"minimum": 1,
"type": "integer"
},
"name_contains": {
"description": "Case-insensitive substring filter over the label. Used only when `query` is omitted.",
"type": "string"
},
"offset": {
"default": 0,
"description": "Zero-based pagination offset into the match set. When the response reports truncated, pass the returned nextOffset here to fetch the next page. Ignored for exact-code lookups (always single-page).",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"query": {
"description": "Full-text search term, FTS5-matched against the dimension labels with prefix matching (e.g. \"wheat\", \"import quantity\"). Relevance-ranked.",
"type": "string"
}
},
"required": [
"domain",
"dimension"
],
"type": "object"
},
"name": "faostat_resolve_codes",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"domain",
"dimension",
"matches",
"totalMatches",
"truncated"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"dimension": {
"description": "The dimension resolved.",
"type": "string"
},
"domain": {
"description": "The domain code echoed back.",
"type": "string"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `unknown_domain`: The domain code is not a selected (indexed) FAOSTAT domain. `index_not_ready`: The dimension tables are not yet populated (mirror has never completed a sync). `query_timeout`: The item or element lookup's mirror read — time queued behind other calls' reads plus execution — ran past the 45-second per-call ceiling. Other values are possible when a failure originates below the handler.",
"examples": [
"unknown_domain",
"index_not_ready",
"query_timeout"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"matches": {
"description": "Matching codes, relevance-ranked for query mode, else by code.",
"items": {
"additionalProperties": false,
"description": "One resolved code match.",
"properties": {
"code": {
"description": "The opaque integer code to pass into faostat_query_observations.",
"type": "number"
},
"cpc_code": {
"description": "CPC crosswalk code for items (apostrophe stripped), when available.",
"type": "string"
},
"kind": {
"anyOf": [
{
"enum": [
"country",
"aggregate"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "For areas: \"country\" (individual nation) or \"aggregate\" (region/grouping; excluded from sums by default). Null for items/elements."
},
"name": {
"description": "Human-readable label.",
"type": "string"
}
},
"required": [
"code",
"name",
"kind"
],
"type": "object"
},
"type": "array"
},
"nextOffset": {
"description": "Offset to pass on the next call to fetch the following page. Present only when truncated is true; absent on the last page and for exact-code lookups.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"notice": {
"description": "Guidance when nothing matched, more pages remain, or the dimension is not yet indexed.",
"type": "string"
},
"totalMatches": {
"description": "Total matches in this domain before the result cap.",
"type": "number"
},
"truncated": {
"description": "True when more matches remain beyond the returned page — fetch them with nextOffset.",
"type": "boolean"
}
},
"type": "object"
}
}
]
}Verify it yourself
curl -s https://api.teppi.xyz/v1/evidence/sha256:5d74cc5e99192ddd9e3f6a93186434ead444c45f660cda22653ad4c043e5f3a1 | sha256sum