Skip to main content
Glama

faostat-mcp-server

by io.github.cyanheads

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.

Input Schema

TableJSON 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

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

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
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.4/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: discovery (list_domains), code resolution (resolve_codes), raw data query (query_observations), high-level profile assembly (commodity_profile), and dataframe management (describe/query). The composite profile tool overlaps slightly with query_observations, but its description clearly positions it as a convenience wrapper, eliminating ambiguity.

Naming Consistency4/5

All tools share the faostat_ prefix, and most use verb_noun structure (list_domains, query_observations, resolve_codes, dataframe_describe, dataframe_query). The exception is commodity_profile, which is a noun_phrase rather than verb-first, though it is still descriptive and follows the overall underscore convention. This minor deviation keeps the set mostly consistent.

Tool Count5/5

With 6 tools, the server is well-scoped for its purpose: it covers the essential workflow of discovering domains, resolving codes, querying data, and analyzing results via dataframes. Each tool has a clear role, and the count is appropriate for a focused statistical data server without excess or deficiency.

Completeness5/5

The tool surface covers the full data retrieval lifecycle: domain discovery, code resolution, raw data extraction, and flexible post-query analysis (including a high-level commodity profile shortcut). The descriptions handle edge cases like aggregation exclusion and flag validation, and no obvious gaps exist for a read-only FAOSTAT querying server.

Resources