Provides tools to query the FAOSTAT database of the United Nations Food and Agriculture Organization (FAO), enabling AI assistants to retrieve and analyze global food, agriculture, trade, nutrition, emissions, forestry, and fisheries statistics across 245 countries and territories.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@FAOSTAT MCP Server what was the global wheat production in 2020?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Query UN food and agriculture statistics with AI — powered by the Model Context Protocol
An MCP (Model Context Protocol) server that exposes the full FAOSTAT API as tools for AI assistants. Connect any MCP-compatible client — Claude, Cursor, Windsurf, Zed, or your own agent — to the world's most comprehensive database of food, agriculture, fisheries, forestry, and nutrition statistics, covering 245 countries and territories from the United Nations Food and Agriculture Organization (FAO).
Keywords: FAOSTAT, MCP server, Model Context Protocol, AI agriculture data, FAO statistics, food security AI, agricultural data Python, UN data, crop production statistics, Claude, Cursor, Windsurf
Researchers, data journalists, policy analysts, and developers can ask natural-language questions and get answers directly from FAOSTAT — without writing a single API call. Your AI assistant handles domain discovery, filtering, and interpretation automatically.
Who is this for?
Agricultural economists and food security researchers
Journalists and policy analysts working with FAO data
Developers building AI pipelines on top of FAOSTAT
Anyone who wants to explore crop, trade, nutrition, or emissions data conversationally
Related MCP server: USDA MCP Server
FAOSTAT is the statistical database of the United Nations Food and Agriculture Organization (FAO). It is the world's most comprehensive freely available source of data on food and agriculture, covering:
Crop and livestock production — yields, harvested area, and quantities for hundreds of commodities
Trade — import/export volumes and values between countries
Food security — prevalence of undernourishment, dietary energy supply, and access indicators
Emissions — greenhouse gas emissions from agriculture, land use, and food systems
Forestry and fisheries — production and trade data
Prices, inputs, and population — producer prices, fertilizer use, and demographic context
Data spans from 1961 to the present, across 245 countries and territories, in multiple languages.
The Model Context Protocol is an open standard that lets AI assistants call external tools at runtime. This server registers all FAOSTAT API endpoints as discoverable tools — your AI assistant automatically selects and chains the right calls when you ask a question.
21 MCP tools covering every FAOSTAT endpoint (data, metadata, rankings, bulk downloads, reports)
245 countries and territories across dozens of domains: crops, livestock, trade, food security, emissions, forestry, fisheries, and more
Built-in rate limiting (2 req/s) — safe for the FAOSTAT production API out of the box
Auto-retry with exponential backoff on transient network errors
Rich tool descriptions so the AI knows exactly when and how to call each tool
3-tier hybrid caching — in-memory (20 min) → SQLite disk (24 h, cross-session) → Redis (optional, 30 min)
Zero-config auth via faostat_setup — store credentials once, never touch a config file again
Disambiguation via faostat_search_codes — agents ask before guessing ambiguous codes
Works with Claude Desktop, Claude Code, Cursor, Windsurf, Zed, and any MCP-compatible client
Python 3.10+
Any MCP-compatible client (Claude Desktop, Cursor, Windsurf, Zed, or a custom agent)
Listed on the official MCP Registry — discoverable directly from Claude Desktop, Cursor, and any MCP-compatible client.
# Install with pip or uvx (no virtual env needed):
pip install faostat-mcp
uvx faostat-mcpgit clone https://github.com/berba-q/faostat-mcp.git
cd faostat-mcp
pip install -e .Easiest — use the faostat_setup tool (no config files needed):
Once the server is running and connected to your AI client, ask your assistant:
"Call faostat_setup with my FAOSTAT username and password."
The tool validates your credentials against the API, then stores them securely in your system keychain (macOS/Windows) or ~/.config/faostat-mcp/credentials.json (Linux/Docker). All subsequent sessions authenticate automatically — no env vars or .env file required.
Alternative — environment variables (CI/CD, Docker, advanced):
cp .env.example .env
# Edit .env:
# FAOSTAT_API_TOKEN=your_token_here ← API token, OR
# FAOSTAT_USERNAME=your_email ← username + password
# FAOSTAT_PASSWORD=your_passwordRegister for a free FAOSTAT API account at the FAOSTAT Developer Portal.
The server works without Redis (SQLite disk cache is used instead). For shared or high-volume setups, launch Redis via Docker:
docker run -p 6379:6379 -it redis/redis-stack:latestThen set REDIS_HOST_IP_ADDRESS, REDIS_HOST_PORT_NUMBER, and REDIS_DATABASE in .env.
mcp dev faostat_mcp/server.pyOpens a browser UI at http://localhost:5173 where you can browse and test all 21 tools interactively.
python -m faostat_mcp.server
# or, using the installed script:
faostat-mcpThe server uses a 3-tier cache to minimise redundant API calls. FAOSTAT data updates at most daily, so most repeated queries are served instantly.
Tier | TTL | Scope | Notes |
In-memory | 20 min | Current session | Fastest; reset on server restart |
SQLite disk | 24 h | Cross-session |
|
Redis | 30 min | Multi-user shared | Optional; set |
Cache lookup order: memory → disk → Redis → API call. A disk or Redis hit promotes the value to memory for the rest of the session.
To disable the disk cache (e.g. on a read-only filesystem), set FAOSTAT_DISK_CACHE=false.
The server speaks standard MCP over stdio, so it works with any compatible client.
{
"mcpServers": {
"faostat": {
"command": "uvx",
"args": ["faostat-mcp"]
}
}
}{
"mcpServers": {
"faostat": {
"command": "python",
"args": ["-m", "faostat_mcp.server"],
"cwd": "/path/to/faostat-mcp",
"env": {
"FAOSTAT_API_TOKEN": "your_token_here"
}
}
}
}Add one of the blocks above to:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Restart Claude Desktop — faostat will appear in the tools panel.
Add the block to .cursor/mcp.json in your project root, or to your global Cursor MCP settings. See the Cursor MCP docs for details.
Any client that supports MCP stdio servers accepts the same config shape. Consult your client's documentation for the config file location.
Once connected, ask your AI assistant questions like:
Domain | Example Question |
Crop production | "What were the top 10 wheat-producing countries in 2022?" |
Food security | "Show me food security indicators for Ethiopia from 2015 to 2020" |
Trade | "Which countries are most dependent on food imports?" |
Yield comparison | "Compare maize yields between the USA and Brazil over the last decade" |
Emissions | "What are greenhouse gas emissions from agriculture in Sub-Saharan Africa?" |
Discovery | "What agricultural datasets does FAOSTAT have for trade?" |
Your AI assistant will automatically:
Call faostat_list_groups or faostat_groups_and_domains to find the right domain
Call faostat_search_codes to look up a code by name — if multiple codes match (e.g. "production" matches both Production and Gross Production Index), the assistant pauses and asks you to choose before proceeding
Call faostat_get_data or faostat_get_rankings with the confirmed codes
Interpret and summarize the results in plain language
Tool | Description |
| Check API health |
| List all data groups |
| Full domain tree |
| Domains within a group |
| Available filters for a domain |
| Browse all country/item/element filter codes |
| Search codes by name — returns |
| Domain definitions |
| Definitions by type |
| All definition types |
| Full domain metadata |
| Printable metadata |
Tool | Description |
| Fetch actual statistics |
| Estimate query result size before fetching |
| Top-N country rankings |
| Report data |
| Report column headers |
| Bulk download file listing |
| Related documents |
Tool | Description |
| First-time setup — validate and store credentials securely; subsequent sessions authenticate automatically |
| Manually refresh the API access token |
faostat-mcp/
├── pyproject.toml
├── smithery.yaml ← Smithery MCP registry manifest
├── .env.example
├── mcp_config_example.json ← AI config snippet
└── faostat_mcp/
├── server.py ← FastMCP server + all 21 tool definitions
└── client.py ← HTTP client, rate limiting, 3-tier cache, credential storageThe FAOSTAT API uses two different code systems: filter codes (used in query parameters) and display codes (shown in response data and bulk CSVs). Always use filter codes from faostat_get_codes when calling faostat_get_data.
Area, item, and year codes are the same for both. Only element codes differ:
Filter Code | Display Code | Element |
|
| Area harvested |
|
| Yield |
|
| Production quantity |
|
| Stocks |
|
| Producing animals / slaughtered |
Filter Code | Display Code | Element |
| — | Import quantity |
| — | Import value |
| — | Export quantity |
| — | Export value |
Filter Code | Display Code | Element |
| — | Value |
| — | Confidence interval |
Always call
faostat_get_codes(dimension_id='element', domain_code=...)before querying data. Filter codes vary by domain and cannot be inferred from display codes.
# WRONG — uses display code 5510, returns empty data
faostat_get_data('QCL', area='2', item='515', element='5510', year='2024')
# CORRECT — uses filter code 2510, returns data
faostat_get_data('QCL', area='2', item='515', element='2510', year='2024')This server targets the FAOSTAT production API (https://faostatservices.fao.org/api/v1).
Rate limit: 2 requests/second, enforced automatically via token bucket.
Responses are cached across 3 tiers (memory → SQLite disk → Redis) to reduce API calls — see .env.example for TTL and size configuration.
The SQLite disk cache lives at ~/.cache/faostat-mcp/cache.db and defaults to 24 h TTL with a 1,000-entry LRU cap. Set FAOSTAT_DISK_CACHE=false to disable.
For large domains (e.g., Trade Matrix), always apply area, item, and year filters to keep response sizes manageable.
Want guided analysis workflows on top of this server? Check out FAOSTAT Skills — 9 platform-agnostic AI skills for country profiles, commodity briefings, trade analysis, climate assessments, data visualization, and more. Works with Claude Code, OpenAI Codex, and any AI assistant that supports the SKILL.md format.
FAOSTAT Skills — analysis skills built on top of this MCP server
Model Context Protocol — the open standard powering this server
FAOSTAT — UN FAO's official statistics portal
FAOSTAT API Docs — developer reference
Claude Desktop — one of the AI assistants this server works with
Cursor — AI code editor with MCP support
Windsurf — AI IDE with MCP support
Thanks to everyone who has contributed to this project.
Contributor | Contribution |
Project author — API client, MCP tool layer, response formatting | |
Hybrid caching — in-memory (dict + min-heap TTL) and Redis tiers with graceful fallback |
Contributions are welcome — see CONTRIBUTING.md for guidelines.
If you use this tool in academic work or research, please cite it:
Plain text:
Obli-Laryea, G., & Contributors. (2026). FAOSTAT MCP Server: AI-assisted access to FAOSTAT (v1.2.2) [Computer software]. https://github.com/berba-q/faostat-mcp
BibTeX:
@software{faostat_mcp,
author = {Obli-Laryea, Griffiths and {Contributors}},
title = {FAOSTAT MCP Server: AI-assisted access to UN food and agriculture statistics},
year = {2026},
url = {https://github.com/berba-q/faostat-mcp},
version = {1.2.2}
}See the Contributors section for a full list of authors.
When citing the underlying FAOSTAT data, use the FAO's recommended format with the specific domain:
FAO, {year}. FAOSTAT: {Domain Name}, http://www.fao.org/faostat/en/#data/{domain_code}
For example:
FAO, 2026. FAOSTAT: Crops and Livestock Products, http://www.fao.org/faostat/en/#data/QCL
FAO, 2026. FAOSTAT: Emissions Totals, http://www.fao.org/faostat/en/#data/GT
See CHANGELOG.md for a full history of changes, generated automatically from conventional commits.
If you fork or star this repo, suggested topics: mcp, faostat, model-context-protocol, ai-tools, agriculture, food-security, fao, un-data, python, llm, unfao, undata
List all available definition types (used with faostat_get_definitions_by_type).
Args: lang: Language code (default: 'en')
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | en |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states the basic action and the lang parameter, without disclosing behavioral traits like authentication, rate limits, or output format (though an output schema exists but is not referenced).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with two sentences, no wasted words. The Args section is inline and functional, though not as structured as some definitions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists and the tool is simple (one optional param), the description is mostly adequate. However, it lacks context on when to use vs siblings and does not mention any behavioral details like pagination or data limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It adds that 'lang' is a language code with a default of 'en', which provides some meaning beyond the schema, but remains minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'definition types', with a usage hint connecting to faostat_get_definitions_by_type. However, it does not differentiate this tool from other sibling tools like faostat_get_codes or faostat_get_dimensions beyond the specific resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage as a precursor to faostat_get_definitions_by_type, but provides no explicit guidance on when not to use this tool or mention of alternatives among the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the list of available FILTER codes for a specific dimension in a domain. You MUST call this before faostat_get_data to get the correct codes for filtering.
IMPORTANT: For the 'element' dimension, filter codes differ from the display codes shown in data responses. For example in QCL, faostat_get_codes returns filter code '2510' for Production, but the data response shows '5510' in the Element Code column. Always use the codes from this tool when filtering.
Args: dimension_id: Dimension identifier (e.g. 'area', 'item', 'element', 'year') domain_code: Domain code (e.g. 'QCL', 'TM', 'FS') lang: Language code (default: 'en') limit: Maximum number of codes to return (default: 0 = no limit). Useful for large dimensions like 'item' which can have 1000+ entries.
Examples: faostat_get_codes(dimension_id='element', domain_code='QCL') → Returns element filter codes: 2510=Production, 2312=Area harvested, etc.
faostat_get_codes(dimension_id='area', domain_code='QCL')
→ Returns country/area codes: 2=Afghanistan, 3=Albania, etc.TIP: To find a code by name (e.g. 'production', 'wheat', 'Nigeria'), use faostat_search_codes instead — it returns filtered results and signals whether the match is unambiguous before you proceed to faostat_get_data.
| Name | Required | Description | Default |
|---|---|---|---|
| dimension_id | Yes | ||
| domain_code | Yes | ||
| lang | No | en | |
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses a crucial quirk (filter codes vs display codes for 'element') and explains the limit parameter's default behavior. It does not mention idempotency or rate limits, but covers key behavioral aspects thoroughly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured into sections (main purpose, important note, args, examples, tip). Every sentence adds value, but it is slightly lengthy. However, given the complexity (quirks and parameter details), the length is justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema existence, the description covers all necessary aspects: parameter details, usage prerequisites, behavioral nuances, and examples. It anticipates common pitfalls and guides the agent effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains all four parameters: dimension_id, domain_code, lang (with default), and limit (with default and example usage for large dimensions). Examples further clarify usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves filter codes for a dimension in a domain, using a specific verb ('get') and resource ('codes'). It distinguishes itself from sibling tools by explicitly contrasting with faostat_get_data and faostat_search_codes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'You MUST call this before faostat_get_data' and provides a TIP directing to faostat_search_codes for name-based searches. It also clarifies when to use which tool and the importance of using correct codes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch statistical data from a FAOSTAT domain. This is the primary tool for retrieving actual data values.
When you do not have an exact item, element, or area code, call faostat_search_codes first. If it returns requires_confirmation=True, you MUST ask the user to choose from the listed options before calling this tool.
IMPORTANT: For large domains, always filter by area/item/year to avoid very large responses. Check query size first with faostat_get_datasize.
IMPORTANT: Element codes used for filtering differ from the display codes returned in the response. Always use faostat_get_codes(dimension_id='element', domain_code=...) to get the correct filter codes. For example, in QCL:
Filter with element='2510' → response shows Element Code '5510' (Production)
Filter with element='2312' → response shows Element Code '5312' (Area harvested)
Args: domain_code: Domain code (e.g. 'QCL' for Crops and Livestock Products) lang: Language code (default: 'en') area: Country/area codes, comma-separated (e.g. '2' for Afghanistan). Use faostat_get_codes(dimension_id='area', domain_code=...) to find codes. element: Element FILTER codes, comma-separated (e.g. '2510' for Production, '2312' for Area harvested in QCL). These differ from the display codes in the response. Always look up via faostat_get_codes first. item: Item/commodity codes, comma-separated (e.g. '515' for Apples, '15' for Wheat) year: Year codes, comma-separated (e.g. '2020' or '2018,2019,2020') area_cs: Area code set name (alternative to individual area codes) element_cs: Element code set name item_cs: Item code set name year_cs: Year code set name (e.g. 'FAO_YEAR_RECENT' for recent years) show_codes: Include code columns in response (default: False — names are more useful for interpretation; codes are for filtering) show_unit: Include unit column in response (default: True) show_flags: Include data quality flags (default: False — rarely needed) null_values: Include rows with null values (default: False) limit: Maximum number of rows to return (default: 50). Set to 0 for no limit. Use faostat_get_datasize first if you expect a large result set. response_format: Output format (default: 'objects'). - 'objects': Array of self-describing JSON objects (best LLM comprehension) - 'compact': Columnar {"columns": [...], "rows": [[...]]} (~3x smaller) - 'csv': Plain CSV text with header row (~4x smaller) Use 'compact' or 'csv' when retrieving larger datasets to reduce token usage. fields: Comma-separated column names to include (e.g. 'Area,Year,Value'). Omit to include all columns. Use to reduce response size further.
Examples: # Apple production in Afghanistan 2024 (element 2510 = Production filter code) faostat_get_data('QCL', area='2', item='515', element='2510', year='2024')
# Food security indicators for all African countries
faostat_get_data('FS', area_cs='AFRICA')
# Minimal response — only area, year and value in CSV format
faostat_get_data('QCL', area='231', item='15', element='2510', year='2024',
response_format='csv', fields='Area,Year,Value')
| Name | Required | Description | Default |
|---|---|---|---|
| domain_code | Yes | ||
| lang | No | en | |
| area | No | ||
| element | No | ||
| item | No | ||
| year | No | ||
| area_cs | No | ||
| element_cs | No | ||
| item_cs | No | ||
| year_cs | No | ||
| show_codes | No | ||
| show_unit | No | ||
| show_flags | No | ||
| null_values | No | ||
| limit | No | ||
| response_format | No | objects | |
| fields | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description fully bears the burden. It discloses crucial behavioral nuances like the difference between filter and display codes for elements, response format options with token usage implications, and all parameter defaults. However, it lacks explicit mention of rate limits or authentication, which are not critical for core usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with clear sections (purpose, important notes, args, examples). It front-loads critical warnings and efficiently covers all parameters. While not maximally concise, every sentence adds value, and the structure aids comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 17 parameters, the description is remarkably complete. It covers all parameters with examples, explains relationships with sibling tools, and provides best practices for large queries and response format optimization. The presence of an output schema reduces the need to explain return values, but the description still gives sufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides extensive detail for each of the 17 parameters, including usage context, examples, defaults, and cross-references to other tools (e.g., area codes via faostat_get_codes). This adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches statistical data from a FAOSTAT domain and is the primary tool for retrieving data values. It distinguishes from sibling tools like faostat_search_codes (for looking up codes) and faostat_get_datasize (for checking query size), ensuring the agent knows when to use this tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance on when to use faostat_search_codes first if exact codes are unknown, and warns about large domains with instructions to check query size via faostat_get_datasize. It also mandates asking user confirmation when required, and differentiates from alternative tools, covering both when-to-use and when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Estimate the number of rows a data query will return BEFORE fetching. Use this to check if a query is too large before calling faostat_get_data. Accepts the same filter parameters as faostat_get_data.
Args: domain_code: Domain code (e.g. 'QCL', 'TM', 'FS') lang: Language code (default: 'en') area: Country/area codes, comma-separated element: Element filter codes, comma-separated item: Item/commodity codes, comma-separated year: Year codes, comma-separated area_cs: Area code set name element_cs: Element code set name item_cs: Item code set name year_cs: Year code set name
| Name | Required | Description | Default |
|---|---|---|---|
| domain_code | Yes | ||
| lang | No | en | |
| area | No | ||
| element | No | ||
| item | No | ||
| year | No | ||
| area_cs | No | ||
| element_cs | No | ||
| item_cs | No | ||
| year_cs | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description discloses it returns an estimate and accepts the same filters, but lacks details on accuracy, speed, or limitations. The word 'estimate' implies non-exact, but more behavioral context would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear purpose first, followed by a list of parameters. No redundant sentences, and the structure is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description does not need to detail return values. It covers all 10 parameters adequately. Minor missing details: the unit of the estimate and any constraints on query size, but overall sufficient for its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the full burden. It provides brief explanations for each parameter (e.g., 'comma-separated' for area), adding basic meaning. However, it does not give examples or valid value ranges, so it only partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it estimates the number of rows before fetching, with the verb 'estimate' and specific resource 'data query row count'. It distinguishes itself from the sibling faostat_get_data by its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use this tool to check query size before calling faostat_get_data, giving clear context. However, it does not mention when not to use it or provide alternatives, though the sibling context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all definitions (descriptions of items, elements, flags) for a domain.
Args: domain_code: Domain code (e.g. 'QCL', 'FS', 'TM') lang: Language code (default: 'en')
| Name | Required | Description | Default |
|---|---|---|---|
| domain_code | Yes | ||
| lang | No | en |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It indicates a read operation but omits details on authentication, rate limits, pagination, or output format beyond parameter examples.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise with two lines and an Args list. No superfluous text, though it could be better structured with front-loaded purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists but is not described. With 20 sibling tools, the description does not differentiate sufficiently. Missing details on data scope and behavior for a tool with 2 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage. The description adds examples for domain_code ('QCL', 'FS', 'TM') and states lang default, but does not explain valid values or format beyond what schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'definitions (descriptions of items, elements, flags)' for a specific domain. It distinguishes from siblings like faostat_get_definitions_by_type by implying it retrieves all definitions for a domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like faostat_get_definitions_by_type. Does not mention when not to use or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get definitions for a domain filtered by type (e.g. items, elements, flags).
Args: domain_code: Domain code (e.g. 'QCL') definition_type: Type of definition. Use faostat_definition_types to see options. lang: Language code (default: 'en')
| Name | Required | Description | Default |
|---|---|---|---|
| domain_code | Yes | ||
| definition_type | Yes | ||
| lang | No | en |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It does not disclose that the operation is read-only, nor does it mention authentication, rate limits, or any side effects. The name implies a read operation but fails to confirm.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one line for purpose, then parameter docs in a standard format. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, return values need less explanation. However, the description lacks context on when to retrieve definitions by type versus other tools, and does not mention any dependencies like having a domain code from another source.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds value: domain_code is explained with an example, definition_type references another tool for options, and lang notes its default. This goes beyond the bare property names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'definitions', and the filtering by 'type' (items, elements, flags). This distinguishes it from sibling tools like faostat_get_definitions (no type filter) and faostat_definition_types (lists types).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description hints at using faostat_definition_types to see options for definition_type, but does not explicitly state when to use this tool versus alternatives like faostat_get_definitions. No prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the structure of a domain — what dimensions (filters) are available, such as area (country), item (commodity), element (measure), and year.
Args: domain_code: Domain code (e.g. 'QCL' for Crops and Livestock, 'TM' for Trade, 'FS' for Food Security) lang: Language code (default: 'en')
| Name | Required | Description | Default |
|---|---|---|---|
| domain_code | Yes | ||
| lang | No | en |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as authentication requirements, rate limits, or whether the operation is read-only. The agent must infer safety from the tool name alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a single sentence for purpose followed by parameter details in a clear, front-loaded structure. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, no nested objects) and the presence of an output schema that likely documents return structure, the description is nearly complete. It omits behavioral context like error handling or performance, but these are not critical for a retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description compensates by explaining domain_code with concrete examples ('QCL', 'TM', 'FS') and specifying the default for lang. This adds meaning beyond the bare schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves domain structure/dimensions with examples like area, item, element. It distinguishes from siblings by specifying the unique function of getting dimensions rather than codes or data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to see available dimensions for a domain) and provides parameter examples. However, it does not explicitly contrast with sibling tools like faostat_get_codes or state conditions to avoid using it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full methodology and metadata for a domain — including data sources, collection methods, coverage, and limitations.
Args: domain_code: Domain code (e.g. 'QCL', 'FS', 'GCE') lang: Language code (default: 'en')
| Name | Required | Description | Default |
|---|---|---|---|
| domain_code | Yes | ||
| lang | No | en |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses the scope of the operation (methodology and metadata) and lists included items. It implies a read-only operation, which is appropriate. It lacks details on response size or error handling, but the core behavior is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph plus a clean Args list. Every sentence adds value, and the main purpose is front-loaded. It is concise without being terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a metadata retrieval tool: it explains the purpose, parameters, and what is returned. The presence of an output schema reduces the need to detail return values. Coverage is adequate for the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description's Args section adds meaningful explanations: examples for domain_code and default for lang. This goes beyond the schema's bare titles, compensating for the 0% schema description coverage. Parameter semantics are well explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns 'full methodology and metadata for a domain' and lists specific content types (data sources, collection methods, coverage, limitations). The verb 'get' plus resource 'metadata' is specific and distinct from siblings like faostat_get_definitions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as faostat_get_definitions or faostat_get_dimensions. There is no mention of prerequisites or typical use cases, leaving the agent without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get metadata for a domain in a printable/simplified format.
Args: domain_code: Domain code (e.g. 'QCL', 'FS') lang: Language code (default: 'en')
| Name | Required | Description | Default |
|---|---|---|---|
| domain_code | Yes | ||
| lang | No | en |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals the tool is a read operation (non-destructive) and produces simplified output, but no annotations are present. It lacks details on authorization, rate limits, or response characteristics beyond what the output schema may provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at two sentences plus argument list. However, the 'Args:' formatting is slightly verbose for a tool description. It could be more streamlined.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and many sibling tools, the description is adequate but not thorough. It does not explain what the simplified format entails or how it differs from the standard metadata output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description adds meaning by explaining each parameter's purpose, providing examples (e.g., 'QCL', 'FS') and noting the default for 'lang'. This compensates well for the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves metadata in a 'printable/simplified format'. However, it does not explicitly distinguish itself from the sibling tool faostat_get_metadata, leaving the agent to infer the difference from the format description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for printable metadata but does not provide explicit guidance on when to use this versus alternatives like faostat_get_metadata. No exclusion criteria or contextual advice is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get rankings — e.g. top countries by production, yield, or trade value. Use this to answer "which country produces the most X?" questions.
NOTE: element_code here is the DISPLAY code (e.g. '5510'), not the filter code used in faostat_get_data. Rankings use the same codes shown in data responses.
Args: domain_code: Domain to rank within (e.g. 'QCL') element_code: Display element code to rank by (e.g. '5510' for Production in QCL) item_code: Commodity code (e.g. '56' for Maize, '15' for Wheat) year: The year to rank for (e.g. '2022') lang: Language code (default: 'en') limit: Number of top results to return (default: 10) response_format: Output format: 'objects' (default), 'compact', or 'csv'
Example: faostat_get_rankings(domain_code='QCL', element_code='5510', item_code='56', year='2022', limit=10) → Top 10 maize-producing countries in 2022
| Name | Required | Description | Default |
|---|---|---|---|
| domain_code | Yes | ||
| element_code | Yes | ||
| item_code | Yes | ||
| year | Yes | ||
| lang | No | en | |
| limit | No | ||
| response_format | No | objects |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It explains the element_code nuance and output formats, but does not disclose potential behaviors like rate limits or data volume.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with a summary, a usage note, an Args section, and an example. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 7 parameters and 4 required, the description explains each parameter and provides an example. The presence of an output schema reduces the need for return value description, so it is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context beyond the empty schema: each parameter is described with examples and default values, covering all required and optional parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool retrieves rankings (e.g., top countries by production, yield, or trade value) and explicitly differentiates from data retrieval tools like faostat_get_data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an example and a critical note about element_code being the display code, which guides correct usage and distinguishes from faostat_get_data. However, it does not explicitly exclude other sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get structured report data from FAOSTAT.
Args: payload: Report query parameters (structure depends on report type) lang: Language code (default: 'en')
| Name | Required | Description | Default |
|---|---|---|---|
| payload | Yes | ||
| lang | No | en |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as whether the operation is read-only, has rate limits, or requires authentication. The term 'Get' implies a read, but no explicit safety or side-effect information is given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with no redundant sentences. It efficiently conveys the core purpose and parameter hints, though it could be slightly more detailed without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (many sibling tools, no annotations, a flexible payload with undefined structure, and an output schema not described), the description is incomplete. It lacks differentiation, behavioral context, and payload structure guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to both parameters: 'payload' is described as report query parameters with type-dependent structure, and 'lang' as a language code with default. However, the payload description is vague, and the schema coverage is 0%, so the description only partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets structured report data from FAOSTAT, using a specific verb and resource. However, it does not distinguish from the sibling tool 'faostat_get_data', which likely has similar functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like faostat_get_data or faostat_get_metadata. Given the large number of sibling tools, this is a significant gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the column headers/schema for a report before fetching its data.
Args: payload: Report query parameters lang: Language code (default: 'en')
| Name | Required | Description | Default |
|---|---|---|---|
| payload | Yes | ||
| lang | No | en |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It lacks disclosure about read-only nature, authentication requirements, or any side effects, leaving significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with one sentence and a parameter list, no unnecessary words. Every part contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (2 parameters, nested objects, output schema exists), the description is minimal. It doesn't explain what headers are returned or how to interpret them, though output schema may compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description adds only minimal meaning: 'payload: Report query parameters' and 'lang: Language code'—not enough to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves column headers/schema for a report, distinguishing it from sibling tools like faostat_get_report_data which fetch actual data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage before fetching data but does not explicitly state when not to use or provide alternatives. It offers minimal guidance beyond the immediate use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full hierarchical tree of all FAOSTAT groups and their domains. Use this for a complete overview of all available datasets.
Args: lang: Language code (default: 'en')
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | en |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals the key behavioral trait: it returns a hierarchical tree structure. With no annotations provided, the description carries the full burden and adequately conveys the read-only, non-destructive nature, though it omits details like authentication or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two front-loaded sentences and a brief Args line. Every part serves a purpose, though the Args line adds minimal value over the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and an output schema, the description covers the main functionality and usage context. However, it lacks explanation of the lang parameter, leaving a gap in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'lang' is listed but not described beyond its default value. With 0% schema description coverage, the description should compensate by explaining that lang controls the language of group/domain names, which it fails to do.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and resource ('full hierarchical tree of all FAOSTAT groups and their domains'), clearly distinguishing it from sibling tools like 'faostat_list_groups' which likely return flat lists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Use this for a complete overview of all available datasets,' providing clear context for when to use it. However, it does not explicitly mention when not to use it or suggest alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available bulk download files for a domain (ZIP/CSV archives). These contain the full domain dataset and can be very large.
Args: domain_code: Domain code (e.g. 'QCL', 'TM') lang: Language code (default: 'en')
| Name | Required | Description | Default |
|---|---|---|---|
| domain_code | Yes | ||
| lang | No | en |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It notes files are 'very large', which is a key behavioral trait, but lacks disclosure on rate limits, authentication, pagination, or response format. The behavior is partially transparent but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences plus an Args block. The key purpose is front-loaded, and no unnecessary words are present. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description doesn't need to detail return values. However, for a tool listing large files, it lacks context on download process, limits, or link availability. It is adequate but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains domain_code with examples (e.g., 'QCL', 'TM') and lang with default 'en', adding meaning beyond the schema's bare titles and types. However, it does not list valid lang values or provide more domain code details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list', the resource 'bulk download files for a domain', and specifies they are ZIP/CSV archives containing the full domain dataset. This distinguishes it from sibling tools that retrieve data subsets or codes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing full domain downloads but does not explicitly state when to use this tool vs alternatives, such as faostat_get_data for smaller data queries. No when-not-to-use guidance or mention of alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List related documents (methodology papers, questionnaires) for a domain.
Args: domain_code: Domain code (e.g. 'QCL', 'FS') lang: Language code (default: 'en')
| Name | Required | Description | Default |
|---|---|---|---|
| domain_code | Yes | ||
| lang | No | en |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only says 'list' which implies read-only. No mention of authentication, rate limits, or side effects. Lacks behavioral context beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one sentence plus a two-line parameter description with examples. No wasted information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with 2 params and an output schema, so description is adequate but could mention that a valid domain code is required and how to obtain it (e.g., via faostat_list_domains).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description provides examples for domain_code and default for lang, adding value beyond the schema which lacks descriptions. Schema coverage is 0%, so description compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists documents (methodology papers, questionnaires) for a domain. Implicitly differentiates from sibling tools by focusing on documents instead of data, definitions, or metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like faostat_get_definitions or faostat_get_metadata. User must infer from the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all datasets (domains) within a FAOSTAT group.
Args: group_code: The group code (e.g. 'Q' for Production, 'T' for Trade, 'FS' for Food Security). Get codes from faostat_list_groups. lang: Language code (default: 'en')
| Name | Required | Description | Default |
|---|---|---|---|
| group_code | Yes | ||
| lang | No | en |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not mention behavioral traits such as read-only nature, authentication needs, or side effects. For a list operation, it should explicitly indicate it is safe and non-mutating.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using two sentences and parameter explanations with no fluff. It front-loads the tool's purpose, making it efficient for an AI agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description does not need to detail return values. However, it lacks mention of prerequisites (e.g., valid group code) and possible limits or pagination, which would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining group_code with examples and source, and lang with a default value. This adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists datasets (domains) within a FAOSTAT group, using a specific verb and resource. It distinguishes itself from sibling tools like faostat_list_groups by requiring a group code and referencing where to obtain it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by instructing to get group codes from faostat_list_groups, but it does not explicitly state when to use this tool versus alternatives like faostat_groups_and_domains, nor does it provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all top-level FAOSTAT data groups (e.g. Production, Trade, Food Security). Use this to discover what categories of data are available.
Args: lang: Language code (default: 'en')
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | en |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention whether the operation is read-only, requires authentication, has rate limits, or any side effects. For a simple listing tool, the omission is significant, especially given the lack of annotation safety signals.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the primary action and examples. It includes an Args section explicitly. No extraneous text. However, the parameter description could be integrated more naturally.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return value details are not required. However, given 9 sibling tools and no annotations, the description omits context like pagination, error handling, or whether the list is exhaustive. It minimally covers the purpose but leaves gaps for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It merely restates 'lang: Language code (default: 'en')', which duplicates the schema's title and default. No valid language codes, formats, or constraints are provided, offering little extra value beyond the parameter name itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'List all top-level FAOSTAT data groups' with examples (Production, Trade, Food Security), providing a specific verb and resource. It also notes 'Use this to discover what categories of data are available.' However, it does not explicitly distinguish from siblings like faostat_list_domains or faostat_groups_and_domains, which could be confused for similar operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a use case ('discover what categories of data are available') but lacks guidance on when not to use this tool versus alternatives. No exclusions or references to sibling tools are provided, leaving the agent to infer appropriateness.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the FAOSTAT API health status. Returns a status message indicating if the API is online.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It states a status message is returned but lacks detail on format or interpretation of 'online'. Slightly vague but adequate for a trivial ping.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two succinct sentences, no wasted words. Front-loaded with the action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple health check with no parameters and an output schema (not detailed but implied), the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. The description correctly adds no param info, meeting the baseline for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Check the FAOSTAT API health status' with a specific verb and resource. It distinguishes from sibling tools that deal with data retrieval, definitions, and domains.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is clear: check if the API is online. While it doesn't explicitly exclude alternatives or provide when-not-to-use, the simplicity of a health check makes the guidance sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Force-refresh the FAOSTAT API authentication token.
Use this tool when other FAOSTAT tools fail with 401 Unauthorized or token-expiry errors. It logs in with the configured credentials (FAOSTAT_USERNAME + FAOSTAT_PASSWORD) and obtains a fresh JWT token.
Requires FAOSTAT_USERNAME and FAOSTAT_PASSWORD to be configured — either as environment variables or via faostat_setup.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool logs in with configured credentials and obtains a fresh JWT token. It also notes configuration requirements. Does not detail side effects (e.g., token invalidation), but acceptable for a simple refresh.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Clearly states purpose, usage scenario, and prerequisite. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter tool, the description covers what it does, when to use, and prerequisites. Could mention token lifespan or impact on other tools, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and 100% coverage, so the baseline is 3. No parameter info is needed; the description does not add any parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Force-refresh') and resource ('FAOSTAT API authentication token'). Among siblings, no other tool refreshes tokens, so differentiation is evident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool: 'when other FAOSTAT tools fail with 401 Unauthorized or token-expiry errors.' It also mentions prerequisites (FAOSTAT_USERNAME and FAOSTAT_PASSWORD). Lacks explicit when-not-to-use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search codes in a dimension by name — use this BEFORE faostat_get_data when you have a partial or uncertain code name (e.g. 'production', 'wheat', 'Nigeria').
This tool prevents wrong-code errors by making ambiguity explicit:
Exactly 1 match → safe to proceed (requires_confirmation=False)
Multiple matches → STOP and ask the user to choose (requires_confirmation=True)
No matches → broaden your search term
AGENT INSTRUCTION: When the response contains "requires_confirmation": true, you MUST present ALL entries in the "matches" list to the user and ask them to select one before calling faostat_get_data, faostat_get_rankings, or any other data tool. Do NOT guess or automatically pick the first match.
Args: domain_code: Domain code to search within (e.g. 'QCL', 'TM', 'FS'). dimension_id: Dimension to search ('element', 'item', 'area', 'year'). query: Partial or full name to search for (case-insensitive substring). Examples: 'production', 'wheat', 'gross production index'. lang: Language code (default: 'en').
Returns a JSON object with one of these shapes:
Single match — safe to proceed: {"match": {"code": "2510", "label": "Production"}, "requires_confirmation": false, "message": "Unique match found. Use code '2510' as the element filter."}
Multiple matches — MUST ask user before proceeding: {"matches": [{"code": "2510", "label": "Production"}, {"code": "2512", "label": "Gross Production Index Number"}], "requires_confirmation": true, "message": "Multiple matches for 'production' in element/QCL. Ask the user."}
No matches: {"matches": [], "requires_confirmation": false, "message": "No codes match '...'. Use faostat_get_codes to browse all codes."}
Examples: faostat_search_codes('QCL', 'element', 'production') → Multiple matches (Production, Gross Production Index) — ask user.
faostat_search_codes('QCL', 'area', 'nigeria')
→ Single match for Nigeria — safe to proceed with code '231'.
| Name | Required | Description | Default |
|---|---|---|---|
| domain_code | Yes | ||
| dimension_id | Yes | ||
| query | Yes | ||
| lang | No | en |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description fully bears the burden. It details the three possible outcomes (single match, multiple matches, no matches) with explicit flags (requires_confirmation), includes agent instructions for handling each case, and provides message examples that clarify system behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
While lengthy, every section serves a purpose: the opening states use case, followed by behavioral details, parameter descriptions, return shapes, and examples. The structure is logical and front-loaded, making it easy for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters (3 required), no enums, and a text-described output schema, the description covers all necessary context: when to use, how to interpret results, and agent actions for each case. No gaps remain for the agent to guess behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds comprehensive details for each parameter: domain_code is explained as a domain code (e.g., 'QCL'), dimension_id lists valid options, query is described as a case-insensitive substring with examples, and lang has a default explained. This far exceeds the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches codes in a dimension by name, specifies its role as a precursor to faostat_get_data for partial or uncertain code names, and distinguishes it from sibling tools like faostat_get_codes by noting it should be used when browsing all codes is not needed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('before faostat_get_data when you have a partial or uncertain code name'), provides clear instructions for multiple matches ('STOP and ask the user'), and suggests an alternative (faostat_get_codes) for no matches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Configure FAOSTAT credentials — call this once to authenticate. After setup, all other tools work automatically across sessions without any manual config file editing.
The tool validates your credentials against the FAOSTAT API before saving, then stores them securely for future use:
macOS / Windows: stored in the system keychain (if keyring package is installed)
Linux / Docker: stored in ~/.config/faostat-mcp/credentials.json (mode 600)
You can register for a free FAOSTAT account at https://www.fao.org/faostat/
Args: username: Your FAOSTAT account email address. password: Your FAOSTAT account password.
Returns confirmation of where credentials were saved, or an error with a clear message if authentication failed.
| Name | Required | Description | Default |
|---|---|---|---|
| username | Yes | ||
| password | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses storage locations per OS, validation before saving, and secure storage. Also mentions return value and error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections and bullet points, front-loading the main action. Could be slightly more concise, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers authentication process, credential storage, registration link, and what to expect as output. Complete for a setup tool with output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description adds meaning: username is 'FAOSTAT account email address', password is 'FAOSTAT account password'. Also notes validation against API before saving.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it configures FAOSTAT credentials for authentication, using specific verbs like 'Configure' and 'authenticate'. It distinguishes from siblings by being the setup step for all other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'call this once to authenticate' and 'after setup, all other tools work automatically', guiding the agent to use it before other tools. No explicit alternatives (none needed), but clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0faostat_definition_typesfaostat_get_codesfaostat_get_datafaostat_get_datasizefaostat_get_definitionsfaostat_get_definitions_by_typefaostat_get_dimensionsfaostat_get_metadatafaostat_get_metadata_printfaostat_get_rankingsfaostat_get_report_datafaostat_get_report_headersfaostat_groups_and_domainsfaostat_list_bulk_downloadsfaostat_list_documentsfaostat_list_domainsfaostat_list_groupsfaostat_pingfaostat_refresh_tokenfaostat_search_codesfaostat_setupEach tool has a clearly distinct purpose, from authentication (faostat_setup, faostat_refresh_token) to data retrieval (faostat_get_data, faostat_get_rankings, faostat_get_report_data). Overlapping tools like faostat_get_definitions and faostat_get_definitions_by_type are differentiated by the type parameter, and descriptions clarify their use.
All tools begin with 'faostat_' and mostly follow a verb_noun pattern (e.g., faostat_get_codes, faostat_list_groups). However, there are minor inconsistencies such as faostat_definition_types (noun phrase) and faostat_groups_and_domains (conjunction) which deviate from the predominant pattern.
With 21 tools, the set is well-scoped for a comprehensive statistical database API. Each tool covers a necessary function—discovery, metadata, filtering, data retrieval, and authentication—without being overly redundant or sparse.
The tool surface covers the full lifecycle of interacting with FAOSTAT: exploration (groups, domains, dimensions, codes), data retrieval (data, datasize, rankings, reports), and metadata (definitions, documents, methodology). No obvious gaps exist for a read-only API.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Real SEO data for AI assistants: page audits, Keyword Planner volumes, Search Console history.
AI access to Quadratic spreadsheets: open files, run Python/SQL, query connected databases.
Real-time data API for AI Agents: stocks, weather, forex, logistics, search, scrape, news, IP.
Primary-source commodities data for AI agents — EIA, FRED, CFTC, USDA, USGS via x402 on Base.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/berba-q/faostat-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
