geonames-mcp-server

List GeoNames children

geonames_get_children

Read-onlyIdempotent

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.

Input Schema

TableJSON Schema

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.

Output Schema

TableJSON Schema

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.

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedOct 18, 2026

changedInput schema / properties / geonameId / description

Previous 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."

changedInput schema / properties / hierarchy / description

Previous 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."

changedInput schema / properties / limit / description

Previous 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."

changedInput schema / properties / limit / maximum
```
Previous value: -500New value: +1000
```

changedOutput schema / properties / cap / description

Previous value: -"The limit that was applied."New value: +"The limit applied: limit as given, or 500 when it asked for more."

changedOutput schema / properties / notice / description

Previous 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."

First observedOct 2, 2026

TDQS

A4.8/5.0

Behavior5/5

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.

Conciseness4/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

All geonames-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.