Trends

---
name: faostat-trends
description: Use when the user wants to identify biggest changes, fastest-growing or declining agricultural productions, or anomalies in FAOSTAT data over a time window for a region or set of countries. Keywords — trends, growth, decline, anomaly, change, biggest movers, acceleration, deceleration, monitoring, shift, surge, drop, spike. Do NOT use for a global commodity briefing → `faostat-commodity`. Do NOT use for a country food security profile → `faostat-country-profile`. Do NOT use for side-by-side comparison → `faostat-compare`.
---

# Agricultural Trend Monitor

Identify the biggest changes and anomalies in agricultural production data over a specified time window and geography.

## Prerequisites

Before starting, confirm the FAOSTAT MCP tools are available by checking that tools `faostat_get_data`, `faostat_search_codes`, and `faostat_get_rankings` are accessible. If they are not, inform the user that this skill requires the FAOSTAT MCP server to be connected and stop.

## Workflow

### Step 1 — Gather Parameters

Ask the user for:
- **Region or countries** — one or more countries, a continent, or a region (e.g., "Africa", "Brazil and Argentina", "Southeast Asia")
- **Time window** — default to the last 5 years if not specified
- **Focus** (optional) — specific commodity groups to monitor, or leave broad for all major groups

If the user provides these in their initial message, proceed without re-asking.

### Step 2 — Resolve Area Codes

Use `faostat_search_codes` with `domain_code='QCL'` and `dimension_id='area'` to resolve each country or region name to its FAOSTAT area code.

**CRITICAL:** If `requires_confirmation` is `true` in the response (multiple matches), present the options to the user and ask them to choose before proceeding. Do NOT guess.

### Step 3 — Pull Production Data for Major Commodity Groups

Query the **QCL** (Crops and Livestock Products) domain using `faostat_get_data`. Pull production quantity data (element FILTER code resolved at runtime via `faostat_search_codes(domain_code='QCL', dimension_id='element', query='production')` → e.g. `'2510'`) across major commodity groups.

For broad monitoring, query across these key items:
- Cereals (wheat, rice, maize, barley, sorghum, millet)
- Oilcrops (soybeans, palm fruit, sunflower seed, rapeseed)
- Roots and tubers (cassava, potatoes, yams, sweet potatoes)
- Fruits (bananas, citrus, mangoes, avocados)
- Vegetables (tomatoes, onions)
- Livestock products (milk, meat — cattle, chicken, pig, sheep)

Use `faostat_search_codes` with `domain_code='QCL'` and `dimension_id='item'` to resolve each item name to its item code.

For each query, use `response_format='compact'` when pulling data for multiple entities to keep payloads efficient. Set `limit` appropriately to cover the full time window. Use explicit comma-separated year lists (e.g., `year='2019,2020,2021,2022,2023'`) — colon ranges like `'2019:2023'` have returned empty in practice.

**CRITICAL — FILTER vs DISPLAY.** Element codes come in two flavors:
- `faostat_get_data(..., element='<resolved_filter_code>')` uses the **FILTER** code for Production quantity (hint: `2510`).
- `faostat_get_rankings(..., element_code='<resolved_display_code>')` uses the **DISPLAY** code for Production quantity (hint: `5510`).
Do not invert these. Always resolve first: `faostat_search_codes(domain_code='QCL', dimension_id='element', query='production')` returns both codes for every element.

> Element codes above are verified hints. Resolve at runtime via `faostat_search_codes` before use.

**China composite rule (user preference, Apr 2026).** When building a regional aggregate or top-N ranking that includes China, default to composite `China` (area code 351) — the roll-up of mainland + HK SAR + Macao SAR + Taiwan. Do NOT substitute `China, mainland` (41) unless the user specifies 41 explicitly. Flag the choice in the output and note that FAOSTAT's own publications default to 41, so the numbers here are marginally larger than the FAO data-portal default.

