faostat-mcp-server

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['item_query'], 'properties': {'top_n': {'type': 'integer', 'default': 10, 'maximum': 50, 'minimum': 1, 'description': 'Number of top producers / exporters / importers to return. Max 50.'}, 'year_end': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Inclusive end year for the trend (e.g. 2022).'}, 'canvas_id': {'type': 'string', 'pattern': '^[A-Za-z0-9_-]{10}$', 'description': 'Canvas ID to stage onto, as returned by a prior faostat_query_observations / faostat_commodity_profile call â\x80\x94 exactly 10 characters of letters, digits, hyphens, and underscores. Omit to stage onto this sessionâ\x80\x99s canvas, created on the first spill and reused by every later call, so tables staged earlier in the session sit alongside this one.'}, 'item_query': {'type': 'string', 'minLength': 1, '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 â\x80\x94 the response discloses how many items matched in total.'}, 'year_start': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Inclusive start year for the trend (e.g. 1990).'}}, 'additionalProperties': False}

{'type': 'object', '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']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['no_match', 'index_not_ready', 'invalid_year_range'], 'description': 'Machine-readable failure mode. Declared by this tool: `no_match`: The item query resolved to no commodity code. `index_not_ready`: The production (QCL) mirror is cold â\x80\x94 its initial sync has never completed. `invalid_year_range`: year_start is greater than year_end â\x80\x94 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. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'notice': {'type': 'string', 'description': 'Names any required domain that was not indexed, item-resolution truncation, mixed units in the rankings, or other partial-result context.'}, 'spilled': {'type': 'boolean', 'description': 'True when the merged observation set was staged on a canvas table.'}, 'canvas_id': {'type': 'string', 'description': 'Canvas ID holding the merged set â\x80\x94 pass to faostat_dataframe_query / _describe.'}, 'truncated': {'type': 'boolean', 'description': 'True when the STAGED CANVAS TABLE hit the 50,000-row staging cap and is therefore a PREFIX of the merged observation set â\x80\x94 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.'}, 'item_query': {'type': 'string', 'description': 'The commodity query echoed back.'}, 'table_name': {'type': 'string', 'description': 'Canvas table holding the staged observations â\x80\x94 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.'}, 'trend_points': {'type': 'number', 'description': 'Total production observations aggregated into production_trend. Exact â\x80\x94 the aggregation runs over the complete filtered match, not a capped page.'}, 'top_exporters': {'type': 'array', 'items': {'type': 'object', 'required': ['area_code', 'area', 'value', 'observations', 'unit', 'year', 'flags'], 'properties': {'area': {'type': 'string', 'description': 'Country name.'}, 'unit': {'type': ['string', 'null'], 'description': 'Unit of measure for value; null when unspecified. Rows are grouped by unit, so values in different units are never summed together â\x80\x94 a country can appear once per unit.'}, 'year': {'type': 'number', 'description': "This country's own latest year with data, computed per country â\x80\x94 a country whose series ends earlier still ranks, at its own last reported year."}, 'flags': {'type': ['string', 'null'], 'description': 'Distinct data-quality flags across the summed observations, comma-separated and sorted â\x80\x94 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.'}, 'value': {'type': 'number', 'description': 'Export quantity summed across the resolved items for this country, in its latest reporting year.'}, 'area_code': {'type': 'number', 'description': 'Country code.'}, 'observations': {'type': 'number', 'description': 'Observations summed into value â\x80\x94 one per resolved item reporting that year.'}}, 'description': 'One top-exporting country.', 'additionalProperties': False}, 'description': 'Top exporters by summed export quantity (empty when trade is not indexed).'}, 'top_importers': {'type': 'array', 'items': {'type': 'object', 'required': ['area_code', 'area', 'value', 'observations', 'unit', 'year', 'flags'], 'properties': {'area': {'type': 'string', 'description': 'Country name.'}, 'unit': {'type': ['string', 'null'], 'description': 'Unit of measure for value; null when unspecified. Rows are grouped by unit, so values in different units are never summed together â\x80\x94 a country can appear once per unit.'}, 'year': {'type': 'number', 'description': "This country's own latest year with data, computed per country â\x80\x94 a country whose series ends earlier still ranks, at its own last reported year."}, 'flags': {'type': ['string', 'null'], 'description': 'Distinct data-quality flags across the summed observations, comma-separated and sorted â\x80\x94 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.'}, 'value': {'type': 'number', 'description': 'Import quantity summed across the resolved items for this country, in its latest reporting year.'}, 'area_code': {'type': 'number', 'description': 'Country code.'}, 'observations': {'type': 'number', 'description': 'Observations summed into value â\x80\x94 one per resolved item reporting that year.'}}, 'description': 'One top-importing country.', 'additionalProperties': False}, 'description': 'Top importers by summed import quantity (empty when trade is not indexed).'}, 'top_producers': {'type': 'array', 'items': {'type': 'object', 'required': ['area_code', 'area', 'value', 'observations', 'unit', 'year', 'flags'], 'properties': {'area': {'type': 'string', 'description': 'Country name.'}, 'unit': {'type': ['string', 'null'], 'description': 'Unit of measure for value; null when unspecified. Rows are grouped by unit, so values in different units are never summed together â\x80\x94 a country can appear once per unit.'}, 'year': {'type': 'number', 'description': "This country's own latest year with data, computed per country â\x80\x94 a country whose series ends earlier still ranks, at its own last reported year."}, 'flags': {'type': ['string', 'null'], 'description': 'Distinct data-quality flags across the summed observations, comma-separated and sorted â\x80\x94 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.'}, 'value': {'type': 'number', 'description': 'Production summed across the resolved items for this country, in its latest reporting year.'}, 'area_code': {'type': 'number', 'description': 'Country code.'}, 'observations': {'type': 'number', 'description': 'Observations summed into value â\x80\x94 one per resolved item reporting that year.'}}, 'description': 'One top-producing country.', 'additionalProperties': False}, 'description': 'Top producers by summed production (countries only).'}, 'itemsTruncated': {'type': 'boolean', 'description': 'True when the commodity name matched more items than the profile folded in â\x80\x94 the profile then covers only the most relevant few.'}, 'resolved_items': {'type': 'array', 'items': {'type': 'object', 'required': ['code', 'name'], 'properties': {'code': {'type': 'number', 'description': 'Resolved item code.'}, 'name': {'type': 'string', 'description': 'Resolved item name.'}}, 'description': 'One resolved commodity.', 'additionalProperties': False}, 'description': 'Commodities the query resolved to (the profile aggregates across all of them).'}, 'production_trend': {'type': 'array', 'items': {'type': 'object', 'required': ['year', 'value', 'observations', 'unit', 'flags'], 'properties': {'unit': {'type': ['string', 'null'], '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.'}, 'year': {'type': 'number', 'description': 'Observation year.'}, 'flags': {'type': ['string', 'null'], 'description': 'Distinct data-quality flags across the summed observations, comma-separated and sorted â\x80\x94 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.'}, 'value': {'type': 'number', 'description': 'Production summed across every country and resolved item reporting that year.'}, 'observations': {'type': 'number', 'description': 'Observations summed into value â\x80\x94 read it alongside value, since a change in coverage moves the total independently of production.'}}, 'description': 'One annual trend point.', 'additionalProperties': False}, '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.'}, 'staged_row_count': {'type': 'number', 'description': 'Rows actually staged on the merged canvas table (present when spilled). Equals the 50,000-row cap when truncated.'}, 'resolvedItemCodes': {'type': 'array', 'items': {'type': 'number'}, 'description': 'Item codes the commodity query resolved to.'}, 'resolvedItemMatches': {'type': 'number', 'description': 'Total items the commodity query matched in QCL, before the 5-item profile cap.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'name': {'type': 'string', '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).'}, 'limit': {'type': 'integer', 'default': 20, 'maximum': 100, 'minimum': 1, '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.'}, 'offset': {'type': 'integer', 'default': 0, 'maximum': 9007199254740991, 'minimum': 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.'}, 'canvas_id': {'type': 'string', 'pattern': '^[A-Za-z0-9_-]{10}$', 'description': 'Optional canvas ID as returned by a prior faostat_query_observations / faostat_commodity_profile call â\x80\x94 exactly 10 characters of letters, digits, hyphens, and underscores. Omit to list the tables staged in this session (the common case).'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['tables', 'totalMatches', 'truncated']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['canvas_disabled', 'canvas_not_found', 'missing_table'], '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 â\x80\x94 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.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'notice': {'type': 'string', 'description': 'Guidance when nothing is staged yet or more pages remain.'}, 'tables': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'source_tool', 'query_params', 'created_at', 'expires_at', 'row_count', 'truncated', 'column_schema'], 'properties': {'name': {'type': 'string', 'description': 'Canvas table name (faostat_xxxxxxxx).'}, 'row_count': {'type': 'number', 'description': 'Rows staged in the table.'}, 'truncated': {'type': 'boolean', 'description': 'True when the staging cap was hit and the table holds fewer rows than the full result.'}, 'created_at': {'type': 'string', 'description': 'ISO 8601 creation timestamp.'}, 'expires_at': {'type': 'string', 'description': 'ISO 8601 expiry timestamp. Sliding TTL touched on every staged-table op.'}, 'source_tool': {'type': 'string', 'description': 'Tool that staged this table.'}, 'query_params': {'type': 'object', 'description': 'Input parameters the source tool was called with.', 'propertyNames': {'type': 'string'}, 'additionalProperties': {}}, 'column_schema': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'type'], 'properties': {'name': {'type': 'string', 'description': 'Column name.'}, 'type': {'type': 'string', 'description': 'Canvas column type (VARCHAR, BIGINT, DOUBLE, â\x80¦).'}}, 'description': 'One column declaration.', 'additionalProperties': False}, 'description': 'Resolved column schema for the staged table.'}}, 'description': 'Provenance and schema for one staged table.', 'additionalProperties': False}, 'description': 'Active staged tables for this session, newest first â\x80\x94 one page of them. Empty when none are staged.'}, 'truncated': {'type': 'boolean', 'description': 'True when more staged tables remain beyond the returned page â\x80\x94 fetch them with nextOffset. Always false for a single-table `name` lookup, which is never paged.'}, 'nextOffset': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, '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.'}, 'totalMatches': {'type': 'number', 'description': 'Staged tables on the resolved canvas, before the page limit is applied.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['sql'], 'properties': {'sql': {'type': 'string', 'minLength': 1, '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. CAST(value AS DOUBLE) for arithmetic.'}, 'canvas_id': {'type': 'string', 'pattern': '^[A-Za-z0-9_-]{10}$', 'description': 'Optional canvas ID as returned by a prior faostat_query_observations / faostat_commodity_profile call â\x80\x94 exactly 10 characters of letters, digits, hyphens, and underscores. Omit to query the tables staged in this session (the common case).'}, 'row_limit': {'type': 'integer', 'default': 1000, 'maximum': 10000, 'minimum': 1, 'description': 'Hard cap on rows in the response. Default 1000, max 10000.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['columns', 'row_count', 'rows', 'truncated']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'rows': {'type': 'array', 'items': {'type': 'object', 'propertyNames': {'type': 'string'}, 'additionalProperties': {}}, 'description': 'Materialized result rows, bounded by row_limit.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['canvas_disabled', 'canvas_not_found', 'missing_table', 'system_catalog_access', 'invalid_sql'], '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 â\x80\x94 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.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'notice': {'type': 'string', 'description': 'Guidance when the query returned no rows or when results were capped.'}, 'columns': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Column names in projection order.'}, 'row_count': {'type': 'number', 'description': 'Rows returned in this response â\x80\x94 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.'}, 'truncated': {'type': 'boolean', '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.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'code': {'type': 'string', '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.'}, 'limit': {'type': 'integer', 'default': 20, 'maximum': 200, 'minimum': 1, 'description': 'Maximum domains to return on this page (max 200 â\x80\x94 above the catalog size, so raise it to fetch everything at once). Domain descriptions are long; the default keeps a browse call small.'}, 'topic': {'type': 'string', 'description': 'Case-insensitive substring filter over domain code, name, and topic (e.g. "trade", "emissions", "QCL"). Omit to list the full catalog.'}, 'offset': {'type': 'integer', 'default': 0, 'maximum': 9007199254740991, 'minimum': 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).'}, 'indexed_only': {'type': 'boolean', 'default': False, 'description': 'When true, return only domains indexed in the local mirror (queryable now).'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['domains', 'totalCount', 'totalMatches', 'truncated', 'indexedCount']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'description': 'Machine-readable failure mode.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'notice': {'type': 'string', 'description': 'Guidance when a filter matched nothing, more pages remain, or no domains are indexed yet.'}, 'domains': {'type': 'array', 'items': {'type': 'object', 'required': ['code', 'name', 'last_update', 'indexed', 'index_ready'], 'properties': {'code': {'type': 'string', 'description': 'Domain code â\x80\x94 the key for every query (e.g. "QCL").'}, 'name': {'type': 'string', 'description': 'Human-readable domain name.'}, 'topic': {'type': 'string', 'description': 'FAOSTAT topic grouping, when provided.'}, 'indexed': {'type': 'boolean', 'description': 'True when this domain is in the local mirror selection (FAOSTAT_DOMAINS).'}, 'description': {'type': 'string', 'description': 'Domain description, when provided.'}, 'index_ready': {'type': 'boolean', 'description': 'True when the local mirror for this domain has completed an initial sync.'}, 'last_update': {'type': 'string', 'description': 'Upstream last-update date (ISO 8601) from the manifest.'}, 'indexed_last_sync': {'type': 'string', 'description': 'ISO 8601 timestamp of the last completed local sync (when synced).'}, 'indexed_row_count': {'type': 'number', 'description': 'Rows in the local mirror for this domain (present when indexed and synced).'}, 'file_size_in_bytes': {'type': 'number', 'description': 'Compressed ZIP size in bytes, parsed from the manifest size string.'}, 'upstream_row_count': {'type': 'number', 'description': 'Row count reported by the manifest for the full domain.'}}, 'description': 'One FAOSTAT domain with catalog metadata and local mirror status.', 'additionalProperties': False}, 'description': 'Matching domains, sorted by code.'}, 'truncated': {'type': 'boolean', 'description': 'True when more matches remain beyond the returned page â\x80\x94 fetch them with nextOffset.'}, 'nextOffset': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, '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.'}, 'totalCount': {'type': 'number', 'description': 'Total domains in the FAOSTAT catalog, independent of any filter.'}, 'indexedCount': {'type': 'number', 'description': 'Domains currently indexed in the local mirror.'}, 'totalMatches': {'type': 'number', 'description': 'Domains matching the current filters, before the page limit is applied.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['domain'], 'properties': {'limit': {'type': 'integer', 'default': 200, 'maximum': 1000, 'minimum': 1, 'description': 'Max observations returned inline â\x80\x94 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': {'type': 'string', 'minLength': 1, 'description': 'FAOSTAT domain code (e.g. "QCL"). Must be indexed locally.'}, 'year_end': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Inclusive end year (e.g. 2022).'}, 'canvas_id': {'type': 'string', 'pattern': '^[A-Za-z0-9_-]{10}$', 'description': 'Canvas ID to stage onto, as returned by a prior faostat_query_observations / faostat_commodity_profile call â\x80\x94 exactly 10 characters of letters, digits, hyphens, and underscores. Omit to stage onto this sessionâ\x80\x99s 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': {'type': 'array', 'items': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'description': 'Area codes from faostat_resolve_codes. When set, aggregates are NOT auto-excluded â\x80\x94 the codes are honored verbatim.'}, 'item_codes': {'type': 'array', 'items': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'description': 'Item codes from faostat_resolve_codes.'}, 'year_start': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Inclusive start year (e.g. 2000).'}, 'element_codes': {'type': 'array', 'items': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'description': 'Element codes from faostat_resolve_codes (e.g. 5510 Production).'}, 'include_aggregates': {'type': 'boolean', 'default': False, 'description': 'When false (default), exclude aggregate-region rows (codes â\x89¥ 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.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['domain', 'observations', 'spilled', 'truncated', 'totalCount']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['domain_not_indexed', 'index_not_ready', 'canvas_disabled', 'invalid_year_range'], 'description': 'Machine-readable failure mode. Declared by this tool: `domain_not_indexed`: The domain is not in the local mirror selection (FAOSTAT_DOMAINS) â\x80\x94 whether a valid FAOSTAT code or not. `index_not_ready`: The domain mirror is cold â\x80\x94 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. `invalid_year_range`: year_start is greater than year_end â\x80\x94 a self-contradictory range that can never match. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'domain': {'type': 'string', 'description': 'The domain code echoed back.'}, 'notice': {'type': 'string', 'description': 'Guidance on empty results, aggregate exclusion, or how to reach the spilled set.'}, 'spilled': {'type': 'boolean', 'description': 'True when the full result was staged on a DataCanvas table.'}, 'canvas_id': {'type': 'string', 'description': 'Canvas ID holding the staged result â\x80\x94 pass to faostat_dataframe_query / _describe.'}, 'truncated': {'type': 'boolean', 'description': 'True when the staged table hit the 50,000-row staging cap â\x80\x94 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': {'type': 'string', 'description': 'Canvas table name holding the full result set (present when spilled).'}, 'totalCount': {'type': 'number', 'description': 'Observations matched. Exact when the result was returned inline or fully staged. A floor â\x80\x94 more matched â\x80\x94 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': {'type': 'array', 'items': {'type': 'object', 'required': ['area_code', 'area', 'item_code', 'item', 'element_code', 'element', 'year', 'value', 'unit', 'flag'], 'properties': {'area': {'type': 'string', 'description': 'Area name.'}, 'flag': {'type': ['string', 'null'], 'description': 'Data-quality flag â\x80\x94 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.'}, 'item': {'type': 'string', 'description': 'Item name.'}, 'unit': {'type': ['string', 'null'], 'description': 'Unit of measure; null when unspecified.'}, 'year': {'type': 'number', 'description': 'Observation year.'}, 'value': {'type': ['number', 'null'], 'description': 'Observed value; null when the cell is empty.'}, 'element': {'type': 'string', 'description': 'Element (metric) name.'}, 'area_code': {'type': 'number', 'description': 'Area code.'}, 'item_code': {'type': 'number', 'description': 'Item code.'}, 'element_code': {'type': 'number', 'description': 'Element code.'}}, 'description': 'One observation. The flag is load-bearing â\x80\x94 never drop or ignore it.', 'additionalProperties': False}, 'description': 'Inline observations (preview when the full set spilled to a canvas table).'}, 'staged_row_count': {'type': 'number', '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.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['domain', 'dimension'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Exact code lookup. Takes precedence over `query`/`name_contains` when provided.'}, 'limit': {'type': 'integer', 'default': 50, 'maximum': 200, 'minimum': 1, 'description': 'Maximum matches to return (max 200).'}, 'query': {'type': 'string', 'description': 'Full-text search term, FTS5-matched against the dimension labels with prefix matching (e.g. "wheat", "import quantity"). Relevance-ranked.'}, 'domain': {'type': 'string', 'minLength': 1, '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.'}, 'offset': {'type': 'integer', 'default': 0, 'maximum': 9007199254740991, 'minimum': 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).'}, 'dimension': {'enum': ['area', 'item', 'element'], 'type': 'string', 'description': 'Which dimension to resolve: "area" (countries/regions), "item" (commodities), or "element" (metrics).'}, 'name_contains': {'type': 'string', 'description': 'Case-insensitive substring filter over the label. Used only when `query` is omitted.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['domain', 'dimension', 'matches', 'totalMatches', 'truncated']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['unknown_domain', 'index_not_ready'], '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). Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'domain': {'type': 'string', 'description': 'The domain code echoed back.'}, 'notice': {'type': 'string', 'description': 'Guidance when nothing matched, more pages remain, or the dimension is not yet indexed.'}, 'matches': {'type': 'array', 'items': {'type': 'object', 'required': ['code', 'name', 'kind'], 'properties': {'code': {'type': 'number', 'description': 'The opaque integer code to pass into faostat_query_observations.'}, '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': {'type': 'string', 'description': 'Human-readable label.'}, 'cpc_code': {'type': 'string', 'description': 'CPC crosswalk code for items (apostrophe stripped), when available.'}}, 'description': 'One resolved code match.', 'additionalProperties': False}, 'description': 'Matching codes, relevance-ranked for query mode, else by code.'}, 'dimension': {'type': 'string', 'description': 'The dimension resolved.'}, 'truncated': {'type': 'boolean', 'description': 'True when more matches remain beyond the returned page â\x80\x94 fetch them with nextOffset.'}, 'nextOffset': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, '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.'}, 'totalMatches': {'type': 'number', 'description': 'Total matches in this domain before the result cap.'}}, 'additionalProperties': False}