mcp-stargazing

get_telescope_targets

Rank deep-sky imaging targets for your telescope by entering focal length, location, time, and camera sensor specs to get a suitability-ranked target list.

Instructions

Recommend astrophotography targets for a telescope setup.

Use when: place, time, and optics are known and you need ranked deep-sky imaging targets. Do not use when: you only need naked-eye targets, a timed schedule, or a choice of sites. Requires: focal length, observer coordinates, time, and timezone; supply known sensor and optical details for matching. For equipment presets use plan_stargazing_session. Follow-up: get_shooting_plan for timed imaging slots; plan_stargazing_session if the observing place or night still needs comparison; get_celestial_pos for altitude at a specific clock time (the target altitude field is at civil dusk).

Given a telescope/camera configuration and observing location+time, returns a ranked list of deep-sky objects best suited for imaging. Interpretation: altitude is at civil dusk, not at the requested clock time; azimuth is at civil midnight. Use altitude_curve or get_celestial_pos for another time. transit_alt is the sampled peak within the civil-night window, in degrees; transit_time and curve time values are UTC Unix seconds. Null rise/set values mean no crossing was found inside that window, not that an object can never rise/set. suitability_score is a heuristic (higher is better), not a probability or weather clearance. Missing photometry is unknown; do not infer a seasonal visibility error from missing magnitude or from the civil-dusk altitude alone.

Args: focal_length_mm: Telescope focal length in mm (e.g. 250 for RedCat51) lon: Observer longitude in degrees lat: Observer latitude in degrees time: Observation time string "YYYY-MM-DD HH:MM:SS" time_zone: IANA timezone string (e.g. "Asia/Shanghai", "UTC") aperture_mm: Telescope aperture in mm (optional, for limiting magnitude) sensor_width_mm: Camera sensor width in mm (optional) sensor_height_mm: Camera sensor height in mm (optional) sensor_pixel_size_um: Camera pixel size in microns (optional) central_obstruction_pct: Central obstruction percentage (0-50) reducer_factor: Focal reducer factor (default 1.0) barlow_factor: Barlow/extender factor (default 1.0) mount_type: "equatorial" or "altaz" (default "equatorial") filter_type: Filter type — "Hα", "OIII", "SII", or None for LRGB limit: Maximum number of targets to return (default 20)

Returns: data.targets[] — ranked list, best first. Each target has: name, type, magnitude, catalog altitude (civil dusk, degrees), azimuth (civil midnight, degrees), dawn_altitude angular_size_arcmin, angular_size_min_arcmin, angular_size_pa_deg surface_brightness (mag/arcmin²), fov_fit_score, fov_fill_ratio suitability_score (0-100), mosaic_recommended, optimal_rotation_deg rise_time, set_time, transit_time (UTC unix timestamps), transit_alt (degrees) altitude_curve[{time, alt}] civil_dusk, civil_dawn, observation_time data.moon — {illumination, phase, altitude_curve, always_down, always_up, dark_fraction, moonrise, moonset} data.config — the TelescopeConfig used data.total — number of targets returned

Input Schema

Name	Required	Default
`lat`	Yes
`lon`	Yes
`time`	Yes
`limit`	No
`time_zone`	Yes
`mount_type`	No	equatorial
`aperture_mm`	No
`filter_type`	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.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 behavioral burden and does so well: it states required inputs, interpretation caveats for altitude/azimuth timing, null rise/set semantics, and that suitability_score is a heuristic rather than weather clearance. It also explains that missing photometry means unknown rather than a visibility error.

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?

The description is well structured and front-loaded with Use when / Do not use / Requires / Follow-up guidance. However, the Returns block substantially restates the output schema and makes the definition longer than strictly necessary, even though the interpretive notes within it are useful.

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 complex 15-parameter tool with no annotations and no schema descriptions, the definition is complete: it covers purpose, usage boundaries, required and optional inputs with units, alternatives, follow-ups, and return-field interpretation. The existing output schema means the description does not need to carry the entire return structure, but its added timing and null-value semantics are valuable.

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%, but the description documents all 15 parameters in the Args section, including optional fields, examples, units, enum-like values for filter_type and mount_type, defaults, and the 0-50 range for central_obstruction_pct. This fully compensates for the schema's lack of parameter 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?

The description states a specific verb and resource: recommend astrophotography targets for a telescope setup and return a ranked list of deep-sky imaging targets. It also distinguishes the tool from naked-eye targeting, timed scheduling, and site comparison, so an agent can identify its role among siblings.

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?

It explicitly names when to use it, when not to use it, and alternatives such as plan_stargazing_session and get_shooting_plan. Follow-up guidance is also provided for timed slots, site comparison, and altitude at a specific clock time.

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