Skip to main content
Glama
xmpuspus

ph-civic-data-mcp

by xmpuspus

Browse the COMELEC 2025 election results tree

browse_election_results
Read-onlyIdempotent

Browse Philippine election results by administrative code, from regions down to provinces, barangays, and precincts.

Instructions

Walk the COMELEC 2025 election results tree: region down to precinct.

Starts at the 20 regions when code is "0", the default. Pass a child's code from the response to go one level deeper. A barangay's children are its precincts, since the geography tree stops at the barangay level and precincts sit in a separate family. Examples:

browse_election_results() the 20 regions browse_election_results(code="R001000") provinces of Region I browse_election_results(code="2801000") barangays of Adams, Ilocos Norte browse_election_results(code="2801001") precincts of one barangay

On failure: a code that is not "0", a region code, or 7 digits gives validation_error true and data_status "invalid_request", with no request sent. A well-formed code the archive does not recognize gives the same shape after the lookup. A tree response whose rows all fail to parse gives data_status "indeterminate", never cached. A response with some bad rows returns the good rows, with a caveat naming the skipped count. A real outage gives upstream_error true and data_status "unavailable", with the real error in caveats.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
codeNo"0" for the region list, a region code such as "R001000", or a 7-digit province, city, or barangay code from a previous call.0

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.8.0

TDQS

A4.9/5.0
Behavior5/5

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

The description is exceptionally transparent about behavior: it details validation errors, 'indeterminate' status with never-cached responses, partial failures with caveats, and upstream errors with real error messages. This goes beyond the annotations (readOnlyHint, idempotentHint) and adds substantial context about system behavior.

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 typical but well-structured: opening sentence, examples, and then a clear breakdown of failure modes. While it could be trimmed slightly, the density of useful information justifies the length, and it remains readable.

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 presence of an output schema and annotations, the description covers all necessary context: navigation pattern, error handling, caching behavior, and partial-failure semantics. It leaves no gaps for an agent to guess about how to invoke or interpret results.

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?

The single parameter 'code' is fully documented in the schema (100% coverage) and further explained in the description with examples. The semantics of '0', region codes, and 7-digit codes are explicit, leaving no ambiguity about what values to pass.

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: walking the election results tree from regions down to precincts. It uses specific verbs like 'Walk' and 'go one level deeper', and distinguishes it from other data-browsing tools by focusing on the hierarchical COMELEC 2025 results structure.

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?

Provides explicit usage instructions: start with code '0' for regions, use returned codes to drill down, and includes concrete examples for each level. It also explains what happens with invalid input and partial failures, giving clear guidance on when and how to use the tool.

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