ph-civic-data-mcp

Overview Schema Source Related Servers Discussions Admin

Full PSGC hierarchy for a place

get_location_hierarchy

Read-onlyIdempotent

Retrieve the full administrative hierarchy (region, province, city/municipality, barangay) for a given Philippine Standard Geographic Code.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`psgc_code`	Yes	9-digit PSGC code (leading zeros optional).

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.4.0May 22, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Beyond the annotations (read-only, idempotent), the description explains validation before network calls, distinct failure modes for malformed codes, unknown well-formed codes, and mirror outages, plus which return fields distinguish them. This is substantial behavioral disclosure that annotations alone do not provide.

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 longer than average but each part earns its place: purpose, behavioral model, examples, and failure modes. The main purpose is front-loaded, and the examples illustrate edge cases clearly. Minor redundancy exists between the examples and the later failure explanation.

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 a single required parameter, rich annotations, and an output schema, the description covers everything needed to invoke the tool correctly: valid input, rejected input, unknown input, and outage behavior. An agent can predict results across all relevant cases.

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?

Even though the schema covers the single psgc_code parameter 100%, the description adds meaningful semantics: well-formedness checks, examples with real codes, and how different code classes map to different return fields. An agent gains practical understanding beyond the raw type/format.

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 first sentence states a specific verb and resource: 'Return the full chain region -> province -> city/municipality -> barangay for one PSGC code.' The output is precisely scoped, making it easy to distinguish this from location-adjacent siblings like resolve_ph_location or list_admin_units.

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: this is for a single PSGC code and produces a full hierarchical chain. It does not explicitly name alternative tools or exclusion conditions, but the usage context is strong enough that an agent can decide when this tool applies.

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

Deploy Server