Search GeoNames places, walk admin hierarchies, reverse geocode, get postal codes and country info.
Scored across 8 tools
Each tool maps to a distinct GeoNames operation: text search, fetch by ID, reverse geocoding, postal lookup, hierarchy traversal, country facts, and vocabulary reference. The only closely related pair, get_children and get_hierarchy, is clearly split into downward vs upward traversal, so agents should not confuse them.
All tools use the geonames_ prefix with snake_case and an action-resource pattern (get_, find_, list_, search_, reverse_). The small variation in verbs reflects the action accurately rather than introducing inconsistent conventions.
8 tools is well-scoped for a GeoNames read-only server; each tool covers a distinct capability and no obvious redundant tools inflate the set.
The surface covers core gazetteer workflows: search, record retrieval, reverse geocoding, hierarchy/children, postal codes, country facts, and reference vocab. Minor gaps exist for specialized GeoNames endpoints such as street/address lookup or a standalone timezone/elevation call, though some of these are folded into other tools.
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; 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); 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). Case-insensitive. | |
| limit | No | Maximum entries to return, 1 to 100. Default 10. | |
| radiusKm | No | Search radius in kilometres for mode nearby, above 0 and at most 30 (GeoNames' free-tier limit). Default 10. | |
| countries | No | 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. | |
| 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: 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. | |
| 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 that was applied. |
| mode | No | The lookup mode that ran. |
| error | No | Present when the call failed. Absent on success. |
| shown | No | Postal codes returned. |
| notice | No | Guidance when nothing matched, or when a full page suggests more matches. |
| truncated | No | True when a full page came back: GeoNames reports no total, so more may match. |
| postalCodes | No | Matching postal codes; nearest first in mode nearby. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnly/idempotent annotations: it discloses credit cost (1, 2 for nearby), caching, the 30 km free-tier radius ceiling, and per-country data truncation quirks (Ireland returns only Eircode routing keys, Malta only the letter prefix). These are exactly the operational facts an agent cannot infer from structured fields.
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 core purpose, then modes, then caveats, then cost — a sensible order. It is a dense paragraph with semicolon-chained clauses, but each clause carries real information and little is redundant.
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 9-parameter tool with an output schema, the description covers what the schema cannot: cost model, caching, geographic coverage limits, and per-country data caveats. Nothing an agent needs to call this correctly appears to be 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 mode enum, radius bounds, and country code formats. The description largely restates the mode semantics rather than adding syntax or edge-case meaning beyond the schema, 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 (look up postal codes in the GeoNames postal database) and enumerates the three operating modes with their exact semantics. It also scopes coverage (122 countries) so the agent can distinguish it from sibling geocoders like 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?
Modes map cleanly to intents, and it routes the agent to geonames_list_reference (topic postal_countries) to verify coverage before calling. It does not address the overlap with geonames_reverse_geocode for coordinate-based lookups, which is the closest sibling to mode nearby.
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 500. Default 100. | |
| offset | No | Entries to skip before the first one returned, for paging. Default 0. | |
| geonameId | Yes | 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. | |
| 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. Case-insensitive. | 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 that was applied. |
| 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, 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 cover read-only/idempotent/open-world, and the description adds real behavioral context: the full list is fetched once for 1 credit and cached making paging/filtering free, tourism/dependency calls may read the admin list for 1 extra credit, and sameAsAdministrative flags fallback. These cost and caching traits go well beyond the annotations, though the redundancy of the credit note in two places dilutes it slightly.
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?
Purpose and tree enumeration are front-loaded, and the routing advice is easy to find. It is dense but mostly earns its length, though the sameAsAdministrative/extra-credit point is stated twice (description and the hierarchy enum), a minor redundancy.
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 not be explained, and the description covers scope, starting IDs, hierarchy options, fallback semantics, caching/credit behavior, and sibling routing. An agent has everything needed to call it 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 coverage is 100% and each parameter is already documented, including the hierarchy fallback and nameContains accent/word matching, so the description largely repeats schema content. Baseline 3 applies; it does not add much new per-parameter syntax or format detail.
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 the direct children of a GeoNames feature') and enumerates the concrete levels it can descend. It also names the sibling it is not for other feature types (geonames_search_places with a boundingBox), so an agent can distinguish it from siblings without opening schemas.
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 an explicit starting point (a country's geonameId from geonames_get_countries or any admin division's) and an explicit exclusion ('For other feature types inside a place, use geonames_search_places with a boundingBox'), naming the alternative and the condition that selects it.
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 250. 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. Case-insensitive. | |
| countries | No | 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. | |
| 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 that was applied. |
| 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. |
| 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 the read-only/idempotent/open-world profile, but the description adds real context the agent can't get elsewhere: the table is fetched once a day for 1 GeoNames credit and cached, and geonamesUsername spends that account's credit only on a cache miss. This informs cost and side-effect behavior 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?
Three sentences, front-loaded with the purpose, then the cross-tool anchoring, then the caching/cost note. The long first-sentence enumeration is dense but each field earns its place; 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 zero-required-param, fully schema-documented, annotations-covered tool with an output schema, the description supplies everything an agent still needs: selection modes, the geonameId hand-off to sibling tools, and credit/caching behavior. Nothing essential 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, but the description adds semantics beyond the schema: 'UK is accepted for GB', that name matching should use nameContains instead of countries, and that the geonamesUsername credit is consumed only when uncached.
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 (Get) and resource (GeoNames country facts) and enumerates the exact payload (ISO/FIPS codes, geonameId, capital, population, area, continent, languages, currency, postal format, bounding box). It also scopes it as 'countries named, a continent, or all 250', which an agent can immediately distinguish from sibling search/place tools.
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 states the three selection modes (named countries, a continent, or all 250) and routes the agent to geonames_get_children and geonames_get_hierarchy via the returned geonameId. It lacks an explicit when-not-to-use (e.g., prefer geonames_search_places for name lookups), so it stops short of 5.
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, 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. | |
| 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?
Annotations already declare readOnly, openWorld, and idempotent, so safety is covered. The description adds value beyond them: the failure mode for an unknown id ('returns found: false'), a per-call credit cost, and caching behavior — all useful operational context an agent would otherwise not have.
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 tight sentences, front-loaded with what is returned and its ordering, then usage, then cost/error behavior. No filler or redundancy.
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?
An output schema exists, so return values need not be spelled out, yet the description still sketches the chain shape for orientation. With annotations covering safety and the description covering error semantics and cost, nothing needed to invoke the 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%, with rich per-parameter docs (id pattern, URL reduction, username/credits behavior), so the baseline is 3. The description adds no parameter-level syntax or constraints beyond what the schema already provides — its detail about geonameId, feature code, and coordinates describes output rather than inputs.
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') with the exact ordering semantics (Earth → continent → country → admin divisions → feature). It is clearly distinguishable from siblings like geonames_get_children and geonames_get_place.
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 ('find which country, state, and county contain a place', 'fill an admin path for a geonameId'), which is clear context for selection. It stops short of naming an alternative tool or an explicit when-not-to-use condition, so it falls just below the top band.
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, 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. | |
| nameLanguages | No | 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. | |
| 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?
Beyond the readOnly/idempotent/openWorld annotations, the description discloses credit cost (1 GeoNames credit), caching of repeat lookups, and the unknown-id behavior (found: false), giving the agent operationally useful context the annotations do not cover.
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 purpose and usage routing are front-loaded cleanly, but the long enumeration of returned fields is somewhat redundant given the output schema exists, adding length without much selection value.
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 and rich annotations, the description covers provenance of the id, error behavior, cost, and caching, leaving no significant gap an agent would need before invoking it.
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% and the schema explains geonameId format, nameLanguages filtering semantics, and geonamesUsername auth behavior in detail; the description adds no parameter-level guidance beyond what the schema already provides, 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?
The description opens with a specific verb and resource ('Fetch the full GeoNames record for one geonameId') and enumerates the record's contents, making it clearly distinct from search/reverse/children/country sibling tools that produce or consume geonameIds.
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?
It explicitly names the sibling tools that supply the required geonameId (geonames_search_places, geonames_reverse_geocode, geonames_get_children, geonames_get_countries), so an agent knows exactly where this lookup fits in a workflow.
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 700. 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). Case-insensitive. | |
| 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). Case-insensitive. | |
| 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 that was applied. |
| 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. |
| 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 read-only/idempotent/open-world, and the description goes well beyond them: it discloses that feature_classes and feature_codes spend no credits while postal_countries costs 1 credit/day and is cached, plus that geonamesUsername spends the caller's own credit and requires free web services enabled. That is exactly the cost/caching behavior an agent needs before invoking.
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 tight sentences, purpose front-loaded, with the free-vs-credit distinction placed last. Every clause earns its place, though the topic enumeration is somewhat dense.
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?
An output schema exists so return shapes need no explanation, and the description covers all three topics plus their cost and caching semantics. A brief word on how filters interact across topics (e.g., nameContains applying to postal_countries too) is the only minor gap.
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 still adds value by tying filters to topics (feature_codes filterable by class and text) and by pairing each topic with its data size, which helps an agent reason about pagination via limit/offset.
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 ('Decode... vocabulary') and resource, then enumerates exactly the three topics it can return with their sizes (9 classes, 684 codes, 122 countries). This clearly distinguishes it from sibling place-lookup tools like geonames_search_places or geonames_get_place.
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?
'Decode GeoNames vocabulary used by the other tools' frames the use case — it is a lookup of vocabulary needed to interpret the other tools' outputs — and the per-topic credit note tells the agent which topic is cheap. It does not explicitly state when-not to use it, but the context is clear.
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 50. 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 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. | |
| 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. 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. | |
| 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 that was applied. |
| 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, nearby is full, 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 nearby is full at nearbyLimit, so more may lie within the radius. |
| 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 cover the safety profile (readOnly, idempotent, openWorld), and the description goes well beyond them: it discloses credit costs per operation, the exact offshore/sea resolution behavior, that coastalBufferKm up to 50 matches the nearest country, that nearby/timezone lookups keep the exact point, and that PPLX/PPLH places are marked by featureCode. This is unusually rich behavioral context.
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 purpose is front-loaded in the first clause and every clause carries substantive information about a 10-parameter tool. It is one dense paragraph rather than a structured list, which slightly hurts scanability, but there is little waste for the complexity involved.
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?
An output schema exists, yet the description still names the key return fields (geonameId, ISO 3166-2, distanceInKm, timezone components), covers offshore edge cases, credit accounting, and alternate modes. Combined with 100% schema coverage and annotations, an agent has everything needed to invoke it 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 description coverage is 100%, so the baseline is 3, but the description adds real value beyond the schema: it links nearbyLimit=0 to skipping the 3-4 credits, explains why coastalBufferKm exists (harbor/pier/shoreline edge cases) and that it costs no extra credit, and clarifies the non-combinability rules with cities. This lifts it above the schema-only baseline.
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 precise verb+resource ('resolve a latitude/longitude to the country and admin subdivisions') and enumerates the exact outputs (ADM levels, geonameId, ISO 3166-2, ocean/sea fallback, nearest places with distances). An agent can immediately tell this apart from search_places or get_place, which are name-based lookups.
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?
Clearly explains when to switch behavior: set featureClasses/featureCodes to list nearest features instead, cities to filter by population tier, coastalBufferKm for harbor/shoreline points that fall outside country outlines. It also cross-references the sibling geonames_list_reference for feature codes. It lacks explicit when-not-to-use-this-tool-vs-siblings guidance (e.g. vs geonames_search_places), 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.
Search the GeoNames gazetteer of 13M+ places by name and filters: country, 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 100. 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. Case-insensitive. | |
| 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. Case-insensitive. | |
| offset | No | Entries to skip before the first one returned, for paging, 0 to 5000. Default 0. | |
| orderBy | No | Result order: relevance (GeoNames' default) or population, largest first. Case-insensitive. | |
| countries | No | 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. | |
| 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 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. | |
| 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. 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. | |
| 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 that was applied. |
| error | No | Present when the call failed. Absent on success. |
| shown | No | Places returned on this page. |
| notice | No | Guidance when nothing matched or more pages remain. |
| 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 readOnly/openWorld/idempotent, so the safety profile is covered; the description adds real value beyond that by disclosing cost ('1 GeoNames credit per call') and the default name-matching behavior that shapes results. It does not mention result pagination limits or ranking caveats, but those live 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?
Front-loaded with purpose and filter list, then the practical matching note and cost. It is dense but each clause carries meaning; the parenthetical feature-class/code examples are the only slightly redundant element given full schema coverage.
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 an 11-parameter, nested-schema tool with an output schema and annotations, the description supplies the decision-relevant extras (credit cost, default match behavior, filter-only requirement) and does not need to explain return values. Only the absence of explicit alternative-tool routing keeps it from a 5.
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 11 parameters in detail; the baseline is 3. The description's glosses (P populated places, PPLC capitals, population tier) add a small amount of orienting context but largely restate what the schema already says.
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') and enumerates the filter dimensions, so an agent knows exactly what this tool retrieves. It also names the sibling tools (geonames_get_place, geonames_get_hierarchy, geonames_get_children) that consume its geonameId output, which separates it from those id-based lookups.
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 default match semantics ('Berlin, Germany' pattern) and the filter-only fallback, which tells the agent how to frame a call. It does not explicitly route the agent away from siblings like geonames_reverse_geocode when coordinates (not names) are the input, so it stops short of full when-not guidance.
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_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.