### Step 4 — Calculate Period-over-Period Changes

For each country-commodity pair:
1. Identify the **baseline value** (first year or average of first 2 years in the window)
2. Identify the **latest value** (most recent year or average of last 2 years)
3. Calculate:
   - **Absolute change** = latest - baseline
   - **Percentage change** = ((latest - baseline) / baseline) * 100
   - **Annualized growth rate** = ((latest / baseline)^(1/years) - 1) * 100

Exclude any country-commodity pairs where baseline data is zero or missing.

### Step 5 — Rank by Magnitude

Sort all country-commodity pairs by:
- **Percentage change** (descending) for top growers
- **Percentage change** (ascending) for top decliners

Select:
- **Top 5 fastest-growing** productions (highest positive percentage change)
- **Top 5 largest declines** (most negative percentage change)

### Step 6 — Flag Anomalies

For each country-commodity time series:
1. Calculate the mean and standard deviation of annual values across the time window
2. Flag any year where the value deviates by more than 2 standard deviations from the mean
3. Note the direction (spike up or drop down) and the year

An anomaly could indicate a drought, bumper harvest, policy change, conflict, or data issue.

### Step 7 — Compile the Trend Report

Present the results in a structured format:

**Top 5 Growing Productions**
For each entry: country, commodity, baseline value, latest value, percentage change, annualized growth rate. Add a brief note on possible drivers if context is evident.

**Top 5 Declining Productions**
Same format as above. Flag any that may indicate food security concerns.

**Anomaly Flags**
For each anomaly: country, commodity, year, actual value vs. expected range, direction (spike/drop). Note if additional investigation is warranted.

**Trend Directions Summary**
A concise table showing all analyzed country-commodity pairs with trend direction indicators:
- Strong growth (>20% over period)
- Moderate growth (5-20%)
- Stable (-5% to +5%)
- Moderate decline (-5% to -20%)
- Sharp decline (>20% decline)

### Step 8 — Attribution

End the report with:

> Source: FAOSTAT (FAO), accessed [current date]. Domain: QCL (Crops and Livestock Products).

Replace `[current date]` with today's date.

### Step 9 — Offer Next Steps

Suggest to the user:
- "Would you like me to visualize any of these trends as charts?" (invokes the visualization skill)
- "Want a deeper dive into any specific commodity or country?" (invokes the commodity or country-profile skill)
- "Should I check the trade data for any of the anomalies?" (invokes the trade skill)

## Important Rules

**Element and item code resolution.** Never use a hardcoded numeric element or item code as the primary value in a `faostat_get_data` call. Always resolve at runtime: `faostat_search_codes(domain_code='<dom>', dimension_id='element', query='<metric name>')` for elements; `faostat_search_codes(domain_code='<dom>', dimension_id='item', query='<item name>')` for items. Numeric codes shown in reference tables and code examples are verified hints — use them to validate the search result, not as the authoritative source. Domain letter-codes (QCL, TCL, GT, EM, FBS, FS…) are stable and may be used directly.

## Error Handling and Reliability Notes

- **`faostat_get_rankings` sometimes returns HTTP 500.** If you were planning to use it to pre-rank top producers before pulling time series, fall back to `faostat_get_data` with a country list and sort client-side. Document the fallback in the output.
- **FILTER vs DISPLAY codes.** See Step 3 — the two forms are not interchangeable.
- **Colon year ranges return empty.** Use comma-separated year lists.
- **Zero baseline excluded.** In Step 4 exclude any country-commodity pairs where the baseline is zero or missing — dividing by zero produces infinite growth rates that dominate the rankings.

## Related Skills

| If you need… | Use |
|---|---|
| Commodity deep dive | `/faostat-commodity` |
| Country food security profile | `/faostat-country-profile` |
| Side-by-side comparison | `/faostat-compare` |
| Import dependency | `/faostat-trade` |
| Visualize results as charts | `/faostat-viz` |