faostat-skills 0.1.0

package/skills/compare/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: faostat-compare
+description: Use when the user wants to compare countries, commodities, or agricultural metrics side by side. Keywords: compare, comparison, versus, vs, benchmark, ranking, countries, crops, production, yield, area harvested, trade, growth rate
+---
+
+# Comparative Agricultural Analysis
+
+Produce a structured side-by-side comparison of countries, commodities, or both across agricultural metrics using FAOSTAT data.
+
+## Prerequisites
+
+Verify that the following FAOSTAT MCP tools are available before proceeding:
+- `faostat_search_codes`
+- `faostat_get_data`
+- `faostat_get_rankings`
+
+If any tool is missing, inform the user: "This skill requires the FAOSTAT MCP server to be connected. Please ensure it is running and try again."
+
+## Workflow
+
+### Step 1: Clarify Comparison Parameters
+
+Determine from the user's message (or ask if unclear):
+
+1. **What to compare:** Countries, commodities, or a cross-comparison (e.g., wheat production in Brazil vs. Argentina).
+2. **Metric:** Production volume, yield, area harvested, trade value, or another indicator. Default to production if unspecified.
+3. **Time range:** Specific years or a span. Default to the most recent 10 years if unspecified.
+4. **Domain:** Infer the FAOSTAT domain:
+   - Production/yield/area harvested: `QCL`
+   - Trade value/quantity: `TM`
+   - Food balance: `FBS`
+   - Food security indicators: `FS`
+
+Map the metric to the correct FAOSTAT element FILTER codes:
+- Production: `'2510'`
+- Yield: `'2413'`
+- Area harvested: `'2312'`
+- For trade, use appropriate TM element codes
+
+### Step 2: Resolve All Codes
+
+For each entity (country or commodity), call `faostat_search_codes`:
+
+**Countries:**
+`faostat_search_codes(domain_code='<domain>', dimension_id='area', query='<country_name>')`
+
+**Commodities:**
+`faostat_search_codes(domain_code='<domain>', dimension_id='item', query='<commodity_name>')`
+
+**CRITICAL:** If ANY search returns `requires_confirmation: true`, present the options to the user and wait for confirmation before proceeding. Resolve each entity independently — do not skip confirmation for any of them.
+
+Store all confirmed codes.
+
+### Step 3: Pull Data for All Entities
+
+For each entity combination, call `faostat_get_data` with:
+- `domain_code='<domain>'`
+- `area='<area_code>'` (or comma-separated codes if comparing multiple countries for one item)
+- `item='<item_code>'` (or comma-separated codes if comparing multiple items)
+- `element='<element_filter_code>'`
+- `year='<year_range>'` (e.g., `'2014:2023'` for a 10-year span)
+- `response_format='compact'` (saves tokens for multi-entity queries)
+- `limit=200` (increase limit for multi-year, multi-entity queries)
+- `show_unit=True`
+
+If comparing many entities, batch the calls to avoid excessively large responses. Prefer 2-4 entities per call.
+
+### Step 4: Calculate Derived Metrics
+
+From the retrieved data, compute:
+
+- **Growth rate:** Percentage change from first year to last year in the range.
+- **Average annual growth rate (CAGR):** `(end_value / start_value) ^ (1 / years) - 1`
+- **Period average:** Mean value across all years.
+- **Volatility (optional):** Standard deviation of year-over-year changes, if the user is interested in stability.
+
+### Step 5: Present the Comparison
+
+Structure the output as follows:
+
+**Title:** Comparative Analysis: [Entity A] vs. [Entity B] [vs. Entity C...] — [Metric]
+
+1. **Comparison Table** — Tabular summary with entities as columns and years (or summary stats) as rows. Include units.
+
+2. **Growth Rates** — CAGR and total period change for each entity, clearly indicating which grew faster.
+
+3. **Key Differences** — Narrative highlighting:
+   - Largest producer/highest yield/biggest trader
+   - Fastest and slowest growth
+   - Any crossover points (where one entity overtook another)
+   - Notable divergences or convergences in trends
+
+4. **Context & Insights** — Brief interpretation:
+   - Possible explanations for differences (climate, policy, investment)
+   - Caveats about the data (reporting gaps, methodology changes)
+
+End with:
+
+> Source: FAOSTAT (FAO), accessed [current date].
+
+## Error Handling
+
+- If data is missing for some years for an entity, note the gap and compute metrics on available data only.
+- If an entity has no data for the chosen domain/metric, inform the user and suggest an alternative metric or domain.
+- Limit comparisons to 5 entities maximum. If the user requests more, suggest narrowing the scope or running multiple comparisons.
+
+## Output Format
+
+Use a clean tabular layout for numerical comparisons. Follow the table with a concise narrative analysis. Keep growth rate calculations transparent by showing the formula values used.

