AstroWay Core astrology

Place search

astroway_geo_search

Read-onlyIdempotent

A place name to candidates with coordinates and the IANA zone, for a birthplace field. Matches a prefix, ignores case, accents and punctuation (krakow finds Kraków, St. Petersburg finds Saint Petersburg), and knows the names GeoNames carries in our 21 languages and older ones such as Kiev. Ranked by population, an exact name counting ten times its size, so an ambiguous name such as Springfield lists every town largest first; q=Springfield, Illinois or Springfield, MA narrows by region or country after the comma.

[Group: Astro-Geography] [Endpoint: GET /v1/geo/search] [Required: q] [Cost: 5 credits (Tier ½)]

Tool call template

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

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

Input Schema

Name	Required	Description
`q`	Yes	Place name or its beginning, in any of our languages and scripts. Case, accents and punctuation are ignored. Text after the first comma narrows by region or country instead: `Springfield, Illinois`, `Springfield, MA`, `Paris, US`.
`lang`	No	Language for `name`, `admin1` and `country`. Where GeoNames has no name in it, the GeoNames name stays. Matching always covers every language.
`limit`	No	How many candidates to return.
`fields`	No	Compact mode: comma-separated dotted paths to keep, relative to `data`, e.g. "planets.name,planets.longitude,houses.cusp". Omit for the whole response.
`country`	No	Restrict to these ISO 3166-1 alpha-2 codes, comma separated, up to 20.
`precision`	No	Compact mode: round fractional numbers to this many decimals. Longitudes carry 14 by default; 2 is finer than any chart is drawn.

Output Schema

Name	Required	Description	Default
`lang`	No
`note`	No
`count`	No
`query`	No
`dataset`	No
`results`	No
`attribution`	No

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 7, 2026

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already cover the safety profile (read-only, idempotent, non-destructive, closed-world), so the description only needs to add what the annotations cannot: it discloses the ranking algorithm (population order, exact match weighted tenfold), the 21-language GeoNames name coverage including historical names like Kiev, and the output shape. It omits what happens on no-match and does not mention pagination or credit cost inline.

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?

The content is front-loaded – output shape first, then matching rules, then ranking, then the disambiguation idiom – so an agent skimming the first clause already knows what it gets. The opening clause is telegraphic ("A place name to candidates...") and the single run-on sentence is dense, but no sentence is filler.

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

Completeness4/5

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

With an output schema present and rich annotations, the description does not need to explain return values, and it correctly focuses on matching and ranking behaviour that no structured field expresses. For a 6-parameter search tool whose required input is a single string, an agent has everything needed to call it and to interpret a large candidate list.

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

Parameters3/5

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

Schema description coverage is 100%, so the baseline is 3. The description restates the matching semantics (prefix, case/accent/punctuation folding) and comma narrowing that the `q` schema field already documents, and says nothing about `lang`, `limit`, `country`, or `precision`. Ranking by population with an exact-name boost is the only genuinely additive semantic, and it is about result ordering rather than parameters.

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

Purpose4/5

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

The description states precisely what the tool maps: a place name to candidates with coordinates and the IANA zone, scoped to a birthplace field. That is specific enough to distinguish it from the heavier geo siblings (acg, relocation, reverse). It stops short of naming the neighbouring tools (e.g. astroway_geo_timezone, astroway_geo_reverse) that an agent might confuse it with, which is what a 5 would require.

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

Usage Guidelines4/5

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

"For a birthplace field" gives a concrete usage context, and the comma trick ("Springfield, Illinois", "Springfield, MA") tells the agent how to disambiguate rather than dumping an unfiltered list. There is no explicit when-not guidance or mention of which sibling to prefer for reverse geocoding or timezone lookup.

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

All AstroWay Core astrology 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.

Resources

Need Help?