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.8% over 42 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.6/5.0

Scored across 6 tools

Disambiguation5/5

Each tool maps to a distinct pipeline stage: domain discovery, code resolution, raw observations, a commodity profile, staged-table introspection, and SQL analysis. Although several tools involve querying, their targets and outputs are clearly separated in the descriptions.

Naming Consistency3/5

All tools share the faostat_ prefix and use snake_case, which adds some coherence, but the naming convention is mixed: list_domains/query_observations/resolve_codes are verb-first, while dataframe_describe/dataframe_query are noun-first and commodity_profile is a noun phrase. This is readable but not a consistent pattern.

Tool Count5/5

Six tools is a well-scoped size for the server's purpose. Each tool does meaningful, non-redundant work within the query workflow, and the set feels neither thin nor bloated.

Completeness5/5

The server covers the full read-only workflow: discovering domains, resolving codes, querying raw observations, building commodity profiles, discovering staged tables, and running SQL over them. Since this is a read-only data service, update/delete operations are not expected, and there are no obvious dead ends for completing a query task.

Available Tools

6 tools
faostat_commodity_profilefaostat-mcp-server: commodity profileA
Read-only
Inspect

Assemble a global profile for one commodity in a single call: top-producing countries, the annual production trend, and trade flows (top exporters and importers). Accepts a commodity name, resolves it to item codes, then queries the production (QCL) and trade (TCL) domains and merges the results. Each ranking is a per-country sum across the resolved items, taken at that country's own latest year with data and grouped by unit so incomparable quantities are never added. The trend is returned inline as year/value points. Country-level only (aggregates excluded). When a required domain is not indexed locally, returns a partial profile with a notice naming the gap rather than failing. The full merged observation set spills to a DataCanvas table for deeper SQL via faostat_dataframe_query.

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_queryYesCommodity 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.
year_startNoInclusive start year for the trend (e.g. 1990).

Output Schema

ParametersJSON Schema
NameRequiredDescription
errorNoPresent when the call failed. Absent on success.
noticeNoNames any required domain that was not indexed, item-resolution truncation, mixed units in the rankings, or other partial-result context.
spilledNoTrue when the merged observation set was staged on a canvas table.
canvas_idNoCanvas ID holding the merged set — pass to faostat_dataframe_query / _describe.
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_queryNoThe commodity query echoed back.
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.
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).
itemsTruncatedNoTrue when the commodity name matched more items than the profile folded in — the profile then covers only the most relevant few.
resolved_itemsNoCommodities the query resolved to (the profile aggregates across all of them).
production_trendNoThe annual production series for the resolved commodity, summed over countries and items per year and ordered oldest-first. Aggregated in SQL over the complete filtered match, so it is not affected by the canvas staging cap.
staged_row_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.
resolvedItemMatchesNoTotal items the commodity query matched in QCL, before the 5-item profile cap.

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the readOnly annotation, it discloses partial-profile fallback with a notice instead of failing, country-level-only aggregation with aggregates excluded, per-country latest-year summing grouped by unit to avoid mixing incomparable quantities, and the DataCanvas spill side effect. These details materially shape call expectations.

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 dense and front-loaded with the core purpose, and every sentence adds a behavioral or routing fact. It is longer than minimal, but the tool is complex enough to justify the length; a few return-format details could have been left to the output schema.

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 complex aggregation tool, the description covers the main flow, ranking semantics, edge cases (missing local domain), country-level scope, and the SQL hand-off. Combined with fully described parameters, annotations, and an output schema, an agent has enough context to invoke it correctly.

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 extra meaning for item_query: relevance matching, folding the 5 best-matching items into one profile, and narrowing broad names with a disclosed match count. Other parameters already have adequate schema descriptions.

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 opens with a specific verb and resource — 'Assemble a global profile for one commodity in a single call' — and enumerates concrete deliverables: top-producing countries, annual production trend, and trade flows. It names a sibling (faostat_dataframe_query) for deeper SQL, which further disambiguates its role.

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?

It clearly positions this as the one-call profile tool and routes heavy analysis to faostat_dataframe_query after the observation set spills to a DataCanvas table. It does not, however, explicitly state when to prefer faostat_query_observations or faostat_resolve_codes instead.

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. CAST(value AS DOUBLE) for arithmetic.
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.9/5.0
Behavior5/5

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses meaningful behavioral constraints: writes, DDL, DROP, COPY, PRAGMA, ATTACH, external-file table functions, and system catalogs are all rejected. It also explains the data-quality `flag` field and warns that unknown flags should never be assumed official, which is valuable behavioral context for interpreting results.

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?

The description is dense but every clause earns its place: purpose, use cases, restrictions, sibling routing, and flag semantics. The most important sentence is front-loaded, and the lengthy details about rejected statements and flag meanings are all operationally important for correct use.

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 powerful SQL query tool, the description is fully complete: it explains the data source, the supported SQL features, the read-only constraints, the denied catalogs, how to discover tables, and the meaning of the `flag` column. The output schema exists, so return-value details do not need to be repeated. There are no obvious gaps an agent would face when deciding whether and how to call this tool.

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?

