Skip to main content
Glama
Sign In

faostat-mcp-server

by io.github.cyanheads
OverviewDiscussionsAdmin

faostat-mcp-server: list domains

faostat_list_domains
Read-onlyIdempotent

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.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "faostat_list_domains"
  }
}

Input 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

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

Schema Changelog

Changes observed during successful MCP inspections.

  1. 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": [
+      "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"
-]
  2. Changed9 schema 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"
+]
  3. First observed

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.

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