Skip to main content
Glama

Vietnam Address Converter (2025 reform)

Find administrative units by name

find_units
Read-onlyIdempotent

Search Vietnamese administrative units by name or code, ignoring case and diacritics. scope "new" (default) searches the post-reform units (34 provinces, 3,321 communes); scope "old" searches units as of 30 June 2025 (63 provinces, districts, communes). Use to check spelling, get a code, or see every place with the same name before converting. Returns code, full name, level, match quality (code, exact, partial) and parent district/province. Examples: {"query":"Bến Nghé","scope":"old"}; {"query":"thu duc"}; {"query":"Tân Phú","scope":"old","level":"ward","province":"79","limit":20}.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "find_units"
  }
}

Input Schema

NameRequiredDescriptionDefault
levelNoRestrict to one level. "district" exists only with scope "old".
limitNoMaximum results, 1-50, default 10.
queryYesUnit name or code to look up, e.g. "Bến Nghé", "ben nghe", "Thủ Đức", "26734". Case and diacritics are ignored.
scopeNo"new" (default): units after the 2025 reform (34 provinces, 3,321 communes). "old": units as of 30 June 2025 (63 provinces, districts, 10,035 communes).
provinceNoOptional province filter in the same scope: code or name.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already cover read-only, idempotent, closed-world behavior, so the description focuses on what annotations cannot say: the semantic difference between scopes, the row counts in each, and the returned fields including match quality (code/exact/partial) and parent district/province. It omits edge behavior such as zero-result responses or how partial matches are ranked.

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?

Front-loaded with purpose, then scope semantics, then use cases, then return shape, then examples — a logical progression with no filler sentences. The example block is somewhat long for the marginal information it adds, but each example demonstrates a distinct parameter combination.

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?

For a read-only lookup with no output schema, the description covers the scope model, the returned fields, the match-quality notion, and query behavior, which is everything an agent needs to call it and interpret results. No prerequisite or permission information is missing for a public reference-data lookup.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents every parameter including enums, limits, and the district-only-in-old-scope constraint. The description's added value is mostly illustrative examples showing parameter combinations (level, province, limit together), which reinforces but does not extend the schema's semantics; baseline 3 applies.

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?

States a specific verb and resource ("Search Vietnamese administrative units by name or code") plus the key matching property (case- and diacritic-insensitive). It also bounds the domain with the scope split (34 provinces/3,321 communes vs. 63 provinces/districts) and implicitly separates itself from convert_old_to_new via "before converting".

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?

Gives explicit when-to-use triggers: check spelling, obtain a code, or enumerate homonyms before converting. It does not name a specific sibling to prefer when the goal is already a conversion, and gives no when-not-to-use case, so it stops short of a 5.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.