IPGeolocation MCP Server

Astronomy Data

get_astronomy

Read-only

Read-only single-date astronomy lookup via GET /v3/astronomy. Works on free and paid plans. Cost: 1 credit. This endpoint covers one date or real-time sun/moon position; get_astronomy_time_series provides daily sunrise, moon, and twilight…

Instructions

Returns { location, astronomy } plus ip for IP/server-address lookups. astronomy includes date/current_time, sunrise/sunset, moonrise/moonset, twilight blocks, day_length, sun/moon position, distance, status, moon_phase, moon_illumination_percentage, and moon_angle.

Selector priority is lat/long, location, ip, then the server's public egress IP when no selector is provided. lat and long must be provided together; date must be YYYY-MM-DD; elevation must be 0-10000 meters. time_zone changes timestamp formatting to include full dates. lang only changes location fields; non-English lang is paid-only and returns 401 on free plans.

Input Schema

Name	Required	Description
`ip`	No	IPv4 or IPv6 address to get astronomy data for that IP's location.
`lat`	No	Latitude coordinate. Highest priority. Must be used with long.
`date`	No	Date in YYYY-MM-DD format. Defaults to today.
`lang`	No	Response language for location fields in IP-based lookups (en, de, ru, ja, fr, cn, es, cs, it, ko, fa, pt, ar). Paid plans only. Free plan returns 401 for non-English language values.
`long`	No	Longitude coordinate. Must be used with lat.
`location`	No	City or address string (e.g. San Francisco, CA).
`elevation`	No	Elevation in meters above sea level (0-10000). Affects sunrise/sunset calculations for higher accuracy.
`time_zone`	No	IANA timezone name to express times in (e.g. America/New_York). If set, time fields include full date instead of just time.

Output Schema

Name	Required	Description
`data`	No	Present on success: API result after field selection, redaction, and transport limits.
`page`	No
`error`	No	Present on failure, with isError: true.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv2.0.3Oct 28, 2026

removedOutput schema / properties / data / additionalProperties / anyOf

Removed value: -[
-  {
-    "type": "null"
-  },
-  {
-    "type": "boolean"
-  },
-  {
-    "type": "number"
-  },
-  {
-    "type": "string"
-  },
-  {
-    "type": "array"
-  },
-  {
-    "type": "object"
-  }
-]

addedOutput schema / properties / data / additionalProperties / type

Added value: +[
+  "null",
+  "boolean",
+  "number",
+  "string",
+  "array",
+  "object"
+]

Addedv2.0.1Oct 13, 2026
Removedv2.0.0Jul 25, 2026
First observedv1.0.10Mar 16, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already cover readOnlyHint and openWorldHint, yet the description adds plan gating, per-call credit cost, the 401 failure mode for non-English lang on free plans, and the pairing constraint on lat/long. It also describes the response envelope ({ location, astronomy } plus ip for IP-based lookups), which goes well beyond what annotations declare.

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 identity, endpoint, plan, and cost before the sibling comparison, then constraints. Slightly over-allocated to enumerating every field inside the astronomy object, which is partly redundant given an output schema exists, but the prose itself has no filler.

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

Completeness5/5

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

For an 8-parameter, zero-required, open-world lookup tool, the description covers selection logic, defaults, cost, plan restrictions, validation formats, and output shape. An agent could call it correctly from this text alone; 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 parameter baseline is 3; the description earns above that by adding the full selector precedence order and the implicit server-egress-IP fallback, which the schema does not state as a chain. It also restates date format, elevation bounds, time_zone formatting effect, and the free-plan 401 for non-English lang, giving genuine operational context beyond field descriptions.

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 ('single-date astronomy lookup via GET /v3/astronomy') with the scope constraint ('one date or real-time sun/moon position'), and explicitly names the sibling get_astronomy_time_series as the range-based alternative. An agent can disambiguate from siblings without opening the schema.

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?

Explicitly routes between this tool and get_astronomy_time_series on the single-date vs date-range axis, and states the selector priority chain (lat/long, location, ip, then server egress IP when nothing is provided). Plan eligibility and credit cost are also disclosed, so the when-to-use decision is fully supported.

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

Deploy Server