ph-civic-data-mcp

Overview Schema Source Related Servers Discussions Admin

List Philippine administrative units

list_admin_units

Read-onlyIdempotent

Retrieve Philippine administrative units by parent code or level, from top-level regions to barangays, with pagination support.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Description
`level`	No	Filter children by level (region\|province\|city\|municipality\|district\|barangay).
`limit`	No	Max units to return (default 50, capped at 500).
`offset`	No	Skip this many matching units before returning results. Page past 500 children (for example, Manila has 897 barangays) by calling again with offset=500.
`parent_code`	No	Parent PSGC code. None returns the regions list.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.8.0Sep 7, 2026

changedInput schema / properties / offset / description

Previous value: -"Skip this many matching units before returning results —\n    page past 500 children (e.g. Manila has 897 barangays) by\n    calling again with offset=500."New value: +"Skip this many matching units before returning results.\n    Page past 500 children (for example, Manila has 897\n    barangays) by calling again with offset=500."

Changed4 schema fields changedv0.5.0Jun 17, 2026

addedInput schema / properties / offset

Added value: +{
+  "default": 0,
+  "description": "Skip this many matching units before returning results —\n    page past 500 children (e.g. Manila has 897 barangays) by\n    calling again with offset=500.",
+  "type": "integer"
+}

addedOutput schema / properties / result / anyOf

Added value: +[
+  {
+    "items": {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "additionalProperties": true,
+    "type": "object"
+  }
+]

removedOutput schema / properties / result / items

Removed value: -{
-  "additionalProperties": true,
-  "type": "object"
-}

removedOutput schema / properties / result / type
```
Removed value: -"array"
```

Addedv0.4.0May 22, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Beyond the readOnly/idempotent annotations, the description explicitly explains malformed inputs return an empty list rather than a validation error, and that only an upstream API outage produces a failure envelope. This goes well beyond the annotations in setting caller expectations.

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

Conciseness4/5

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

The description is well-structured with examples and clear behavior notes. It is slightly repetitive around malformed arguments returning empty results, but overall every sentence serves a purpose and the layout aids readability.

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?

Given the tool has optional parameters, an output schema, and no prerequisites, the description covers all necessary caller context: pagination, empty-result behavior, and error semantics. It does not need to describe return fields because the output schema exists.

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

Parameters4/5

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

The input schema already covers all parameters with useful descriptions, and the tool description reinforces this with examples, offset pagination guidance, and the parent_code=None region-list behavior. It adds helpful context without being redundant with the schema.

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's purpose with a specific verb ('Browse'/'List') and resource ('children of a PSGC node' or 'top-level regions'). The examples further distinguish it from related location tools by showing concrete calls such as list_admin_units(parent_code="072200000").

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

Usage Guidelines4/5

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

The description gives clear context for when to invoke the tool: top-level regions without parent_code, children with parent_code, and optional level filtering. It does not explicitly compare against sibling tools like get_location_hierarchy, but the examples and parameter semantics sufficiently imply the intended usage.

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

Deploy Server