The schema already covers all three parameters at 100%, so the baseline is 3. The description adds real guidance for the `sql` parameter by stating that standard DuckDB SQL is supported (joins, aggregates, window functions, CTEs) and by encouraging the agent to keep `flag` in projections. That lifts it above a purely redundant description.

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 opens with a specific verb+resource: 'Run a single-statement SELECT against the canvas tables staged by...'. It also distinguishes itself from siblings by explaining the tables come from faostat_query_observations and faostat_commodity_profile, and points to faostat_dataframe_describe for listing tables. An agent can immediately understand what this tool does and how it differs from the other faostat tools.

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 states the intended use cases: cross-country and cross-item aggregation, GROUP BY rankings, joins, and time-series analysis over the full result set. It also gives a clear when-not-to guide by enumerating rejected statement types and directing the agent to faostat_dataframe_describe when listing staged tables is the goal.

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) for GROUP BY / ranking / time-series analysis via faostat_dataframe_query. 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 result — pass to faostat_dataframe_query / _describe.
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 name holding the full result set (present when spilled).
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?

Beyond the readOnlyHint annotation, the description discloses that large results are staged to a DataCanvas table (returned canvas_id + table_name), that aggregate regions are excluded by default to prevent double-counting, and that quality flags must be honored (e.g., never assume an estimated or imputed value is official). These are non-obvious behavioral traits that materially affect how an agent should interpret results.

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 front-loaded with the core query action and return fields, then flows logically through prerequisite, aggregate handling, spill behavior, and flag warnings. It is somewhat long, especially the flag enumeration, but every sentence carries substantive guidance, so the length is justified by the tool's complexity.

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 9-parameter schema with 100% coverage and an existing output schema, the description covers all necessary operational aspects: what the tool returns, the hard dependency on faostat_resolve_codes, the aggregate behavior and its double-counting risk, the staging mechanism for large results, and the meaning and caution around data-quality flags. Nothing critical for correct invocation 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 description coverage is 100%, so the baseline is 3, but the description adds meaningful workflow context beyond the schema: it ties all code parameters to the prerequisite faostat_resolve_codes and explains why include_aggregates defaults to false (avoid double-counting in a naive SUM). It also clarifies the semantic relationship between explicit area_codes and aggregate exclusion, which the schema states but the description reinforces with rationale.

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 opens with a precise verb and resource: "Query a FAOSTAT domain's data cube by area(s), item(s), element(s), and year range, returning observations..." This fully distinguishes it from siblings like faostat_resolve_codes (which resolves names to codes) and faostat_dataframe_query (which runs SQL on staged tables). The return fields are enumerated, making the tool's role unmistakable.

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 when-to-use guidance: "Resolve codes first with faostat_resolve_codes — the cube is unqueryable without them." It also names the alternative path for large results: "spill to a DataCanvas table ... for GROUP BY / ranking / time-series analysis via faostat_dataframe_query." The aggregate-exclusion caveat further instructs when to set include_aggregates=true versus passing explicit area_codes.

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

A5/5.0
Behavior5/5

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

The description adds substantial behavior beyond annotations: domain scoping of item/element results, the 'country' vs 'aggregate' flag, the ≥5000 code heuristic (plus curated exceptions like China=351), double-counting risk, and the truncated/nextOffset pagination contract. It never contradicts readOnlyHint or idempotentHint—it enriches them.

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?

The description is dense but every sentence contributes: purpose, three matching modes, domain scoping, pagination mechanics, aggregate warning with specific examples. It is front-loaded with the core purpose and ends with the critical usage caveat. No filler; each clause earns its place.

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 7-parameter tool with an output schema and annotations, the description leaves nothing ambiguous: it covers all parameter relationships, pagination, domain scoping, and a major data-quality pitfall. Given the existence of an output schema, the lack of return-value details is appropriate. It is fully complete for correct invocation.

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

Parameters5/5

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

Despite 100% schema coverage, the description adds real meaning: it gives a concrete example ('maize' → item 56), clarifies precedence relationships among query/name_contains/code, states that code takes precedence and name_contains is used only when query is omitted, and explains offset/limit behavior. This is more than the schema provides.

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

Purpose5/5

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

The description states a clear verb and resource ('Resolve human terms to the opaque integer codes... within a dimension') and enumerates the three dimensions (areas, items, elements). It explicitly distinguishes itself from faostat_query_observations by saying these codes are what that tool needs, so agents can tell them apart without inspecting schemas.

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

Usage Guidelines5/5

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

It explicitly says when to use this tool ('resolve before querying') and what to exclude (aggregates unless you want the regional roll-up). It also details the three matching modes and when each applies, plus pagination instructions with nextOffset. This is among the best guidance seen, covering both when and how.

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. 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"
+]
  2. 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"
-]
  3. 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."
  4. 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"
+]
  5. 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"
+]
  6. 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."
  7. 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."
  8. 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)."
  9. 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"
+]
  10. 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
    C
    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
    B
    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.
    Apache 2.0

  • monarch-mcp

    sdeiley
    A
    license
    Not graded
    quality
    B
    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