faostat-mcp-server

Name: faostat-mcp-server
Author: cyanheads

Server Details

UN FAOSTAT global food & agriculture statistics over a local SQLite mirror, via MCP.

If you are the author of this connector, you can claim ownership by verifying the domain or GitHub account it belongs to. Claimed connector authors can inspect health checks, view analytics, and manage their listing.

Status: Healthy
Uptime: 99.8% over 82 days
Last Tested: 2026-11-07 11:21
Transport: Streamable HTTP · MCP 2025-11-25
URL
Repository: cyanheads/faostat-mcp-server
GitHub Stars: 3
Server Listing: @cyanheads/faostat-mcp-server
ChatGPT: –
Claude: –

TDQS

A4.5/5.0

Scored 2026-11-03 22:01 across 6 tools

Disambiguation5/5

Each tool has a clearly distinct role: catalog discovery (list_domains), identifier resolution (resolve_codes), raw observation querying (query_observations), high-level profiling (commodity_profile), spill-table inspection (dataframe_describe), and SQL analysis (dataframe_query). The boundary between query_observations and commodity_profile is explicitly described as the latter being a one-call convenience wrapper, so misselection risk is low.

Naming Consistency4/5

All tools use the same faostat_ prefix and snake_case style, and most follow a verb_noun pattern (list_domains, resolve_codes, query_observations, dataframe_describe, dataframe_query). faostat_commodity_profile is the one minor deviation, using a noun-only label, but it remains predictable and readable.

Tool Count5/5

Six tools is well-scoped for a read-only FAOSTAT data-access server. Each tool covers a necessary phase of the workflow—discover, resolve, query, profile, inspect spill tables, and analyze—without redundant surface area.

Completeness4/5

The surface covers the core lifecycle for analytical access: domain discovery, code resolution, observation querying, commodity profiling, and canvas SQL analysis. Minor gaps exist around standalone metadata retrieval or export workflows, but agents can accomplish all essential query and analysis tasks with the available tools.

Available Tools

6 tools

faostat_commodity_profilefaostat-mcp-server: commodity profileA

Read-only

Inspect

Assemble a global profile for one QCL item in a single call: top-producing countries, the annual production trend, and trade flows (top exporters and importers). Supply item_code or item_query; code wins when both are supplied. A query selects a unique normalized exact label, otherwise a unique relevance match; ambiguous queries require an explicit code. Each ranking uses the selected item at each country's own latest year with data, grouped by unit. The trend is returned inline as year/value points. Country-level only (aggregates excluded). QCL is required; unavailable TCL yields a production-only profile with a notice. 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.

Name	Required	Description
`top_n`	No	Number of top producers / exporters / importers to return. Max 50.
`year_end`	No	Inclusive end year for the trend (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.
`item_code`	No	Exact item code present in QCL; takes precedence over item_query. Obtain it from faostat_resolve_codes with domain QCL and dimension item.
`item_query`	No	Commodity label or search term (e.g. "Wheat"). A unique normalized exact QCL label wins, otherwise the relevance search must match exactly one item. Broad queries such as "maize" or "milk" require item_code. Supply this or item_code.
`year_start`	No	Inclusive start year for the trend (e.g. 1990).

Output Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`notice`	No	States where the observation set went — the canvas table, inline result, staging failure, or disabled canvas — plus unavailable trade data, mixed units, or other partial-result context.
`spilled`	No	True when the merged observation set was staged on a canvas table.
`canvas_id`	No	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.
`truncated`	No	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.
`item_query`	No	Supplied query echoed back, or the canonical selected label for code-only calls.
`table_name`	No	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.
`trend_points`	No	Total production observations aggregated into production_trend. Exact — the aggregation runs over the complete filtered match, not a capped page.
`top_exporters`	No	Top exporters by summed export quantity (empty when trade is not indexed).
`top_importers`	No	Top importers by summed import quantity (empty when trade is not indexed).
`top_producers`	No	Top producers by summed production (countries only).
`itemsTruncated`	No	Always false: successful profiles select one item without truncating selection.
`resolved_items`	No	The single selected QCL item and its canonical label.
`production_trend`	No	The annual production series for the selected item, summed over countries 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`	No	Rows actually staged on the merged canvas table (present when spilled). Equals the 50,000-row cap when truncated.
`resolvedItemCodes`	No	Item codes the commodity query resolved to.
`resolvedItemMatches`	No	Number of selected QCL items; always one for a successful profile.

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only cover the read-only/open-world/idempotency profile, so the description carries extra behavioral weight and delivers: country-level only (aggregates excluded), each ranking resolved at each country's own latest year with data, grouping by unit, TCL-unavailable fallback with a notice, and the DataCanvas spill contract (canvas_id + table_name). This is exactly the context annotations cannot supply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the deliverable, then progressively tightens to parameter rules and the spill path; no filler sentences. It is dense enough that the ambiguity and spill rules sit late in the block, slightly hurting scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation, and the description instead covers the things an agent actually needs to predict: fallback when TCL is missing, country-only scoping, and the spill-to-DataCanvas handoff with named follow-up tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds genuinely non-redundant semantics: precedence of item_code over item_query and the uniqueness/ambiguity rule that forces an explicit code. Trend fields (year_start/year_end) and canvas_id staging are left to the schema, so it does not fully close the loop.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb and resource ('Assemble a global profile for one QCL item') and enumerates the three outputs it bundles: top producers, annual production trend, and trade flows. It also implicitly separates itself from sibling faostat_query_observations by being a pre-composed multi-part profile rather than a raw observation fetch.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete selection rules: supply item_code or item_query, code wins on conflict, ambiguous queries require an explicit code, and QCL is required while TCL degrades to a production-only profile with a notice. It also routes downstream work to faostat_dataframe_describe and faostat_dataframe_query on spill, though it never explicitly contrasts itself with faostat_query_observations as an alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

faostat_dataframe_describefaostat-mcp-server: dataframe describeA

Read-onlyIdempotent

Inspect

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.

Name	Required	Description
`name`	No	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`	No	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`	No	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`	No	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).

