mcp-stargazing

get_shooting_plan

Generate a timed single-night astrophotography shooting plan with matched targets and moon data for fixed optics, location, and night.

Instructions

Generate a single-night astrophotography shooting plan.

Use when: optics, place, and night are fixed and you need matched targets in timed slots. Do not use when: you still need to choose a site or compare nights, or only need target ranks. Requires: focal length, observer coordinates, time, and the observing timezone (defaults to UTC); optional sensor, optical, and minimum-altitude settings. Follow-up: get_telescope_targets for target details; plan_stargazing_session to reconsider place, date, equipment preset, or observing constraints.

Runs match_telescope_targets then generate_shooting_schedule, returning targets + moon + timed shooting slots in one response. Interpretation: target altitude is at civil dusk, not the requested clock time; use altitude_curve or get_celestial_pos for another time. The schedule uses a civil-dark window (Sun below -6 degrees), not astronomical darkness (-18 degrees), and does not validate weather, access, obstructions or achieved integration time. Empty/null slots or exposure values are not an all-night imaging commitment.

Returns: data.targets[] — same structure as get_telescope_targets data.moon — {illumination, phase, moonrise, moonset, always_down, always_up, dark_fraction, altitude_curve} data.plan — {date, slots[{start_time, end_time, target_name}], total_exposure_min, moon_phase, moon_illumination, moon_delay_min} data.config — the TelescopeConfig used data.total — number of matched targets

Input Schema

Name	Required	Default
`lat`	Yes
`lon`	Yes
`time`	Yes
`limit`	No
`time_zone`	No	UTC
`mount_type`	No	equatorial
`aperture_mm`	No
`filter_type`	No
`min_altitude`	No
`barlow_factor`	No
`reducer_factor`	No
`focal_length_mm`	Yes
`sensor_width_mm`	No
`sensor_height_mm`	No
`sensor_pixel_size_um`	No
`central_obstruction_pct`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.7.0Jul 7, 2026

TDQS

A4.6/5.0

Behavior5/5

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

No annotations, so the description carries the full burden and does it well: it discloses the pipeline composition, that target altitude is reported at civil dusk rather than the requested clock time, that scheduling uses a -6 degree civil-dark window rather than -18 degree astronomical darkness, and that weather/access/obstructions are NOT validated. It also pre-empts misreading empty slots as an all-night imaging commitment.

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 and the use/do-not-use routing, then caveats, then returns. Every section earns its place except the multi-line Returns block, which largely restates the existing output schema.

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?

An output schema exists, so return values needn't be explained, yet the description still supplies the interpretive context an agent actually needs: which pipeline it wraps, the civil-dusk vs clock-time discrepancy, the -6 degree dark window, and the unvalidated factors.

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 coverage is 0% across 16 parameters, and the description only names the four required inputs plus a vague grouping of 'optional sensor, optical, and minimum-altitude settings'. Non-obvious knobs such as limit, mount_type, filter_type, barlow_factor/reducer_factor and central_obstruction_pct get no semantic explanation, so it only partly compensates for the coverage gap.

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?

Specific verb+resource ('Generate a single-night astrophotography shooting plan') with the composition stated explicitly: it runs match_telescope_targets then generate_shooting_schedule and returns targets + moon + timed slots in one response. That immediately distinguishes it from get_telescope_targets and the multi-night/stargazing planners.

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' (optics, place and night fixed) and 'Do not use when' (still choosing a site, comparing nights, only needing target ranks), with the alternative sibling named. The Follow-up line routes to get_telescope_targets and plan_stargazing_session for the excluded cases.

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