package/skills/country-profile/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: faostat-country-profile
+description: Use when the user asks for a food security profile, country agricultural overview, country hunger or nutrition assessment, or food system summary for a specific country. Keywords: country profile, food security, undernourishment, production, trade, nutrition, calorie supply, dietary energy
+---
+
+# Country Food Security Profile
+
+Generate a comprehensive food security and agricultural profile for a given country using FAOSTAT data.
+
+## Prerequisites
+
+Verify that the following FAOSTAT MCP tools are available before proceeding:
+- `faostat_search_codes`
+- `faostat_get_data`
+- `faostat_get_rankings`
+- `faostat_list_domains`
+
+If any tool is missing, inform the user: "This skill requires the FAOSTAT MCP server to be connected. Please ensure it is running and try again."
+
+## Workflow
+
+### Step 1: Accept Country Input
+
+Identify the country name from the user's message or ask for it if not provided.
+
+### Step 2: Resolve Country Code
+
+Call `faostat_search_codes(domain_code='QCL', dimension_id='area', query='<country_name>')`.
+
+**CRITICAL:** If the response contains `requires_confirmation: true`, present ALL matching options to the user and ask them to select the correct one. Do NOT proceed until the user confirms. This commonly happens with names like "China" (mainland vs. aggregate), "Sudan" (former vs. current), or "Korea".
+
+Store the confirmed `area` code for all subsequent queries.
+
+### Step 3: Pull Production Data (Top Crops)
+
+Call `faostat_get_data` with:
+- `domain_code='QCL'`
+- `area='<resolved_area_code>'`
+- `element='2510'` (Production — this is the FILTER code)
+- `year='<most_recent_year>'` (try the current year minus 2; if no data, try minus 3)
+- `response_format='compact'`
+- `limit=20`
+- `show_unit=True`
+
+Sort the results by value descending and identify the **top 5 crops by production volume**.
+
+### Step 4: Pull Food Security Indicators
+
+Call `faostat_get_data` with:
+- `domain_code='FS'`
+- `area='<resolved_area_code>'`
+- `response_format='objects'`
+- `limit=50`
+
+Look for these key indicators:
+- Prevalence of undernourishment (%)
+- Number of undernourished people
+- Average dietary energy supply adequacy (%)
+- Prevalence of severe food insecurity (%)
+
+If data is sparse, note which indicators are unavailable.
+
+### Step 5: Pull Food Balance Sheet Data
+
+Call `faostat_get_data` with:
+- `domain_code='FBS'`
+- `area='<resolved_area_code>'`
+- `response_format='compact'`
+- `limit=50`
+
+Extract:
+- Dietary energy supply (kcal/capita/day)
+- Protein supply (g/capita/day)
+- Fat supply (g/capita/day)
+
+### Step 6: Pull Trade Summary
+
+Call `faostat_get_data` with:
+- `domain_code='TM'`
+- `area='<resolved_area_code>'`
+- `response_format='compact'`
+- `limit=30`
+
+Determine:
+- Total import value vs. total export value
+- Whether the country is a net food importer or exporter
+- Key imported and exported commodities
+
+### Step 7: Synthesize the Report
+
+Compose a narrative report with the following sections:
+
+**Title:** Food Security Profile: [Country Name]
+
+1. **Production Capacity** — Top 5 crops, total agricultural output volume, any notable specializations.
+
+2. **Food Access & Security** — Undernourishment prevalence, food insecurity rates, trends over available years (improving/worsening/stable).
+
+3. **Nutritional Supply** — Calorie and protein supply per capita, how these compare to global benchmarks (2,100 kcal/day minimum; 2,500 kcal/day adequate).
+
+4. **Trade Position** — Net importer or exporter, main trade partners if available, key agricultural imports and exports.
+
+5. **Key Risks & Trends** — Synthesize insights: dependency on imports, narrow crop base, declining yields, improving food security, etc.
+
+Include trend indicators where multi-year data is available:
+- Rising trend
+- Declining trend
+- Stable
+
+End the report with:
+
+> Source: FAOSTAT (FAO), accessed [current date]. Data may reflect reporting lags of 1-3 years.
+
+## Error Handling
+
+- If a domain returns no data for the country, note it in the report and continue with available data.
+- If the country code cannot be resolved, ask the user to try an alternative name or spelling.
+- If rate limits are hit, wait briefly and retry. Inform the user if delays are expected.
+
+## Output Format
+
+Deliver the report as a well-structured narrative with clear section headings. Use bullet points for data summaries and tables where comparisons aid readability. Keep the tone analytical and factual.

