Server health and data-source catalog probe.

Doubles as the version and health endpoint: returns server_version so an agent can confirm which release it is talking to. Also returns the full upstream-source catalog: cache TTLs, freshness expectations, and licenses. Use it to judge whether a stale cached response is fine or a re-fetch is needed.

Examples: get_data_freshness() # the only call, it takes no arguments

On failure: this tool calls no upstream itself, so it always returns a dict. source_health is a process-local, in-memory registry, not a database. It starts empty on a cold process and fills as fetch_with_retry runs calls, so a fresh restart always reports an empty dict here.

Returns: server_version, server_name, transport, tool_count, asof, sources (list of {source, source_url, freshness, cache_ttl_seconds, license}), source_health (per-host {last_success_at, last_failure_at, last_error, last_latency_ms, success_count, failure_count}), cache_age (per-cache {size, ttl_seconds}), note.

Get the latest earthquake events from PHIVOLCS.

Reads the live PHIVOLCS earthquake list, the same table shown at earthquake.phivolcs.dost.gov.ph. Give center_lat, center_lon, and radius_km together to filter events near one place, and each matched event then carries a distance_km field. Give all three together, or leave out all three. Examples:

get_latest_earthquakes() latest events, default filters get_latest_earthquakes(min_magnitude=4.0, limit=10) strong events only get_latest_earthquakes(center_lat=14.5995, center_lon=120.9842, radius_km=50) near Manila

On failure: an invalid trio, an out-of-range radius_km, center_lat, or center_lon gives validation_error true and data_status "invalid_request". An unreachable or unparsable PHIVOLCS list gives upstream_error true and data_status "unavailable". Both return results: [] with the real error in caveats.

Get the full bulletin for a PHIVOLCS earthquake event.

Parses the bulletin page PHIVOLCS publishes for one event: magnitude, depth, location, date and time, and per-municipality intensity reports. Give the bulletin_url a prior get_latest_earthquakes call returned. A hand-built or off-host URL is refused before any fetch is attempted. Examples:

get_earthquake_bulletin("https://phivolcs.dost.gov.ph/index.php") # real bulletin URL shape

On failure: an empty, malformed, or non-PHIVOLCS bulletin_url, or a 404 on the page itself, returns a dict with url, source, caveats, and data_retrieved_at only, with no data_status, upstream_error, magnitude, or location fields. A fetch that raises an exception sets data_status "unavailable" and upstream_error true.

Get current alert level for Philippine volcanoes.

Reads the WOVODAT bulletin list PHIVOLCS publishes for its monitored volcanoes: Mayon, Taal, Kanlaon, Bulusan, Pinatubo, Hibok-Hibok, and Parker. When one volcano's bulletin fetch fails, that entry carries upstream_error true and a caveat with the real error, not a null alert_level. Examples:

get_volcano_status() all monitored volcanoes, one call get_volcano_status("Mayon") one volcano by name get_volcano_status("Taal")

On failure: WOVODAT list unreachable or empty gives data_status "unavailable", upstream_error true, results: [], and the real error in caveats. An unmatched volcano_name gives a one-item list with alert_level null and a caveat, not a failure envelope.

Get the weather forecast for a Philippine location.

Uses the PAGASA TenDay API when PAGASA_API_TOKEN is set, and falls back to Open-Meteo when the token is absent or the PAGASA call fails. This tool sets no data_status field on a success or an unknown-location result. Check data_source and caveats instead. Examples:

get_weather_forecast("Manila") 3-day default forecast get_weather_forecast("Cebu City", days=2) 2-day forecast get_weather_forecast("Wakanda") unknown location, no coordinates found

On failure, a location with no known coordinates returns days: [] and a caveat, with no data_status or upstream_error key. An Open-Meteo fetch failure, or a PSGC outage during location resolution, returns data_status "unavailable", upstream_error: true, days: [], and the real error in caveats. An Open-Meteo response with no daily forecast entries returns data_status "indeterminate" instead, and is never cached.

Get active tropical cyclones in/near the Philippine Area of Responsibility (PAR).

Returns an empty list when no cyclone is active. This tool parses the live PAGASA bulletin page with regular expressions. A bulletin wording change can miss a cyclone, but the "no active" state itself is reliably detected.

