Skip to main content
Glama

faostat-mcp-server

by io.github.cyanheads
OverviewDiscussionsAdmin

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.7% over 62 days
Last Tested
Transport
Streamable HTTP · MCP 2025-11-25
URL
Repository
cyanheads/faostat-mcp-server
GitHub Stars
2
Server Listing
@cyanheads/faostat-mcp-server

TDQS

A4.5/5.0

Scored across 6 tools

Disambiguation4/5

Each tool has a distinct role: discovery (list_domains), code resolution (resolve_codes), raw querying (query_observations), a bundled preset (commodity_profile), and canvas follow-up (dataframe_describe/query). The mild overlap is between commodity_profile and query_observations, but the profile's bundled aggregation clearly separates it from the raw cube query.

Naming Consistency4/5

All names share the faostat_ prefix and use a readable snake_case scheme, mostly verb_noun (list_domains, query_observations, resolve_codes). The deviations are faostat_commodity_profile and the dataframe_* pair whose noun_verb ordering differs slightly, but the set remains predictable.

Tool Count5/5

Six tools is well-scoped for a FAOSTAT data-access server, with each tool earning its place across discover→resolve→query→analyze workflows. No redundant or filler tools.

Completeness4/5

The surface covers the full workflow: domain discovery, code resolution, raw observation querying, a convenience profile, and SQL-based analysis over spilled results. Minor gaps exist, such as no dedicated schema/metadata inspection beyond resolve_codes and list_domains, but agents can work around them.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
top_nNoNumber of top producers / exporters / importers to return. Max 50.
year_endNoInclusive end year for the trend (e.g. 2022).
canvas_idNoCanvas 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_codeNoExact item code present in QCL; takes precedence over item_query. Obtain it from faostat_resolve_codes with domain QCL and dimension item.
item_queryNoCommodity 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_startNoInclusive start year for the trend (e.g. 1990).

Output Schema

ParametersJSON Schema
NameRequiredDescription
errorNoPresent when the call failed. Absent on success.
noticeNoStates 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.
spilledNoTrue when the merged observation set was staged on a canvas table.
canvas_idNoCanvas 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.
truncatedNoTrue 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_queryNoSupplied query echoed back, or the canonical selected label for code-only calls.
table_nameNoCanvas 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_pointsNoTotal production observations aggregated into production_trend. Exact — the aggregation runs over the complete filtered match, not a capped page.
top_exportersNoTop exporters by summed export quantity (empty when trade is not indexed).
top_importersNoTop importers by summed import quantity (empty when trade is not indexed).
top_producersNoTop producers by summed production (countries only).
itemsTruncatedNoAlways false: successful profiles select one item without truncating selection.
resolved_itemsNoThe single selected QCL item and its canonical label.
production_trendNoThe 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_countNoRows actually staged on the merged canvas table (present when spilled). Equals the 50,000-row cap when truncated.
resolvedItemCodesNoItem codes the commodity query resolved to.
resolvedItemMatchesNoNumber 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.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameNoOptional 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).
limitNoMaximum staged tables to return on this page (max 100). Each entry carries a full column schema, so the default keeps a discovery call small.
offsetNoZero-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_idNoOptional 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

ParametersJSON Schema
NameRequiredDescription
errorNoPresent when the call failed. Absent on success.
noticeNoGuidance when nothing is staged yet or more pages remain.
tablesNoActive staged tables for this session, newest first — one page of them. Empty when none are staged.
truncatedNoTrue 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.
nextOffsetNoOffset 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.
totalMatchesNoStaged tables on the resolved canvas, before the page limit is applied.

TDQS

A4.7/5.0
Behavior5/5

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

The description discloses ordering (newest-first), pagination behavior with `truncated` and `nextOffset`, the precedence of `name` over pagination parameters, and the per-entry output contents. This adds substantial behavioral context beyond the readOnlyHint and idempotentHint annotations, and nothing contradicts the annotations.

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

Conciseness5/5

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

Three dense sentences with no filler. The purpose and output contents lead, followed by the call-before context and pagination mechanics. Every clause earns its place, and the most decision-relevant information is front-loaded.

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?

The description is complete for a read-only discovery tool: it names the source tools, tells the agent when to call it, explains both lookup and pagination paths, and references the output schema where return details already live. The output schema handles the return-value burden, so nothing essential is missing.

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?

