A
license-
qualityB
maintenanceMCP server that exposes SQLite datasets as queryable tools and resources via Streamable HTTP, enabling read-only exploration and SQL queries.
Apache 2.0
faostat-mcp-server
Server Details
UN FAOSTAT global food & agriculture statistics over a local SQLite mirror, via MCP.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
- Repository
- cyanheads/faostat-mcp-server
- GitHub Stars
- 1
- Server Listing
- @cyanheads/faostat-mcp-server
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
MCP client
Glama
MCP server
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
100% free. Your data is private.
Tool Definition Quality
A4.4/5.0
Tool DescriptionsA
Average 4.5/5 across 6 of 6 tools scored.
Server CoherenceA
Disambiguation5/5
Each tool has a clearly distinct purpose: listing domains, resolving codes, querying observations, generating commodity profiles, describing staged dataframes, and running SQL queries. There is no meaningful overlap; the descriptions effectively differentiate them.
Naming Consistency4/5
Most tools follow a consistent snake_case verb_noun pattern (list_domains, resolve_codes, query_observations, dataframe_query). The exception is 'commodity_profile' which is noun_noun, but it is still descriptive and fits the style. Overall, naming is predictable and clear.
Tool Count5/5
Six tools is an ideal size for this server's purpose. They cover discovery, data retrieval, code resolution, composite analysis, and query capabilities without excess or deficiency.
Completeness5/5
The tool set covers the full workflow for FAOSTAT data: discover domains, resolve codes, query observations, obtain commodity profiles, and perform ad-hoc analysis via SQL. There are no obvious gaps, and the read-only nature of the data is respected.
Available Tools
6 toolsfaostat_commodity_profilefaostat-mcp-server: commodity profileARead-onlyInspect
Assemble a global profile for one commodity in a single call: top-producing countries, the annual production trend, and trade flows (top exporters and importers). Accepts a commodity name, resolves it to item codes, then queries the production (QCL) and trade (TCL) domains and merges the results. Each ranking is a per-country sum across the resolved items, taken at that country's own latest year with data and grouped by unit so incomparable quantities are never added. The trend is returned inline as year/value points. Country-level only (aggregates excluded). When a required domain is not indexed locally, returns a partial profile with a notice naming the gap rather than failing. The full merged observation set spills to a DataCanvas table for deeper SQL via faostat_dataframe_query.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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 from a prior call to stage onto. Omit to start a fresh canvas. | |
| 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
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| notice | No | Names any required domain that was not indexed, item-resolution truncation, mixed units in the rankings, or other partial-result context. |
| spilled | Yes | 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 | Yes | 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 | Yes | 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 | Yes | Total production observations aggregated into production_trend. Exact — the aggregation runs over the complete filtered match, not a capped page. |
| top_exporters | Yes | Top exporters by summed export quantity (empty when trade is not indexed). |
| top_importers | Yes | Top importers by summed import quantity (empty when trade is not indexed). |
| top_producers | Yes | Top producers by summed production (countries only). |
| itemsTruncated | Yes | True when the commodity name matched more items than the profile folded in — the profile then covers only the most relevant few. |
| resolved_items | Yes | Commodities the query resolved to (the profile aggregates across all of them). |
| production_trend | Yes | 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 | Yes | Item codes the commodity query resolved to. |
| resolvedItemMatches | Yes | Total items the commodity query matched in QCL, before the 5-item profile cap. |
Tool Definition Quality
A4.6/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond readOnlyHint annotation, description details behavior: resolves item codes, queries multiple domains, merges with careful unit grouping, returns partial profiles on missing domains, and spills to canvas. No contradictions with annotations.
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?
Description is fairly long but each sentence adds value; front-loaded with summary. Could be slightly more concise, but well-structured.
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?
Covers merging logic, fallback behavior, country-level restriction, canvas spill. Output schema exists, so return values are covered. Complete for a complex composite tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage, so baseline is 3. Description adds extra context like matching by relevance with 5-item limit, narrowing broad names, and canvas staging. Adds value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it assembles a global profile for one commodity, listing top producers, trend, and trade flows. It distinguishes itself from sibling tools like faostat_query_observations and faostat_dataframe_query by being a composite, single-call profile.
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?
The description implies when to use (for a quick commodity profile) and mentions deeper SQL via canvas, but does not explicitly state when not to use or compare to all siblings. Still provides good context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
faostat_dataframe_describefaostat-mcp-server: dataframe describeARead-onlyIdempotentInspect
List the canvas tables (faostat_xxxxxxxx) staged by faostat_query_observations and faostat_commodity_profile, each with its source tool, the query parameters that produced it, creation/expiry timestamps, row count, and column schema. Call this before faostat_dataframe_query to discover the exact table and column names to reference in SQL.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional table name (faostat_xxxxxxxx) to describe a single staged table. Omit to list all. | |
| canvas_id | No | Optional canvas ID from a prior faostat_query_observations / faostat_commodity_profile call. Omit to list the tables staged in this session (the common case). |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| tables | Yes | Active staged tables for this session, newest first. Empty when none are staged. |
Tool Definition Quality
A4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent behavior; the description adds details on what information is returned (timestamps, row count, columns) but no further behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no redundant or verbose phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, and output details; with output schema present, return value explanation is not needed. Minor gap: no mention of behavior when no tables exist.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear parameter descriptions; the tool description adds no additional meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists canvas tables with details like source tool and query parameters, and explicitly differentiates from sibling faostat_dataframe_query by advising to call it first.
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?
Explicit guidance to call before faostat_dataframe_query to discover table and column names, but does not mention alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
faostat_dataframe_queryfaostat-mcp-server: dataframe queryARead-onlyIdempotentInspect
Run a single-statement SELECT against the canvas tables staged by faostat_query_observations and faostat_commodity_profile (table names look like faostat_xxxxxxxx). Use this for cross-country and cross-item aggregation, GROUP BY rankings, joins, and time-series analysis over the full result set the inline preview only sampled. Standard DuckDB SQL — joins, aggregates, window functions, CTEs all work. Read-only: writes, DDL, DROP, COPY, PRAGMA, ATTACH, and external-file table functions are rejected; system catalogs (information_schema, sqlite_master, duckdb_*) are denied — list staged tables via faostat_dataframe_describe. Every row carries its data-quality flag — commonly A=Official, B=time-series break, E=Estimated, I=Imputed, M=Missing (value cannot exist), T=Unofficial, X=from an international organization, plus others FAOSTAT defines per domain — keep it in projections, treat any unrecognized flag as informational, and never assume it is official.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | Single-statement read-only SELECT against staged faostat_<id> tables. Columns: area_code, area, item_code, item, element_code, element, year, unit, value, flag. CAST(value AS DOUBLE) for arithmetic. | |
| canvas_id | No | Optional canvas ID from a prior faostat_query_observations / faostat_commodity_profile call. Omit to query the tables staged in this session (the common case). | |
| row_limit | No | Hard cap on rows in the response. Default 1000, max 10000. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| rows | Yes | Materialized result rows, bounded by row_limit. |
| notice | No | Guidance when the query returned no rows or when results were capped. |
| columns | Yes | Column names in projection order. |
| row_count | Yes | Rows returned in this response — the materialized count, equal to rows.length. When truncated is true this is NOT the full result total (this path computes no exact total); page or aggregate to reach the rest. |
| truncated | Yes | True when row_limit capped the result and more rows exist than were returned. To reach them: page with ORDER BY + SQL LIMIT/OFFSET, raise row_limit (max 10000), or aggregate with GROUP BY. |
Tool Definition Quality
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint. The description goes beyond by detailing exactly what operations are rejected (writes, DDL, COPY, PRAGMA, ATTACH, external-file table functions) and that system catalogs are denied. It also explains flag semantics, adding significant behavioral context.
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 informative but somewhat lengthy. It front-loads the core purpose and includes necessary details. Minor redundancy exists (e.g., multiple mentions of read-only), but overall it is well-structured and each sentence adds value.
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 complexity of a SQL query tool with 3 parameters and an output schema, the description covers allowed SQL operations, restrictions, flag handling, column names, and references sibling tools. It is complete enough for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds extra context beyond the schema, such as recommending CAST(value AS DOUBLE) for arithmetic and explaining the flag column's meaning and common codes. This additional insight justifies a score of 4.
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 the tool runs a single-statement SELECT against staged tables, specifying the use case (cross-country aggregation, GROUP BY, joins, time-series analysis). It distinguishes itself from sibling tools by referencing faostat_dataframe_describe for listing tables and faostat_query_observations/commodity_profile for staging.
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 explicitly says when to use ('cross-country and cross-item aggregation, GROUP BY rankings, joins, and time-series analysis') and what is not allowed (writes, DDL, DROP, etc.). It also provides guidance on flags and mentions alternative tools for listing tables.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
faostat_list_domainsfaostat-mcp-server: list domainsARead-onlyIdempotentInspect
Discover FAOSTAT statistical domains (production, trade, food balances, food security, land use, agri-emissions, prices, value) with their codes, descriptions, last-update date, upstream row count, and local index status. Every query keys on a domain code from here. The indexed flag tells you which domains are queryable right now; un-indexed domains exist in the catalog but must be added to FAOSTAT_DOMAINS and re-synced before faostat_query_observations can read them. The catalog runs to ~69 domains with long descriptions, so responses are paged: narrow with topic / indexed_only, pass code to fetch one domain outright, or page with offset + limit — when the response reports truncated, pass the returned nextOffset to fetch the rest.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | 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. | |
| limit | No | 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. | |
| topic | No | Case-insensitive substring filter over domain code, name, and topic (e.g. "trade", "emissions", "QCL"). Omit to list the full catalog. | |
| offset | No | 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). | |
| indexed_only | No | When true, return only domains indexed in the local mirror (queryable now). |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| notice | No | Guidance when a filter matched nothing, more pages remain, or no domains are indexed yet. |
| domains | Yes | Matching domains, sorted by code. |
| truncated | Yes | True when more matches remain beyond the returned page — fetch them with nextOffset. |
| nextOffset | No | 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. |
| totalCount | Yes | Total domains in the FAOSTAT catalog, independent of any filter. |
| indexedCount | Yes | Domains currently indexed in the local mirror. |
| totalMatches | Yes | Domains matching the current filters, before the page limit is applied. |
Tool Definition Quality
A4.8/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already confirm read-only, idempotent, and closed-world behavior. The description adds practical context: the indexed flag for queryability, pagination mechanics with nextOffset, and that limit can be set above catalog size. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured paragraph. It first states purpose, then the key indexed flag, then pagination and filtering guidance. Each sentence adds unique information without redundancy.
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 output schema existence and full parameter coverage, the description covers all critical aspects: what the tool returns, how to filter, paginate, and the relationship to query tools. It is fully self-contained for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the description still adds value: explains limit's max allows fetching all at once, offset is ignored for code lookups, code overrides other filters, and topic is case-insensitive. These clarifications go beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the tool's purpose—listing FAOSTAT domains—and details the returned fields (codes, descriptions, last-update, row count, index status). It clearly distinguishes from sibling tools, which focus on queries, commodity profiles, and code resolution.
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 explicitly states that domain codes from here are keys for queries, explains when to use indexed_only vs topic filters, and provides step-by-step pagination instructions including handling truncation. It also contrasts with faostat_query_observations by noting the indexed flag.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
faostat_query_observationsfaostat-mcp-server: query observationsARead-onlyInspect
Query a FAOSTAT domain's data cube by area(s), item(s), element(s), and year range, returning observations (area, item, element, year, value, unit, and the data-quality flag). Resolve codes first with faostat_resolve_codes — the cube is unqueryable without them. Aggregate regions (World, continents, economic groupings) are EXCLUDED by default so a naive SUM does not double-count a region with its member countries; set include_aggregates=true to get the regional roll-ups, or pass explicit area_codes to query exactly what you name. Small result sets return inline; large ones spill to a DataCanvas table (returned canvas_id + table_name) for GROUP BY / ranking / time-series analysis via faostat_dataframe_query. Every row carries its flag — commonly A=Official, B=time-series break, E=Estimated, I=Imputed, M=Missing (value cannot exist), T=Unofficial, X=from an international organization, plus others FAOSTAT defines per domain — so honor it, treat any unrecognized flag as informational, and never assume an estimated, imputed, or unrecognized value is official.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max observations returned inline — also the preview size when the result stages to a canvas table. Rows past it are never dropped silently: a match larger than limit stages in full to a DataCanvas table (canvas_id + table_name), and when no table is staged the notice reports how many matched so you can raise limit or narrow the filters. Max 1000. | |
| domain | Yes | FAOSTAT domain code (e.g. "QCL"). Must be indexed locally. | |
| year_end | No | Inclusive end year (e.g. 2022). | |
| canvas_id | No | Canvas ID from a prior call to stage onto. Omit to start a fresh canvas (a new id is returned). | |
| area_codes | No | Area codes from faostat_resolve_codes. When set, aggregates are NOT auto-excluded — the codes are honored verbatim. | |
| item_codes | No | Item codes from faostat_resolve_codes. | |
| year_start | No | Inclusive start year (e.g. 2000). | |
| element_codes | No | Element codes from faostat_resolve_codes (e.g. 5510 Production). | |
| include_aggregates | No | When false (default), exclude aggregate-region rows (codes ≥ 5000 plus a few curated sub-threshold roll-ups such as China=351) so sums are not double-counted. Set true for World/continent/grouping roll-ups. Ignored when explicit area_codes are passed. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| domain | Yes | The domain code echoed back. |
| notice | No | Guidance on empty results, aggregate exclusion, or how to reach the spilled set. |
| spilled | Yes | True when the full result was staged on a DataCanvas table. |
| canvas_id | No | Canvas ID holding the staged result — pass to faostat_dataframe_query / _describe. |
| truncated | Yes | True when the staged table hit the 50,000-row staging cap — the staged set is a PREFIX of the match, not the complete result. Partition the query by year or code ranges to capture the rest. |
| table_name | No | Canvas table name holding the full result set (present when spilled). |
| totalCount | Yes | Observations matched. Exact when the result was returned inline or fully staged. A floor — more matched — in two cases, both named by the notice: the match exceeded the 50,000-row staging cap (truncated is then true), or staging failed and the response fell back to an inline page. |
| observations | Yes | Inline observations (preview when the full set spilled to a canvas table). |
| staged_row_count | No | Rows actually staged on the canvas table (present when spilled). Equals the full match count unless truncated, in which case it is the 50,000-row cap. |
Tool Definition Quality
A4.5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond readOnlyHint, the description discloses data-quality flags, default exclusion of aggregates to avoid double-counting, and behavior for large result sets including that rows past limit are never dropped silently. No contradiction with annotations.
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 moderately long but well-structured, front-loading purpose then guidelines. Each sentence adds value, though it could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complexity and rich schema/output schema, the description covers key requirements: prerequisite resolve, default aggregation handling, spill mechanism, and flag meanings. Slightly lacking details on output schema but output schema exists.
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%, baseline 3. The description adds value by explaining that area_codes from faostat_resolve_codes, include_aggregates is ignored when area_codes passed, and limit behavior with staging.
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 explicitly states the tool queries a FAOSTAT domain data cube by areas, items, elements, and year range, returning observations with specific fields. It distinguishes from siblings by referencing faostat_resolve_codes and faostat_dataframe_query.
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?
The description gives clear guidance: resolve codes first, explains include_aggregates behavior, and mentions spilling to canvas for large results. It does not explicitly exclude alternatives but provides good context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
faostat_resolve_codesfaostat-mcp-server: resolve codesARead-onlyIdempotentInspect
Resolve human terms to the opaque integer codes faostat_query_observations needs, within a dimension: areas (countries/regions), items (commodities), or elements (metrics like production, yield, import quantity). Pass query for fuzzy full-text matching ("maize" → item 56), name_contains for a substring filter, or code for an exact-code lookup; omit all three to list the whole dimension. Item and element results are scoped to the requested domain — only codes present in that domain's cube are returned, so a resolved code is always queryable there (areas are shared across domains). Page large listings with offset + limit: when the response reports truncated, pass the returned nextOffset to fetch the next page. Every area match is flagged country or aggregate — aggregates (World, continents, economic groupings — codes ≥ 5000 plus a few curated sub-threshold roll-ups such as China=351, which sums mainland + Taiwan + Hong Kong + Macao) double-count if summed with their member countries, so resolve before querying and exclude aggregates unless you want the regional roll-up.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | Exact code lookup. Takes precedence over `query`/`name_contains` when provided. | |
| limit | No | Maximum matches to return (max 200). | |
| query | No | Full-text search term, FTS5-matched against the dimension labels with prefix matching (e.g. "wheat", "import quantity"). Relevance-ranked. | |
| domain | Yes | FAOSTAT domain code (e.g. "QCL"). Item and element resolution is scoped to the codes present in this domain's data; area code lists are shared across all indexed domains. | |
| offset | No | Zero-based pagination offset into the match set. When the response reports truncated, pass the returned nextOffset here to fetch the next page. Ignored for exact-code lookups (always single-page). | |
| dimension | Yes | Which dimension to resolve: "area" (countries/regions), "item" (commodities), or "element" (metrics). | |
| name_contains | No | Case-insensitive substring filter over the label. Used only when `query` is omitted. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| domain | Yes | The domain code echoed back. |
| notice | No | Guidance when nothing matched, more pages remain, or the dimension is not yet indexed. |
| matches | Yes | Matching codes, relevance-ranked for query mode, else by code. |
| dimension | Yes | The dimension resolved. |
| truncated | Yes | True when more matches remain beyond the returned page — fetch them with nextOffset. |
| nextOffset | No | 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. |
| totalMatches | Yes | Total matches in this domain before the result cap. |
Tool Definition Quality
A4.5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, idempotentHint), the description adds critical behavioral details: domain scoping for items/elements, pagination with truncated and nextOffset, and the country/aggregate distinction with examples. This fully informs the agent of side effects and constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and is structured logically, but it is somewhat lengthy. Every sentence adds value, but it could be slightly more concise without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, 2 required, and output schema existence, the description covers key aspects: usage of each parameter, pagination, domain scoping, and aggregate warning. It lacks explanation of the output schema, but since schema exists, this is acceptable.
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?
With 100% schema coverage, baseline is 3. The description adds meaningful context: domain scoping for items/elements, pagination with offset/limit, precedence of code over query, and the aggregate flag in responses. This enhances understanding beyond parameter names and types.
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 the tool resolves human terms to integer codes needed by faostat_query_observations, specifying it operates within dimensions areas, items, or elements. This distinguishes it from sibling tools like faostat_query_observations by clarifying its role in the pipeline.
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?
The description provides explicit guidance on when to use each parameter (query, name_contains, code, or omit all) and warns about aggregate double-counting. However, it does not explicitly state when to use this tool versus alternatives like faostat_dataframe_query, so it slightly misses the when-not aspect.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!
Related MCP Servers
- Alicense-qualityBmaintenanceProvides an MCP server for querying and managing Monarch Money personal finance data through a local SQLite mirror with read-only SQL access. It enables users to sync transaction history from the Monarch API and analyze accounts, categories, and tags.1MIT
- Flicense-qualityCmaintenanceCustom MCP server connected to a read-only SQLite database, exposing a schema resource and a query tool for safe data retrieval.
- AlicenseAqualityBmaintenanceLocal-first MCP server for discovering, downloading, and analyzing official IBGE microdata using DuckDB and Parquet.221MIT
Try in Browser
Your Connectors
Sign in to create a connector for this server.