Examples: get_active_typhoons() # only call form, no arguments

On failure: When the PAGASA bulletin page is unreachable, this tool returns data_status "unavailable", upstream_error: true, results: [], and the real error in caveats. That shape never matches a genuine "no active typhoons" answer, which is a bare empty list. When the page loads but neither the "no active cyclone" marker nor a cyclone name matches, this tool returns data_status "indeterminate" instead of guessing at "no active typhoons".

Returns: list of typhoons, each with local_name, international_name, category, max_winds_kph, within_par, signal_numbers, bulletin_number, source, bulletin_url, data_retrieved_at. Or the failure dict above.

Get active PAGASA weather alerts and advisories.

The PAGASA homepage embeds alert names such as "Heavy Rainfall Warning" in its navigation menu and breadcrumbs, as well as in real active-warning sections. This tool reliably detects the "No Active Warnings" state, but it cannot yet isolate a real active warning from that navigation text. To avoid a fabricated advisory, this tool returns a bare empty list only for the confirmed "no active warnings" marker. For real-time advisories, call bagong.pagasa.dost.gov.ph directly. Examples:

get_weather_alerts() no region argument get_weather_alerts(region="NCR") region only changes the cache key

On failure, when the PAGASA homepage is unreachable, this tool returns data_status "unavailable", upstream_error: true, results: [], and the real error in caveats. When the page is reachable but the "no active warnings" marker does not match, this tool returns data_status "indeterminate" instead of guessing, and never caches that response.

Search PH government procurement from PhilGEPS open data.

Note: the PhilGEPS public portal does not expose server-side search for external clients, so this tool fetches the latest ~100 bid notices and filters them in-memory. Data is cached 6 hours. Keyword/agency/region filters are applied client-side (case-insensitive substring match). Examples:

search_procurement(keyword="flood") search_procurement(keyword="", agency="DPWH", limit=10)

On failure: returns {results: [], upstream_error: true, data_status: "unavailable", caveats: [...]} instead of a bare list, so an outage is never read as "no matching notices". A date_from or date_to that does not parse returns {results: [], validation_error: true, data_status: "invalid_request"} before any fetch, naming the bad value.

Aggregate procurement statistics over the latest notices cached from PhilGEPS.

This tool aggregates the same latest ~100-notice window search_procurement reads (6h cache). rules_evaluated names which breakdowns ran, by_mode and by_region. rules_not_computable explains why total_value_php stays null: PhilGEPS open notices do not publish approved budget amounts. Examples:

get_procurement_summary() get_procurement_summary(agency="DPWH", year=2025)

On failure: data_status "unavailable", upstream_error true, totals zero and by_mode/by_region/top_agencies empty, with the real PhilGEPS error in caveats. A year that is not a plain integer returns validation_error: true and data_status "invalid_request" before any fetch, naming the bad value.

Fuzzy-resolve a Philippine place name to its canonical PSGC record.

Handles common nicknames directly, such as "QC", "Gensan", "CDO", and "Metro Manila". An ambiguous name such as "San Juan" still returns one best match, plus an alternatives list of the other candidates. This tool sets no data_status field on any path. Check matched and upstream_error instead. Examples:

resolve_ph_location("Cebu City") exact city match resolve_ph_location("QC") nickname resolves to Quezon City resolve_ph_location("San Juan") ambiguous name, returns alternatives

On failure, a clean no-match returns matched: false and caveats, with no upstream_error key at all. When the PSGC API itself is unreachable, it returns matched: false, upstream_error: true, and the real error in caveats.

Browse children of a PSGC node, or top-level regions when parent_code is None.

An unrecognized parent_code or level filter matches no children and returns an empty list. This tool never returns validation_error. A malformed argument degrades to an empty result instead of a failure. Examples:

list_admin_units() top-level regions list_admin_units(parent_code="072200000") children of Cebu province list_admin_units(level="city-municipality", limit=10) first 10 cities and municipalities

On failure, only a PSGC API outage returns a failure envelope: data_status "unavailable", upstream_error: true, results: [], and the real error in caveats. A malformed parent_code or level returns an empty list instead of this failure shape.

Return the full chain region -> province -> city/municipality -> barangay for one PSGC code.