The input schema already documents all four parameters at 100% coverage, so the baseline is 3. The description reinforces the key semantics such as `name` taking precedence and `offset`/`limit` being used for paging, but it does not add meaning that is absent from 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?

The description uses a specific verb ('List the canvas tables') and names the exact resource type (faostat_xxxxxxxx tables) and which source tools stage them. It clearly distinguishes this discovery tool from faostat_dataframe_query, which is the tool that executes SQL against those tables.

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?

It explicitly instructs the agent to call this before faostat_dataframe_query to discover table and column names for SQL. It also provides concrete selection guidance for the two modes: pass `name` for a single table, or use `offset`/`limit` and `nextOffset` for paging, which covers the key decision points.

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 the canvas tables staged by faostat_query_observations and faostat_commodity_profile (table names look like faostat_xxxxxxxx). Use this for cross-country and cross-item aggregation, GROUP BY rankings, joins, and time-series analysis over the full result set the inline preview only sampled. Standard DuckDB SQL — joins, aggregates, window functions, CTEs all work. Read-only: writes, DDL, DROP, COPY, PRAGMA, ATTACH, and external-file table functions are rejected; system catalogs (information_schema, sqlite_master, duckdb_*) are denied — list staged tables via faostat_dataframe_describe. Every row carries its data-quality flag — commonly A=Official, B=time-series break, E=Estimated, I=Imputed, M=Missing (value cannot exist), T=Unofficial, X=from an international organization, plus others FAOSTAT defines per domain — keep it in projections, treat any unrecognized flag as informational, and never assume it is official.

ParametersJSON Schema
NameRequiredDescriptionDefault
sqlYesSingle-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_idNoOptional 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_limitNoHard cap on rows in the response. Default 1000, max 10000.

Output Schema

ParametersJSON Schema
NameRequiredDescription
rowsNoMaterialized result rows, bounded by row_limit.
errorNoPresent when the call failed. Absent on success.
noticeNoGuidance when the query returned no rows or when results were capped.
columnsNoColumn names in projection order.
row_countNoRows 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.
truncatedNoTrue 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.4/5.0
Behavior5/5

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

Far exceeds the annotations: it enumerates rejected statements (writes, DDL, DROP, COPY, PRAGMA, ATTACH, external-file functions), denied catalogs (information_schema, sqlite_master, duckdb_*), and the read-only posture reinforcement. It also explains the data-quality `flag` semantics (A/B/E/I/M/T/X) and instructs the agent to keep flag in projections and not assume official — behavior an agent could not infer from readOnlyHint/idempotentHint alone.

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 immediately followed by use cases and the security envelope. Dense and mostly waste-free, though the long flag enumeration and the repeated safety framing make it slightly heavier than necessary.

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 query tool with 3 params, full schema coverage, an output schema, and read-only annotations, this is complete: it covers staging source, SQL dialect, security limits, table discovery route, and the flag column's meaning. An agent has everything needed to write and scope a valid query.

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%, so the schema already documents sql, canvas_id, and row_limit. The description reinforces canvas usage ('tables staged in this session, the common case') but adds no syntax or format detail beyond the schema; the substantive added semantics (flag meanings) concern output columns, not parameters. Baseline 3 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?

States a specific verb and resource — 'Run a single-statement SELECT against the canvas tables staged by faostat_query_observations and faostat_commodity_profile' — and names the exact table-naming convention (faostat_xxxxxxxx). This clearly separates it from the sibling staging tools that produce the tables it queries.

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 explicit when-to-use cases: 'cross-country and cross-item aggregation, GROUP BY rankings, joins, and time-series analysis over the full result set the inline preview only sampled.' That sampling contrast tells the agent why to reach for this rather than the inline preview, but it names no exclusions or the sibling to use for other needs (e.g., faostat_dataframe_describe for listing).

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
codeNoExact 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.
limitNoMaximum 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.
topicNoCase-insensitive substring filter over domain code, name, and topic (e.g. "trade", "emissions", "QCL"). Omit to list the full catalog.
offsetNoZero-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_onlyNoWhen true, return only domains indexed in the local mirror (queryable now).

Output Schema