package/skills/explore/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: faostat-explore
+description: Use when the user wants to discover what data is available in FAOSTAT, browse domains, understand what a domain contains, or is new to FAOSTAT and wants a guided tour. Use when the user mentions a topic and wants to know what FAOSTAT data covers it. Keywords: explore, discover, browse, what data, available, domains, catalog, tour, overview, what can I find, show me, help me understand, new to FAOSTAT, getting started
+---
+
+# FAOSTAT Explorer
+
+Guided discovery of FAOSTAT's data catalog. Help users understand what data is available, browse domains, see sample data, and find the right starting point for their analysis.
+
+## Prerequisites
+
+Before starting, confirm the FAOSTAT MCP tools are available by checking that tools `faostat_list_groups`, `faostat_list_domains`, `faostat_get_dimensions`, `faostat_get_data`, and `faostat_get_metadata` 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 — Understand the User's Interest
+
+Ask the user: "What topic are you interested in exploring?" Examples:
+- A subject area: "fisheries", "fertilizers", "food prices", "livestock", "trade"
+- A question: "What data does FAO have about rice production?"
+- A broad theme: "climate and agriculture", "food security in Africa"
+- Or just: "Show me what's available" (full catalog overview)
+
+If the user provides their interest in their initial message, proceed without re-asking.
+
+### Step 2 — Map the FAOSTAT Catalog
+
+Call `faostat_list_groups(lang='en')` to retrieve all domain groups in FAOSTAT.
+
+Present the groups to the user in a clear, organized list. FAOSTAT organizes data into groups such as:
+- Production
+- Trade
+- Food Security
+- Food Balances
+- Prices
+- Inputs
+- Population
+- Investment
+- Macro-Statistics
+- Emissions (Agriculture, Land Use, Forestry)
+- Climate Change
+- and more
+
+If the user gave a specific topic, identify which group(s) are most relevant. If the user asked for a full overview, present all groups briefly.
+
+### Step 3 — Drill Into Relevant Domain Groups
+
+For each relevant group, call `faostat_list_domains(group_code, lang='en')` to list the specific domains within that group.
+
+Present the domains with their codes and descriptions. For example, within the Production group:
+- **QCL** — Crops and Livestock Products
+- **QI** — Production Indices
+- etc.
+
+If the user's topic spans multiple groups, show domains from all relevant groups.
+
+### Step 4 — Explore Domain Structure
+
+For each domain the user finds interesting (or the 1-3 most relevant domains if the user gave a specific topic):
+
+**A. Show Dimensions**
+
+Call `faostat_get_dimensions(domain_code, lang='en')` to show what dimensions (filters) the domain supports.
+
+Present the dimensions in plain language. For example:
+- "This domain lets you filter by: **Area** (countries/regions), **Item** (commodities like wheat, rice, cattle), **Element** (metrics like Production, Area Harvested, Yield), and **Year**."
+
+**B. Show Sample Data**
+
+Call `faostat_get_data(domain_code, lang='en', limit=5, response_format='objects')` to pull a small sample of data.
+
+Present the sample rows in a readable format (a table or formatted list). Explain what each column means:
+- What does the "Element" represent?
+- What are the units?
+- What time period is covered?
+
+**C. Explain the Domain**
+
+Call `faostat_get_metadata(domain_code, lang='en')` to retrieve the domain's metadata description.
+
+Summarize the metadata for the user in accessible language:
+- What does this domain measure?
+- What is the data source?
+- How frequently is it updated?
+- What geographic and temporal coverage does it have?
+- Any important caveats or methodology notes?
+
+### Step 5 — Suggest Analytical Paths
+
+Based on what the user is exploring, suggest which skills would help them go deeper:
+
+- **For production data:** "You could use `/faostat-commodity` for a deep dive into a specific crop, or `/faostat-country-profile` to see a country's full production picture."
+- **For trade data:** "Try `/faostat-trade` to analyze import dependencies and trade flows."
+- **For emissions/climate data:** "Use `/faostat-climate` to analyze emissions profiles, compare countries, or examine the inputs-emissions link."
+- **For trends and changes:** "Use `/faostat-trends` to identify the biggest movers and anomalies."
+- **For comparison questions:** "Try `/faostat-compare` for a structured side-by-side comparison."
+- **For visual output:** "Use `/faostat-viz` to generate interactive charts from any data you find."
+- **For narrative output:** "Use `/faostat-story` to build a data-driven article with embedded charts."
+
+### Step 6 — Offer to Run a Query
+
+Ask the user:
+- "Would you like me to pull specific data from any of these domains?"
+- "Want me to search for a particular country, commodity, or indicator?"
+- "Should I run one of the suggested skills for a deeper analysis?"
+
+If the user wants to query, use `faostat_search_codes` to resolve any entity names to codes before calling `faostat_get_data`.
+
+**CRITICAL:** If `requires_confirmation` is `true` in a search response (multiple matches), present the options to the user and ask them to choose before proceeding. Do NOT guess.
+
+**Important:** Element FILTER codes differ from DISPLAY codes. When calling `faostat_get_data`, use the filter code for the `element` parameter. When calling `faostat_get_rankings`, use the DISPLAY code. If unsure, use `faostat_search_codes` with `dimension_id='element'` to find the correct code.
+
+### Step 7 — Attribution
+
+When presenting any data, always include:
+
+> Source: FAOSTAT (FAO), accessed [current date].
+
+Replace `[current date]` with today's date. Include the domain code(s) referenced.

