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.
+29 more tools listed on main page