Output Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Guidance when nothing is staged yet or more pages remain.
`tables`	No	Active staged tables for this session, newest first — one page of them. Empty when none are staged.
`truncated`	No	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.
`nextOffset`	No	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`	No	Staged tables on the resolved canvas, before the page limit is applied.

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover safety (readOnlyHint, idempotentHint, closed-world), and the description adds genuine behavioral context beyond them: newest-first ordering, pagination with a `truncated` signal and `nextOffset` continuation, and that name lookups are always single-page. It doesn't state expiry semantics in detail (tables carry expiry timestamps but the consequence of expiry is unstated), which keeps it from a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with what the tool returns before the call-ordering guidance, with no filler. Minor redundancy: the precedence and nextOffset rules appear in both the description and the parameter schemas.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values needn't be explained, and annotations carry the safety profile. The description still supplies everything an agent needs to invoke it correctly: when to call it, the two invocation modes, and how to continue a paged listing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema descriptions already state that `name` takes precedence over `offset`/`limit` and that `nextOffset` should be fed back. The description restates this pagination contract in prose, which reinforces but does not materially extend what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List the canvas tables (faostat_xxxxxxxx) staged by...') and enumerates what each entry carries: source tool, query parameters, timestamps, row count, column schema. It also names the sibling it feeds into (faostat_dataframe_query), so an agent can distinguish it from the query tools without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly prescribes call ordering ('Call this before faostat_dataframe_query to discover the exact table and column names to reference in SQL') and explains the two modes: name lookup versus offset/limit paging. The truncated/nextOffset continuation rule tells the agent exactly what to do on a partial response.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

faostat_dataframe_queryfaostat-mcp-server: dataframe queryA

Read-onlyIdempotent

Inspect

Run a single-statement SELECT against canvas tables staged by faostat_query_observations and faostat_commodity_profile (faostat_xxxxxxxx). Use DuckDB joins, aggregates, window functions, and CTEs for rankings and time-series analysis. Item groups can overlap their members even with matching units; do not sum them together, and resolver kind=null does not establish safe-to-sum. Separate source methodologies and respect bounded values and multi-year periods. Read-only: writes, DDL, DROP, COPY, PRAGMA, ATTACH, and external-file functions are rejected; system catalogs are denied. List tables and columns with faostat_dataframe_describe. Preserve data-quality flags in projections: commonly A=Official, B=time-series break, E=Estimated, I=Imputed, M=Missing, T=Unofficial, X=international organization; unrecognized flags never establish official status.

Name	Required	Description
`sql`	Yes	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.
`canvas_id`	No	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).
`row_limit`	No	Hard cap on rows in the response. Default 1000, max 10000.

Output Schema

Name	Required	Description
`rows`	No	Materialized result rows, bounded by row_limit.
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Guidance when the query returned no rows or when results were capped.
`columns`	No	Column names in projection order.
`row_count`	No	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.
`truncated`	No	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.

TDQS

A4.3/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint, yet the description adds substantial context beyond them: the exact rejected statement classes (writes, DDL, DROP, COPY, PRAGMA, ATTACH, external-file functions) and denial of system catalogs. It also discloses semantic hazards an agent would otherwise miss — overlapping item groups with matching units, distinct source methodologies, bounded values, and multi-year periods.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and staging dependency, then organized into safety, discovery, and flag semantics. It is dense and several sentences are semicolon-chained, and the full flag glossary is arguably longer than needed, but nearly every clause carries operational meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex SQL-execution tool, the description covers the sandbox boundaries, table naming, sibling for schema discovery, and data-quality flag semantics; the output schema carries return values. It does not address error/failure reporting or how row_limit interacts with large results, leaving a small gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so sql, canvas_id, and row_limit are already documented in the schema, including the omit-to-use-session-tables behavior. The description adds only the faostat_xxxxxxxx table naming pattern and does not elaborate on row_limit or SQL constraints beyond what the schema states. Baseline 3 applies when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Run a single-statement SELECT against canvas tables staged by faostat_query_observations and faostat_commodity_profile (faostat_xxxxxxxx)'. The staging dependency and table-naming convention distinguish it cleanly from siblings such as faostat_dataframe_describe and the staging tools themselves.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete usage context — DuckDB joins, aggregates, window functions and CTEs for rankings and time-series — and routes schema discovery to faostat_dataframe_describe. It also supplies analytical guardrails (don't sum overlapping item groups, resolver kind=null is not safe-to-sum). It stops short of an explicit when-not-to-use statement relative to faostat_query_observations, so it is strong but not exhaustive.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

faostat_list_domainsfaostat-mcp-server: list domainsA

Read-onlyIdempotent

Inspect

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.

Name	Required	Description
`code`	No	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`	No	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.
`topic`	No	Case-insensitive substring filter over domain code, name, and topic (e.g. "trade", "emissions", "QCL"). Omit to list the full catalog.
`offset`	No	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`	No	When true, return only domains indexed in the local mirror (queryable now).

Output Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Guidance when a filter matched nothing, more pages remain, or no domains are indexed yet.
`domains`	No	Matching domains, sorted by code.
`truncated`	No	True when more matches remain beyond the returned page — fetch them with nextOffset.
`nextOffset`	No	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`	No	Total domains in the FAOSTAT catalog, independent of any filter.
`indexedCount`	No	Domains currently indexed in the local mirror.
`totalMatches`	No	Domains matching the current filters, before the page limit is applied.

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint:true and idempotentHint:true, and the description does not contradict these. Beyond annotations, it discloses substantial behavioral traits: pagination with the truncated flag and nextOffset, the indexed flag meaning queryability, the precedence of code over other filters, and the absence of un-indexed domains from queries. This adds rich context beyond what annotations provide, fully satisfying the burden.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long (roughly 200 words) but every sentence contributes: purpose, indexing semantics, pagination, and filter guidance. It is front-loaded with the core purpose and then elaborates on usage. It could be trimmed slightly without loss, but the density of value justifies a 4 rather than a 5, as a more compact version would be possible while retaining clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's five parameters, pagination, and indexing logic, the description covers everything an agent needs to call it correctly: the exact fields, filter behavior, precedence, pagination with truncated/nextOffset, and the relationship to querying. The presence of an output schema means return values are defined there, and the description still mentions the truncated flag and nextOffset, which are key for iterative calling. It is complete for its complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with detailed per-parameter descriptions, so the baseline is 3. The description adds cross-parameter semantics such as code's precedence over topic/indexed_only, the pagination flow with offset/limit, and the meaning of indexed_only in the broader workflow. It also clarifies the purpose of limit relative to catalog size. This goes beyond simply restating schema fields, though the schema already covers much, so a 4 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states what the tool does: 'Discover FAOSTAT statistical domains' and enumerates the specific attributes returned (codes, descriptions, last-update date, etc.). It uses a specific verb (discover/list) and resource (domains), and distinguishes itself from siblings by explaining that domain codes from here are the entry point for faostat_query_observations, a sibling tool. This gives unambiguous purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit guidance: 'Every query keys on a domain code from here' and states that un-indexed domains must be added to FAOSTAT_DOMAINS before faostat_query_observations can read them. It also explains when to narrow with filters, when to pass a code, and how to page. This is direct 'when to use' advice, including interplay with a named sibling tool, exceeding mere implication.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

