mcp-stargazing

Plan Stargazing Session

plan_stargazing_session

Read-onlyIdempotent

Plan a stargazing session by comparing one to seven nights and nearby locations, returning the selected observing window and equipment-matched targets.

Instructions

Preferred end-to-end planning entry point for choosing when, where, and what to observe across one to seven nights.

Use when: you need a complete observing decision or comparisons of places and nights. Do not use when: you only need raw weather, celestial facts, or task status. Requires: request.location (place name, center/radius, or exact bounds) and start_date; timezone, one-to-seven nights, observing goal, equipment preset/overrides, and supported preference fields have explicit defaults or are optional. A center/radius is a regional search, not a plan locked to the center point. The radius becomes an approximate search box, not a strict circular distance filter. Quietness/popularity adjustments require the corresponding preference flags. Pass request as a JSON object, not a JSON string; inspect resolved_location before describing a candidate as the exact user-specified site. Returns: normalized request, decision, alternatives, evidence, uncertainties, missing inputs, ranking-change conditions, and next actions in the standard envelope. Weather evidence uses dated night-hour forecasts. Missing weather or no usable window excludes a candidate from decision and alternatives; unranked_planning_reference evidence retains known location/sky facts with weather_unknown or no_usable_window status. If none qualify, decision=null. Partial coverage remains provisional. Civil-dark windows are not astronomical darkness. Interpretation: recommendation_score is a relative ranking, not a probability or an absolute go/no-go threshold. _meta.status=success means execution succeeded; decision=null means no selected session. A null observation_window means no usable window was established, not an all-night opening. Inspect evidence, uncertainties, missing_inputs and next_actions even on success. nightly_weather_unavailable and no_usable_observation_window are high-uncertainty warnings; long_range_forecast requires a forecast recheck near departure. Never replace missing night hours with summary.current or summary.daily, or infer a provider from weather wording. Civil darkness means Sun below -6 degrees, not astronomical darkness at -18 degrees; its duration is not guaranteed exposure time. Popularity/quiet scores are heuristics, not measured noise or calibrated crowd probabilities. When equipment is supplied, decision.targets already contains equipment-matched targets; use that list to answer the selected session's target question without a second lookup. Keep the returned target order; do not compare scores across generic and equipment rankings. This is a synchronous call and can exceed a client default deadline; a timeout does not establish that a background planning task exists. Follow-up: get_shooting_plan for an imaging schedule at the selected place/night; get_weather_by_position for updated weather facts. Inspect missing inputs and next actions before treating a degraded decision as final.

Input Schema

Name	Required	Description	Default
`request`	Yes

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.10.0Oct 28, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Goes well past the annotations (readOnly/idempotent/openWorld) by disclosing that this is a synchronous call that can exceed a client deadline and that a timeout does not imply a background task exists. It also explains degradation behavior (missing weather excludes a candidate, decision=null when none qualify, unranked_planning_reference retention) and warns the agent to inspect evidence, uncertainties and missing_inputs even on success.

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, use-when/when-not, requirements and return shape in that order, which is the right structure for a complex planning entry point. It is long and carries some redundancy — civil vs astronomical darkness is asserted twice ('Civil-dark windows are not astronomical darkness' and later 'Civil darkness means Sun below -6 degrees, not astronomical darkness at -18 degrees') — so it is dense rather than tight.

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?

Even with an output schema present, the description adds the interpretation layer an agent actually needs: recommendation_score is relative not probabilistic, _meta.status=success is separate from decision=null, null observation_window is not an all-night opening, and the named high-uncertainty warnings plus long_range_forecast recheck. It also closes the equipment loop by pointing to decision.targets to avoid a second lookup.

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?

The headline schema-coverage metric is 0% (only a $ref at the top level), so the description carries real weight — and it does: it states which fields are required, that timezone/nights/goal/equipment have defaults, that a radius becomes an approximate search box rather than a circular filter, and that quietness/popularity adjustment requires the corresponding flags. It also adds an operational rule the schema cannot express: pass request as a JSON object, not a JSON string, and inspect resolved_location before calling a candidate the exact site.

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?

States a specific verb+resource with scope: 'Preferred end-to-end planning entry point for choosing when, where, and what to observe across one to seven nights.' The word 'preferred' implicitly claims primacy over near-neighbors like get_best_stargazing_plan and get_multiday_stargazing_plan, but those overlapping planners are never named, so the agent still has to guess when the others win.

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:' (need a complete observing decision or comparisons of places and nights) and 'Do not use when:' (raw weather, celestial facts, task status) sections, plus a dedicated Follow-up block routing to get_shooting_plan and get_weather_by_position. When and when-not are both spelled out rather than inferred.

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