This tool checks that psgc_code is well-formed before it sends any request. A malformed code never reaches the network. An unknown but well-formed code, or a PSGC mirror outage, both produce an empty chain instead of a match. Check the fields named below to tell the two apart. Examples:

get_location_hierarchy("072217000") Cebu City, chain walks up through province and region get_location_hierarchy("999999999") well-formed but unknown code get_location_hierarchy("not-a-code") malformed, rejected before any network call

On failure, a malformed code returns validation_error: true, data_status "invalid_request", and chain: [], with no network call made. A genuine mirror outage during lookup or the hierarchy walk returns chain: [], upstream_error: true, and the real error in caveats. A clean unknown-code answer returns chain: [] and caveats, with neither key set.

Population from the PSA Census of Population, discovered live on OpenSTAT.

Defaults to the latest census PSA publishes: the 2024 Census of Population, reference date 2024-07-01, as of 2026-09. Pass year for an older census (2010, 2015, 2020). Every result names its census, reference date and geography level, and for the 2024 tables the PSGC code PSA keyed the row on. Examples:

get_population_stats() national total, latest census get_population_stats(region="NCR") one region, province or HUC by PSA label get_population_stats(region="Cebu", year=2020) get_population_stats(psgc_code="0831600000") City of Tacloban, 2024 Census get_population_stats(psgc_code="083747000") same place, 9-digit code get_population_stats(psgc_code="1380100001") one barangay, 2024 Census

On failure: data_status is "unavailable" when PSA is down, with upstream_error true. data_status is "invalid_request" for an unknown region, year, or PSGC code, with validation_error true. data_status is "empty" when a valid PSGC code has no row in the chosen census table. caveats always carries the real error text. population is None in every failure. Failures are never cached.

Poverty incidence from the PSA Full Year Poverty Statistics table.

PSA publishes this once a year, with a lag. As of 2026-09 the latest published year is 2023. The tool discovers the current table live, so a later release shows up without a code change. It also returns the subsistence incidence when PSA publishes both tables for the same year. Examples:

get_poverty_stats() national poverty incidence, latest year get_poverty_stats(region="Bicol") one region, PSA label get_poverty_stats(region="NCR") National Capital Region

On failure: a discovery failure, a missing Incidence dimension, an unparseable year label, or a query failure sets data_status "unavailable" and upstream_error true. A region PSA does not list sets data_status "invalid_request" and validation_error true. A table with no matching incidence measure, or a cell whose values field is not a list, sets data_status "indeterminate" and upstream_error true. A published ".." cell for the region and year sets no error flag and no data_status. Check caveats instead. A subsistence-table failure sets upstream_error true on an otherwise valid poverty figure, but leaves data_status at "success".

Headline consumer-price inflation (year-on-year, all items) from PSA.

Source: PSA OpenSTAT Consumer Price Index, 2018-based. The tool discovers the current CPI series by text, never a hardcoded table id, and returns the most recently published month's year-on-year change. PSA publishes with a lag, so the reported period is the latest one PSA has, not always the current month. Examples:

get_inflation_stats() national headline inflation, latest month get_inflation_stats(area="NCR") one region

On failure: every failure, including an area name PSA does not list, sets data_status "unavailable" and upstream_error true, with the real error or a not-found message in caveats. validation_error stays false in every case, because a bad area name is treated as an outage here, not a caller mistake.

Key labor-force indicators from the PSA Labor Force Survey.

Returns labor-force participation, employment, unemployment, and underemployment rates for the latest published reference period. The PSA key-indicator series is national only. Passing region does not filter the figure. It only adds an explanatory caveat, because this table has no regional breakdown. Examples:

get_labor_stats() national rates, latest reference period get_labor_stats(region="Cebu") same national rates, plus a caveat

On failure: an OpenSTAT discovery or query failure sets data_status "unavailable" and upstream_error true, with the real error in caveats. validation_error stays false in every case.

National health indicators from PSA OpenSTAT (subject 1D).

With no argument, returns the curated national headline set: maternal mortality ratio and total fertility rate. Pass a free-text indicator to fuzzy-match any table published under the Health subject. The available list is browse-discovered, never hardcoded. Examples:

get_health_indicators() maternal mortality ratio and fertility rate get_health_indicators(indicator="fertility") one matching table