faostat_query_observationsfaostat-mcp-server: query observationsA

Read-only

Inspect

Query 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.

Name	Required	Description
`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
`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.

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/openWorld=false, but the description adds substantial behavior beyond them: aggregate regions excluded by default unless include_aggregates=true, explicit area_codes honored verbatim, overlapping item groups and kind=null not establishing safe-to-sum, source methodologies must be kept separate before summing, and unrecognized flags never establishing official status. It also discloses the inline-vs-canvas spill threshold behavior, which is exactly the kind of operational trait an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then workflow guidance, then behavioral caveats, and every clause carries signal. It is dense with semicolons and slightly long, and the canvas spill mechanics duplicate what the limit and canvas_id schema descriptions already say, so it is not maximally tight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter analytic tool with an output schema, the description covers the missing pieces an agent cannot infer: prerequisite resolution, aggregate default behavior, the spill-to-canvas handoff workflow, and data-quality flag interpretation. The output schema handles return shape, so nothing material is left unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: element resolution accepts item selectors and returns units, item_codes_text must be exact alphanumeric identities and is mutually exclusive with item_codes, and source_codes omission returns every methodology (with a warning to separate before summing). Year range and include_aggregates interaction are also clarified, though limit/canvas_id details largely restate the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Query a FAOSTAT domain's data cube') and enumerates the filter axes and return payload (values with units and data-quality flags). It also names the sibling resolvers it depends on, so an agent can distinguish it from faostat_resolve_codes and the dataframe tools without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing guidance: resolve codes or alphanumeric item identities with faostat_resolve_codes, and after a canvas spill call faostat_dataframe_describe for columns then faostat_dataframe_query for analysis. It also explains the empty-query semantics (pass items and elements to list available elements) and when to set include_aggregates, so the agent knows both when to use it and how to vary the call.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

faostat_resolve_codesfaostat-mcp-server: resolve codesA

Read-onlyIdempotent

Inspect

Resolve labels to the numeric codes or exact alphanumeric item identities faostat_query_observations needs: areas (countries/regions), items (commodities), and elements (metrics). Use query for full-text matching, name_contains for substring matching, code or code_text for exact identity, or omit them to list. Item and element matches occur in the selected domain; areas use shared vocabulary. For elements, optionally pass item_codes or item_codes_text to discover metrics and distinct units observed for those items; this does not establish area/year/source coverage. Empty item selectors match nothing. Page with offset and limit using nextOffset when truncated. Areas carry country/aggregate classification. Verified domain-specific item groups carry aggregate; null means unclassified, not safe-to-sum. Item groups can overlap their members even with matching units. Area aggregates include codes ≥ 5000 and curated roll-ups such as China=351; exclude overlapping regional and country rows when summing.

Name	Required	Description
`code`	No	Exact code lookup. Takes precedence over `query`/`name_contains` when provided.
`limit`	No	Maximum matches to return (max 200).
`query`	No	Full-text search term, FTS5-matched against the dimension labels with prefix matching (e.g. "wheat", "import quantity"). Relevance-ranked.
`domain`	Yes	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`	No	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).
`code_text`	No	Exact alphanumeric item code. Only for dimension item; mutually exclusive with code. Numeric identities use code.
`dimension`	Yes	Which dimension to resolve: "area" (countries/regions), "item" (commodities), or "element" (metrics).
`item_codes`	No	For element resolution only: restrict elements and units to these items. Empty matches nothing; omit for domain-wide elements. Mutually exclusive with item_codes_text.
`name_contains`	No	Case-insensitive substring filter over the label. Used only when `query` is omitted.
`item_codes_text`	No	For element resolution only: restrict elements and units to these exact text items. Empty matches nothing; mutually exclusive with item_codes.

Output Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`domain`	No	The domain code echoed back.
`notice`	No	Guidance when nothing matched, more pages remain, or the dimension is not yet indexed.
`matches`	No	Matching codes, relevance-ranked for query mode, else by code.
`dimension`	No	The dimension resolved.
`truncated`	No	True when more matches remain beyond the returned page — fetch them with nextOffset.
`nextOffset`	No	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`	No	Total matches in this domain before the result cap.

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/closed-world, so the bar is lower, and the description clears it by disclosing domain scoping (items/elements domain-bound, areas shared), truncation/nextOffset paging, and that empty item selectors match nothing. It goes further with aggregation hazards: null aggregate means unclassified not safe-to-sum, item groups overlap their members, and area aggregates include codes >= 5000 plus curated roll-ups like China=351. Only the absence of a concrete return-shape note keeps it from 5, and an output schema exists anyway.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and selector routing are front-loaded, and every sentence carries operational content. It is a dense single paragraph with compressed jargon in the aggregate/overlap sentences, which slows parsing for an agent skimming the definition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter resolver with an output schema, the description covers the remaining risk surface: selector precedence, pagination, domain scoping, and double-counting pitfalls when summing aggregates. Nothing an agent needs to call and interpret this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds workflow-level meaning beyond field docs: the precedence of code over query/name_contains and the caveat that element item filtering does not establish area/year/source coverage. Some of it repeats the schema (nextOffset paging, empty-selector behavior), so it is additive rather than transformative.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (resolve) and resource (area/item/element labels to codes) and ties the output directly to what faostat_query_observations consumes, which distinguishes it from every sibling. An agent can tell it is the code-lookup prerequisite step without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes between selector modes: query for full-text, name_contains for substring, code/code_text for exact identity, omit to list. It also states the downstream consumer (faostat_query_observations) and the element-specific item_codes workflow, leaving little to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

2 tool updatesNov 3, 2026

Changedfaostat_query_observations13 fields changed

addedInput schema / properties / item_codes_text