ParametersJSON Schema
NameRequiredDescription
errorNoPresent when the call failed. Absent on success.
noticeNoGuidance when a filter matched nothing, more pages remain, or no domains are indexed yet.
domainsNoMatching domains, sorted by code.
truncatedNoTrue when more matches remain beyond the returned page — fetch them with nextOffset.
nextOffsetNoOffset 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.
totalCountNoTotal domains in the FAOSTAT catalog, independent of any filter.
indexedCountNoDomains currently indexed in the local mirror.
totalMatchesNoDomains 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), and year range, returning observations (area, item, element, year, value, unit, and the data-quality flag). Resolve codes first with faostat_resolve_codes — the cube is unqueryable without them. Aggregate regions (World, continents, economic groupings) are EXCLUDED by default so a naive SUM does not double-count a region with its member countries; set include_aggregates=true to get the regional roll-ups, or pass explicit area_codes to query exactly what you name. Small result sets return inline; large ones spill to a DataCanvas table (returned canvas_id + table_name) — call faostat_dataframe_describe for its columns, then faostat_dataframe_query for GROUP BY / ranking / time-series analysis. Every row carries its flag — commonly A=Official, B=time-series break, E=Estimated, I=Imputed, M=Missing (value cannot exist), T=Unofficial, X=from an international organization, plus others FAOSTAT defines per domain — so honor it, treat any unrecognized flag as informational, and never assume an estimated, imputed, or unrecognized value is official.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMax 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.
domainYesFAOSTAT domain code (e.g. "QCL"). Must be indexed locally.
year_endNoInclusive end year (e.g. 2022).
canvas_idNoCanvas 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_codesNoArea codes from faostat_resolve_codes. When set, aggregates are NOT auto-excluded — the codes are honored verbatim.
item_codesNoItem codes from faostat_resolve_codes.
year_startNoInclusive start year (e.g. 2000).
element_codesNoElement codes from faostat_resolve_codes (e.g. 5510 Production).
include_aggregatesNoWhen 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

ParametersJSON Schema
NameRequiredDescription
errorNoPresent when the call failed. Absent on success.
domainNoThe domain code echoed back.
noticeNoGuidance on empty results, aggregate exclusion, or how to reach the spilled set.
spilledNoTrue when the full result was staged on a DataCanvas table.
canvas_idNoCanvas 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.
truncatedNoTrue 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_nameNoCanvas 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.
totalCountNoObservations 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.
observationsNoInline observations (preview when the full set spilled to a canvas table).
staged_row_countNoRows 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.

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only cover readOnly/openWorld/idempotent; the description adds substantial beyond-schema behavior: the anti-double-counting exclusion rule, the inline-vs-canvas spill threshold and returned canvas_id/table_name, and a flag taxonomy with the explicit warning to treat unrecognized flags as informational and never assume imputed/estimated values are official.

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?

Dense and front-loaded, with the code-resolution prerequisite and aggregate rule before the spill/flag detail. It is long and echoes some schema text (limit, canvas_id), but each sentence carries actionable meaning rather than filler.

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 not be re-explained, yet the description still conveys result shape, spill handling, and flag semantics. For a 9-param query tool with a full schema and annotations, nothing an agent needs to call it 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 the baseline is 3, but the description adds interpretive value: it explains why aggregates are excluded (double-counting), that area_codes are honored verbatim and suppress auto-exclusion, and that limit is also the canvas preview size and never silently drops rows.

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 (Query) and resource (a FAOSTAT domain's data cube) plus the exact filter axes and returned fields, which is more than the title. It names and differentiates the siblings it hands off to (faostat_resolve_codes, faostat_dataframe_describe, faostat_dataframe_query).

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 states a prerequisite ('Resolve codes first ... the cube is unqueryable without them') and the routing rule to canvas follow-ups. It also gives when/when-not on aggregates (excluded by default, set include_aggregates=true, or pass explicit area_codes) rather than leaving it to inference.

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 human terms to the opaque integer codes faostat_query_observations needs, within a dimension: areas (countries/regions), items (commodities), or elements (metrics like production, yield, import quantity). Pass query for fuzzy full-text matching ("maize" → item 56), name_contains for a substring filter, or code for an exact-code lookup; omit all three to list the whole dimension. Item and element results are scoped to the requested domain — only codes present in that domain's cube are returned, so a resolved code is always queryable there (areas are shared across domains). Page large listings with offset + limit: when the response reports truncated, pass the returned nextOffset to fetch the next page. Every area match is flagged country or aggregate — aggregates (World, continents, economic groupings — codes ≥ 5000 plus a few curated sub-threshold roll-ups such as China=351, which sums mainland + Taiwan + Hong Kong + Macao) double-count if summed with their member countries, so resolve before querying and exclude aggregates unless you want the regional roll-up.

ParametersJSON Schema
NameRequiredDescriptionDefault
codeNoExact code lookup. Takes precedence over `query`/`name_contains` when provided.
limitNoMaximum matches to return (max 200).
queryNoFull-text search term, FTS5-matched against the dimension labels with prefix matching (e.g. "wheat", "import quantity"). Relevance-ranked.
domainYesFAOSTAT 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.
offsetNoZero-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).
dimensionYesWhich dimension to resolve: "area" (countries/regions), "item" (commodities), or "element" (metrics).
name_containsNoCase-insensitive substring filter over the label. Used only when `query` is omitted.

