Skip to main content
Glama

faostat-mcp-server

by io.github.cyanheads
OverviewDiscussionsAdmin

faostat-mcp-server: commodity profile

faostat_commodity_profile
Read-only

Assemble a global profile for one QCL item in a single call: top-producing countries, the annual production trend, and trade flows (top exporters and importers). Supply item_code or item_query; code wins when both are supplied. A query selects a unique normalized exact label, otherwise a unique relevance match; ambiguous queries require an explicit code. Each ranking uses the selected item at each country's own latest year with data, grouped by unit. The trend is returned inline as year/value points. Country-level only (aggregates excluded). QCL is required; unavailable TCL yields a production-only profile with a notice. When the merged observation set is too large to inline, it spills to a DataCanvas table (canvas_id + table_name) — call faostat_dataframe_describe for its columns, then faostat_dataframe_query for deeper SQL.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
top_nNoNumber of top producers / exporters / importers to return. Max 50.
year_endNoInclusive end year for the trend (e.g. 2022).
canvas_idNoCanvas ID to stage onto, as returned by a prior faostat_query_observations / faostat_commodity_profile call — exactly 10 characters of letters, digits, hyphens, and underscores. Omit to stage onto this session’s canvas, created on the first spill and reused by every later call, so tables staged earlier in the session sit alongside this one.
item_codeNoExact item code present in QCL; takes precedence over item_query. Obtain it from faostat_resolve_codes with domain QCL and dimension item.
item_queryNoCommodity label or search term (e.g. "Wheat"). A unique normalized exact QCL label wins, otherwise the relevance search must match exactly one item. Broad queries such as "maize" or "milk" require item_code. Supply this or item_code.
year_startNoInclusive start year for the trend (e.g. 1990).

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
noticeNoStates where the observation set went — the canvas table, inline result, staging failure, or disabled canvas — plus unavailable trade data, mixed units, or other partial-result context.
spilledNoTrue when the merged observation set was staged on a canvas table.
canvas_idNoCanvas ID this call staged onto. When spilled it holds table_name — pass both to faostat_dataframe_describe (table_name as name) for the columns and types, then canvas_id to faostat_dataframe_query for SQL. Also present when the merged set fit inline and no table was staged; faostat_dataframe_describe with this canvas_id then lists any tables already staged on it. Absent when the canvas is disabled or staging failed.
truncatedNoTrue when the STAGED CANVAS TABLE hit the 50,000-row staging cap and is therefore a PREFIX of the merged observation set — re-query faostat_query_observations partitioned by year to stage the rest. The rankings and production_trend above are SQL aggregates over the complete match and stay exact either way.
item_queryNoSupplied query echoed back, or the canonical selected label for code-only calls.
table_nameNoCanvas table holding the staged observations — production plus trade when the trade domain (TCL) is indexed, production only when it is not (present when spilled). The notice names which of the two the table holds. Pass it as name to faostat_dataframe_describe for its columns (a domain column tags each row QCL or TCL), then reference it in faostat_dataframe_query SQL.
trend_pointsNoTotal production observations aggregated into production_trend. Exact — the aggregation runs over the complete filtered match, not a capped page.
top_exportersNoTop exporters by summed export quantity (empty when trade is not indexed).
top_importersNoTop importers by summed import quantity (empty when trade is not indexed).
top_producersNoTop producers by summed production (countries only).
itemsTruncatedNoAlways false: successful profiles select one item without truncating selection.
resolved_itemsNoThe single selected QCL item and its canonical label.
production_trendNoThe annual production series for the selected item, summed over countries per year and ordered oldest-first. Aggregated in SQL over the complete filtered match, so it is not affected by the canvas staging cap.
staged_row_countNoRows actually staged on the merged canvas table (present when spilled). Equals the 50,000-row cap when truncated.
resolvedItemCodesNoItem codes the commodity query resolved to.
resolvedItemMatchesNoNumber of selected QCL items; always one for a successful profile.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed18 schema fields changed
    • addedInput schema / properties / item_code
      Added value: +{
+  "description": "Exact item code present in QCL; takes precedence over item_query. Obtain it from faostat_resolve_codes with domain QCL and dimension item.",
+  "maximum": 9007199254740991,
+  "minimum": 1,
+  "type": "integer"
+}
    • changedInput schema / properties / item_query / description
      Previous value: -"Commodity name to profile (e.g. \"maize\", \"wheat\", \"coffee green\"). Matched by relevance; the 5 best-matching items are folded into one profile, so a broad name such as \"milk\" is narrowed — the response discloses how many items matched in total."New value: +"Commodity label or search term (e.g. \"Wheat\"). A unique normalized exact QCL label wins, otherwise the relevance search must match exactly one item. Broad queries such as \"maize\" or \"milk\" require item_code. Supply this or item_code."
    • removedInput schema / required
      Removed value: -[
-  "item_query"
-]
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `no_match`: The item query resolved to no commodity code. `domain_not_indexed`: The production domain (QCL) is not in the local mirror selection (FAOSTAT_DOMAINS), so there is no production data to profile. `index_not_ready`: The production domain (QCL) is selected, but its mirror is cold — its initial sync has never completed. `invalid_year_range`: year_start is greater than year_end — a self-contradictory range that can never match. The bounds reach the production, trade, and merged canvas-stream queries alike, so every one of them would return nothing. `canvas_not_found`: DataCanvas is enabled and canvas_id does not resolve to a live canvas — unknown, expired, or owned by another tenant. `query_timeout`: The profile's mirror reads (commodity resolution, rankings, trend, staging stream) — time queued behind other calls plus execution — ran past the 45-second per-call ceiling. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `missing_item`: Neither item_code nor item_query was supplied. `ambiguous_item`: The query matches more than one QCL item without a unique exact label. `no_match`: The query matched no item, or item_code is absent from QCL. `domain_not_indexed`: The production domain (QCL) is not in the local mirror selection (FAOSTAT_DOMAINS), so there is no production data to profile. `index_not_ready`: The production domain (QCL) is selected, but its mirror is cold — its initial sync has never completed. `invalid_year_range`: year_start is greater than year_end — a self-contradictory range that can never match. The bounds reach the production, trade, and merged canvas-stream queries alike, so every one of them would return nothing. `canvas_not_found`: DataCanvas is enabled and canvas_id does not resolve to a live canvas — unknown, expired, or owned by another tenant. `query_timeout`: The profile's mirror reads (commodity resolution, rankings, trend, staging stream) — time queued behind other calls plus execution — ran past the 45-second per-call ceiling. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
-  "no_match",
-  "domain_not_indexed",
-  "index_not_ready",
-  "invalid_year_range",
-  "canvas_not_found",
-  "query_timeout"
-]New value: +[
+  "missing_item",
+  "ambiguous_item",
+  "no_match",
+  "domain_not_indexed",
+  "index_not_ready",
+  "invalid_year_range",
+  "canvas_not_found",
+  "query_timeout"
+]
    • changedOutput schema / properties / item_query / description
      Previous value: -"The commodity query echoed back."New value: +"Supplied query echoed back, or the canonical selected label for code-only calls."
    • changedOutput schema / properties / itemsTruncated / description
      Previous value: -"True when the commodity name matched more items than the profile folded in — the profile then covers only the most relevant few."New value: +"Always false: successful profiles select one item without truncating selection."
    • changedOutput schema / properties / notice / description
      Previous value: -"States where the observation set went — the canvas table it was staged on (with the describe-then-query pointer), fit inline, a staging failure, or a disabled canvas — plus a trade domain (TCL) that was not indexed, item-resolution truncation, mixed units in the rankings, or other partial-result context."New value: +"States where the observation set went — the canvas table, inline result, staging failure, or disabled canvas — plus unavailable trade data, mixed units, or other partial-result context."
    • changedOutput schema / properties / production_trend / description
      Previous value: -"The annual production series for the resolved commodity, summed over countries and items per year and ordered oldest-first. Aggregated in SQL over the complete filtered match, so it is not affected by the canvas staging cap."New value: +"The annual production series for the selected item, summed over countries per year and ordered oldest-first. Aggregated in SQL over the complete filtered match, so it is not affected by the canvas staging cap."
    • changedOutput schema / properties / production_trend / items / properties / value / description
      Previous value: -"Production summed across every country and resolved item reporting that year."New value: +"Selected item production summed across every country reporting that year."
    • changedOutput schema / properties / resolvedItemMatches / description
      Previous value: -"Total items the commodity query matched in QCL, before the 5-item profile cap."New value: +"Number of selected QCL items; always one for a successful profile."
    • changedOutput schema / properties / resolved_items / description
      Previous value: -"Commodities the query resolved to (the profile aggregates across all of them)."New value: +"The single selected QCL item and its canonical label."
    • changedOutput schema / properties / top_exporters / items / properties / observations / description
      Previous value: -"Observations summed into value — one per resolved item reporting that year."New value: +"Observations summed into value for the selected item and reporting year."
    • changedOutput schema / properties / top_exporters / items / properties / value / description
      Previous value: -"Export quantity summed across the resolved items for this country, in its latest reporting year."New value: +"Export quantity for the selected item and country in its latest reporting year."
    • changedOutput schema / properties / top_importers / items / properties / observations / description
      Previous value: -"Observations summed into value — one per resolved item reporting that year."New value: +"Observations summed into value for the selected item and reporting year."
    • changedOutput schema / properties / top_importers / items / properties / value / description
      Previous value: -"Import quantity summed across the resolved items for this country, in its latest reporting year."New value: +"Import quantity for the selected item and country in its latest reporting year."
    • changedOutput schema / properties / top_producers / items / properties / observations / description
      Previous value: -"Observations summed into value — one per resolved item reporting that year."New value: +"Observations summed into value for the selected item and reporting year."
    • changedOutput schema / properties / top_producers / items / properties / value / description
      Previous value: -"Production summed across the resolved items for this country, in its latest reporting year."New value: +"Production for the selected item and country in its latest reporting year."
  2. Changed5 schema fields changed
    • changedOutput schema / properties / canvas_id / description
      Previous value: -"Canvas ID holding the merged set — pass to faostat_dataframe_query / _describe."New value: +"Canvas ID this call staged onto. When spilled it holds table_name — pass both to faostat_dataframe_describe (table_name as name) for the columns and types, then canvas_id to faostat_dataframe_query for SQL. Also present when the merged set fit inline and no table was staged; faostat_dataframe_describe with this canvas_id then lists any tables already staged on it. Absent when the canvas is disabled or staging failed."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `no_match`: The item query resolved to no commodity code. `index_not_ready`: The production (QCL) mirror is cold — its initial sync has never completed. `invalid_year_range`: year_start is greater than year_end — a self-contradictory range that can never match. The bounds reach the production, trade, and merged canvas-stream queries alike, so every one of them would return nothing. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_match`: The item query resolved to no commodity code. `domain_not_indexed`: The production domain (QCL) is not in the local mirror selection (FAOSTAT_DOMAINS), so there is no production data to profile. `index_not_ready`: The production domain (QCL) is selected, but its mirror is cold — its initial sync has never completed. `invalid_year_range`: year_start is greater than year_end — a self-contradictory range that can never match. The bounds reach the production, trade, and merged canvas-stream queries alike, so every one of them would return nothing. `canvas_not_found`: DataCanvas is enabled and canvas_id does not resolve to a live canvas — unknown, expired, or owned by another tenant. `query_timeout`: The profile's mirror reads (commodity resolution, rankings, trend, staging stream) — time queued behind other calls plus execution — ran past the 45-second per-call ceiling. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
-  "no_match",
-  "index_not_ready",
-  "invalid_year_range"
-]New value: +[
+  "no_match",
+  "domain_not_indexed",
+  "index_not_ready",
+  "invalid_year_range",
+  "canvas_not_found",
+  "query_timeout"
+]
    • changedOutput schema / properties / notice / description
      Previous value: -"Names any required domain that was not indexed, item-resolution truncation, mixed units in the rankings, or other partial-result context."New value: +"States where the observation set went — the canvas table it was staged on (with the describe-then-query pointer), fit inline, a staging failure, or a disabled canvas — plus a trade domain (TCL) that was not indexed, item-resolution truncation, mixed units in the rankings, or other partial-result context."
    • changedOutput schema / properties / table_name / description
      Previous value: -"Canvas table holding the staged observations — production plus trade when the trade domain (TCL) is indexed, production only when it is not (present when spilled). The notice names which of the two the table holds."New value: +"Canvas table holding the staged observations — production plus trade when the trade domain (TCL) is indexed, production only when it is not (present when spilled). The notice names which of the two the table holds. Pass it as name to faostat_dataframe_describe for its columns (a domain column tags each row QCL or TCL), then reference it in faostat_dataframe_query SQL."
  3. Changed18 schema 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"
+]
  4. Changed6 schema 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"
-]
  5. Changed33 schema 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"
+]
  6. Changed3 schema 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."
  7. Changed4 schema 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"
+]
  8. First observed

TDQS

A4.6/5.0
Behavior5/5

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

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

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

Conciseness4/5

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

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

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

Completeness5/5

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

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

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

Parameters4/5

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

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

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

Purpose5/5

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

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

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

Usage Guidelines4/5

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

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

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

All faostat-mcp-server toolsInspect
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