Search GeoNames places, walk admin hierarchies, reverse geocode, get postal codes and country info.
Scored across 8 tools
Most tools target distinct resources or actions, but geonames_get_place and geonames_get_hierarchy overlap in returning admin chain information, which could cause misselection. Descriptions are detailed and help, but no explicit guidance on when to use one over the other.
All tools share the same geonames_ prefix and use snake_case with a clear verb_noun pattern (find, get, list, reverse_geocode, search). The naming is consistent and predictable throughout.
Eight tools cover the core GeoNames operations without redundancy. The set is well-scoped for the domain, with each tool earning its place.
The surface covers most core GeoNames functions: search, place details, hierarchy, children, reverse geocoding, postal codes, country facts, and reference lists. A minor gap is the lack of a direct way to list all features of a given type (e.g., mountains, lakes) in a region without a name query, though admin divisions are covered via geonames_get_children.
Look up postal codes in the GeoNames postal database (122 countries): mode code resolves a postal code to its place, admin names, and centroid; mode place_name finds postal codes for a place name; both page with offset, up to 5000; mode nearby lists postal codes within radiusKm (up to 30 km) of a coordinate, nearest first. Ireland returns only Eircode routing keys and Malta only the letter prefix; the United Kingdom (GB), Canada, and the Netherlands hold both full codes and their outward or district prefixes. Check coverage with geonames_list_reference topic postal_countries. Costs 1 GeoNames credit (2 for nearby); a code or place_name lookup with countries that returns nothing at offset 0 also reads the postal coverage list, 1 more credit unless that list is cached. Repeat lookups are cached.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude in decimal degrees, -90 to 90. Required in mode nearby. | |
| lng | No | Longitude in decimal degrees, -180 to 180. Required in mode nearby. | |
| mode | Yes | What to look up. code: the place for postalCode (required). place_name: the postal codes of placeName (required). nearby: postal codes around lat and lng (both required; countries not accepted). | |
| limit | No | Maximum entries to return, 1 to 1,000. This tool returns at most 100 per call: a larger limit is held to 100, and the notice says so when more entries remain. Default 10. | |
| offset | No | Postal codes to skip before the first one returned, 0 to 5000. Default 0. Modes code and place_name only; pass the nextOffset of the previous page to read the next one. | |
| radiusKm | No | Search radius in kilometres for mode nearby, above 0 and at most 30 (GeoNames' free-tier limit). Default 10. | |
| countries | No | Countries to look up postal codes in: ISO 3166-1 codes, up to 10, as a list: alpha-2 (US, GB, DE), alpha-3 (USA, GBR, DEU), or three-digit numeric (840, 826, 276), each sent to GeoNames as alpha-2. UK is accepted for GB and FL for LI. A listed country also returns the territories GeoNames files under it (GB also returns IM, JE, and GG), each postal code's countryCode naming its own country. Modes code and place_name only. | |
| placeName | No | Place name to find postal codes for, up to 100 characters. GeoNames matches it against place, admin, and country names. Required in mode place_name; in mode code it narrows the match; not used in mode nearby. | |
| postalCode | No | Postal code to resolve, such as 98101, SW1A 1AA, or K1A 0A1: capital letters, digits, spaces, and hyphens, up to 12 characters. Required in mode code; in mode place_name it narrows the match; not used in mode nearby. | |
| geonamesUsername | No | Your own GeoNames username, so the call spends that account's free credits instead of the server's. Omit it to use the server's account. The account needs free web services enabled on its geonames.org account page. |
| Name | Required | Description |
|---|---|---|
| cap | No | The limit applied: limit as given, or 100 when it asked for more. |
| mode | No | The lookup mode that ran. |
| error | No | Present when the call failed. Absent on success. |
| shown | No | Postal codes returned on this page. |
| notice | No | Guidance: why nothing matched or nothing lies at offset, or how to reach the postal codes past this page (naming a limit held to 100), and which postal codes on the page lie in countries that countries does not list. |
| truncated | No | True when more postal codes remain past this page; in mode nearby, more lie within radiusKm. |
| nextOffset | No | Offset of the next page in modes code and place_name; absent on the last page, in mode nearby, and once offset is 5000. Capped at 5000, the last offset GeoNames' free service accepts, so that page can repeat rows of this one. |
| postalCodes | No | Matching postal codes on this page; nearest first in mode nearby. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent/openWorld annotations it discloses credit costs (1 credit, 2 for nearby, plus an extra credit when an empty code/place_name result at offset 0 reads the coverage list), caching of repeat lookups, the hard 100-per-call return cap despite limit allowing 1,000, and country-specific data quirks (Ireland, Malta, GB/CA/NL prefixes). This is exactly the operational context annotations cannot carry.
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 single dense paragraph is front-loaded with purpose before mode and cost detail, and almost every clause carries information. It is long, however, and would scan faster with the three modes and the credit model broken into separate lines rather than one continuous block.
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?
With an output schema present, return values need no explanation, and the description still covers all three modes, pagination limits, radius limits, credit accounting, caching, and the coverage-check sibling. An agent has everything needed for a 10-parameter tool with a required enum discriminator.
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%, so the baseline is 3, and each parameter already documents its mode-specific requirement. The description adds value on top by describing mode semantics as a whole (code/place_name page with offset up to 5000; nearby returns nearest-first) and tying credit cost to the selected mode.
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 opens with a specific verb and resource: 'Look up postal codes in the GeoNames postal database (122 countries)', then enumerates the three distinct lookup modes. An agent can distinguish this from siblings like search_places or reverse_geocode without opening any schema.
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?
Mode selection is spelled out (resolve a code, find codes by place name, list codes near a coordinate), and it routes the agent to geonames_list_reference with topic postal_countries to check coverage. It stops short of explicit exclusions, e.g. it never says to prefer geonames_reverse_geocode over mode nearby when the goal is a place rather than postal codes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the direct children of a GeoNames feature — Earth's continents, a continent's countries, a country's first-level divisions, a state's counties, a city's sections — in the administrative tree, or in the tourism tree (islands, coasts, and their municipalities; almost all in Spain) or the dependency tree (a country's dependent territories). Start from a country's geonameId (geonames_get_countries) or any admin division's. Children are mostly admin divisions (class A) and populated places (class P); continents and coasts are class L and islands class T. For other feature types inside a place, use geonames_search_places with a boundingBox. GeoNames answers a tourism or dependency request with the administrative children when the feature has no such tree, so the tool compares the two lists and sets sameAsAdministrative when they match, keeping the rows (a real tree can match too). The full child list is fetched once (1 GeoNames credit) and cached, so paging and nameContains filtering are free; a tourism or dependency call also reads the administrative list for the comparison, 1 more credit unless it is cached.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum entries to return, 1 to 1,000. This tool returns at most 500 per call: a larger limit is held to 500, and the notice says so when more entries remain. Default 100. | |
| offset | No | Entries to skip before the first one returned, for paging. Default 0. | |
| geonameId | Yes | GeoNames id of the parent feature as a digit string up to 2147483647, such as "6252001" (United States): the geonameId the other geonames tools return, sent as a string. | |
| hierarchy | No | Which tree to descend: administrative (the default: continents (class L), countries, admin divisions, populated places), tourism (islands (class T), coasts (class L), and their municipalities; almost all in Spain), or dependency (a country's dependent territories). For a feature with no tourism or dependency tree, GeoNames answers with its administrative children, which sameAsAdministrative flags; the comparison reads the administrative list, 1 more credit unless it is cached. | administrative |
| nameContains | No | Keep only children whose name or toponym name contains every word of this text as a substring (kansas also matches Arkansas), ignoring case, accents, and punctuation. | |
| geonamesUsername | No | Your own GeoNames username, so the call spends that account's free credits instead of the server's. Omit it to use the server's account. The account needs free web services enabled on its geonames.org account page. |
| Name | Required | Description |
|---|---|---|
| cap | No | The limit applied: limit as given, or 500 when it asked for more. |
| error | No | Present when the call failed. Absent on success. |
| found | No | False when GeoNames has no feature with this geonameId. |
| shown | No | Children returned on this page. |
| notice | No | Guidance when a tourism or dependency answer is the administrative children, there are no children, nothing matched, the offset is past the end, more pages remain (naming a limit held to 500), or GeoNames holds more children than it returns. |
| children | No | Children on this page, in GeoNames' order; empty when found is false or the feature has none. |
| guidance | No | What to do next; present only when found is false. |
| hierarchy | No | The tree that was descended. |
| truncated | No | True when more children remain past this page. |
| nextOffset | No | Offset of the next page; absent on the last page. |
| totalCount | No | Children matching nameContains, before paging. |
| parentGeonameId | No | The geonameId whose children were requested. |
| sameAsAdministrative | No | Tourism and dependency trees only, when the feature has children there: true when they are exactly its administrative children (same geonameIds and total). GeoNames answers with the administrative children when a feature has no such tree, so true most likely means it has none; a real tree can also match. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/openWorld/idempotent, and the description adds substantial behavior beyond them: credit costing (1 GeoNames credit per full fetch, caching making paging/filtering free), the extra credit read for tourism/dependency comparisons, and the sameAsAdministrative fallback semantics when GeoNames answers a non-administrative request with admin children. This is exactly the kind of context annotations cannot carry.
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?
Front-loaded with purpose and scope, and each sentence carries real information (scope, alternative, fallback, credits). It is dense and a few clauses (e.g. the sameAsAdministrative parenthetical) are convoluted, slightly taxing readability for the amount packed into one paragraph.
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?
With an output schema present, a 100%-covered input schema, and annotations covering the safety profile, the description supplies everything else an agent needs: enumeration of trees, class distinctions (A/P/L/T), entry points, the sibling alternative, and the credit/caching model. Nothing material is missing.
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%, so the baseline is 3. The description adds meaning beyond the schema by explaining the tourism/dependency fallback for the hierarchy enum and the caching consequences for limit/offset/nameContains, though it does not deepen the geonameId or username semantics the schema already covers well.
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?
States a specific verb+resource (list direct children of a GeoNames feature) and enumerates the exact scope across three trees (administrative, tourism, dependency). It explicitly differentiates from siblings by naming geonames_search_places for other feature types inside a place and geonames_get_countries as an entry point.
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?
Gives concrete when-to-use guidance (start from a country's or any admin division's geonameId) and an explicit alternative with its condition: use geonames_search_places with a boundingBox for other feature types inside a place. The hierarchy parameter's fallback behavior is also framed as guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get GeoNames country facts — ISO alpha-2, alpha-3, and numeric codes, FIPS code, geonameId, capital, population, area in km², continent, languages, currency, postal-code format, and mainland bounding box — for the countries named, a continent, or all 250. The geonameId anchors geonames_get_children (a country's first-level divisions) and geonames_get_hierarchy. The full table is fetched once a day (1 GeoNames credit) and cached.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum entries to return, 1 to 1,000. This tool returns at most 250 per call: a larger limit is held to 250, and the notice says so when more entries remain. Default 50. | |
| offset | No | Entries to skip before the first one returned, for paging. Default 0. | |
| continent | No | Keep only countries on this continent: AF Africa, AN Antarctica, AS Asia, EU Europe, NA North America, OC Oceania, SA South America. | |
| countries | No | Countries to return by ISO 3166-1 code: alpha-2 (US), alpha-3 (USA), or three-digit numeric (840), up to 250, as a list. UK is accepted for GB and FL for LI. Match country names with nameContains instead. | |
| nameContains | No | Keep only countries whose English name contains every word of this text as a substring (niger also matches Nigeria), ignoring case, accents, and punctuation. | |
| geonamesUsername | No | Your own GeoNames username, spent only when the country table is not already cached, so the call uses that account's credit instead of the server's. The account needs free web services enabled on its geonames.org account page. |
| Name | Required | Description |
|---|---|---|
| cap | No | The limit applied: limit as given, or 250 when it asked for more. |
| error | No | Present when the call failed. Absent on success. |
| shown | No | Countries returned on this page. |
| notice | No | Guidance when nothing matched, the offset is past the end, or more pages remain (naming a limit held to 250). |
| notFound | No | Requested codes that match no GeoNames country; empty when every code matched. |
| countries | No | Countries on this page, in GeoNames order (by alpha-2 code). |
| truncated | No | True when more countries remain past this page. |
| nextOffset | No | Offset of the next page; absent on the last page. |
| totalCount | No | Countries matching the filters, before paging. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, open-world, so the safety profile is done. The description adds genuinely new operational context: the full table is fetched once a day for 1 GeoNames credit and cached, implying later calls are cheap and the data is at most a day stale, that is exactly the kind of behavior an agent cannot infer from annotations.
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, front-loaded with the verb and resource, then a field list that is long but earns its place by telling the agent what comes back. No filler or marketing language.
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?
With an output schema present, return values need no elaboration, and the description still covers selection modes, the credit/caching model, and the follow-up tools that consume geonameId. Nothing an agent needs to call this correctly is missing.
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 description coverage is 100%, so the schema already documents every parameter including the 250-entry cap, continent enum, and username/credit semantics. The description restates the selection modes and the 250 cap but adds no syntax or format detail beyond the schema, so the baseline 3 applies.
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?
States a specific verb and resource ('Get GeoNames country facts') and enumerates the returned fields (ISO codes, capital, population, area, continent, bounding box). It also names the three selection modes — named countries, a continent, or all 250 — so an agent can distinguish it from the search/reference siblings at a glance.
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?
Explains the input modes and tells the agent that the returned geonameId anchors geonames_get_children and geonames_get_hierarchy, which is real routing value. However, it never states when NOT to use it (e.g., use geonames_search_places or geonames_get_place for city-level lookups), so guidance is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the parent chain of a GeoNames feature, ordered from Earth and its continent through the country and admin divisions down to the feature itself, each with its geonameId, feature code, and coordinates. Use it to find which country, state, and county contain a place, or to fill an admin path for a geonameId. An unknown id returns found: false. Costs 1 GeoNames credit; cached.
| Name | Required | Description | Default |
|---|---|---|---|
| geonameId | Yes | GeoNames feature id as a digit string up to 2147483647, such as "5809844" (Seattle): the geonameId the other geonames tools return, sent as a string. | |
| geonamesUsername | No | Your own GeoNames username, so the call spends that account's free credits instead of the server's. Omit it to use the server's account. The account needs free web services enabled on its geonames.org account page. |
| Name | Required | Description |
|---|---|---|
| chain | No | Administrative ancestors, Earth first and the requested feature last; empty when found is false. Levels a feature does not sit under are skipped. |
| error | No | Present when the call failed. Absent on success. |
| found | No | False when GeoNames has no feature with this geonameId. |
| guidance | No | What to do next; present only when found is false. |
| geonameId | No | The geonameId that was requested. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes beyond the annotations (readOnly/idempotent/openWorld) by disclosing cost ('1 GeoNames credit'), caching, and the failure mode ('An unknown id returns found: false'). Those are exactly the behavioral traits annotations cannot express.
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 tightly packed sentences: what is returned, when to use it, and the edge case plus cost. Front-loaded with the return shape and no filler.
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 read-only lookup with a full output schema, the description covers scope, ordering, intended uses, credit cost, caching, and the not-found behavior. Nothing an agent needs to invoke it correctly is missing.
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 description coverage is 100%, so both parameters (geonameId, geonamesUsername) are already fully documented in the schema. The description only references 'a geonameId' without adding format or sourcing context beyond what the schema provides, so baseline 3 applies.
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?
States a specific verb and resource ('Return the parent chain of a GeoNames feature') and defines the exact scope and ordering (Earth → continent → country → admin divisions → feature). This clearly separates it from siblings like geonames_get_children (descendants) and geonames_get_place (single-feature detail).
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?
Gives concrete use cases: finding which country/state/county contain a place, or filling an admin path for a geonameId. It does not explicitly name an alternative or a when-not-to-use condition (e.g. use get_children for descendants), 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.
Fetch the full GeoNames record for one geonameId: coordinates, feature type, the admin chain with each level's code, name, and geonameId, timezone, bounding box, recorded and DEM elevation, population, Wikipedia URL, names in other languages, postal codes, and external identifiers (IATA, ICAO, UN/LOCODE, Wikidata). Take the geonameId from geonames_search_places, geonames_reverse_geocode, geonames_get_children, or geonames_get_countries. An unknown id returns found: false. Costs 1 GeoNames credit; repeat lookups are cached.
| Name | Required | Description | Default |
|---|---|---|---|
| geonameId | Yes | GeoNames feature id as a digit string up to 2147483647, such as "5809844" (Seattle): the geonameId the other geonames tools return, sent as a string. | |
| nameLanguages | No | Keep only alternate names in these languages, up to 20, as a list. A tag also matches its regional forms: zh keeps names GeoNames tags zh, zh-CN, or zh-TW. Omit to return every alternate name, including those under GeoNames pseudo-language tags (abbr, phon, piny, fr_1793), which this filter cannot select. Postal codes, links, and identifiers are unaffected. | |
| geonamesUsername | No | Your own GeoNames username, so the call spends that account's free credits instead of the server's. Omit it to use the server's account. The account needs free web services enabled on its geonames.org account page. |
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| found | No | False when GeoNames has no feature with this geonameId. |
| place | No | The full record; absent when found is false. |
| guidance | No | What to do next; present only when found is false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/openWorld, so the description's job is incremental. It adds real operational context: a 1-credit cost, caching of repeat lookups, and the behavior of an unknown id ('returns found: false'). Missing rate-limit/quota detail, but the additions go meaningfully beyond the annotations.
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?
Front-loaded with the purpose, then a dense but scannable enumeration of returned fields and a single routing sentence. The field enumeration partially duplicates the existing output schema, which is mild padding rather than wasted prose.
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?
With an output schema, rich annotations, and 100% parameter description coverage, the description only needs to supply provenance, cost, and edge-case behavior — and it supplies all three. Nothing an agent needs to invoke this tool correctly is missing.
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 description coverage is 100%, so the baseline is 3. The description adds the provenance of geonameId and the unknown-id outcome, but says nothing about nameLanguages filtering or the geonamesUsername account switch beyond what the schema already documents.
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?
States a specific verb and resource ('Fetch the full GeoNames record for one geonameId') and then enumerates the record's contents, so an agent immediately knows this is a detail lookup rather than a search. It is clearly separable from siblings like geonames_search_places and geonames_reverse_geocode.
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?
Explicitly routes the agent to the right producers of the id ('Take the geonameId from geonames_search_places, geonames_reverse_geocode, geonames_get_children, or geonames_get_countries'), which is strong usage guidance. It stops short of an explicit when-not-use / alternative-for-retrieval statement (e.g. vs geonames_get_hierarchy), so it falls just short of the top band.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Decode GeoNames vocabulary used by the other tools: topic feature_classes lists the 9 one-letter classes; topic feature_codes lists the 684 feature codes with names and definitions, filterable by class and text; topic postal_countries lists the 122 countries with postal-code data and each one's code range and count. feature_classes and feature_codes are bundled and spend no credits; postal_countries costs 1 GeoNames credit a day (cached).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum entries to return, 1 to 1,000. This tool returns at most 700 per call: a larger limit is held to 700, and the notice says so when more entries remain. Default 100. | |
| topic | Yes | Vocabulary to list: feature_classes (the 9 one-letter classes), feature_codes (the 684 codes), or postal_countries (countries with postal-code data). | |
| offset | No | Entries to skip before the first one returned, for paging. Default 0. | |
| featureClass | No | Topic feature_codes only: keep the codes of this one-letter class (A, H, L, P, R, S, T, U, V). | |
| nameContains | No | Keep only entries whose code, name, or description contains every word of this text as a substring (port also matches airport), ignoring case, accents, and punctuation. | |
| geonamesUsername | No | Topic postal_countries only, and only when the list is not already cached: your own GeoNames username, so the call spends that account's credit instead of the server's. The account needs free web services enabled on its geonames.org account page. |
| Name | Required | Description |
|---|---|---|
| cap | No | The limit applied: limit as given, or 700 when it asked for more. |
| error | No | Present when the call failed. Absent on success. |
| shown | No | Entries returned on this page. |
| topic | No | The topic listed. |
| notice | No | Guidance when nothing matched, the offset is past the end, or more pages remain (naming a limit held to 700). |
| entries | No | Entries on this page, in GeoNames order. |
| truncated | No | True when more entries remain past this page. |
| nextOffset | No | Offset of the next page; absent on the last page. |
| totalCount | No | Entries matching the topic and filters, before paging. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only, idempotent, open-world profile, yet the description adds genuinely non-obvious behavior: two topics spend no credits, postal_countries costs one credit per day, and results are cached. It also implies the geonamesUsername path avoids server credit spend. Missing is any note on truncation/paging limits, which live only in the schema.
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?
One densely packed sentence with the purpose front-loaded and three semicolon-separated clauses, one per topic, so nothing is wasted. It is a single long sentence with no explicit structure or line breaks, which slightly harms scannability.
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?
With six parameters, a full output schema and annotations present, the description covers what an agent needs: what each topic yields, which are free, which costs a credit, and that results are cached. The only gap is paging behavior when results exceed the 700-per-call cap, which is left entirely to the schema.
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 description coverage is 100%, so the parameters are already fully self-documenting and 3 is the baseline. The description corroborates that feature_codes is filterable by class and text and that postal_countries returns code range and count, but names no parameter and adds no semantics the schema lacks.
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?
States a specific verb and resource ('Decode GeoNames vocabulary') and then enumerates all three topics with concrete contents (9 one-letter classes, 684 codes with names and definitions, 122 postal countries with code ranges). Relative to siblings like geonames_search_places or geonames_reverse_geocode, it is unmistakably a static reference-lookup tool rather than a query tool.
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?
'Vocabulary used by the other tools' gives a clear context for when to reach for it, and the cost split tells the agent which topic is free versus paid. It stops short of explicit exclusions (e.g., 'do not use this to look up a place') or an ordered workflow such as resolving feature codes before calling search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a latitude/longitude to the country and admin subdivisions that contain it (down to ADM5, each with its geonameId and ISO 3166-2 code where one exists), or the ocean or sea when the point is offshore, plus the nearest populated places with distances; these include neighborhood sections (PPLX) and historical places (PPLH), marked by featureCode. Set featureClasses or featureCodes to list the nearest features of that type instead (peaks, lakes, airports), cities to keep only places above a population tier, and includeTimezone for the IANA timezone with local time, sunrise, and sunset (offshore points get only GeoNames' UTC-offset estimate). A harbor, pier, or shoreline point can fall just outside every country outline and resolve to the sea; coastalBufferKm (up to 50) matches the nearest country within that distance instead. Costs 1 GeoNames credit for containment, with or without the buffer, plus 3 for nearest populated places or 4 for nearest features (nearbyLimit 0 skips them), 1 for the ocean when no country contains the point or lies within the buffer, and 1 for the timezone.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | Yes | Latitude in decimal degrees, -90 to 90. | |
| lng | Yes | Longitude in decimal degrees, -180 to 180. | |
| cities | No | Keep only nearby populated places with a population of at least 1,000 (cities1000), 5,000 (cities5000), or 15,000 (cities15000), plus seats of admin divisions: GeoNames' cities tiers. Not combinable with featureClasses or featureCodes. | |
| radiusKm | No | Radius in kilometres for the nearby lookup, above 0 and at most 300 (GeoNames' free-tier limit). Default 20. | |
| nearbyLimit | No | How many nearest places or features to list, 0 to 1,000. This tool returns at most 50 per call: a larger nearbyLimit is held to 50, and the notice says so when more lie within the radius. Default 5. 0 skips the nearby lookup and its 3 or 4 credits. | |
| featureCodes | No | List the nearest features with these GeoNames codes instead of populated places (MT mountain, PK peak, LK lake, AIRP airport), up to 20, as a list. Each code implies its class; with featureClasses too, the two lists intersect, so featureClasses must list exactly these codes' classes. geonames_list_reference topic feature_codes lists every code. Not combinable with cities. | |
| featureClasses | No | List the nearest features of these GeoNames classes instead of populated places: A admin divisions, H water, L areas, P populated places, R roads, S spots and buildings, T terrain, U undersea, V vegetation. With featureCodes too, the two lists intersect: list exactly the classes of those codes, or pass featureCodes alone. Not combinable with cities. | |
| coastalBufferKm | No | When no country contains the point, match the nearest country within this many kilometres, 0 to 50. Default 0: exact containment only. Set it for a harbor, pier, or shoreline point, which can fall just outside a country's outline as GeoNames maps it and otherwise resolves to the sea; a match carries country.distanceInKm. The nearby and timezone lookups keep the exact point. No extra credit. | |
| includeTimezone | No | Also return the timezone: IANA id, UTC offsets, local time, sunrise, and sunset (1 more credit). Default false. | |
| geonamesUsername | No | Your own GeoNames username, so the call spends that account's free credits instead of the server's. Omit it to use the server's account. The account needs free web services enabled on its geonames.org account page. |
| Name | Required | Description |
|---|---|---|
| cap | No | The nearbyLimit applied: nearbyLimit as given, or 50 when it asked for more. |
| lat | No | The latitude that was looked up. |
| lng | No | The longitude that was looked up. |
| error | No | Present when the call failed. Absent on success. |
| ocean | No | The ocean or sea at the point; present only when no country contains it or lies within coastalBufferKm. |
| shown | No | Nearby places or features returned. |
| nearby | No | Nearest places or features, nearest first; empty when nearbyKind is none. |
| notice | No | Guidance when the point is offshore or unmapped, its country was matched within coastalBufferKm, nothing is nearby, more lie within the radius than nearby holds (naming a nearbyLimit held to 50), or no IANA timezone covers it. |
| country | No | The country containing the point, or with coastalBufferKm the nearest country within that distance (then distanceInKm is set); absent offshore and in unmapped areas. |
| timezone | No | The timezone at the point; present only with includeTimezone. |
| truncated | No | True when more places or features lie within the radius than nearby holds. |
| nearbyKind | No | What nearby lists: populated_places, features (featureClasses or featureCodes was set), or none (nearbyLimit 0). |
| adminLevels | No | Admin divisions containing the point, first level first; for a country matched within coastalBufferKm, the divisions of its part nearest the point. Empty offshore, and where GeoNames records no subdivision of the country. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover readOnly/openWorld/idempotent; the description goes well beyond them, disclosing exact credit costs per component, the 50-result cap on nearbyLimit, the sea fallback for offshore points, UTC-offset-only timezone for offshore, and the PPLX/PPLH featureCode marking of 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?
Front-loaded with the primary resolution behavior, and every sentence carries information. The trailing credit-cost sentence is dense and run-on, which costs readability but not correctness.
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?
With an output schema present, return values need no explanation; the description fully covers the behaviors an agent needs to call correctly — cost model, offshore/coastal edge cases, parameter interactions, and per-account credit usage via geonamesUsername.
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%, so the baseline is 3, but the description adds cross-parameter semantics the schema does not: cities is non-combinable with featureClasses/featureCodes, featureCodes and featureClasses intersect, and each optional branch carries a specific credit cost. That is real value beyond the schema text.
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?
States a specific verb and resource ('Resolve a latitude/longitude to the country and admin subdivisions ... or the ocean or sea'), and enumerates the secondary outputs (nearest populated places, features, timezone). An agent can distinguish this from geonames_search_places or geonames_get_place purely from the description.
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?
Gives explicit conditions for the option branches: set featureClasses/featureCodes to list other feature types, cities to filter by population tier, coastalBufferKm when a harbor/pier/shoreline point falls outside a country outline, and nearbyLimit 0 to skip the nearby lookup. It does not route between named sibling tools, which keeps it 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.
Search the GeoNames gazetteer of 13M+ places by name and filters: country, admin division by its GeoNames code (adminCode1 TX with countries US for Texas), feature class (P populated places, A admin divisions, T mountains and terrain, H water, S buildings and spots), feature code (PPLC capitals, ADM1 states, MT mountains, AIRP airports), population tier, and bounding box. Results carry the geonameId that geonames_get_place, geonames_get_hierarchy, and geonames_get_children take. The default match requires a query term in the place name while letting other terms match the country or admin names ("Berlin, Germany"). Costs 1 GeoNames credit per call.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum entries to return, 1 to 1,000. This tool returns at most 100 per call: a larger limit is held to 100, and the notice says so when more entries remain. Default 10. | |
| match | No | How query is matched. name_required (the default) needs at least one query term in the place name while other terms may match the country or admin names; any_field lets every term match any of those fields; exact_name matches the whole name exactly, alternate and historical names included; name_prefix matches names that start with query. Needs query. | |
| query | No | Place name to search for, such as Springfield or "Berlin, Germany", up to 200 characters. match sets how it is compared. Omit it to search by filters alone, which then needs at least one of countries, featureClasses, featureCodes, or boundingBox (cities alone is not enough). | |
| cities | No | Keep only populated places (class P) with a population of at least 1,000 (cities1000), 5,000 (cities5000), or 15,000 (cities15000), plus seats of admin divisions: GeoNames' cities tiers. Beside featureClasses or featureCodes, list only class P or class-P codes such as PPLC. | |
| offset | No | Entries to skip before the first one returned, for paging, 0 to 5000. Default 0. | |
| orderBy | No | Result order: relevance or population, largest first. Omit it for GeoNames' own order, which matches relevance except with match name_prefix. | |
| countries | No | ISO 3166-1 country codes, up to 10, as a list: alpha-2 (US, GB, DE), alpha-3 (USA, GBR, DEU), or three-digit numeric (840, 826, 276), each sent to GeoNames as alpha-2. UK is accepted for GB and FL for LI. A listed country also returns the territories GeoNames files under it (GB also returns IM, JE, and GG), each result naming its own country in countryCode. | |
| adminCode1 | No | First-level admin division (state, province, region) to search inside, by its GeoNames admin code: TX is Texas in US. Take it from geonames_get_place or geonames_reverse_geocode (adminLevels[].code at level 1), or from adminCode1 on rows of geonames_search_places, geonames_get_hierarchy, and geonames_get_children. GeoNames codes are neither ISO 3166-2 nor postal admin codes: Bavaria is 02, not BY. Needs exactly one country in countries. 1 to 20 letters or digits, zero padding kept (02, not 2). Case-insensitive. | |
| adminCode2 | No | Second-level admin division (a US county, a French département) to search inside, by its GeoNames admin code: 033 is King County in WA. Take it from geonames_get_place or geonames_reverse_geocode (adminLevels[].code at level 2). Needs adminCode1 and exactly one country in countries. 1 to 20 letters or digits, zero padding kept (033, not 33). Case-insensitive. | |
| adminCode3 | No | Third-level admin division to search inside, by its GeoNames admin code: 09162 is Munich in DE. Take it from geonames_get_place or geonames_reverse_geocode (adminLevels[].code at level 3). Needs adminCode1 and exactly one country in countries. 1 to 20 letters or digits, zero padding kept. Case-insensitive. | |
| adminCode4 | No | Fourth-level admin division to search inside, by its GeoNames admin code: 92012 is Boulogne-Billancourt in FR. Take it from geonames_get_place or geonames_reverse_geocode (adminLevels[].code at level 4). Needs adminCode1 and exactly one country in countries. 1 to 20 letters or digits, zero padding kept. Case-insensitive. | |
| boundingBox | No | Keep only places inside this box. The box cannot cross the 180° meridian: split such an area into two searches. | |
| featureCodes | No | GeoNames feature codes (PPLC capital, ADM1 state, MT mountain, AIRP airport), up to 20, as a list. Each code implies its class; with featureClasses too, the two lists intersect, so featureClasses must list exactly these codes' classes. geonames_list_reference topic feature_codes lists every code. | |
| featureClasses | No | GeoNames feature classes: A admin divisions, H water, L areas, P populated places, R roads, S spots and buildings, T terrain, U undersea, V vegetation. With featureCodes too, the two lists intersect: list exactly the classes of those codes, or pass featureCodes alone. | |
| geonamesUsername | No | Your own GeoNames username, so the call spends that account's free credits instead of the server's. Omit it to use the server's account. The account needs free web services enabled on its geonames.org account page. |
| Name | Required | Description |
|---|---|---|
| cap | No | The limit applied: limit as given, or 100 when it asked for more. |
| error | No | Present when the call failed. Absent on success. |
| shown | No | Places returned on this page. |
| notice | No | Guidance: why nothing matched, or how to reach the next page (naming a limit held to 100), and which places on the page lie in countries that countries does not list. |
| places | No | Places on this page, in the requested order. |
| truncated | No | True when more matching places remain past this page. |
| nextOffset | No | Offset of the next page; absent on the last page and once offset is 5000. Capped at 5000, the last offset GeoNames' free service accepts, so that page can repeat rows of this one. |
| totalCount | No | GeoNames' count of matching places, before paging. |
| effectiveQuery | No | The match mode, query, and filters as the server sent them to GeoNames. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavioral context on top: the cost model (1 GeoNames credit per call) and the precise default matching semantics, which is not something the annotations convey.
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?
One long but well front-loaded passage: the search capability and filter vocabulary come first, then the match semantics and cost. The parenthetical code examples are somewhat redundant with the schema and inflate the sentence, but nearly every clause earns its place for an agent scanning the filter space.
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 15-parameter, zero-required filter tool with a full output schema and exhaustive schema descriptions, the description covers purpose, filter vocabulary, default matching, cost, and downstream linkage. Pagination caps (100 per call) and the optional geonamesUsername auth path are left to the schema, which is acceptable given their depth there.
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 description coverage is 100%, so the schema already documents all 15 parameters thoroughly. The description's filter cheat-sheets (P/PPLC/ADM1/MT/AIRP) and the adminCode1 TX + countries US example largely restate what the schema says, adding scanning convenience rather than new meaning; the baseline of 3 applies.
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?
States a specific verb and resource (search the GeoNames gazetteer of 13M+ places) plus the filter dimensions it accepts. It also differentiates itself from siblings by saying results carry the geonameId that geonames_get_place, geonames_get_hierarchy, and geonames_get_children consume, so the agent can place this tool in the workflow without opening another schema.
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?
Gives clear operational context: filters can be combined, omitting query requires at least one of countries/featureClasses/featureCodes/boundingBox, and the default match requires a term in the place name ("Berlin, Germany"). It does not, however, state when to prefer a sibling such as geonames_reverse_geocode or geonames_find_postal_codes, so no explicit when-not guidance is present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
geonames_find_postal_codes13 fields changedInput schema / properties / countries / descriptionPrevious value: -"Keep only postal codes in these countries: ISO 3166-1 codes, up to 10, as a list or a comma-separated string: alpha-2 (US, GB, DE), alpha-3 (USA, GBR, DEU), or three-digit numeric (840, 826, 276), each sent to GeoNames as alpha-2. Case-insensitive; UK is accepted for GB. Modes code and place_name only."New value: +"Countries to look up postal codes in: ISO 3166-1 codes, up to 10, as a list: alpha-2 (US, GB, DE), alpha-3 (USA, GBR, DEU), or three-digit numeric (840, 826, 276), each sent to GeoNames as alpha-2. UK is accepted for GB and FL for LI. A listed country also returns the territories GeoNames files under it (GB also returns IM, JE, and GG), each postal code's countryCode naming its own country. Modes code and place_name only."Input schema / properties / limit / descriptionPrevious value: -"Maximum entries to return, 1 to 100. Default 10."New value: +"Maximum entries to return, 1 to 1,000. This tool returns at most 100 per call: a larger limit is held to 100, and the notice says so when more entries remain. Default 10."Input schema / properties / limit / maximumPrevious value: -100New value: +1000Input schema / properties / mode / descriptionPrevious value: -"What to look up. code: the place for postalCode (required). place_name: the postal codes of placeName (required). nearby: postal codes around lat and lng (both required; countries not accepted). Case-insensitive."New value: +"What to look up. code: the place for postalCode (required). place_name: the postal codes of placeName (required). nearby: postal codes around lat and lng (both required; countries not accepted)."Input schema / properties / offsetAdded value: +{
+ "default": 0,
+ "description": "Postal codes to skip before the first one returned, 0 to 5000. Default 0. Modes code and place_name only; pass the nextOffset of the previous page to read the next one.",
+ "maximum": 5000,
+ "minimum": 0,
+ "type": "integer"
+}Input schema / properties / postalCode / descriptionPrevious value: -"Postal code to resolve, such as 98101, SW1A 1AA, or K1A 0A1: letters, digits, spaces, and hyphens, up to 12 characters. Case and extra spaces are normalized. Required in mode code; in mode place_name it narrows the match; not used in mode nearby."New value: +"Postal code to resolve, such as 98101, SW1A 1AA, or K1A 0A1: capital letters, digits, spaces, and hyphens, up to 12 characters. Required in mode code; in mode place_name it narrows the match; not used in mode nearby."Output schema / properties / cap / descriptionPrevious value: -"The limit that was applied."New value: +"The limit applied: limit as given, or 100 when it asked for more."Output schema / properties / error / properties / data / properties / reason / descriptionPrevious value: -"Machine-readable failure mode. Declared by this tool: `mode_fields_mismatch`: A field the mode requires is missing, or countries is given in mode nearby. The message names the field. `unknown_country_code`: A countries entry is a well-formed alpha-3 or three-digit numeric code that no country has. `username_required`: Neither geonamesUsername nor the server's GEONAMES_USERNAME supplies a GeoNames account. `caller_account_rejected`: GeoNames rejected the caller-supplied geonamesUsername (unknown user, or free web services not enabled). `server_account_rejected`: GeoNames rejected the server's GEONAMES_USERNAME. `quota_exhausted`: GeoNames reported the account's hourly, daily, or weekly credit limit spent, or this server's pacer for the account shed the call. `upstream_rejected_parameter`: GeoNames rejected a value the schema let through; the message carries its text. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `mode_fields_mismatch`: A field the mode requires is missing, or countries is given or offset above 0 in mode nearby. The message names the field. `unknown_country_code`: A countries entry, once mapped to alpha-2, is none of the 250 country codes or the retired AN, CS, and YU: an alpha-2 such as EL or EU, or an unassigned alpha-3 or numeric code. `username_required`: Neither geonamesUsername nor the server's GEONAMES_USERNAME supplies a GeoNames account. `caller_account_rejected`: GeoNames rejected the caller-supplied geonamesUsername (unknown user, or free web services not enabled). `server_account_rejected`: GeoNames rejected the server's GEONAMES_USERNAME. `quota_exhausted`: GeoNames reported the account's hourly, daily, or weekly credit limit spent, or this server's pacer for the account shed the call. `upstream_rejected_parameter`: GeoNames rejected a value the schema let through; the message carries its text. Other values are possible when a failure originates below the handler."Output schema / properties / nextOffsetAdded value: +{
+ "description": "Offset of the next page in modes code and place_name; absent on the last page, in mode nearby, and once offset is 5000. Capped at 5000, the last offset GeoNames' free service accepts, so that page can repeat rows of this one.",
+ "type": "number"
+}Output schema / properties / notice / descriptionPrevious value: -"Guidance when nothing matched, or when a full page suggests more matches."New value: +"Guidance: why nothing matched or nothing lies at offset, or how to reach the postal codes past this page (naming a limit held to 100), and which postal codes on the page lie in countries that countries does not list."Output schema / properties / postalCodes / descriptionPrevious value: -"Matching postal codes; nearest first in mode nearby."New value: +"Matching postal codes on this page; nearest first in mode nearby."Output schema / properties / shown / descriptionPrevious value: -"Postal codes returned."New value: +"Postal codes returned on this page."Output schema / properties / truncated / descriptionPrevious value: -"True when a full page came back: GeoNames reports no total, so more may match."New value: +"True when more postal codes remain past this page; in mode nearby, more lie within radiusKm."geonames_get_children6 fields changedInput schema / properties / geonameId / descriptionPrevious value: -"GeoNames id of the parent feature, a positive integer up to 2147483647 such as 6252001 (United States), as returned in geonameId by the other geonames tools. A geonames.org/<id> URL is reduced to its id."New value: +"GeoNames id of the parent feature as a digit string up to 2147483647, such as \"6252001\" (United States): the geonameId the other geonames tools return, sent as a string."Input schema / properties / hierarchy / descriptionPrevious value: -"Which tree to descend: administrative (the default: continents (class L), countries, admin divisions, populated places), tourism (islands (class T), coasts (class L), and their municipalities; almost all in Spain), or dependency (a country's dependent territories). For a feature with no tourism or dependency tree, GeoNames answers with its administrative children, which sameAsAdministrative flags; the comparison reads the administrative list, 1 more credit unless it is cached. Case-insensitive."New value: +"Which tree to descend: administrative (the default: continents (class L), countries, admin divisions, populated places), tourism (islands (class T), coasts (class L), and their municipalities; almost all in Spain), or dependency (a country's dependent territories). For a feature with no tourism or dependency tree, GeoNames answers with its administrative children, which sameAsAdministrative flags; the comparison reads the administrative list, 1 more credit unless it is cached."Input schema / properties / limit / descriptionPrevious value: -"Maximum entries to return, 1 to 500. Default 100."New value: +"Maximum entries to return, 1 to 1,000. This tool returns at most 500 per call: a larger limit is held to 500, and the notice says so when more entries remain. Default 100."Input schema / properties / limit / maximumPrevious value: -500New value: +1000Output schema / properties / cap / descriptionPrevious value: -"The limit that was applied."New value: +"The limit applied: limit as given, or 500 when it asked for more."Output schema / properties / notice / descriptionPrevious value: -"Guidance when a tourism or dependency answer is the administrative children, there are no children, nothing matched, the offset is past the end, more pages remain, or GeoNames holds more children than it returns."New value: +"Guidance when a tourism or dependency answer is the administrative children, there are no children, nothing matched, the offset is past the end, more pages remain (naming a limit held to 500), or GeoNames holds more children than it returns."geonames_get_countries7 fields changedInput schema / properties / continent / descriptionPrevious value: -"Keep only countries on this continent: AF Africa, AN Antarctica, AS Asia, EU Europe, NA North America, OC Oceania, SA South America. Case-insensitive."New value: +"Keep only countries on this continent: AF Africa, AN Antarctica, AS Asia, EU Europe, NA North America, OC Oceania, SA South America."Input schema / properties / countries / descriptionPrevious value: -"Countries to return by ISO 3166-1 code: alpha-2 (US), alpha-3 (USA), or three-digit numeric (840), up to 50, as a list or a comma-separated string. Case-insensitive; UK is accepted for GB. Match country names with nameContains instead."New value: +"Countries to return by ISO 3166-1 code: alpha-2 (US), alpha-3 (USA), or three-digit numeric (840), up to 250, as a list. UK is accepted for GB and FL for LI. Match country names with nameContains instead."Input schema / properties / countries / maxItemsPrevious value: -50New value: +250Input schema / properties / limit / descriptionPrevious value: -"Maximum entries to return, 1 to 250. Default 50."New value: +"Maximum entries to return, 1 to 1,000. This tool returns at most 250 per call: a larger limit is held to 250, and the notice says so when more entries remain. Default 50."Input schema / properties / limit / maximumPrevious value: -250New value: +1000Output schema / properties / cap / descriptionPrevious value: -"The limit that was applied."New value: +"The limit applied: limit as given, or 250 when it asked for more."Output schema / properties / notice / descriptionPrevious value: -"Guidance when nothing matched, the offset is past the end, or more pages remain."New value: +"Guidance when nothing matched, the offset is past the end, or more pages remain (naming a limit held to 250)."geonames_get_hierarchy1 field changedInput schema / properties / geonameId / descriptionPrevious value: -"GeoNames feature id, a positive integer up to 2147483647 such as 5809844 (Seattle), as returned in geonameId by the other geonames tools. A geonames.org/<id> URL is reduced to its id."New value: +"GeoNames feature id as a digit string up to 2147483647, such as \"5809844\" (Seattle): the geonameId the other geonames tools return, sent as a string."geonames_get_place5 fields changedInput schema / properties / geonameId / descriptionPrevious value: -"GeoNames feature id, a positive integer up to 2147483647 such as 5809844 (Seattle), as returned in geonameId by the other geonames tools. A geonames.org/<id> URL is reduced to its id."New value: +"GeoNames feature id as a digit string up to 2147483647, such as \"5809844\" (Seattle): the geonameId the other geonames tools return, sent as a string."Input schema / properties / nameLanguages / descriptionPrevious value: -"Keep only alternate names in these languages, up to 20, as a list or a comma-separated string. Case-insensitive; a tag also matches its regional forms (zh matches zh, zh-CN, and zh-TW). Omit to return every alternate name, including those under GeoNames pseudo-language tags (abbr, phon, piny, fr_1793), which this filter cannot select. Postal codes, links, and identifiers are unaffected."New value: +"Keep only alternate names in these languages, up to 20, as a list. A tag also matches its regional forms: zh keeps names GeoNames tags zh, zh-CN, or zh-TW. Omit to return every alternate name, including those under GeoNames pseudo-language tags (abbr, phon, piny, fr_1793), which this filter cannot select. Postal codes, links, and identifiers are unaffected."Output schema / properties / place / properties / adminLevels / items / properties / code / descriptionPrevious value: -"The division's GeoNames admin code."New value: +"The division's GeoNames admin code. At levels 1 to 4, pass it as written to geonames_search_places as that level's adminCode (adminCode1 to adminCode4), with the level 1 code as adminCode1 and countryCode in countries, to search inside the division; level 5 has no search filter."Output schema / properties / place / properties / timezone / properties / dstOffsetInHours / descriptionPrevious value: -"UTC offset in hours on 1 July."New value: +"UTC offset in hours on 1 July of the current year at the place."Output schema / properties / place / properties / timezone / properties / gmtOffsetInHours / descriptionPrevious value: -"UTC offset in hours on 1 January."New value: +"UTC offset in hours on 1 January of the current year at the place."geonames_list_reference6 fields changedInput schema / properties / featureClass / descriptionPrevious value: -"Topic feature_codes only: keep the codes of this one-letter class (A, H, L, P, R, S, T, U, V). Case-insensitive."New value: +"Topic feature_codes only: keep the codes of this one-letter class (A, H, L, P, R, S, T, U, V)."Input schema / properties / limit / descriptionPrevious value: -"Maximum entries to return, 1 to 700. Default 100."New value: +"Maximum entries to return, 1 to 1,000. This tool returns at most 700 per call: a larger limit is held to 700, and the notice says so when more entries remain. Default 100."Input schema / properties / limit / maximumPrevious value: -700New value: +1000Input schema / properties / topic / descriptionPrevious value: -"Vocabulary to list: feature_classes (the 9 one-letter classes), feature_codes (the 684 codes), or postal_countries (countries with postal-code data). Case-insensitive."New value: +"Vocabulary to list: feature_classes (the 9 one-letter classes), feature_codes (the 684 codes), or postal_countries (countries with postal-code data)."Output schema / properties / cap / descriptionPrevious value: -"The limit that was applied."New value: +"The limit applied: limit as given, or 700 when it asked for more."Output schema / properties / notice / descriptionPrevious value: -"Guidance when nothing matched, the offset is past the end, or more pages remain."New value: +"Guidance when nothing matched, the offset is past the end, or more pages remain (naming a limit held to 700)."geonames_reverse_geocode12 fields changedInput schema / properties / featureClasses / descriptionPrevious value: -"List the nearest features of these GeoNames classes instead of populated places: A admin divisions, H water, L areas, P populated places, R roads, S spots and buildings, T terrain, U undersea, V vegetation. A list or a comma-separated string; case-insensitive. With featureCodes too, the two lists intersect: list exactly the classes of those codes, or pass featureCodes alone. Not combinable with cities."New value: +"List the nearest features of these GeoNames classes instead of populated places: A admin divisions, H water, L areas, P populated places, R roads, S spots and buildings, T terrain, U undersea, V vegetation. With featureCodes too, the two lists intersect: list exactly the classes of those codes, or pass featureCodes alone. Not combinable with cities."Input schema / properties / featureCodes / descriptionPrevious value: -"List the nearest features with these GeoNames codes instead of populated places (MT mountain, PK peak, LK lake, AIRP airport), up to 20, as a list or a comma-separated string. Case-insensitive; a class prefix (T.MT) is dropped. Each code implies its class; with featureClasses too, the two lists intersect, so featureClasses must list exactly these codes' classes. geonames_list_reference topic feature_codes lists every code. Not combinable with cities."New value: +"List the nearest features with these GeoNames codes instead of populated places (MT mountain, PK peak, LK lake, AIRP airport), up to 20, as a list. Each code implies its class; with featureClasses too, the two lists intersect, so featureClasses must list exactly these codes' classes. geonames_list_reference topic feature_codes lists every code. Not combinable with cities."Input schema / properties / nearbyLimit / descriptionPrevious value: -"How many nearest places or features to list, 0 to 50. Default 5. 0 skips the nearby lookup and its 3 or 4 credits."New value: +"How many nearest places or features to list, 0 to 1,000. This tool returns at most 50 per call: a larger nearbyLimit is held to 50, and the notice says so when more lie within the radius. Default 5. 0 skips the nearby lookup and its 3 or 4 credits."Input schema / properties / nearbyLimit / maximumPrevious value: -50New value: +1000Output schema / properties / adminLevels / items / properties / code / descriptionPrevious value: -"Admin code at this level."New value: +"GeoNames admin code at this level. At levels 1 to 4, pass it as written to geonames_search_places as that level's adminCode (adminCode1 to adminCode4), with the level 1 code as adminCode1 and country.countryCode in countries, to search inside the division; level 5 has no search filter."Output schema / properties / cap / descriptionPrevious value: -"The nearbyLimit that was applied."New value: +"The nearbyLimit applied: nearbyLimit as given, or 50 when it asked for more."Output schema / properties / notice / descriptionPrevious value: -"Guidance when the point is offshore or unmapped, its country was matched within coastalBufferKm, nothing is nearby, nearby is full, or no IANA timezone covers it."New value: +"Guidance when the point is offshore or unmapped, its country was matched within coastalBufferKm, nothing is nearby, more lie within the radius than nearby holds (naming a nearbyLimit held to 50), or no IANA timezone covers it."Output schema / properties / timezone / properties / dstOffsetInHours / descriptionPrevious value: -"UTC offset in hours on 1 July. Without a timezoneId the offsets are GeoNames' open-water estimate, which has no DST, so this equals rawOffsetInHours."New value: +"UTC offset in hours on 1 July of the current local year. Without a timezoneId the offsets are GeoNames' open-water estimate, which has no DST, so both equal rawOffsetInHours."Output schema / properties / timezone / properties / gmtOffsetInHours / descriptionPrevious value: -"UTC offset in hours on 1 January."New value: +"UTC offset in hours on 1 January of the current local year."Output schema / properties / timezone / properties / sunrise / descriptionPrevious value: -"Today's local sunrise, YYYY-MM-DD HH:mm. Absent offshore."New value: +"Local sunrise on localTime's date, YYYY-MM-DD HH:mm. Absent offshore, in polar day or night, and when GeoNames has none for that date."Output schema / properties / timezone / properties / sunset / descriptionPrevious value: -"Today's local sunset, YYYY-MM-DD HH:mm. Absent offshore."New value: +"Local sunset of the same day as sunrise, YYYY-MM-DD HH:mm; it can fall after midnight. Absent offshore, in polar day or night, and when GeoNames has none for that date."Output schema / properties / truncated / descriptionPrevious value: -"True when nearby is full at nearbyLimit, so more may lie within the radius."New value: +"True when more places or features lie within the radius than nearby holds."geonames_search_places16 fields changedInput schema / properties / adminCode1Added value: +{
+ "description": "First-level admin division (state, province, region) to search inside, by its GeoNames admin code: TX is Texas in US. Take it from geonames_get_place or geonames_reverse_geocode (adminLevels[].code at level 1), or from adminCode1 on rows of geonames_search_places, geonames_get_hierarchy, and geonames_get_children. GeoNames codes are neither ISO 3166-2 nor postal admin codes: Bavaria is 02, not BY. Needs exactly one country in countries. 1 to 20 letters or digits, zero padding kept (02, not 2). Case-insensitive.",
+ "pattern": "^\\s*[A-Za-z0-9]{1,20}\\s*$",
+ "type": "string"
+}Input schema / properties / adminCode2Added value: +{
+ "description": "Second-level admin division (a US county, a French département) to search inside, by its GeoNames admin code: 033 is King County in WA. Take it from geonames_get_place or geonames_reverse_geocode (adminLevels[].code at level 2). Needs adminCode1 and exactly one country in countries. 1 to 20 letters or digits, zero padding kept (033, not 33). Case-insensitive.",
+ "pattern": "^\\s*[A-Za-z0-9]{1,20}\\s*$",
+ "type": "string"
+}Input schema / properties / adminCode3Added value: +{
+ "description": "Third-level admin division to search inside, by its GeoNames admin code: 09162 is Munich in DE. Take it from geonames_get_place or geonames_reverse_geocode (adminLevels[].code at level 3). Needs adminCode1 and exactly one country in countries. 1 to 20 letters or digits, zero padding kept. Case-insensitive.",
+ "pattern": "^\\s*[A-Za-z0-9]{1,20}\\s*$",
+ "type": "string"
+}Input schema / properties / adminCode4Added value: +{
+ "description": "Fourth-level admin division to search inside, by its GeoNames admin code: 92012 is Boulogne-Billancourt in FR. Take it from geonames_get_place or geonames_reverse_geocode (adminLevels[].code at level 4). Needs adminCode1 and exactly one country in countries. 1 to 20 letters or digits, zero padding kept. Case-insensitive.",
+ "pattern": "^\\s*[A-Za-z0-9]{1,20}\\s*$",
+ "type": "string"
+}Input schema / properties / cities / descriptionPrevious value: -"Keep only populated places (class P) with a population of at least 1,000 (cities1000), 5,000 (cities5000), or 15,000 (cities15000), plus seats of admin divisions: GeoNames' cities tiers. Beside featureClasses or featureCodes, list only class P or class-P codes such as PPLC. Case-insensitive."New value: +"Keep only populated places (class P) with a population of at least 1,000 (cities1000), 5,000 (cities5000), or 15,000 (cities15000), plus seats of admin divisions: GeoNames' cities tiers. Beside featureClasses or featureCodes, list only class P or class-P codes such as PPLC."Input schema / properties / countries / descriptionPrevious value: -"ISO 3166-1 country codes, up to 10, as a list or a comma-separated string: alpha-2 (US, GB, DE), alpha-3 (USA, GBR, DEU), or three-digit numeric (840, 826, 276), each sent to GeoNames as alpha-2. Case-insensitive; UK is accepted for GB."New value: +"ISO 3166-1 country codes, up to 10, as a list: alpha-2 (US, GB, DE), alpha-3 (USA, GBR, DEU), or three-digit numeric (840, 826, 276), each sent to GeoNames as alpha-2. UK is accepted for GB and FL for LI. A listed country also returns the territories GeoNames files under it (GB also returns IM, JE, and GG), each result naming its own country in countryCode."Input schema / properties / featureClasses / descriptionPrevious value: -"GeoNames feature classes: A admin divisions, H water, L areas, P populated places, R roads, S spots and buildings, T terrain, U undersea, V vegetation. A list or a comma-separated string; case-insensitive. With featureCodes too, the two lists intersect: list exactly the classes of those codes, or pass featureCodes alone."New value: +"GeoNames feature classes: A admin divisions, H water, L areas, P populated places, R roads, S spots and buildings, T terrain, U undersea, V vegetation. With featureCodes too, the two lists intersect: list exactly the classes of those codes, or pass featureCodes alone."Input schema / properties / featureCodes / descriptionPrevious value: -"GeoNames feature codes (PPLC capital, ADM1 state, MT mountain, AIRP airport), up to 20, as a list or a comma-separated string. Case-insensitive; a class prefix (P.PPLC) is dropped. Each code implies its class; with featureClasses too, the two lists intersect, so featureClasses must list exactly these codes' classes. geonames_list_reference topic feature_codes lists every code."New value: +"GeoNames feature codes (PPLC capital, ADM1 state, MT mountain, AIRP airport), up to 20, as a list. Each code implies its class; with featureClasses too, the two lists intersect, so featureClasses must list exactly these codes' classes. geonames_list_reference topic feature_codes lists every code."Input schema / properties / limit / descriptionPrevious value: -"Maximum entries to return, 1 to 100. Default 10."New value: +"Maximum entries to return, 1 to 1,000. This tool returns at most 100 per call: a larger limit is held to 100, and the notice says so when more entries remain. Default 10."Input schema / properties / limit / maximumPrevious value: -100New value: +1000Input schema / properties / match / descriptionPrevious value: -"How query is matched. name_required (the default) needs at least one query term in the place name while other terms may match the country or admin names; any_field lets every term match any of those fields; exact_name matches the whole name exactly, alternate and historical names included; name_prefix matches names that start with query. Needs query. Case-insensitive."New value: +"How query is matched. name_required (the default) needs at least one query term in the place name while other terms may match the country or admin names; any_field lets every term match any of those fields; exact_name matches the whole name exactly, alternate and historical names included; name_prefix matches names that start with query. Needs query."Input schema / properties / orderBy / descriptionPrevious value: -"Result order: relevance (GeoNames' default) or population, largest first. Case-insensitive."New value: +"Result order: relevance or population, largest first. Omit it for GeoNames' own order, which matches relevance except with match name_prefix."Output schema / properties / cap / descriptionPrevious value: -"The limit that was applied."New value: +"The limit applied: limit as given, or 100 when it asked for more."Output schema / properties / error / properties / data / properties / reason / descriptionPrevious value: -"Machine-readable failure mode. Declared by this tool: `query_or_filter_required`: Neither query nor a narrowing filter (countries, featureClasses, featureCodes, boundingBox) was given. `query_required`: match was set without query. `unknown_country_code`: A countries entry is a well-formed alpha-3 or three-digit numeric code that no country has. `unknown_feature_code`: A featureCodes entry is not a GeoNames feature code. `feature_filter_mismatch`: featureClasses and featureCodes are both set and a code's class is not listed or a listed class has no listed code, or cities (class P only) is set beside another class or a code outside class P. GeoNames intersects the filters, so those entries match nothing. `invalid_bounding_box`: boundingBox has south greater than or equal to north, or west greater than or equal to east. `username_required`: Neither geonamesUsername nor the server's GEONAMES_USERNAME supplies a GeoNames account. `caller_account_rejected`: GeoNames rejected the caller-supplied geonamesUsername (unknown user, or free web services not enabled). `server_account_rejected`: GeoNames rejected the server's GEONAMES_USERNAME. `quota_exhausted`: GeoNames reported the account's hourly, daily, or weekly credit limit spent, or this server's pacer for the account shed the call. `upstream_rejected_parameter`: GeoNames rejected a value the schema let through; the message carries its text. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `query_or_filter_required`: Neither query nor a narrowing filter (countries, featureClasses, featureCodes, boundingBox) was given. `query_required`: match was set without query. `unknown_country_code`: A countries entry, once mapped to alpha-2, is none of the 250 country codes or the retired AN, CS, and YU: an alpha-2 such as EL or EU, or an unassigned alpha-3 or numeric code. `unknown_feature_code`: A featureCodes entry is not a GeoNames feature code. `admin_code_unscoped`: An admin code is set without exactly one country in countries, or adminCode2 to adminCode4 without adminCode1: codes repeat across countries, and lower-level codes across first-level divisions. `feature_filter_mismatch`: featureClasses and featureCodes are both set and a code's class is not listed or a listed class has no listed code, or cities (class P only) is set beside another class or a code outside class P. GeoNames intersects the filters, so those entries match nothing. `invalid_bounding_box`: boundingBox has south greater than or equal to north, or west greater than or equal to east. `username_required`: Neither geonamesUsername nor the server's GEONAMES_USERNAME supplies a GeoNames account. `caller_account_rejected`: GeoNames rejected the caller-supplied geonamesUsername (unknown user, or free web services not enabled). `server_account_rejected`: GeoNames rejected the server's GEONAMES_USERNAME. `quota_exhausted`: GeoNames reported the account's hourly, daily, or weekly credit limit spent, or this server's pacer for the account shed the call. `upstream_rejected_parameter`: GeoNames rejected a value the schema let through; the message carries its text. Other values are possible when a failure originates below the handler."Output schema / properties / error / properties / data / properties / reason / examplesPrevious value: -[
- "query_or_filter_required",
- "query_required",
- "unknown_country_code",
- "unknown_feature_code",
- "feature_filter_mismatch",
- "invalid_bounding_box",
- "username_required",
- "caller_account_rejected",
- "server_account_rejected",
- "quota_exhausted",
- "upstream_rejected_parameter"
-]New value: +[
+ "query_or_filter_required",
+ "query_required",
+ "unknown_country_code",
+ "unknown_feature_code",
+ "admin_code_unscoped",
+ "feature_filter_mismatch",
+ "invalid_bounding_box",
+ "username_required",
+ "caller_account_rejected",
+ "server_account_rejected",
+ "quota_exhausted",
+ "upstream_rejected_parameter"
+]Output schema / properties / notice / descriptionPrevious value: -"Guidance when nothing matched or more pages remain."New value: +"Guidance: why nothing matched, or how to reach the next page (naming a limit held to 100), and which places on the page lie in countries that countries does not list."geonames_find_postal_codesgeonames_get_childrengeonames_get_countriesgeonames_get_hierarchygeonames_get_placegeonames_list_referencegeonames_reverse_geocodegeonames_search_placesGeocode, reverse-geocode, autocomplete, route and search places.
Geocode, reverse geocode, and run Overpass spatial queries on OpenStreetMap data.
Geocode, reverse geocode, and run Overpass spatial queries on OpenStreetMap data.
Free GeoNames MCP: countries, cities, POIs, distance & nearby. Remote HTTP + agent token signup.
Add one secure layer between your agents and this server.
