mcp-stargazing

get_best_stargazing_plan

Creates a ranked one-night stargazing plan for a geographic bounding box and observation time, scoring regional locations by weather, viewing windows, and targets.

Instructions

Create a composite stargazing plan for a region and time.

Use when: an existing bbox-first integration needs ranked regional places for one night. Do not use when: starting a new intent-based integration, providing a place name, comparing several nights, or only requesting weather facts. Requires: south/west/north/east bounds, observation time, and timezone. Returns: data.query, ranked data.candidates with scores, windows, weather and targets, and data.summary; all within the standard response envelope. recommendation_score is a relative ranking, not a probability or go/no-go threshold. _meta.status=success can still contain summary.warnings and candidate notes. Only candidates with dated weather and a usable window can be recommended. Missing-weather references retain their place weight without renormalization; weather base score/contribution/weight are zero compatibility placeholders, not bad-weather facts. summary.recommended_location_name is null when none qualify. Missing night-hour weather is unknown, not clear; a null best_observation_window is not an all-night opening. night_window is civil darkness (Sun below -6 degrees), not astronomical darkness (-18 degrees) or guaranteed exposure time. Inspect the returned candidate coordinates; a regional result is not a fixed-site plan. Follow-up: plan_stargazing_session is preferred for new integrations; get_multiday_stargazing_plan preserves bbox-first comparison across nights.

Input Schema

Name	Required	Default
`east`	Yes
`time`	Yes
`west`	Yes
`north`	Yes
`south`	Yes
`time_zone`	Yes
`network_type`	No	drive
`target_limit`	No
`max_locations`	No
`db_config_path`	No
`road_radius_km`	No
`candidate_limit`	No
`min_height_diff`	No
`weather_provider`	No	all
`observation_style`	No	balanced
`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.

Changed4 schema fields changedv0.10.0Oct 28, 2026
- addedInput schema / properties / avoid_popular_spots
```
Added value: +{
+  "default": false,
+  "type": "boolean"
+}
```
- addedInput schema / properties / observation_style
```
Added value: +{
+  "default": "balanced",
+  "type": "string"
+}
```
- 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"
+}
```
Addedv0.4.0Jun 27, 2026

TDQS

A4.1/5.0

Behavior4/5

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

With no annotations at all, the description carries the entire burden and does most of it: it discloses that recommendation_score is relative not probabilistic, that _meta.status=success can still carry warnings, that missing-weather candidates are zero-weight placeholders rather than bad-weather facts, and that night_window is civil (-6°) not astronomical (-18°) darkness. The remaining gap is operational — nothing says whether this is read-only, whether it is expensive/slow (db_config_path and road_radius_km hint at heavy geospatial computation), or what permissions it needs.

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?

Well front-loaded: purpose, use-when, do-not-use-when, requires, returns, then caveats. Nearly every line carries decision-relevant information, though the block of return-value caveats is lengthy and partly overlaps territory an output schema already covers.

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

Completeness3/5

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

Return-value semantics are covered far beyond what the output schema provides, so an agent knows how to interpret degraded results. But for an 18-parameter, annotation-free tool, the description leaves the majority of tuning parameters semantically undefined, which is the gap most likely to cause a wrong invocation (e.g., misusing observation_style or the three different limit parameters).

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

Parameters2/5

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

Schema description coverage is 0% across 18 parameters. The description only restates the six required ones ('south/west/north/east bounds, observation time, and timezone'), which the schema's required array already conveys. The twelve optional parameters — observation_style, weather_provider, candidate_limit vs max_locations vs target_limit, avoid_popular_spots, prefer_quiet_at_night, network_type, min_height_diff — get no meaning, valid values, or default rationale anywhere, so an agent must guess at all the ranking-affecting knobs.

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 — 'Create a composite stargazing plan for a region and time' — and immediately scopes it as bbox-first, night-scoped, and ranked. It explicitly names the siblings it is not (plan_stargazing_session, get_multiday_stargazing_plan), so an agent can distinguish it without opening any 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?

Contains an explicit 'Use when' clause, an explicit 'Do not use when' list with four named exclusions (new intent-based integration, place-name input, multi-night comparison, weather-only), and a 'Follow-up' line routing to the two preferred alternatives. This is the full when/when-not/alternative triad.

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