package/skills/story/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: faostat-story
+description: Use when the user wants to build a data-driven narrative, article, or report from FAOSTAT data for journalists, researchers, or communicators. Use when the user provides a research question, story angle, or topic they want to explore as a data story with embedded charts. Keywords: story, narrative, article, journalism, report, data story, investigation, angle, headline, write-up, briefing, explainer, data journalism
+---
+
+# Data Storyteller
+
+Build data-driven narratives for journalists, researchers, and communicators using FAOSTAT data, with embedded interactive charts and properly sourced statistics.
+
+## Prerequisites
+
+Before starting, confirm the FAOSTAT MCP tools are available by checking that tools `faostat_get_data`, `faostat_search_codes`, `faostat_list_groups`, `faostat_list_domains`, 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 — Understand the Story Angle
+
+Ask the user for their research question or story angle. Examples:
+- "The global avocado boom"
+- "Africa's fertilizer gap"
+- "Wheat after the Ukraine crisis"
+- "Who feeds the world's growing cities?"
+- "The rise of quinoa"
+
+If the user provides the angle in their initial message, proceed without re-asking.
+
+Identify:
+- **Subject** — what commodity, country, or theme?
+- **Tension** — what's surprising, changing, or at stake?
+- **Scope** — global, regional, or country-level?
+- **Time frame** — recent years, historical arc, or a specific event window?
+
+### Step 2 — Identify Relevant FAOSTAT Domains
+
+Based on the story angle, determine which FAOSTAT domains contain relevant data. Use `faostat_list_groups` and `faostat_list_domains` to confirm domain availability.
+
+Common domain mappings:
+- Production stories: **QCL** (Crops and Livestock Products)
+- Trade stories: **TM** (Trade Matrix)
+- Food security stories: **FS** (Food Security), **FBS** (Food Balance Sheets)
+- Climate/emissions stories: **GT** (Emissions Totals), **ET** (Temperature Change), **GF** (Forests)
+- Input stories: **RFN/RFM/RFB** (Fertilizers), **RP** (Pesticides)
+- Land use stories: **RL** (Land Use)
+
+### Step 3 — Resolve Codes and Pull Data
+
+For each entity referenced in the story:
+
+1. Use `faostat_search_codes` with the appropriate `domain_code` and `dimension_id` to resolve names to codes.
+
+   **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.
+
+2. Pull data using `faostat_get_data` with the resolved codes.
+
+   **Important:** Element FILTER codes differ from DISPLAY codes. When calling `faostat_get_data`, use the filter code for the `element` parameter (e.g., filter `'2510'` for Production). When calling `faostat_get_rankings`, use the DISPLAY code (e.g., `'5510'` for Production).
+
+3. Use `response_format='compact'` for multi-entity queries.
+
+4. Use `faostat_get_rankings` (with DISPLAY element codes) to find top producers, importers, or exporters for context and rankings.
+
+Pull data across multiple domains to build a multi-dimensional picture. A good data story typically draws from at least 2-3 different domains.
+
+### Step 4 — Find the Narrative Arc
+
+Analyze the pulled data to identify:
+
+1. **The hook** — what is the single most surprising or compelling finding? A number that stops the reader.
+2. **The trend** — what direction is the data moving, and does it break at some point? Inflection points make great story elements.
+3. **The key players** — which countries or entities dominate? Are there unexpected names in the top ranks?
+4. **The contrast** — what counterpoint or comparison makes the trend more vivid? (e.g., "Country X now produces more avocados than Y, which was the dominant producer just a decade ago")
+5. **The stakes** — why does this matter for food security, livelihoods, climate, or trade?
+
+### Step 5 — Generate Supporting Charts
+
+For each key data point in the story, generate a standalone HTML chart using Chart.js. Each chart file must include:
+
+- **Chart.js loaded via CDN** (`https://cdn.jsdelivr.net/npm/chart.js`)
+- **Descriptive title** as an HTML heading above the chart
+- **Properly labeled axes** with units (tonnes, hectares, USD, %, etc.)
+- **Legend** with clear entity names
+- **Colorblind-friendly palette** — use these colors in order:
+  `#2271B2`, `#F748A5`, `#359B73`, `#D55E00`, `#E69F00`, `#56B4E9`, `#009E73`, `#CC79A7`
+- **Responsive design** — canvas should resize with the viewport
+- **FAOSTAT source attribution** — a footer line: "Source: FAOSTAT (FAO), accessed [current date]"
+
+Choose chart types that match the data relationship:
+- **Line chart** for trends over time
+- **Bar chart** for comparisons across entities at a point in time
+- **Stacked bar** for composition breakdowns
+- **Scatter plot** for correlations between two variables
+
+Do NOT use pie charts for trends or comparisons with more than 5 categories.
+
+Generate 3-5 charts that support the narrative arc. Save each as a separate HTML file.
+
+### Step 6 — Draft the Data Narrative
+
+Compose an HTML report that interleaves narrative text with embedded charts. Structure:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>[Story Title]</title>
+    <style>
+        /* Clean, readable typography */
+        body { font-family: Georgia, 'Times New Roman', serif; max-width: 800px; margin: 0 auto; padding: 2rem; line-height: 1.7; color: #1a1a1a; }
+        h1 { font-size: 2.2rem; line-height: 1.2; margin-bottom: 0.5rem; }
+        .subtitle { font-size: 1.1rem; color: #666; margin-bottom: 2rem; }
+        .stat-callout { background: #f0f4f8; border-left: 4px solid #2271B2; padding: 1rem 1.5rem; margin: 1.5rem 0; font-size: 1.2rem; }
+        .chart-container { margin: 2rem 0; }
+        .chart-container canvas { max-height: 400px; }
+        .source { font-size: 0.85rem; color: #888; margin-top: 0.5rem; }
+        .takeaways { background: #f8f8f8; padding: 1.5rem; border-radius: 4px; margin-top: 2rem; }
+        .takeaways h2 { margin-top: 0; }
+        footer { margin-top: 3rem; padding-top: 1rem; border-top: 1px solid #ddd; font-size: 0.85rem; color: #888; }
+    </style>
+    <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
+</head>
+<body>
+    <!-- Narrative sections interleaved with charts -->
+</body>
+</html>
+```
+
+The narrative must include:
+
+1. **Headline** — concise, attention-grabbing, data-grounded
+2. **Subtitle** — one sentence expanding on the headline
+3. **Hook paragraph** — lead with the most surprising statistic or finding
+4. **Key statistics callouts** — highlighted stat boxes with the source noted
+5. **Body sections** — each building on the previous, with a chart following each major claim
+6. **Context paragraphs** — explain why the data looks the way it does (policy, climate, economic factors)
+7. **Key takeaways** — 3-5 bullet points summarizing the story
+8. **Footer** — full FAOSTAT attribution with access date and domain codes used
+
+Every statistic cited must include the FAOSTAT domain it came from.
+
+### Step 7 — Produce the Final Output
+
+Save the complete HTML report as a single file. If the charts are embedded inline (preferred), produce one HTML file. If charts are separate files, list them and explain how they connect to the narrative.
+
+Open the HTML file in the browser for the user to review.
+
+### Step 8 — Attribution
+
+Every chart and the report footer must include:
+
+> Source: FAOSTAT (FAO), accessed [current date]. Domains: [list domain codes used].
+
+Replace `[current date]` with today's date.
+
+### Step 9 — Offer Refinements
+
+Ask the user:
+- "Would you like me to adjust the angle or emphasis?"
+- "Should I add more charts or data points?"
+- "Want me to explore a related angle?" (e.g., if the story is about avocados, offer to look at trade flows or environmental impact)
+- "Should I dig deeper into any country or time period?"

package/skills/trade/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: faostat-trade
+description: Use when the user asks about food import dependence, self-sufficiency ratio, supply chain risk, trade partners, trade concentration, food security vulnerability, import reliance, export dependence, or whether a country can feed itself for a specific commodity. Keywords: import, export, trade, self-sufficiency, dependency, supply chain, food security, trade partners, concentration risk, import reliance, vulnerability
+---
+
+# Trade Dependency Analyzer
+
+Assess a country's import dependence for critical food commodities, calculate self-sufficiency ratios, identify supply chain concentration risks, and track dependency trends over time.
+
+## Prerequisites
+
+Before starting, verify that the FAOSTAT MCP tools are available: `faostat_search_codes`, `faostat_get_data`. If they are not available, inform the user they need the FAOSTAT MCP server configured and stop.
+
+## Domain Reference (CRITICAL -- use exactly these codes)
+
+| Domain | Code | Content |
+|--------|------|---------|
+| Crops & Livestock Products | **QCL** | Domestic production (area, yield, production volume) |
+| Trade Matrix | **TM** | Bilateral trade -- imports and exports by partner country |
+
+## Element Code Reference (CRITICAL)
+
+- **Production quantity**: filter code `2510`, display code `5510`
+- For `faostat_get_data` queries, use FILTER codes in the `element` parameter (e.g., `element='2510'`)
+- For `faostat_get_rankings` queries, use DISPLAY codes in the `element_code` parameter (e.g., `element_code='5510'`)
+
+## Workflow
+
+### Step 1: Accept inputs
+
+Ask the user for:
+- **Country** (required) -- e.g., "Egypt", "Japan", "Nigeria"
+- **Commodity** (required) -- e.g., "wheat", "rice", "soybeans", "palm oil"
+
+If the user provides both in their initial message, proceed directly. If either is missing, ask.
+
+### Step 2: Resolve codes
+
+1. Resolve the country to an area code:
+   `faostat_search_codes(domain_code='QCL', dimension_id='area', query='<country>')`
+   - If `requires_confirmation` is true, present the matching options and ask the user to choose. Do NOT proceed until confirmed.
+
+2. Resolve the commodity to an item code in the production domain:
+   `faostat_search_codes(domain_code='QCL', dimension_id='item', query='<commodity>')`
+   - Handle `requires_confirmation` the same way.
+
+3. Also resolve the commodity in the trade domain (item codes may differ):
+   `faostat_search_codes(domain_code='TM', dimension_id='item', query='<commodity>')`
+   - Handle `requires_confirmation`.
+
+### Step 3: Pull domestic production
+
+Query the QCL domain for the country's domestic production of this commodity:
+```
+faostat_get_data(
+  domain_code='QCL',
+  area='<area_code>',
+  item='<item_code_qcl>',
+  element='2510',
+  response_format='compact'
+)
+```
+Extract production quantities for the most recent 10-15 years to establish a trend.
+
+### Step 4: Pull trade data
+
+Query the TM domain for imports and exports of this commodity for the country:
+```
+faostat_get_data(
+  domain_code='TM',
+  area='<area_code>',
+  item='<item_code_tm>',
+  response_format='compact'
+)
+```
+Extract:
+- **Total import volume** (by year)
+- **Total export volume** (by year)
+- **Import values** (USD, if available)
+- **Partner country breakdown** -- who supplies the imports, who receives the exports
+
+### Step 5: Calculate self-sufficiency ratio
+
+For each year where data is available, calculate:
+
+```
+Self-Sufficiency Ratio (SSR) = Production / (Production + Imports - Exports)
+```
+
+Interpretation:
+- **SSR > 1.0** -- the country produces more than it consumes; net exporter
+- **SSR = 1.0** -- perfectly self-sufficient (rare)
+- **SSR 0.7-1.0** -- mostly self-sufficient, moderate import reliance
+- **SSR 0.5-0.7** -- significant import dependence
+- **SSR < 0.5** -- heavily import-dependent; vulnerable
+
+Calculate SSR for the latest year and for 5 and 10 years ago (if data available) to show the trend.
+
+### Step 6: Identify trading partners and concentration risk
+
+From the trade data, rank import partners by volume:
+1. List the top 5 import source countries with their share of total imports.
+2. Calculate a concentration metric: what percentage of imports comes from the top 1, top 2, and top 3 suppliers?
+3. Assess concentration risk:
+   - **Top 1 supplier > 50%** -- HIGH concentration risk (single point of failure)
+   - **Top 3 suppliers > 80%** -- MODERATE concentration risk
+   - **No single supplier > 30%** -- LOW concentration risk (diversified)
+
+### Step 7: Trend analysis
+
+Analyze the trajectory:
+- Is the SSR **improving** (moving toward 1.0), **stable**, or **deteriorating** (moving away from 1.0)?
+- Is import volume growing faster than domestic production?
+- Are trading partners becoming more or less concentrated over time?
+
+### Step 8: Present the dependency assessment
+
+Structure the output as follows:
+
+**1. Self-Sufficiency Summary**
+- Current SSR with interpretation
+- SSR 5 years ago and 10 years ago
+- Trend direction (improving / stable / deteriorating)
+
+**2. Domestic Production**
+- Latest production volume with units
+- Production trend (growing / shrinking / stagnant)
+
+**3. Trade Position**
+- Total imports (volume and value)
+- Total exports (volume and value)
+- Net trade position (net importer or net exporter)
+
+**4. Supply Chain Risk**
+- Top 5 import partners with share percentages
+- Concentration risk rating (HIGH / MODERATE / LOW)
+- Any single-supplier vulnerability
+
+**5. Trend & Outlook**
+- Direction of dependency over time
+- Key risk factors (e.g., "Production is flat while imports grow 5% annually")
+- One-line vulnerability narrative (e.g., "Egypt imports 55% of its wheat, with 40% coming from a single supplier -- Russia")
+
+**6. Source Attribution**
+"Source: FAOSTAT (FAO), accessed [current date]"
+
+## Important Rules
+
+- Always use `faostat_search_codes` before `faostat_get_data` to resolve codes. Never guess or hardcode domain-specific codes.
+- When `requires_confirmation` is true in a search result, always present options to the user and wait for their choice.
+- Use `response_format='compact'` for multi-year or multi-partner queries to keep response sizes manageable.
+- For `faostat_get_data`, use FILTER element codes (e.g., '2510'). For `faostat_get_rankings`, use DISPLAY element codes (e.g., '5510').
+- If production data returns zero or null for a country-commodity pair, note this explicitly -- it may mean the country does not produce this commodity at all (SSR = 0, fully import-dependent).
+- Always include the source attribution line at the end of any output.