faostat-mcp-server: query observations
faostat_query_observationsQuery a FAOSTAT domain's data cube by area(s), item(s), element(s), sources, and year range, returning values with units and data-quality flags. Resolve numeric codes or exact alphanumeric item identities with faostat_resolve_codes; element resolution accepts item selectors and returns units. Empty queries with explicit items and elements list available elements for those items across the domain, without establishing area/year/source coverage. Aggregate regions are excluded by default; include_aggregates=true returns roll-ups, and explicit area_codes are honored verbatim. Item groups can overlap their members even with matching units; they remain included, and kind=null does not establish safe-to-sum. Keep source methodologies separate. Small results return inline; large ones spill to a DataCanvas table (canvas_id + table_name); call faostat_dataframe_describe for columns, then faostat_dataframe_query for analysis. Honor every row's flag: commonly A=Official, B=time-series break, E=Estimated, I=Imputed, M=Missing, T=Unofficial, X=international organization; unrecognized flags never establish official status.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"domain": "<domain>"
},
"name": "faostat_query_observations"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | 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. | |
| domain | Yes | FAOSTAT domain code (e.g. "QCL"). Must be indexed locally. | |
| year_end | No | Inclusive end year (e.g. 2022). | |
| canvas_id | No | 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. | |
| area_codes | No | Area codes from faostat_resolve_codes. When set, aggregates are NOT auto-excluded — the codes are honored verbatim. | |
| item_codes | No | Item codes from faostat_resolve_codes. | |
| year_start | No | Inclusive start year (e.g. 2000). | |
| source_codes | No | Exact source codes, such as 3050 or 3051 in GLE. Omit to return every methodology; choose or group sources before summing. | |
| element_codes | No | Element codes from faostat_resolve_codes (e.g. 5510 Production). | |
| item_codes_text | No | Exact alphanumeric item identities from resolver code_text; mutually exclusive with item_codes. Numeric codes use item_codes. | |
| include_aggregates | No | 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. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| domain | No | The domain code echoed back. | |
| notice | No | Guidance on empty results, aggregate exclusion, or how to reach the spilled set. | |
| spilled | No | True when the full result was staged on a DataCanvas table. | |
| canvas_id | No | 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. | |
| truncated | No | 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. | |
| table_name | No | 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. | |
| totalCount | No | 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. | |
| observations | No | Inline observations (preview when the full set spilled to a canvas table). | |
| staged_row_count | No | 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. | |
| available_elements | No | On an empty query with explicit items and elements: all elements available for those items across the domain. Does not establish coverage for requested area/year/source filters. |