Added value: +{
+  "description": "Exact alphanumeric item identities from resolver code_text; mutually exclusive with item_codes. Numeric codes use item_codes.",
+  "items": {
+    "description": "Exact alphanumeric item code.",
+    "pattern": "^\\d+[A-Za-z][A-Za-z0-9]*$",
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / source_codes

Added value: +{
+  "description": "Exact source codes, such as 3050 or 3051 in GLE. Omit to return every methodology; choose or group sources before summing.",
+  "items": {
+    "maximum": 9007199254740991,
+    "minimum": -9007199254740991,
+    "type": "integer"
+  },
+  "type": "array"
+}

addedOutput schema / properties / available_elements

Added value: +{
+  "description": "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.",
+  "items": {
+    "additionalProperties": false,
+    "description": "An element observed for the selected items.",
+    "properties": {
+      "code": {
+        "description": "Element code available for the selected items.",
+        "type": "number"
+      },
+      "name": {
+        "description": "Element label.",
+        "type": "string"
+      },
+      "units": {
+        "description": "Distinct specified units for these items in this domain.",
+        "items": {
+          "description": "Observed unit.",
+          "type": "string"
+        },
+        "type": "array"
+      }
+    },
+    "required": [
+      "code",
+      "name",
+      "units"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"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."New value: +"Machine-readable failure mode. Declared by this tool: `conflicting_item_selectors`: Both numeric item_codes and exact item_codes_text are supplied. `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 requires an initial sync or an ingest upgrade. `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."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "domain_not_indexed",
-  "index_not_ready",
-  "canvas_disabled",
-  "canvas_not_found",
-  "invalid_year_range",
-  "query_timeout"
-]New value: +[
+  "conflicting_item_selectors",
+  "domain_not_indexed",
+  "index_not_ready",
+  "canvas_disabled",
+  "canvas_not_found",
+  "invalid_year_range",
+  "query_timeout"
+]

changedOutput schema / properties / observations / items / properties / item_code / description

Previous value: -"Item code."New value: +"Numeric item code; null for alphanumeric identities."

changedOutput schema / properties / observations / items / properties / item_code / type
```
Previous value: -"number"New value: +[
+  "number",
+  "null"
+]
```

addedOutput schema / properties / observations / items / properties / item_code_text

Added value: +{
+  "description": "Exact alphanumeric item code; null for numeric identities.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / observations / items / properties / period

Added value: +{
+  "description": "Original multi-year period label; null for annual rows. Year is the integer midpoint.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / observations / items / properties / source

Added value: +{
+  "description": "Source methodology label; null when absent.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / observations / items / properties / source_code

Added value: +{
+  "description": "Source methodology code; null when the domain has none.",
+  "type": [
+    "number",
+    "null"
+  ]
+}

addedOutput schema / properties / observations / items / properties / value_qualifier

Added value: +{
+  "description": "Bound operator such as <; value is a bound rather than an exact observation when present.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

changedOutput schema / properties / observations / items / required

Previous value: -[
-  "area_code",
-  "area",
-  "item_code",
-  "item",
-  "element_code",
-  "element",
-  "year",
-  "value",
-  "unit",
-  "flag"
-]New value: +[
+  "area_code",
+  "area",
+  "item_code",
+  "item_code_text",
+  "period",
+  "value_qualifier",
+  "source_code",
+  "source",
+  "item",
+  "element_code",
+  "element",
+  "year",
+  "value",
+  "unit",
+  "flag"
+]

Changedfaostat_resolve_codes11 fields changed

addedInput schema / properties / code_text

Added value: +{
+  "description": "Exact alphanumeric item code. Only for dimension item; mutually exclusive with code. Numeric identities use code.",
+  "pattern": "^\\d+[A-Za-z][A-Za-z0-9]*$",
+  "type": "string"
+}

addedInput schema / properties / item_codes

Added value: +{
+  "description": "For element resolution only: restrict elements and units to these items. Empty matches nothing; omit for domain-wide elements. Mutually exclusive with item_codes_text.",
+  "items": {
+    "maximum": 9007199254740991,
+    "minimum": -9007199254740991,
+    "type": "integer"
+  },
+  "type": "array"
+}

addedInput schema / properties / item_codes_text

Added value: +{
+  "description": "For element resolution only: restrict elements and units to these exact text items. Empty matches nothing; mutually exclusive with item_codes.",
+  "items": {
+    "description": "Exact alphanumeric item identity.",
+    "pattern": "^\\d+[A-Za-z][A-Za-z0-9]*$",
+    "type": "string"
+  },
+  "type": "array"
+}

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"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."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_item_scope`: Item selectors are combined or supplied outside element resolution. `invalid_text_selector`: code_text is supplied with code or outside the item dimension. `unknown_domain`: The domain code is not a selected (indexed) FAOSTAT domain. `index_not_ready`: The shared dimension tables are empty, or the selected item/element domain requires an initial sync or an ingest upgrade. `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."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "unknown_domain",
-  "index_not_ready",
-  "query_timeout"
-]New value: +[
+  "invalid_item_scope",
+  "invalid_text_selector",
+  "unknown_domain",
+  "index_not_ready",
+  "query_timeout"
+]

changedOutput schema / properties / matches / items / properties / code / description

Previous value: -"The opaque integer code to pass into faostat_query_observations."New value: +"Numeric code for faostat_query_observations; null for alphanumeric items carried by code_text."

changedOutput schema / properties / matches / items / properties / code / type
```
Previous value: -"number"New value: +[
+  "number",
+  "null"
+]
```

addedOutput schema / properties / matches / items / properties / code_text

Added value: +{
+  "description": "Exact alphanumeric item identity for item_codes_text; null for numeric codes.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

changedOutput schema / properties / matches / items / properties / kind / description

Previous value: -"For areas: \"country\" (individual nation) or \"aggregate\" (region/grouping; excluded from sums by default). Null for items/elements."New value: +"For areas: country or aggregate region. For items: aggregate only for verified domain-specific groups; null means unclassified, never safe-to-sum. Null for elements."

addedOutput schema / properties / matches / items / properties / units

Added value: +{
+  "description": "Element matches only: distinct non-null units observed in the selected domain and item scope. Empty means no specified units.",
+  "items": {
+    "description": "Observed unit label.",
+    "type": "string"
+  },
+  "type": "array"
+}

changedOutput schema / properties / matches / items / required

Previous value: -[
-  "code",
-  "name",
-  "kind"
-]New value: +[
+  "code",
+  "code_text",
+  "name",
+  "kind"
+]

1 tool updateOct 28, 2026

Changedfaostat_dataframe_describe1 field changed

changedOutput schema / properties / tables / items / properties / expires_at / description

Previous value: -"ISO 8601 expiry timestamp. Sliding TTL touched on every staged-table op."New value: +"ISO 8601 expiry timestamp recorded when this table was staged."

1 tool updateOct 18, 2026

Changedfaostat_commodity_profile18 fields changed

addedInput schema / properties / item_code

Added value: +{
+  "description": "Exact item code present in QCL; takes precedence over item_query. Obtain it from faostat_resolve_codes with domain QCL and dimension item.",
+  "maximum": 9007199254740991,
+  "minimum": 1,
+  "type": "integer"
+}

changedInput schema / properties / item_query / description

Previous value: -"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."New value: +"Commodity label or search term (e.g. \"Wheat\"). A unique normalized exact QCL label wins, otherwise the relevance search must match exactly one item. Broad queries such as \"maize\" or \"milk\" require item_code. Supply this or item_code."

removedInput schema / required
```
Removed value: -[
-  "item_query"
-]
```

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"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."New value: +"Machine-readable failure mode. Declared by this tool: `missing_item`: Neither item_code nor item_query was supplied. `ambiguous_item`: The query matches more than one QCL item without a unique exact label. `no_match`: The query matched no item, or item_code is absent from QCL. `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."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "no_match",
-  "domain_not_indexed",
-  "index_not_ready",
-  "invalid_year_range",
-  "canvas_not_found",
-  "query_timeout"
-]New value: +[
+  "missing_item",
+  "ambiguous_item",
+  "no_match",
+  "domain_not_indexed",
+  "index_not_ready",
+  "invalid_year_range",
+  "canvas_not_found",
+  "query_timeout"
+]

changedOutput schema / properties / item_query / description

Previous value: -"The commodity query echoed back."New value: +"Supplied query echoed back, or the canonical selected label for code-only calls."

changedOutput schema / properties / itemsTruncated / description

Previous value: -"True when the commodity name matched more items than the profile folded in — the profile then covers only the most relevant few."New value: +"Always false: successful profiles select one item without truncating selection."

changedOutput schema / properties / notice / description

Previous value: -"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."New value: +"States where the observation set went — the canvas table, inline result, staging failure, or disabled canvas — plus unavailable trade data, mixed units, or other partial-result context."

changedOutput schema / properties / production_trend / description

Previous value: -"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."New value: +"The annual production series for the selected item, summed over countries per year and ordered oldest-first. Aggregated in SQL over the complete filtered match, so it is not affected by the canvas staging cap."

changedOutput schema / properties / production_trend / items / properties / value / description

Previous value: -"Production summed across every country and resolved item reporting that year."New value: +"Selected item production summed across every country reporting that year."

changedOutput schema / properties / resolvedItemMatches / description

Previous value: -"Total items the commodity query matched in QCL, before the 5-item profile cap."New value: +"Number of selected QCL items; always one for a successful profile."

changedOutput schema / properties / resolved_items / description

Previous value: -"Commodities the query resolved to (the profile aggregates across all of them)."New value: +"The single selected QCL item and its canonical label."

changedOutput schema / properties / top_exporters / items / properties / observations / description

Previous value: -"Observations summed into value — one per resolved item reporting that year."New value: +"Observations summed into value for the selected item and reporting year."

changedOutput schema / properties / top_exporters / items / properties / value / description

Previous value: -"Export quantity summed across the resolved items for this country, in its latest reporting year."New value: +"Export quantity for the selected item and country in its latest reporting year."

changedOutput schema / properties / top_importers / items / properties / observations / description

Previous value: -"Observations summed into value — one per resolved item reporting that year."New value: +"Observations summed into value for the selected item and reporting year."

changedOutput schema / properties / top_importers / items / properties / value / description

Previous value: -"Import quantity summed across the resolved items for this country, in its latest reporting year."New value: +"Import quantity for the selected item and country in its latest reporting year."

changedOutput schema / properties / top_producers / items / properties / observations / description

Previous value: -"Observations summed into value — one per resolved item reporting that year."New value: +"Observations summed into value for the selected item and reporting year."

changedOutput schema / properties / top_producers / items / properties / value / description

Previous value: -"Production summed across the resolved items for this country, in its latest reporting year."New value: +"Production for the selected item and country in its latest reporting year."

4 tool updatesSep 30, 2026

Changedfaostat_commodity_profile5 fields changed

changedOutput schema / properties / canvas_id / description

Previous value: -"Canvas ID holding the merged set — pass to faostat_dataframe_query / _describe."New value: +"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."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"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 — 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. Other values are possible when a failure originates below the handler."New value: +"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."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "no_match",
-  "index_not_ready",
-  "invalid_year_range"
-]New value: +[
+  "no_match",
+  "domain_not_indexed",
+  "index_not_ready",
+  "invalid_year_range",
+  "canvas_not_found",
+  "query_timeout"
+]

changedOutput schema / properties / notice / description

Previous value: -"Names any required domain that was not indexed, item-resolution truncation, mixed units in the rankings, or other partial-result context."New value: +"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."

changedOutput schema / properties / table_name / description

Previous value: -"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."New value: +"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."

Changedfaostat_dataframe_query1 field changed

changedInput schema / properties / sql / description

Previous value: -"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."New value: +"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."

Changedfaostat_query_observations4 fields changed

changedOutput schema / properties / canvas_id / description

Previous value: -"Canvas ID holding the staged result — pass to faostat_dataframe_query / _describe."New value: +"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."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"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. `invalid_year_range`: year_start is greater than year_end — a self-contradictory range that can never match. Other values are possible when a failure originates below the handler."New value: +"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."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "domain_not_indexed",
-  "index_not_ready",
-  "canvas_disabled",
-  "invalid_year_range"
-]New value: +[
+  "domain_not_indexed",
+  "index_not_ready",
+  "canvas_disabled",
+  "canvas_not_found",
+  "invalid_year_range",
+  "query_timeout"
+]

changedOutput schema / properties / table_name / description

Previous value: -"Canvas table name holding the full result set (present when spilled)."New value: +"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."

Changedfaostat_resolve_codes2 fields changed

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"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."New value: +"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."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "unknown_domain",
-  "index_not_ready"
-]New value: +[
+  "unknown_domain",
+  "index_not_ready",
+  "query_timeout"
+]

4 tool updatesSep 19, 2026

Changedfaostat_commodity_profile18 fields changed

changedInput schema / properties / canvas_id / description

Previous value: -"Canvas ID from a prior call to stage onto. Omit to start a fresh canvas."New value: +"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."

addedInput schema / properties / canvas_id / pattern
```
Added value: +"^[A-Za-z0-9_-]{10}$"
```
removedOutput schema / properties / production_trend / items / properties / flags / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
addedOutput schema / properties / production_trend / items / properties / flags / type
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / production_trend / items / properties / unit / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
addedOutput schema / properties / production_trend / items / properties / unit / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / top_exporters / items / properties / flags / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / top_exporters / items / properties / flags / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / top_exporters / items / properties / unit / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / top_exporters / items / properties / unit / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / top_importers / items / properties / flags / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / top_importers / items / properties / flags / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / top_importers / items / properties / unit / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / top_importers / items / properties / unit / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / top_producers / items / properties / flags / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / top_producers / items / properties / flags / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / top_producers / items / properties / unit / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / top_producers / items / properties / unit / type
```
Added value: +[
+  "string",
+  "null"
+]
```

Changedfaostat_dataframe_describe2 fields changed

changedInput schema / properties / canvas_id / description

Previous value: -"Optional canvas ID from a prior faostat_query_observations / faostat_commodity_profile call. Omit to list the tables staged in this session (the common case)."New value: +"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)."

addedInput schema / properties / canvas_id / pattern
```
Added value: +"^[A-Za-z0-9_-]{10}$"
```

Changedfaostat_dataframe_query2 fields changed

changedInput schema / properties / canvas_id / description

Previous value: -"Optional canvas ID from a prior faostat_query_observations / faostat_commodity_profile call. Omit to query the tables staged in this session (the common case)."New value: +"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)."

addedInput schema / properties / canvas_id / pattern
```
Added value: +"^[A-Za-z0-9_-]{10}$"
```

Changedfaostat_query_observations8 fields changed

changedInput schema / properties / canvas_id / description

Previous value: -"Canvas ID from a prior call to stage onto. Omit to start a fresh canvas (a new id is returned)."New value: +"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."

addedInput schema / properties / canvas_id / pattern
```
Added value: +"^[A-Za-z0-9_-]{10}$"
```

removedOutput schema / properties / observations / items / properties / flag / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / observations / items / properties / flag / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / observations / items / properties / unit / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / observations / items / properties / unit / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / observations / items / properties / value / anyOf

Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / observations / items / properties / value / type
```
Added value: +[
+  "number",
+  "null"
+]
```

6 tool updatesAug 25, 2026

Changedfaostat_commodity_profile6 fields changed

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "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"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "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. `index_not_ready`: The production (QCL) 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. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "no_match",
+            "index_not_ready",
+            "invalid_year_range"
+          ],
+          "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"
+}

removedOutput schema / required

Removed value: -[
-  "item_query",
-  "resolved_items",
-  "top_producers",
-  "top_exporters",
-  "top_importers",
-  "production_trend",
-  "trend_points",
-  "spilled",
-  "truncated",
-  "resolvedItemCodes",
-  "resolvedItemMatches",
-  "itemsTruncated"
-]

Changedfaostat_dataframe_describe14 fields changed

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

addedInput schema / properties / limit

Added value: +{
+  "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"
+}

changedInput schema / properties / name / description

Previous value: -"Optional table name (faostat_xxxxxxxx) to describe a single staged table. Omit to list all."New value: +"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)."

addedInput schema / properties / offset

Added value: +{
+  "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"
+}

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "tables",
+      "totalMatches",
+      "truncated"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "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"
+}

addedOutput schema / properties / nextOffset

Added value: +{
+  "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"
+}

addedOutput schema / properties / notice

Added value: +{
+  "description": "Guidance when nothing is staged yet or more pages remain.",
+  "type": "string"
+}

changedOutput schema / properties / tables / description

Previous value: -"Active staged tables for this session, newest first. Empty when none are staged."New value: +"Active staged tables for this session, newest first — one page of them. Empty when none are staged."

addedOutput schema / properties / totalMatches

Added value: +{
+  "description": "Staged tables on the resolved canvas, before the page limit is applied.",
+  "type": "number"
+}

addedOutput schema / properties / truncated

Added value: +{
+  "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"
+}

removedOutput schema / required
```
Removed value: -[
-  "tables"
-]
```

Changedfaostat_dataframe_query6 fields changed

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "columns",
+      "row_count",
+      "rows",
+      "truncated"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "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"
+}

