mcp-stargazing

analysis_area

Analyze a geographic bounding box to find dark, accessible stargazing spots with light pollution, elevation, and road access data. Returns paginated, cached candidate locations for a fixed regional search.

Instructions

Analyze a geographic area for suitable stargazing locations.

Use when: you need synchronous place candidates or cached pages for a fixed regional query. Do not use when: the search needs background polling/cancellation or a complete night plan. Requires: south/west/north/east bounds; keep search parameters fixed while changing pages. Follow-up: analysis_area with the same query for other pages; submit_area_analysis for background work; plan_stargazing_session for dates, weather, and target decisions.

This tool searches for dark, accessible locations with good viewing conditions. Results are cached based on search parameters.

Fast mode: Set road_radius_km=0 to skip road connectivity checks. This avoids OSMnx network downloads from Overpass API and is much faster — use it when you only need candidate locations with light pollution and elevation data, without road distance analysis.

Args: south, west, north, east: Bounding box coordinates. max_locations: Maximum number of candidate locations to find (before pagination). min_height_diff: Minimum elevation difference for prominence. road_radius_km: Search radius for road access. Set to 0 to skip road checks. network_type: Type of road network ('drive', 'walk', etc.). avoid_popular_spots: Penalize heuristically popular locations when ranking results. prefer_quiet_at_night: Favor locations that are likelier to quiet down at night. popularity_radius_km: Preference horizon for the popularity heuristics. db_config_path: Optional path to database config. page: Page number (1-based). page_size: Number of results per page.

Returns: Dict with keys "data", "_meta". "data" contains: - items: List of location results for the current page. - total: Total number of locations found. - page: Current page number. - page_size: Current page size. - resource_id: Cache key for the non-pagination search parameters.

Input Schema

Name	Required	Default
`east`	Yes
`page`	No
`west`	Yes
`north`	Yes
`south`	Yes
`page_size`	No
`network_type`	No	drive
`max_locations`	No
`db_config_path`	No
`road_radius_km`	No
`min_height_diff`	No
`avoid_popular_spots`	No
`popularity_radius_km`	No
`prefer_quiet_at_night`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.10.0Oct 28, 2026
- addedInput schema / properties / avoid_popular_spots
```
Added value: +{
+  "default": false,
+  "type": "boolean"
+}
```
- addedInput schema / properties / popularity_radius_km
```
Added value: +{
+  "default": 3,
+  "type": "number"
+}
```
- addedInput schema / properties / prefer_quiet_at_night
```
Added value: +{
+  "default": false,
+  "type": "boolean"
+}
```
First observedv1.0.0Jan 4, 2026

TDQS

A4.9/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so: it discloses result caching keyed on search parameters, the resource_id cache key contract for pagination, and a concrete cost/latency tradeoff (road_radius_km=0 skips OSMnx network downloads from Overpass API). It also explains that max_locations applies before pagination, avoiding a common misuse.

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 usage guidance, then a fast-mode callout, then a conventional Args block — well structured and scannable. The 'Returns' section partly repeats what the output schema already provides, so a little length is not strictly earned.

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 a 14-parameter, no-annotation, synchronous search tool with pagination and caching, the description covers invocation, cost tradeoffs, pagination stability, and output shape. Nothing an agent needs in order to call it correctly is missing.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must compensate, and it documents all 14 parameters — bounding box, pagination, elevation prominence, road radius, network type, the popularity heuristics and their radius, and db_config_path. Non-obvious semantics such as 'Set to 0 to skip road checks' and 'before pagination' add meaning the bare schema cannot convey.

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 and resource ('Analyze a geographic area for suitable stargazing locations') and immediately contrasts itself with the async sibling ('Do not use when: the search needs background polling/cancellation'), which is exactly the distinction from submit_area_analysis. An agent can route correctly without opening either 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?

Explicit 'Use when' / 'Do not use when' blocks name the conditions (synchronous place candidates, fixed regional query) and the alternatives (submit_area_analysis for background work, plan_stargazing_session for complete night plans). The follow-up line even tells the agent how to fetch further pages.

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