Octagon Deep Research MCP vs Ph Civic Data MCP

get_latest_earthquakes

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_earthquake_bulletin

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_volcano_status

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_weather_forecast

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_typhoons

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_weather_alerts

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_procurement

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.

get_procurement_summary

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.

resolve_ph_location

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.

list_admin_units

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.

get_location_hierarchy

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.