removedOutput schema / required

Removed value: -[
-  "columns",
-  "row_count",
-  "rows",
-  "truncated"
-]

Changedfaostat_list_domains6 fields changed

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "domains",
+      "totalCount",
+      "totalMatches",
+      "truncated",
+      "indexedCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "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"
+}

removedOutput schema / required

Removed value: -[
-  "domains",
-  "totalCount",
-  "totalMatches",
-  "truncated",
-  "indexedCount"
-]

Changedfaostat_query_observations6 fields changed

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "domain",
+      "observations",
+      "spilled",
+      "truncated",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "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. `invalid_year_range`: year_start is greater than year_end — a self-contradictory range that can never match. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "domain_not_indexed",
+            "index_not_ready",
+            "canvas_disabled",
+            "invalid_year_range"
+          ],
+          "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"
+}

removedOutput schema / required

Removed value: -[
-  "domain",
-  "observations",
-  "spilled",
-  "truncated",
-  "totalCount"
-]

Changedfaostat_resolve_codes6 fields changed

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "domain",
+      "dimension",
+      "matches",
+      "totalMatches",
+      "truncated"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "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). Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "unknown_domain",
+            "index_not_ready"
+          ],
+          "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"
+}

removedOutput schema / required

Removed value: -[
-  "domain",
-  "dimension",
-  "matches",
-  "totalMatches",
-  "truncated"
-]