On failure: a catalog browse failure sets data_status "unavailable" and upstream_error true, with an empty indicators list. A keyword that matches no table sets data_status "success" with an empty indicators list and a caveat, not an error flag. A partial fetch failure across matched tables sets data_status "indeterminate" and upstream_error true. validation_error stays false in every case.

Search Philippine government infrastructure projects.

Backed by PhilGEPS open notice listing filtered for infra-related work (construction / road / bridge / flood control / drainage / school building / civil works). Source: https://www.philgeps.gov.ph/. Approved budget amounts are not published in the open notice listing, so cost_php is null in most records. min_cost_php almost never matches, because the open listing omits approved budget for nearly every record. The DPWH transparency portal API is currently blocked by Cloudflare and not used. Examples:

search_infra_projects(keyword="flood control") search_infra_projects(region="ncr") search_infra_projects(min_cost_php=100_000_000)

On failure: returns {results: [], upstream_error: true, data_status: "unavailable", caveats: [...]} instead of a bare list, with the real upstream error in caveats. This tool never checks an argument before the PhilGEPS fetch runs, so validation_error is always false.

Return the full record for one infrastructure project by project_id.

This tool looks up project_id inside the same latest ~100-notice PhilGEPS window search_infra_projects reads. An id from an older window returns matched: false, not an error, because the window has already moved on. Examples:

get_infra_project("PHILGEPS-INF-003") get_infra_project("DOES-NOT-EXIST")

On failure: an empty project_id or a project missing from the current window both return matched: false with a caveat, no upstream_error, and no data_status. A PhilGEPS fetch failure returns matched: false, data_status "unavailable", upstream_error true, and the real error text in caveats.

Aggregate infrastructure procurement statistics over the latest PhilGEPS window.

This tool aggregates the same infra-keyword-matched notice window search_infra_projects reads (cached 6h). rules_evaluated names which breakdowns ran, today by_category and by_region. rules_not_computable names by_funding_source, retired to an always-empty dict because PhilGEPS notices carry no funding source field. sample_size and sufficient_for_per_capita flag whether the window, today under the 500-notice threshold, is large enough for a per-100k rate. Examples:

summarize_infra_spending() summarize_infra_spending(region="ncr", year=2025)

On failure: data_status "unavailable", upstream_error true, totals zero and by_category/by_region/top_agencies empty, with the real PhilGEPS error in caveats. No validation_error path exists.

Multi-hazard risk assessment combining PHIVOLCS + PAGASA.

Makes parallel upstream calls to PHIVOLCS (earthquakes, volcano alert levels) and PAGASA (active typhoons, weather alerts). Expect 3-6 second response time. earthquake_risk_level is a heuristic reading of recent seismic activity, never an official PHIVOLCS hazard assessment. Examples:

assess_area_risk("Manila") assess_area_risk("Batangas")

On failure: this tool never raises. A failed PHIVOLCS or PAGASA sub-call shows up as a caveats entry naming the source, and the other sources still report. data_status is "success" when every sub-call succeeded, "indeterminate" when some failed, and "unavailable" when all failed; upstream_error is true for the last two.

Flag PhilGEPS infrastructure projects that warrant further review by cross-referencing PHIVOLCS earthquakes and PAGASA typhoon footprints.

This tool emits heuristic anomaly indicators, not accusations. Every flagged item ships with the rule that fired and a disclaimer noting that patterns may have legitimate explanations.

Heuristic rules:

• duplicate_titles_same_agency: same agency files multiple notices with effectively identical titles (case-insensitive) within the window

• high_cost_no_published_progress: cost_php exceeds min_cost_php. The PhilGEPS open listing publishes no progress data for ANY notice, so this is a cost-threshold transparency flag, not a project-specific "progress is missing" finding.

• hazard_overlap: project location keywords overlap with a recent PHIVOLCS earthquake (>=M4.0 in last 30d) or an active PAGASA typhoon footprint, suggesting urgency or post-disaster reconstruction context. Examples:

  flag_infra_anomalies() flag_infra_anomalies(min_cost_php=100_000_000)

