Retrieve photometry for a source as a CSV table.

Returns all photometry points for the source in CSV format, suitable for direct analysis or loading into a pandas DataFrame.

Columns returned (mag format): mjd, filter, mag, magerr, limiting_mag, snr, instrument_name, origin

Columns returned (flux format): mjd, filter, flux, fluxerr, snr, instrument_name, origin

Retrieve spectra for a source.

By default returns a summary to avoid token overflow. Use verbose=True or format="csv" to get full spectral data.

Retrieve classifications for a source.

Returns all classifications assigned to the source, including the classification name, probability, and who made the classification.

Retrieve comments and annotations for a source.

Returns a summary of user comments and system/ML annotations on the source. Comments are human-readable notes; annotations are structured data (e.g., ML scores, cross-match results).

Retrieve host galaxy information for a source.

Returns the associated host galaxy from SkyPortal's galaxy catalogs, including angular separation (offset) and physical distance.

SkyPortal can link sources to host galaxies from catalogs like GLADE+. If a host association exists, this returns the galaxy's properties.

SUMMARY TOOL: Generate complete TNS/AstroNote report for a transient.

USE THIS SINGLE TOOL when asked to create TNS reports, AstroNotes, or comprehensive source summaries. It combines all relevant data in one call.

This tool retrieves and formats ALL information needed for TNS submissions:

• Source identification (coordinates in deg and HMS/DMS)

• Discovery information (first detection, magnitude, date, instrument)

• Latest photometry and peak brightness

• Classification (type, probability, classifier)

• Spectroscopy (dates, instruments, redshift)

• Host galaxy information

Accepts ANY source identifier: SkyPortal obj_id, ZTF name, or TNS name.

When to use:

• User asks to "create/generate/write TNS report"

• User asks to "draft AstroNote" or "prepare ATel"

• User asks for "summary of [source]"

• User mentions "TNS submission" or "classification report"

Do NOT call multiple other tools (photometry, spectra, classifications) separately when this single tool provides everything together.

Analyze light curve evolution for multiple photometric bands.

Calculates key temporal properties of a transient's light curve including rise time, fade time, total duration, and pre-peak variability (flares) for each requested photometric band.

Handles incomplete light curves:

• Still rising: Reports time from first detection to current

• Still fading: Reports time from peak to current

• Returned to baseline: Reports complete rise + fade times

Generates CSV data file + Jupyter notebook with interactive Plotly plots showing all bands overlaid, plus editable analysis code cells.

Analyze color evolution and color at peak brightness.

Calculates color curves (band1 - band2) using BOTH methods:

• Matched: Day-to-day colors (pairs close observations)

• Interpolated: Rolling/continuous colors (interpolates for smooth curve)

Generates CSV data file + Jupyter notebook with overlaid plots.

Get the SkyPortal API quick reference guide.

Returns a reference of available API endpoints, required parameters, and usage patterns. Call once to load into context as needed.

Get the MCP tools quick reference guide.

Returns a comprehensive list of all available MCP tools organized by category, with common workflows and usage examples. Call once to load into context when needed.

Make an API call to SkyPortal.

⚠️ WRITE RISK: POST, PUT, and DELETE requests will permanently modify or delete data on your SkyPortal/Fritz instance. These operations cannot be undone through this tool. Always confirm the endpoint and payload before using a non-GET method.

Convert between MJD, JD, ISO datetime, and Unix timestamps.

Get URLs to browse a sky position in common astronomical surveys.

Provide either ra/dec coordinates or a source_id to auto-resolve coordinates from SkyPortal.

Search for sources in SkyPortal near a position (cone search).

Finds all sources within a specified radius of a sky position. Useful for checking if a source already exists in SkyPortal at a given location, or finding nearby sources.

Provide either ra/dec coordinates or a source_id to auto-resolve coordinates.

Generate a Jupyter notebook to bulk download ZTF light curves from Fritz.

Creates a ready-to-run .ipynb notebook that uses ztfquery's Fritz integration to download alert photometry (detection epochs) for multiple sources with multiprocessing, save results to CSV, and create interactive Plotly plots.