1 tool updateJul 27, 2026

Changedfaostat_query_observations2 fields changed

changedInput schema / properties / limit / description

Previous value: -"Max observations returned inline when the result does not spill. Max 1000."New value: +"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."

changedOutput schema / properties / totalCount / description

Previous value: -"Observations matched. Exact when the result was returned inline or fully staged; when the match set exceeded the 50,000-row staging cap this is that cap — a floor, not the exact count (truncated is then true)."New value: +"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."

1 tool updateJul 27, 2026

Changedfaostat_commodity_profile33 fields changed

changedInput schema / properties / item_query / description

Previous value: -"Commodity name to profile (e.g. \"maize\", \"wheat\", \"coffee green\")."New value: +"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."

addedOutput schema / properties / itemsTruncated

Added value: +{
+  "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"
+}

changedOutput schema / properties / notice / description

Previous value: -"Names any required domain that was not indexed, or other partial-result context."New value: +"Names any required domain that was not indexed, item-resolution truncation, mixed units in the rankings, or other partial-result context."

addedOutput schema / properties / production_trend

Added value: +{
+  "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": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "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."
+      },
+      "observations": {
+        "description": "Observations summed into value — read it alongside value, since a change in coverage moves the total independently of production.",
+        "type": "number"
+      },
+      "unit": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "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."
+      },
+      "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"
+}

addedOutput schema / properties / resolvedItemMatches

Added value: +{
+  "description": "Total items the commodity query matched in QCL, before the 5-item profile cap.",
+  "type": "number"
+}

changedOutput schema / properties / table_name / description

Previous value: -"Canvas table holding the merged production+trade observations (present when spilled)."New value: +"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."

changedOutput schema / properties / top_exporters / description

Previous value: -"Top exporters by export quantity (empty when trade is not indexed)."New value: +"Top exporters by summed export quantity (empty when trade is not indexed)."

removedOutput schema / properties / top_exporters / items / properties / flag

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "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."
-}