On failure: this tool never raises. data_status is "success" when PhilGEPS, PHIVOLCS, and PAGASA all load, "indeterminate" when one or two fail, and "unavailable" when all three fail; upstream_error is true for the last two. A failed sub-call shows up as a caveats entry naming the source, and the flagged list still returns data from every source that did respond.

One-call correlated civic profile for a Philippine location.

Resolves the place once to its PSA Standard Geographic Code, then composes demographics (population, poverty), economy (regional inflation, national labor), procurement activity, multi-hazard risk, and the short-range weather outlook — in a single agent turn instead of eight. Adds derived cross-source context (e.g. infrastructure notices per 100k residents) so the caller does not have to normalize raw counts itself. Examples:

get_area_profile("Cebu City") city-level demographics, hazard, weather get_area_profile("NCR") region-level, no province in the chain get_area_profile("Tacloban") city under a resolved province

On failure: each block (population, poverty, inflation, labor, hazard, weather, infra, resolve) gets its own status in blocks. A failed sibling appears there and in caveats, never as a silent null. The top-level upstream_error is true only when a block is genuinely unreachable, not when a sibling rejected an argument or returned a real empty answer.

Daily solar irradiance and climate variables from NASA POWER for any coordinate.

Returns daily solar irradiance, 2m temperature, corrected precipitation, and 2m wind speed, in kWh per m2, Celsius, mm, and m per second. Useful for solar-site screening, farm planning, and historical climate checks. Examples:

get_solar_and_climate(14.5995, 120.9842) # Manila, last 14 days get_solar_and_climate(14.5995, 120.9842, "2026-04-01", "2026-04-02") # a fixed 2-day window

On failure: an upstream fetch failure or a non-object response body returns data_status "unavailable", with upstream_error true, days [], and the real error text in caveats. A properties or parameter field that is missing, null, or not an object returns data_status "indeterminate", with upstream_error true and days []. A start_date or end_date that does not parse as YYYY-MM-DD, an end_date before start_date, a span over 366 days, or a latitude or longitude out of range, returns data_status "invalid_request", with validation_error true and days [].

Real-time air quality for a Philippine city via Open-Meteo (no API key).

Returns PM2.5, PM10, CO, NO2, SO2, and O3, plus European AQI and US AQI with category interpretation. Covers about 80 major PH cities through a local coordinate table. measured_at is always UTC, never Asia/Manila time. Examples:

get_air_quality("Manila") # current readings for Metro Manila get_air_quality("Cebu City") # current readings for Cebu City get_air_quality("Davao") # current readings for Davao City

On failure: a location not in the coordinate table returns data_status "invalid_request", with validation_error true and a caveat naming the location. An Open-Meteo fetch failure returns data_status "unavailable", with upstream_error true and the real error text in caveats. A response with no time, an unparseable time, or no pollutant field returns data_status "indeterminate", with upstream_error true and a caveat naming the problem.

Daily river discharge forecast for a Philippine place, from Open-Meteo's GloFAS model.

Returns a daily river_discharge_m3s series for the nearest river cell to the resolved location, plus its max and min bounds, in cubic meters per second. This is a model estimate, not a gauge reading, so treat it as one signal among many for flood risk. Examples:

get_flood_forecast("Cagayan de Oro") # 7-day default forecast get_flood_forecast("Marikina", forecast_days=14, past_days=3) # 14 days ahead, 3 days back

On failure: an unresolved location, or a forecast_days or past_days value that is not a whole number or is out of range, returns data_status "invalid_request", with validation_error true and days []. A PSGC outage during location resolution, or an Open-Meteo fetch failure, returns data_status "unavailable", with upstream_error true and days []. A response with no readable daily.time entries, or a river_discharge list shorter than daily.time (including an empty list), returns data_status "indeterminate", with upstream_error true, days [], and is never cached.

NASA MODIS MOD13Q1 NDVI and EVI vegetation index at any coordinate.

NDVI (Normalized Difference Vegetation Index) ranges -1 to 1. Higher values indicate denser healthy vegetation. EVI is more sensitive in high-biomass areas. The composite period is 16 days at 250m resolution. Useful for farm monitoring, deforestation tracking, and drought checks. Examples:

get_vegetation_index(15.58, 121.0) # last ~90 days at a point in Isabela get_vegetation_index(15.58, 121.0, "2026-08-01", "2026-08-15") # a fixed 15-day window

