ph-civic-data-mcp

Overview Schema Source Related Servers Discussions Admin

Philippine population statistics

get_population_stats

Read-onlyIdempotent

Retrieve Philippine population figures from official PSA census data, with options for region, city, or barangay via PSGC code, and support for historical census years.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Description
`year`	No	Census year. None picks the latest. A year PSA has no census for returns validation_error with available_vintages.
`region`	No	Region, province or highly urbanized city as PSA labels it, such as "NCR", "Region VII", "CAR", "BARMM", "Leyte", "City of Manila". None returns the national total.
`psgc_code`	No	A 9- or 10-digit PSGC code from resolve_ph_location. Reaches cities, municipalities and barangays (2024 Census only). Not combined with region.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.8.0Sep 7, 2026

addedInput schema / properties / psgc_code

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "A 9- or 10-digit PSGC code from resolve_ph_location.\nReaches cities, municipalities and barangays (2024 Census only).\nNot combined with region."
+}

changedInput schema / properties / region / description

Previous value: -"e.g. \"NCR\", \"Region VII\", \"Cordillera Administrative Region\".\n    None returns national total."New value: +"Region, province or highly urbanized city as PSA labels it,\nsuch as \"NCR\", \"Region VII\", \"CAR\", \"BARMM\", \"Leyte\",\n\"City of Manila\". None returns the national total."

changedInput schema / properties / year / description

Previous value: -"Ignored — latest data is 2020 Census; field kept for API stability."New value: +"Census year. None picks the latest. A year PSA has no census\nfor returns validation_error with available_vintages."

Addedv0.4.0May 22, 2026
Removedv1.0.4Apr 20, 2026
Addedv1.0.2Apr 19, 2026

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description is transparent about output behavior on success and failure, including population being None, caveats carrying error text, and failures never being cached. The readOnlyHint and idempotentHint annotations align with the described behavior, and no side effects are hidden.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well organized with a concise overview, a set of illustrative examples, and a separate failure-mode section. While detailed, the information is directly relevant and avoids unnecessary fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description provides enough context for an agent to know when to call this tool, how to choose parameters, what output fields to expect, and how to interpret error states. Combined with the fully described input schema, it is self-sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All three optional parameters are described in the schema with clear semantics, including examples, default behavior, constraints such as not combining psgc_code with region, and validation_error outcomes for unknown values. The description complements the schema rather than duplicating it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns Philippine population statistics from the PSA Census, including defaulting to the latest census year and supporting national, regional, provincial, city, municipal, and barangay lookups. It also gives concrete examples that illustrate the intended use.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains default behavior, available years, parameter combinations, and the prerequisite relationship to resolve_ph_location for PSGC codes. It also enumerates failure modes with corresponding data_status values, making expected behavior explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server