faostat-analytical-brief

FAOSTAT Analytical Brief

Produce a multi-page PDF analytical brief in the FAOSTAT house visual style, with the corresponding multi-sheet xlsx data appendix so every figure and discussion point is reproducible.

Scope of the visual grammar (no FAO branding). The brief uses the FAOSTAT visual grammar — teal/dark-blue palette, serif titles, → arrow bullets, teal section banners, numbered figures with Source: FAOSTAT … lines, and the familiar section order (HIGHLIGHTS / BACKGROUND / GLOBAL / REGIONAL / COUNTRY / EXPLANATORY NOTES / NEXT RELEASE / REFERENCES). It does not reproduce the FAO logo, "Food and Agriculture Organization of the United Nations" masthead, ISSN strip, "FAO Statistics Division" stamp, "Required citation: FAO. …" line, or any other FAO branding. The output must be clearly attributable as a user-generated analysis, not an FAO publication.

Prerequisites

Confirm the FAOSTAT MCP tools are available: faostat_get_data, faostat_search_codes, faostat_list_domains, faostat_get_metadata. If they are not, tell the user and stop.

Python packages (install on demand via pip install <pkg> --break-system-packages):

• plotly, pandas, kaleido (figure rendering + PNG export, reused from faostat-map)
• reportlab (PDF assembly via Platypus)
• openpyxl (xlsx data appendix)

The forthcoming figure renders compose on top of faostat-viz (line/bar/stacked-bar) and faostat-map (choropleths). When a brief needs a map, invoke the map skill's rendering guidance rather than reimplementing.

Cross-skill invariants (do not violate)

All 6 invariants from the FAOSTAT skill suite apply unchanged:

1. FILTER vs DISPLAY element codes. faostat_get_data takes FILTER codes (e.g., '2510'); never pass DISPLAY codes ('5510').
2. Year syntax. Comma-separated lists only ('2010,2011,...,2024'); colon ranges return empty.
3. Element filter required on every faostat_get_data call.
4. TCL for national trade aggregates, TM only for partner breakdowns. Never sum TM rows to reconstruct national totals.
5. China composite default (user preference, Apr 2026). Default to composite China (area 351) for country rankings, top-N lists and country-level analysis. Offer China, mainland (41) as an opt-in — do not substitute 41 unless the user asks for 41 explicitly. Flag the choice in the Methodology sheet, and include the caveat whenever a China number is quoted: FAOSTAT's own publications default to 41, so a brief using 351 will show a marginally larger "China" value than the FAO data-portal default. (Map figures inside the brief are an exception: they use the disaggregation path — area 41 on the CHN polygon with HKG / MAC / TWN rendered separately — because choropleths cannot sensibly render 351. See the map skill.)
6. faostat_get_rankings HTTP-500 fallback. Reconstruct rankings from faostat_get_data + client-side sort; document fallback in the Methodology sheet.
7. 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.