faostat-mcp-server

faostat-mcp-server: commodity profile

faostat_commodity_profile

Read-only

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.

Input Schema

TableJSON Schema

Name	Required	Description
`top_n`	No	Number of top producers / exporters / importers to return. Max 50.
`year_end`	No	Inclusive end year for the trend (e.g. 2022).
`canvas_id`	No	Canvas ID to stage onto, as returned by a prior faostat_query_observations / faostat_commodity_profile call — exactly 10 characters of letters, digits, hyphens, and underscores. Omit to stage onto this session’s canvas, created on the first spill and reused by every later call, so tables staged earlier in the session sit alongside this one.
`item_query`	Yes	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.
`year_start`	No	Inclusive start year for the trend (e.g. 1990).

Output Schema

TableJSON Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Names any required domain that was not indexed, item-resolution truncation, mixed units in the rankings, or other partial-result context.
`spilled`	No	True when the merged observation set was staged on a canvas table.
`canvas_id`	No	Canvas ID holding the merged set — pass to faostat_dataframe_query / _describe.
`truncated`	No	True when the STAGED CANVAS TABLE hit the 50,000-row staging cap and is therefore a PREFIX of the merged observation set — re-query faostat_query_observations partitioned by year to stage the rest. The rankings and production_trend above are SQL aggregates over the complete match and stay exact either way.
`item_query`	No	The commodity query echoed back.
`table_name`	No	Canvas table holding the staged observations — production plus trade when the trade domain (TCL) is indexed, production only when it is not (present when spilled). The notice names which of the two the table holds.
`trend_points`	No	Total production observations aggregated into production_trend. Exact — the aggregation runs over the complete filtered match, not a capped page.
`top_exporters`	No	Top exporters by summed export quantity (empty when trade is not indexed).
`top_importers`	No	Top importers by summed import quantity (empty when trade is not indexed).
`top_producers`	No	Top producers by summed production (countries only).
`itemsTruncated`	No	True when the commodity name matched more items than the profile folded in — the profile then covers only the most relevant few.
`resolved_items`	No	Commodities the query resolved to (the profile aggregates across all of them).
`production_trend`	No	The annual production series for the resolved commodity, summed over countries and items per year and ordered oldest-first. Aggregated in SQL over the complete filtered match, so it is not affected by the canvas staging cap.
`staged_row_count`	No	Rows actually staged on the merged canvas table (present when spilled). Equals the 50,000-row cap when truncated.
`resolvedItemCodes`	No	Item codes the commodity query resolved to.
`resolvedItemMatches`	No	Total items the commodity query matched in QCL, before the 5-item profile cap.

Schema Changelog

Changes observed during successful MCP inspections.

Changed18 schema fields changedSep 19, 2026

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"
+]
```

Changed6 schema fields changedAug 25, 2026

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"
-]

Changed33 schema fields changedJul 27, 2026

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"
+]

Changed3 schema fields changedJul 14, 2026

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

Changed4 schema fields changedJul 13, 2026

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"
+]

First observedJun 16, 2026

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.

All faostat-mcp-server tools Inspect

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.