On failure: both MODIS bands failing returns data_status "unavailable", upstream_error true, samples [], and both band errors in caveats. One band failing still returns the other band's samples, but data_status stays "unavailable" with upstream_error true. A band whose rows carry no numeric value counts as that band failing. A pixel with no composite in range, such as one over water, is a real success with samples []. A latitude or longitude out of range returns data_status "invalid_request", with validation_error true and samples []. A start_date or end_date that does not parse as YYYY-MM-DD, or a span over 366 days, also returns data_status "invalid_request", checked before any fetch.

Philippine-region earthquakes from USGS, cross-reference to PHIVOLCS.

Returns events inside the PH bounding box (lat 4..22, lng 115..130) that USGS catalogs, including international-standard Mww/Mwc magnitudes and depth solutions. Complements PHIVOLCS with global-network analysis. Give center_lat, center_lon, and radius_km together to filter to one place, and each matched event then carries a distance_km field. Give all three together, or leave out all three. Examples:

get_usgs_earthquakes_ph() last 30 days, magnitude 4.0+ get_usgs_earthquakes_ph(start_date="2026-08-01", end_date="2026-08-31") get_usgs_earthquakes_ph(center_lat=14.5995, center_lon=120.9842, radius_km=50) near Manila

On failure: an invalid trio, an out-of-range radius_km, center_lat, or center_lon gives validation_error true and data_status "invalid_request". The same happens for a start_date or end_date that is not YYYY-MM-DD. An unreachable USGS API, or a payload that is not a GeoJSON FeatureCollection, gives upstream_error true and data_status "unavailable". A nonempty features list where every feature fails to parse gives upstream_error true and data_status "indeterminate", and is never cached. All three return results: [] with the real error in caveats.

Historical tropical cyclone tracks that passed through the Philippine AOR.

Sourced from NOAA IBTrACS (International Best Track Archive), the authoritative global archive for tropical cyclone tracks. Filtered to the Western Pacific basin and coordinates inside the Philippine Area of Responsibility, aggregated per storm. The result streams the source CSV row by row and returns the most recent storms that crossed the PAR, sorted by start time. Returns peak intensity, minimum pressure, and track period. Examples:

get_historical_typhoons_ph() # last 3 years, up to 30 storms get_historical_typhoons_ph(year=2024) # season 2024, up to 30 storms get_historical_typhoons_ph(year=2024, limit=10) # season 2024, up to 10 storms

On failure: a stream error, a response with no data rows, or a CSV header missing a required column returns a dict. data_status is "unavailable", upstream_error is true, and results is empty, with the real error text in caveats.

World Bank macroeconomic and social indicator for the Philippines.

Accepts a World Bank indicator code, such as "NY.GDP.MKTP.CD", or a friendly alias, such as "gdp", "poverty_ratio", "inflation", or "urban_population_pct". The tool checks the indicator code shape before it reaches the URL, so a bad value cannot redirect the request to another country's data. Examples:

get_world_bank_indicator("gdp") # GDP, latest 20 years get_world_bank_indicator("NY.GDP.MKTP.CD", per_page=5) # same indicator, 5 years get_world_bank_indicator("poverty_ratio") # poverty headcount ratio

On failure: an indicator code or alias that fails the shape check returns data_status "invalid_request", with validation_error true and observations []. An upstream fetch failure returns data_status "unavailable", with upstream_error true, observations [], and the real error text in caveats. A row with a non-numeric or non-finite value (NaN, inf) is skipped and counted in caveats. A response where every row is non-numeric or non-finite returns data_status "unavailable" instead of a false empty answer.

List one level of the PSA OpenSTAT statistical catalog.

OpenSTAT publishes roughly 2,900 tables across 27 subjects. This walks that tree one level at a time, so an agent can find a dataset without guessing a table id. A dataset entry is a .px table. Pass its path to describe_psa_dataset before calling query_psa_dataset. Folder depth varies by subject, so keep browsing until entries come back as datasets. Examples:

browse_psa_catalog() the 27 top-level subjects browse_psa_catalog("1F") one level into the Poverty subject browse_psa_catalog("1F/FY") the Full Year Poverty Statistics tables