addedOutput schema / properties / top_exporters / items / properties / flags

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "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."
+}

addedOutput schema / properties / top_exporters / items / properties / observations

Added value: +{
+  "description": "Observations summed into value — one per resolved item reporting that year.",
+  "type": "number"
+}

changedOutput schema / properties / top_exporters / items / properties / unit / description

Previous value: -"Unit of measure; null when unspecified."New value: +"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."

changedOutput schema / properties / top_exporters / items / properties / value / description

Previous value: -"Export quantity in the latest year present."New value: +"Export quantity summed across the resolved items for this country, in its latest reporting year."

changedOutput schema / properties / top_exporters / items / properties / year / description

Previous value: -"The latest year the ranking is drawn from."New value: +"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."

changedOutput schema / properties / top_exporters / items / required

Previous value: -[
-  "area_code",
-  "area",
-  "value",
-  "unit",
-  "year",
-  "flag"
-]New value: +[
+  "area_code",
+  "area",
+  "value",
+  "observations",
+  "unit",
+  "year",
+  "flags"
+]

changedOutput schema / properties / top_importers / description

Previous value: -"Top importers by import quantity (empty when trade is not indexed)."New value: +"Top importers by summed import quantity (empty when trade is not indexed)."

removedOutput schema / properties / top_importers / items / properties / flag

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "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."
-}

addedOutput schema / properties / top_importers / items / properties / flags

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "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."
+}

addedOutput schema / properties / top_importers / items / properties / observations

Added value: +{
+  "description": "Observations summed into value — one per resolved item reporting that year.",
+  "type": "number"
+}

changedOutput schema / properties / top_importers / items / properties / unit / description

Previous value: -"Unit of measure; null when unspecified."New value: +"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."

changedOutput schema / properties / top_importers / items / properties / value / description

Previous value: -"Import quantity in the latest year present."New value: +"Import quantity summed across the resolved items for this country, in its latest reporting year."

changedOutput schema / properties / top_importers / items / properties / year / description

Previous value: -"The latest year the ranking is drawn from."New value: +"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."

changedOutput schema / properties / top_importers / items / required

Previous value: -[
-  "area_code",
-  "area",
-  "value",
-  "unit",
-  "year",
-  "flag"
-]New value: +[
+  "area_code",
+  "area",
+  "value",
+  "observations",
+  "unit",
+  "year",
+  "flags"
+]

changedOutput schema / properties / top_producers / description

Previous value: -"Top producers by production value (countries only)."New value: +"Top producers by summed production (countries only)."

removedOutput schema / properties / top_producers / items / properties / flag

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "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."
-}

addedOutput schema / properties / top_producers / items / properties / flags

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "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."
+}

addedOutput schema / properties / top_producers / items / properties / observations

Added value: +{
+  "description": "Observations summed into value — one per resolved item reporting that year.",
+  "type": "number"
+}

changedOutput schema / properties / top_producers / items / properties / unit / description

Previous value: -"Unit of measure; null when unspecified."New value: +"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."

changedOutput schema / properties / top_producers / items / properties / value / description

Previous value: -"Production value in the latest year present."New value: +"Production summed across the resolved items for this country, in its latest reporting year."

changedOutput schema / properties / top_producers / items / properties / year / description

Previous value: -"The latest year the ranking is drawn from."New value: +"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."

changedOutput schema / properties / top_producers / items / required

Previous value: -[
-  "area_code",
-  "area",
-  "value",
-  "unit",
-  "year",
-  "flag"
-]New value: +[
+  "area_code",
+  "area",
+  "value",
+  "observations",
+  "unit",
+  "year",
+  "flags"
+]

changedOutput schema / properties / trend_points / description

Previous value: -"Count of production trend observations analyzed for the resolved commodity. Capped at the 50,000-row staging limit — when truncated is true this is a floor, not the true count."New value: +"Total production observations aggregated into production_trend. Exact — the aggregation runs over the complete filtered match, not a capped page."

changedOutput schema / properties / truncated / description

Previous value: -"True when the producer ranking / trend and/or the staged canvas table were drawn from a set capped at the 50,000-row staging limit — treat the profile as a PARTIAL view and query faostat_query_observations directly (partitioned by year) for the complete series."New value: +"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."

changedOutput schema / required

Previous value: -[
-  "item_query",
-  "resolved_items",
-  "top_producers",
-  "top_exporters",
-  "top_importers",
-  "trend_points",
-  "spilled",
-  "truncated",
-  "resolvedItemCodes"
-]New value: +[
+  "item_query",
+  "resolved_items",
+  "top_producers",
+  "top_exporters",
+  "top_importers",
+  "production_trend",
+  "trend_points",
+  "spilled",
+  "truncated",
+  "resolvedItemCodes",
+  "resolvedItemMatches",
+  "itemsTruncated"
+]

1 tool updateJul 27, 2026

Changedfaostat_list_domains9 fields changed

addedInput schema / properties / code

Added value: +{
+  "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"
+}

addedInput schema / properties / limit

Added value: +{
+  "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"
+}

addedInput schema / properties / offset

Added value: +{
+  "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"
+}

addedOutput schema / properties / nextOffset

Added value: +{
+  "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"
+}

changedOutput schema / properties / notice / description

Previous value: -"Guidance when a topic filter matched nothing or no domains are indexed yet."New value: +"Guidance when a filter matched nothing, more pages remain, or no domains are indexed yet."

changedOutput schema / properties / totalCount / description

Previous value: -"Total domains in the FAOSTAT catalog."New value: +"Total domains in the FAOSTAT catalog, independent of any filter."

addedOutput schema / properties / totalMatches

Added value: +{
+  "description": "Domains matching the current filters, before the page limit is applied.",
+  "type": "number"
+}

addedOutput schema / properties / truncated

Added value: +{
+  "description": "True when more matches remain beyond the returned page — fetch them with nextOffset.",
+  "type": "boolean"
+}

changedOutput schema / required

Previous value: -[
-  "domains",
-  "totalCount",
-  "indexedCount"
-]New value: +[
+  "domains",
+  "totalCount",
+  "totalMatches",
+  "truncated",
+  "indexedCount"
+]

2 tool updatesJul 14, 2026

Changedfaostat_commodity_profile3 fields changed

changedOutput schema / properties / top_exporters / items / properties / flag / description

Previous value: -"Data-quality flag; null when unflagged."New value: +"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."

changedOutput schema / properties / top_importers / items / properties / flag / description

Previous value: -"Data-quality flag; null when unflagged."New value: +"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."

changedOutput schema / properties / top_producers / items / properties / flag / description

Previous value: -"Data-quality flag; null when unflagged."New value: +"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."