Note: This downloads alert photometry, not forced photometry. For forced photometry (including non-detections/upper limits), use the IRSA ZTF forced photometry service.

Requires: ztfquery + Fritz API token. Setup: from ztfquery.io import set_account; set_account('fritz', token_based=True)

Generate code to perform ZTF cone searches at multiple positions.

This tool generates Python code that searches for ZTF detections within a radius of specified sky coordinates. Useful for cross-matching catalogs or checking if known positions have ZTF coverage.

Use Case: When you have a list of coordinates (e.g., from a catalog, TNS, or previous observations) and want to find all ZTF detections nearby.

Generate code to bulk query Fritz/SkyPortal for multiple sources.

This tool generates code that uses ztfquery's Fritz interface to download photometry, spectra, and metadata for multiple sources from Fritz.

Use Case: When you need to download data products from Fritz for many sources at once (faster than individual API calls).

Note: Requires Fritz API token. Setup: from ztfquery.io import set_account; set_account('fritz', token_based=True)

Generate code to download ZTF alert packets for multiple sources.

This tool generates code that downloads raw ZTF alert packets, which contain the full alert history including candidate info, cutouts, and previous detections.

Use Case: When you need complete alert history or want to access alert-level data that isn't available in forced photometry.

Generate code to visualize ZTF field and CCD coverage.

This tool generates code to create sky maps showing ZTF field footprints and CCD layouts. Useful for understanding coverage and planning observations.

Use Case: When you need to visualize which parts of the sky are covered by specific ZTF fields or CCDs.

Get the reference for filtering candidates and sources on Fritz/SkyPortal.

Returns documentation on available query parameters for the /api/candidates endpoint: annotation-based filters for ML scores (real/bogus, star/galaxy), classification filters, redshift, photometry annotations, and more.

Call this when a user asks to filter, search, or scan for specific types of transients. It tells you what's filterable via API queries vs what requires fetching data and doing custom computation.

Note: This is for query-time filtering (scanning page searches), NOT for creating alert-time MongoDB filters that run on Kowalski.

Search for candidates matching specific criteria on the scanning page.

This performs query-time filtering of existing candidates (not alert-time filtering). Use this to search the scanning page for candidates matching specific properties.

IMPORTANT - Parameter Validation: Before executing this tool, ALWAYS confirm with the user that the filter parameters are reasonable. Explain what the filter will return and ask if they want to proceed. Examples:

• "I'll search for SNe Ia with braai score > 0.9 saved after 2024-01-01. Proceed?"

• "This will find likely galaxy transients (sgScore < 0.3). OK?"

• "Filtering for TDE candidates with ACAI_score > 0.8. Sound good?"

IMPORTANT - After Results: After showing results, offer to display the filter configuration JSON so the user can save it for future use or configure it in the UI.

Generate MongoDB filter JSON for a watchlist to monitor specific coordinates.

Watchlists are alert-time filters that flag new detections near specified sky positions. They run on the Kowalski backend as part of Fritz's alert stream processing. This tool generates the MongoDB aggregation pipeline JSON compatible with Fritz's filter system.

IMPORTANT - This is an ALERT-TIME filter:

• Runs automatically on every incoming alert from the telescope

• Different from query-time filtering (filter_candidates tool)

• Uses MongoDB aggregation pipeline syntax

RECOMMENDED WORKFLOW (MongoDB Compass): Fritz now recommends using MongoDB Compass for filter development:

1. Follow the tutorial: https://github.com/fritz-marshal/fritz/blob/main/doc/filter_tutorial.md

2. Use MongoDB Compass to build and test filters visually

3. Export the pipeline from Compass

4. Import to Fritz

ALTERNATIVE - Direct Use: You can also use the generated JSON directly:

1. Copy the generated JSON

2. Import to Fritz or use in MongoDB Compass as a starting point

3. Refine and test as needed

Compute observing windows for a source from specified telescopes.

USE THIS TOOL for all observability questions. Do NOT use the /api/sources/{id}/observability endpoint (that returns a PDF image which cannot be parsed).

Provide either a source_id (auto-resolves RA/Dec from SkyPortal) or explicit ra/dec coordinates.