On failure: data_status is "invalid_request" for a rejected argument and "unavailable" for an OpenSTAT outage. A bad path sets validation_error true before any request goes out. An unreachable catalog sets upstream_error true, with the real error in caveats. Both return an empty entries list, which never means an empty folder.

Read the dimensions and valid value codes of one PSA OpenSTAT dataset.

Call this before query_psa_dataset. The query tool needs an explicit value code for every dimension, and those codes live here. total_cells is the size of the full cube. A query must select down to max_cells_per_query or fewer, so pick explicit codes per dimension. Examples:

describe_psa_dataset("1F/FY/0241F3DF013.px") dimensions and value codes for one table

On failure: data_status is "invalid_request" for a rejected argument and "unavailable" for an OpenSTAT outage. A path that is not a .px dataset sets validation_error true before any request goes out. An unreadable dataset sets upstream_error true, with the real error in caveats. Both return an empty dimensions list.

Run one bounded query against a PSA OpenSTAT dataset.

Every dimension needs an explicit list of value codes from describe_psa_dataset. That is a hard requirement, not a convention. PXWeb expands an unselected dimension to all of its values, and PSA answers the resulting full-cube request with an HTTP 403. PSA writes a missing cell as "..", and those come back as null, never zero. Examples:

one dataset, every dimension given an explicit code list

query_psa_dataset( "1F/FY/0241F3DF013.px", {"Year": ["2"], "Major Island Group": ["0", "2"], "Among Families/Population": ["0"]}, )

On failure: a bad path, a bad max_rows, or a rejected selection (a missing dimension, an unknown code, or "all"/"*") sets validation_error true and data_status "invalid_request", before any request goes out. An OpenSTAT outage sets upstream_error true and data_status "unavailable". A zero-row reply for a nonzero selection, or a row whose key does not map to the declared columns, sets data_status "indeterminate" and upstream_error true on a real HTTP 200. All four cases return an empty rows list.

Find a PSA OpenSTAT dataset by keyword, without browsing level by level.

Matches a case-insensitive substring against every dataset title and path in the catalog. The first call after a cold start walks the whole ~2,900-table tree and can take a few minutes. The flattened index then caches for 24 hours, so a later search answers from memory. Examples:

search_psa_catalog("fertility") datasets with "fertility" in the title or path search_psa_catalog("poverty incidence", limit=5) at most 5 matches

On failure: data_status is "invalid_request" for an empty keyword or a bad limit, and "unavailable" for an OpenSTAT outage during the catalog walk. validation_error or upstream_error is set to match. The real error sits in caveats. Neither failure is cached.

Compare civic indicators for two to five Philippine places, side by side.

Calls get_area_profile for each place and builds one row per place, so an agent does not have to call the profile tool once per place and merge the results itself. locations needs 2 to 5 entries. metrics, when given, must come from a fixed allowlist of eight names, and it defaults to all eight. format is "json" or "csv". "csv" adds a CSV string under export. Examples:

compare_areas(["Cebu City", "Davao City"]) compare_areas(["Cebu City", "Davao City"], metrics=["population"])

On failure: a rejected request, such as a wrong location count, too many or duplicate metrics, an unknown metric, or a bad format, never calls get_area_profile. It returns validation_error: true and data_status "invalid_request". A place that fails to resolve still gets a row, with resolved_name None, the overall data_status becomes "indeterminate" or "unavailable", and comparable turns false with a caveat naming the unresolved place.

Search HDX for Philippine humanitarian datasets by keyword.

Calls the CKAN package_search action filtered to the Philippines country group and returns matching datasets, most recently modified first, each with its own license and up to 20 resources. Examples:

search_hdx_datasets("flood") datasets matching "flood" search_hdx_datasets("food prices", rows=5) 5 most recently modified matches

On failure: an empty query, a query over 200 characters, a query with a control character, or a rows value outside 1 to 50 gives validation_error true and data_status "invalid_request". An unreachable HDX API gives upstream_error true and data_status "unavailable". A response whose success field is not true, or whose result.results field is not a list, gives upstream_error true and data_status "indeterminate". Datasets sent beside a missing or non-integer count also give data_status "indeterminate", with the parsed datasets kept and never cached: CKAN always sends a real count, so a bad one is drift even when the datasets read fine. Zero datasets on a clean query with a real integer count gives data_status "empty", never a failure, and still caches. Every dataset carries its own license_id: read it before you reuse a resource.