Changedfaostat_query_observations2 fields changed

changedInput schema / properties / include_aggregates / description

Previous value: -"When false (default), exclude aggregate-region rows (codes ≥ 5000) so sums are not double-counted. Set true for World/continent/grouping roll-ups. Ignored when explicit area_codes are passed."New value: +"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."

changedOutput schema / properties / observations / items / properties / flag / description

Previous value: -"Data-quality flag (A=Official, E=Estimated, I=Imputed, B=break, X=external); null when unflagged."New value: +"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."

1 tool updateJul 14, 2026

Changedfaostat_resolve_codes6 fields changed

changedInput schema / properties / domain / description

Previous value: -"FAOSTAT domain code to verify the index is ready (e.g. \"QCL\"). Dimension code lists (areas, items, elements) are shared across all indexed domains."New value: +"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."

addedInput schema / properties / offset

Added value: +{
+  "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"
+}

addedOutput schema / properties / nextOffset

Added value: +{
+  "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"
+}

changedOutput schema / properties / notice / description

Previous value: -"Guidance when nothing matched or the dimension is not yet indexed."New value: +"Guidance when nothing matched, more pages remain, or the dimension is not yet indexed."

changedOutput schema / properties / totalMatches / description

Previous value: -"Total matches before the result cap."New value: +"Total matches in this domain before the result cap."

changedOutput schema / properties / truncated / description

Previous value: -"True when matches were capped at the limit."New value: +"True when more matches remain beyond the returned page — fetch them with nextOffset."

1 tool updateJul 13, 2026

Changedfaostat_query_observations1 field changed

changedOutput schema / properties / totalCount / description

Previous value: -"Total observations matched before any inline cap."New value: +"Observations matched. Exact when the result was returned inline or fully staged; when the match set exceeded the 50,000-row staging cap this is that cap — a floor, not the exact count (truncated is then true)."

3 tool updatesJul 13, 2026

Changedfaostat_commodity_profile4 fields changed

addedOutput schema / properties / staged_row_count

Added value: +{
+  "description": "Rows actually staged on the merged canvas table (present when spilled). Equals the 50,000-row cap when truncated.",
+  "type": "number"
+}

changedOutput schema / properties / trend_points / description

Previous value: -"Count of production trend observations staged for the resolved commodity."New value: +"Count of production trend observations analyzed for the resolved commodity. Capped at the 50,000-row staging limit — when truncated is true this is a floor, not the true count."

addedOutput schema / properties / truncated

Added value: +{
+  "description": "True when the producer ranking / trend and/or the staged canvas table were drawn from a set capped at the 50,000-row staging limit — treat the profile as a PARTIAL view and query faostat_query_observations directly (partitioned by year) for the complete series.",
+  "type": "boolean"
+}

changedOutput schema / required

Previous value: -[
-  "item_query",
-  "resolved_items",
-  "top_producers",
-  "top_exporters",
-  "top_importers",
-  "trend_points",
-  "spilled",
-  "resolvedItemCodes"
-]New value: +[
+  "item_query",
+  "resolved_items",
+  "top_producers",
+  "top_exporters",
+  "top_importers",
+  "trend_points",
+  "spilled",
+  "truncated",
+  "resolvedItemCodes"
+]

Changedfaostat_dataframe_query3 fields changed

changedOutput schema / properties / row_count / description

Previous value: -"Total rows the query produced (may exceed rows.length when capped)."New value: +"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."

addedOutput schema / properties / truncated

Added value: +{
+  "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"
+}

changedOutput schema / required

Previous value: -[
-  "columns",
-  "row_count",
-  "rows"
-]New value: +[
+  "columns",
+  "row_count",
+  "rows",
+  "truncated"
+]

Changedfaostat_query_observations3 fields changed

addedOutput schema / properties / staged_row_count

Added value: +{
+  "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"
+}

addedOutput schema / properties / truncated

Added value: +{
+  "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"
+}

changedOutput schema / required

Previous value: -[
-  "domain",
-  "observations",
-  "spilled",
-  "totalCount"
-]New value: +[
+  "domain",
+  "observations",
+  "spilled",
+  "truncated",
+  "totalCount"
+]

Related MCP Connectors

FaostatA
io.github.pipeworx-io
FAOSTAT MCP — the UN Food and Agriculture Organization's statistics service.
Open Data Research & Data
471
https://gateway.pipeworx.io/faostat/mcp
stagenth · 数据工具箱A
com.stagenth
Query, join, profile, clean and convert CSV/JSON/Parquet with server-side DuckDB over MCP.
Databases Data Platforms File Systems
2
https://stagenth.com/mcp/data-kit/
un-comtrade-mcp-serverA
io.github.cyanheads
UN Comtrade international trade statistics via MCP. Country/HS lookups, flows, balances, rankings.
Open Data Government Data
914
https://un-comtrade.caseyjhand.com/mcp
EurostatA
io.github.pipeworx-io
Eurostat MCP — wraps Eurostat Statistical Data API (no auth required)
Open Data Government Data Research & Data
472
https://gateway.pipeworx.io/eurostat/mcp

Related MCP Servers

Zaia
Databases Search
prithivrajmu
A
license
Not graded
quality
D
maintenance
MCP server that exposes SQLite datasets as queryable tools and resources via Streamable HTTP, enabling read-only exploration and SQL queries.
Updated 4 months ago (2026-07-15 11:02 UTC)
Apache 2.0
@cyanheads/unhcr-refugees-mcp
Open Data Government Data Research & Data
cyanheads
A
license
Not graded
quality
A
maintenance
Enables querying UNHCR refugee, IDP, stateless populations, asylum decisions, returns, and resettlement statistics via MCP, including staging large datasets for SQL queries. Supports stdio or Streamable HTTP transports.
Updated 3 days ago (2026-11-04 12:06 UTC)
98 npm
1
Apache 2.0
monarch-mcp
Finance Databases Search
sdeiley
A
license
Not graded
quality
D
maintenance
Provides an MCP server for querying and managing Monarch Money personal finance data through a local SQLite mirror with read-only SQL access. It enables users to sync transaction history from the Monarch API and analyze accounts, categories, and tags.
Updated 3 months ago (2026-07-28 16:30 UTC)
1
MIT
paycoreDb
Databases Developer Tools
MaxenceBdu
F
license
Not graded
quality
D
maintenance
Custom MCP server connected to a read-only SQLite database, exposing a schema resource and a query tool for safe data retrieval.
Updated 4 months ago (2026-06-30 14:47 UTC)
-

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Server Details

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Related MCP Connectors

Related MCP Servers

Glama MCP Gateway

Resources