Loading ToolBench
faostat-mcp demonstrates solid tool definition quality with consistent naming, comprehensive descriptions, and proper parameter schemas across 17 tools. All tools follow verb_noun naming convention (faostat_<action>). Descriptions are substantive (50-300 chars typically) and include WHEN to use each tool. Input schemas are fully visible in the code with proper JSON Schema typing. However, there are notable gaps: output schemas are not documented (only the source code shows CSV/JSON formatting logic), error handling is minimal (generic exception returns without actionable recovery guidance), and no tool annotations (readOnlyHint, destructiveHint) despite clear idempotency patterns. The faostat_setup tool properly avoids storing credentials in parameters (uses server-side secret injection via environment variables and keyring). Overall, this is a well-structured domain-specific tool suite that follows patterns correctly but lacks some polish in output documentation and error recovery design.
Get food balance sheet data.
Get all codes and descriptions for a specific dimension in a domain.
Fetch data from FAOSTAT with optional filtering and output formatting.
Get the structure of a FAOSTAT domain (its dimensions and dimension codes).
Get agricultural emissions data.
Get food security indicators data.
Get price indices and agricultural prices data.
No output schemas documented. While the code shows response formatting (objects/compact/csv), there is no formal description of what fields users should expect in tool results. This forces LLMs to infer structure from trial calls, increasing errors and wasting context.
Error handling lacks actionable recovery guidance. Exceptions are caught and returned as JSON with only the exception type and message (e.g., 'FAOSTATAuthError: ...'). LLMs receive no instructions on what to do next, should they retry? Call faostat_setup? Call faostat_refresh_token?
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | C | 67 | <=2025-11-25 | v2 |
| 2026-03-09 | F | 23 | - | v1 |
Same as faostat_get_data, but the server guarantees a structured response (JSON objects or columnar format), never raw CSV.
Get trade data (imports/exports of agricultural commodities).
Get the full hierarchical tree of all FAOSTAT groups and their domains. Use this for a complete overview of all available datasets.
List all datasets (domains) within a FAOSTAT group.
List all top-level FAOSTAT data groups (e.g. Production, Trade, Food Security). Use this to discover what categories of data are available.
Check the FAOSTAT API health status. Returns a status message indicating if the API is online.
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.
Search for a dimension code by (partial) name. Use this when you need to find the code for 'production', 'wheat', 'Nigeria', etc. Returns an exact match (if unambiguous), a list of candidate codes (if ambiguous), or a not-found message.
Search for codes in a specific dimension of a domain.
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/
No tool annotations present. Tools like faostat_setup (destructive: modifies credential storage), faostat_get_data (read-only), and faostat_refresh_token (idempotent) should declare hints (readOnlyHint=true, destructiveHint=true, idempotentHint=true) to help agents reason about safety and retry logic.
Generic domain-specific tools (faostat_get_balance, faostat_get_prices, etc.) have minimal descriptions (under 80 chars). These tools should explain WHEN to use each one instead of faostat_get_data and WHY (e.g., 'faostat_get_balance is a convenience wrapper for food balance sheet queries; use it instead of faostat_get_data when querying domain FBS').
faostat_groups_and_domains contains 'and' in the name, signaling potential multiple responsibilities. While the description clarifies it returns a hierarchical tree (not two separate concerns), the name could be more precise (e.g., faostat_get_hierarchy).
Optional parameters (item_code, area_code, year_range, etc.) lack constraint documentation in descriptions. E.g., year_range says 'START_YEAR:END_YEAR' but does not specify valid year ranges, separator rules, or what happens if start > end. This invites invalid agent input.
No pagination or result limiting controls documented. The limit parameter exists but its max value, default, and behavior when exceeded are not stated. Tools may silently truncate or timeout on large result sets.