Output Schema

ParametersJSON Schema
NameRequiredDescription
errorNoPresent when the call failed. Absent on success.
domainNoThe domain code echoed back.
noticeNoGuidance when nothing matched, more pages remain, or the dimension is not yet indexed.
matchesNoMatching codes, relevance-ranked for query mode, else by code.
dimensionNoThe dimension resolved.
truncatedNoTrue when more matches remain beyond the returned page — fetch them with nextOffset.
nextOffsetNoOffset 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.
totalMatchesNoTotal matches in this domain before the result cap.

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already establish readOnly/idempotent/openWorld=false, so the safety profile is covered. The description goes well beyond that with non-obvious traits: item/element results are scoped to the requested domain while areas are shared, aggregates double-count when summed with members (codes >= 5000 plus curated roll-ups like China=351), and truncation is surfaced via a nextOffset field.

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-loads the purpose, then layers mode selection, scoping, and the aggregate caveat in a logical order; every sentence carries information. It runs long as a single dense paragraph, which slightly burdens scanning, but there is little waste.

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 not be explained, yet the description still covers the one returned signal an agent must act on (`truncated` + `nextOffset`). Combined with the domain-scoping and aggregate warnings, an agent has everything needed to call this correctly in sequence with faostat_query_observations.

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%, so all seven parameters are already documented, and the description largely restates that (mode selection, pagination, code precedence). It adds a light illustrative example ('maize' -> 56) but no syntax or format detail the schema lacks, so the baseline 3 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?

States a specific verb ('resolve human terms to the opaque integer codes') and names exactly which sibling consumes the output (faostat_query_observations). It enumerates the three resolvable dimensions with concrete examples, making it unmistakable against siblings like faostat_list_domains or faostat_commodity_profile.

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 distinguishes the three matching modes (`query` fuzzy, `name_contains` substring, `code` exact) and states what happens when all are omitted ('list the whole dimension'). It also gives the conditional rule for excluding aggregates unless a regional roll-up is wanted.

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.

  1. 1 tool update
    • 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."
  2. 4 tool updates
    • 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"
+]
  3. 4 tool updates
    • 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"
+]
  4. 6 tool updates
    • 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"
-]
  5. 1 tool update
    • 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."
  6. 1 tool update
    • 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"
+]
  7. 1 tool update
    • 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"
+]
  8. 2 tool updates
    • 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."
  9. 1 tool update
    • 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."
  10. 1 tool update
    • 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)."
  11. 3 tool updates
    • 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"
+]
  12. 6 tool updates
    • First observedfaostat_commodity_profile
    • First observedfaostat_dataframe_describe
    • First observedfaostat_dataframe_query
    • First observedfaostat_list_domains
    • First observedfaostat_query_observations
    • First observedfaostat_resolve_codes

Related MCP Connectors

Related MCP Servers

  • Zaia

    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.
    Apache 2.0

  • @cyanheads/unhcr-refugees-mcp

    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.
    78 npm
    1
    Apache 2.0

  • monarch-mcp

    sdeiley
    A
    license
    Not graded
    quality
    C
    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.
    1
    MIT

  • paycoreDb

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

Resources