psgc-mcp

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

No annotations provided, so description must carry full burden. It discloses output ordering and null handling for missing codes, but does not explicitly state read-only nature or potential side effects.

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

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

Two concise sentences with no fluff. Each sentence adds unique value: purpose and input format, then output behavior.

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

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

Given no output schema, description adequately explains output behavior. With sibling tools providing context, the description is complete enough for an agent to use correctly.

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

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

Schema has 100% coverage with pattern and length constraints. Description adds critical meaning: array size limit (1-50), same-order output, and null for missing codes, which is not in schema.

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

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

The description clearly states the action ('Look up multiple PSGC entities') and the resource ('PSGC entities'). It distinguishes from sibling tools like lookup (single entity) by specifying batch functionality.

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

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

The description mentions passing an array of codes with a max of 50, which implies usage context. However, it lacks explicit when-not or alternative tool guidance, though siblings provide contrast.

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

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

Given no annotations, the description carries the full burden. It clearly discloses the upward traversal behavior and the hierarchical components returned. However, it omits error handling for invalid codes or authentication requirements, which are minor for a read-like tool.

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

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

Two sentences, no unnecessary words. Front-loaded with the core action and immediate output clarification.

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

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

Without an output schema, the description adequately explains the return value. Sibling tools are listed but not differentiated in description; however, the tool is simple with one parameter and the explanation suffices for its complexity.

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

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

The input schema already documents the single parameter 'code' with a description of the format (10-digit PSGC code). The tool description does not add additional semantics beyond interpreting that code as a PSGC entity, so baseline 3 applies with high schema coverage.

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

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

Description clearly states the tool gets the full administrative hierarchy for a PSGC entity, specifying the return chain (parent city/municipality, province, region). This distinguishes it from siblings like lookup (single entity) and list_children (downward traversal).

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

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

The description implies usage for retrieving upward hierarchy but does not explicitly state when to use versus alternatives like list_children (downward) or lookup (single details). No when-not-to-use guidance is provided.

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

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

No annotations exist, so the description carries full burden. It discloses that Barangay is excluded (critical behavioral constraint) and that results are paginated with a default limit of 50. However, it does not mention error handling, sorting, or response format, which are minor gaps.

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

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

The description is concise: two sentences plus a note on pagination. It prioritizes key information—purpose, exclusion, alternatives, and pagination—without redundancy. Every sentence serves a distinct purpose.

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

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

Given the tool's 3 parameters, no output schema, and siblings, the description is fairly complete. It explains the core behavior, exclusion, and pagination. It could be improved by mentioning the output format or fields, but this is not critical for a listing tool.

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

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

The input schema has 100% coverage with descriptions for all three parameters (level, limit, offset). The description adds value by clarifying the 'level' parameter's exclusion of Barangay and providing pagination defaults (limit 50), going beyond the schema's enum and range descriptions.

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

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

The description clearly states 'List all PSGC entities of a given geographic level' with a specific verb and resource. It distinguishes from siblings by explicitly excluding Barangay and directing users to 'search' or 'list_children' for that level.

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

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

The description provides explicit guidance on when to use this tool (for geographic levels other than Barangay), when not to use it (Barangay), and offers specific alternatives ('search' or 'list_children'). It also mentions pagination with a default limit of 50.

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

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

With no annotations, the description carries full burden and discloses pagination (default limit 50, max 200), optional level filtering, and the specific parent-child hierarchy. It could mention return format or error handling but is otherwise transparent for a read operation.

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

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

Extremely concise: two sentences that front-load the purpose, then hierarchy examples, then optional filtering and pagination. No wasted words.

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

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

For a list tool with no output schema, the description could specify the shape of returned items (e.g., each child includes code, name, level). Otherwise, it covers usage scenarios, filtering, and pagination well.

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

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

Schema coverage is 100% with good parameter descriptions. The description adds value by explaining the hierarchical context for the 'code' parameter and the default/max for 'limit', but does not significantly enhance beyond schema.

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

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

The description explicitly states 'List the direct children of a PSGC entity' and provides clear examples of the hierarchy for different parent types, distinguishing it from sibling tools like get_hierarchy or list_by_type.

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

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

The description clearly implies when to use the tool (when needing direct children of a PSGC entity) but does not explicitly mention when not to use it or alternatives, though the sibling tool names provide context.

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

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

No annotations are provided, so the description carries full burden. It states the return includes name, level, parent, population, and classification, which is helpful but lacks disclosure of any side effects, authentication needs, or rate limits. For a simple read-only lookup, this is adequate but not rich.

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

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

Two sentences, 20 words, front-loaded with the main action. No unnecessary phrasing; every sentence earns its place.

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

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

Given the simple tool with one parameter and no output schema, the description covers the essential aspects: purpose, input method, and return contents. It could mention error behavior or exact structure, but is mostly complete.

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

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

The schema already fully describes the single parameter (code) with pattern and description. The tool description adds no additional meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the action (look up), resource (Philippine geographic entity), and method (by 10-digit PSGC code). It specifies what the return includes, distinguishing it from siblings like batch_lookup or search.

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

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

The description provides no guidance on when to use this tool versus alternatives such as batch_lookup, search, or list_by_type. No explicit when or when-not criteria.

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

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

Without annotations, the description partially covers behavior (sorts by population, requires parent_code for barangays) but omits details like read-only nature, rate limits, or error handling, leaving room for ambiguity.

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

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

Three concise sentences convey all essential information without redundancy, front-loading the primary purpose and key constraint efficiently.

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

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

Given the tool's complexity (7 params, no output schema), the description covers core functionality and a key behavioral rule, but lacks details on return fields or data format, which would improve completeness.

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

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

The schema already describes all parameters (100% coverage), so the description adds only minor value, notably the parent_code requirement for barangays. This meets the baseline expectation for parameter semantics.

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

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

The description clearly states the verb 'Query', the resource 'PSGC entities', and the criterion 'by population range', effectively distinguishing this tool from siblings like 'list_by_type' or 'lookup' which serve different purposes.

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

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

The description provides clear context for when to use the tool (e.g., finding largest/smallest entities) and gives a specific constraint ('Barangay queries require a parent_code'), but does not explicitly list alternatives or when not to use it.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully communicates partial matching support and filtering behavior, but omits operational details such as result sorting, read-only safety, or error handling (e.g., empty results).

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

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

Four compact sentences with zero redundancy. Front-loaded with core purpose, followed by behavioral features, filtering examples, and a domain-specific search tip. Every sentence delivers actionable information.

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

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

Given the simple parameter structure (4 primitives, no nesting) and 100% schema coverage, the description is substantially complete. It compensates for the missing output schema and annotations with domain context and usage examples, though it could briefly characterize the return value (list of entities).

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

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

Despite 100% schema description coverage (baseline 3), the description adds significant semantic value by mapping abstract enum values to concrete examples ('cities, provinces' for the level parameter) and explaining the relationship between partial matching and the strict parameter.

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

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

The description clearly states the verb (Search), resource (Philippine geographic entities), and method (by name). It establishes the domain scope effectively, though it does not explicitly contrast its functionality with sibling tools like lookup or list_by_type.

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

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

Provides explicit usage guidance including when to use the level filter ('narrow results') and domain-specific best practices ('For barangay searches, include the parent city/municipality name'). While it lacks explicit 'when not to use' comparisons with siblings, the contextual tips provide clear guidance on effective usage.

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