Latest issuances from the Official Gazette of the Republic of the Philippines.

Reads the government's own RSS feed of proclamations, memorandum circulars, and other issuances, ten items per page, newest first. Examples:

get_official_gazette_feed() # page 1, the newest 10 issuances get_official_gazette_feed(page=2) # the next 10 issuances

On failure: a page outside 1 to 50 returns data_status "invalid_request" with validation_error true and no fetch attempted. A Cloudflare block page, the only other response this host sends on a bad call, returns data_status "unavailable" with upstream_error true and the real status and content type in caveats. An item with neither a title nor a link is dropped and counted in caveats. A page 1 response that parses as valid RSS but keeps zero issuances, whether the feed sent none or every item was dropped, is drift and returns data_status "indeterminate". A page above 1 with zero issuances is a genuine empty page and returns data_status "empty".

List PAGASA public PDF files from a pubfiles directory listing, newest first.

Reads the nginx directory index PAGASA publishes at pubfiles.pagasa.dost.gov.ph/tamss/weather// and returns each PDF's name, URL, last-modified time, and size. This tool returns file URLs only, never PDF bytes, so fetch a PDF yourself if you need its contents. Examples:

list_pagasa_advisory_files() latest weather advisories list_pagasa_advisory_files(kind="bulletin", limit=5) 5 newest cyclone bulletins list_pagasa_advisory_files(kind="stormsurge") storm surge folder, flagged stale

On failure: an unknown kind, or a limit outside 1 to 100, gives validation_error true and data_status "invalid_request". A 404, a body with no directory listing, zero parsed files, or a parser error on a 200 body gives data_status "indeterminate". A transport failure or a non-2xx status gives data_status "unavailable". All three carry files: [] and the real error in caveats.

Find a PSIC code by description keyword or by code prefix.

Matches a query of only digits against the PSIC code prefix. Matches any other query by whole-word text against the class description, case-insensitive. PSA publishes the full table (roughly 1,360 rows) on one page, so the first call fetches and caches it for 24 hours. Examples:

search_psic_codes("rice") every description with "rice" as a whole word search_psic_codes("0111") every code that starts with "0111" search_psic_codes("mining", limit=5) at most 5 matches

On failure: data_status is "invalid_request" for an empty, over-long, or non-printable query, or for a limit outside 1-100. A Cloudflare challenge in place of the table gives "unavailable". A missing, empty, or partial PSIC table gives "indeterminate". Neither failure is cached, and the real error sits in caveats.

Walk the COMELEC 2025 election results tree: region down to precinct.

Starts at the 20 regions when code is "0", the default. Pass a child's code from the response to go one level deeper. A barangay's children are its precincts, since the geography tree stops at the barangay level and precincts sit in a separate family. Examples:

browse_election_results() the 20 regions browse_election_results(code="R001000") provinces of Region I browse_election_results(code="2801000") barangays of Adams, Ilocos Norte browse_election_results(code="2801001") precincts of one barangay

On failure: a code that is not "0", a region code, or 7 digits gives validation_error true and data_status "invalid_request", with no request sent. A well-formed code the archive does not recognize gives the same shape after the lookup. A tree response whose rows all fail to parse gives data_status "indeterminate", never cached. A response with some bad rows returns the good rows, with a caveat naming the skipped count. A real outage gives upstream_error true and data_status "unavailable", with the real error in caveats.

One precinct's official vote tally from the COMELEC 2025 archive.

Give the 8-digit precinct code from browse_election_results. Returns every national and local contest counted at that precinct, with each candidate's vote count and share. Examples:

get_election_return("28010001") Adams, Ilocos Norte, precinct 0001

On failure: a code that is not 8 digits gives validation_error true and data_status "invalid_request", with no request sent. A code the archive does not recognize (a 403 body carrying its AccessDenied marker) gives the same shape. A body missing 'information', where 'national' or 'local' is not a list, or where a contest carries a non-list nested 'candidates' value, gives data_status "indeterminate" with upstream_error true. Any other outage, including a 403 with no AccessDenied marker, gives data_status "unavailable" with upstream_error true and the real error in caveats.