MCP and assistant tools
The tools the in-page assistant and the MCP server share, generated from src/assistant/toolspec.js. The page's tools act on the analyzer; the MCP server's act on a session document (docs/FORMAT.md) with the same science code. Flags: read-only changes nothing; long may take minutes (a fit); asks first needs the user's consent in the page.
Try it against your server
Start the MCP server on your computer with this site allowed to call it (it still listens on 127.0.0.1 only):
node mcp/server.mjs --workspace ~/esl-work --http 8765 --allow-origin <this site's origin>Then connect below; every tool on this page gets a Try it box. See MCP server for the details.
Not connected. Start your server, then press Connect.
System
get_state
read-only · page and MCP server
The current analysis in full: system, every parameter with its value, whether it is free and its prior, loaded data, sampler settings, whether a fit exists. The CURRENT STATE card you are given each step is the short form of this; call it only when you need a detail the card leaves out.
No arguments.
Try get_state
list_examples
read-only · page and MCP server
List the worked examples that can be opened with load_example (id, title, kinds of data).
No arguments.
Try list_examples
load_example
asks first · page and MCP server
Open a worked example by id (ids: single, hd80606-tess, multi, hd80606-rv, hd80606-joint, hd80606-rm, toi1873, toy1873, toi1873-oc, kepler88, ttvpair; list_examples gives all). It opens with its stored posterior; pass fresh=true to open it without a result. Replaces what is loaded.
| Argument | Type | Description |
|---|---|---|
id required | string | Example id, e.g. "single" for the single-transit example. |
fresh | boolean | true: open without the stored result. |
Try load_example
search_catalog
read-only · page and MCP server
Find planet and host names in the bundled NASA Exoplanet Archive snapshot that match a partial name. Use before lookup_planet when unsure of the spelling.
| Argument | Type | Description |
|---|---|---|
query required | string | Part of a planet or star name, e.g. "wasp-12". |
limit | integer | How many names to return (default 8). |
Try search_catalog
lookup_planet
asks first · page and MCP server
Load a known planet or host from the catalogue snapshot: star, orbit and wide priors centred on the published values. Replaces the system parameters. Observations already loaded from files are kept, and T mid is moved by whole periods onto them; a simulated light curve is replaced. It does not fetch observations.
| Argument | Type | Description |
|---|---|---|
name required | string | Planet or host name, e.g. "WASP-12 b". |
kinds | array of string | Kinds of data the analysis will use (default ["transit"]). |
Try lookup_planet
new_session
MCP server only
Start an empty analysis: one planet with placeholder values around a Sun-like star, no data. Then set the real values (set_parameters), or use lookup_planet instead to start from the catalogue. Replaces the current session.
| Argument | Type | Description |
|---|---|---|
name required | string | Name of the system, e.g. "My target". |
Try new_session
set_parameters
page and MCP server
Set parameter values (the starting point of a fit, and the value a fixed parameter keeps). Give several at once. tmid may be an absolute date (BJD) or days from the time reference.
| Argument | Type | Description |
|---|---|---|
values required | object | Map of key to number, e.g. {"rprs": 0.12, "ecc": 0}. Parameter key: rprs, inc, per, tmid, ecc, omega, mplanet, ars (never free), ld0..ld3, a2, rvlin, rvquad, jit@rv1, mstar, rstar, teff, feh. A second planet's keys carry its letter: per@c. |
Try set_parameters
add_planet
page and MCP server
Add another planet to the system. Its keys carry its letter (per@c, rprs@c). Any existing fit result is cleared.
| Argument | Type | Description |
|---|---|---|
letter | string | Letter of the new planet (default: the next free one). |
parameters | object | Its values: rprs, inc, per, tmid, ecc, omega, mplanet (and ars when Kepler mode is off). Missing ones are copied from the first planet, with twice its period. |
Try add_planet
remove_planet
page and MCP server
Remove a planet (not the last one) from the system by its letter. Any existing fit result is cleared.
| Argument | Type | Description |
|---|---|---|
letter required | string | Letter of the planet to remove. |
Try remove_planet
set_kepler
page and MCP server
Turn Kepler mode on or off. On: a/R* follows from the stellar mass and radius, the period and the planet mass (needed for radial velocities and several planets). Off: a/R* is a fixed number you set.
| Argument | Type | Description |
|---|---|---|
on required | boolean | true to derive a/R* from Kepler's law. |
Try set_kepler
set_limb_darkening
page and MCP server
Choose the limb-darkening law and, optionally, its coefficients. Laws: uniform, linear (1 coefficient), quadratic (2), kipping (2), sqrt (2), nonlinear (Claret, 4). Coefficients are the parameters ld0..ld3 and can be freed with set_free. In the web app follow_star makes them follow the star (Teff, [Fe/H]) in a band instead. Any existing fit result is cleared.
| Argument | Type | Description |
|---|---|---|
law | "uniform" · "linear" · "quadratic" · "kipping" · "sqrt" · "nonlinear" | The law. |
coefficients | array of number | Coefficients in the law's order. Omit to keep or default them. |
follow_star | boolean | true: the coefficients follow the stellar parameters and the band; false: they are parameters. |
band | string | Bandpass name for follow_star, e.g. "TESS", "V", "R" (the analyzer lists its bands in an error when the name is unknown). |
Try set_limb_darkening
set_phase_curve
page and MCP server
Give a planet its own light (secondary eclipse and phase curve), or take it away. mode "harmonic": fpfs (planet-to-star flux ratio), contrast, hotspot (degrees), h2c, h2s; mode "map": fpfs and the map coefficients y10, y11, y1m1. The new keys can be freed with set_free. Any existing fit result is cleared.
| Argument | Type | Description |
|---|---|---|
planet | string | Planet letter (default: the first). |
on | boolean | false removes the planet's own light (default true). |
mode | "harmonic" · "map" | Parametrisation. |
lmax | integer | Degree of the map, 1 to 3 (map mode). |
parameters | object | Starting values, e.g. {"fpfs": 0.001, "hotspot": 10}. |
Try set_phase_curve
set_moon
page and MCP server
Give a planet a moon, or remove it. Keys: rmoon (moon radius / stellar radius), permoon (days), phmoon (orbital phase at mid-transit, 0 to 1), mmoon (moon mass / planet mass), imoon (degrees). They can be freed with set_free. Any existing fit result is cleared.
| Argument | Type | Description |
|---|---|---|
planet | string | Planet letter (default: the first). |
on | boolean | false removes the moon (default true). |
parameters | object | Starting values, e.g. {"rmoon": 0.03, "permoon": 2.5}. |
Try set_moon
set_nbody
page and MCP server
Turn N-body dynamics on or off: mid-transit times and velocities then come from an integration in which the planets pull on each other (needs two planets or more and Kepler mode). The light curve stays Keplerian. An evidence from an N-body fit is not comparable with a Keplerian one.
| Argument | Type | Description |
|---|---|---|
on required | boolean | true: use N-body dynamics. |
epoch | number | Time (BJD) at which the orbital elements are defined (default: the first planet's mid-transit time). |
linear | boolean | Fit a straight line in epoch to each planet's simulated times inside the likelihood. |
Try set_nbody
companion_search
long · page and MCP server
Search the mid-transit times of the planet on show for an unseen companion: N-body simulations on a grid of companion mass and period. Needs at least eight times and the planet's mass. Returns the best companion and whether it is significant, as the analyzer reports them. Takes seconds to a minute.
| Argument | Type | Description |
|---|---|---|
options | object | Optional grid settings: phases (starting phases per cell), masses (Jupiter masses to try), ratios (companion period over the planet's period to try), refine (true or false). Omit for the defaults. |
Try companion_search
add_companion
page and MCP server
Add a companion found by companion_search to the system as a new planet, with N-body dynamics on.
| Argument | Type | Description |
|---|---|---|
candidate | object | The companion as companion_search returned it. Omit to use the last search. |
Try add_companion
Data
describe_data
read-only · page and MCP server
What data are loaded, by handle: the light curve (points, time span, cadence, median error, epochs, airmass column), each radial-velocity set, the timing list. Numbers only, never the arrays.
No arguments.
Try describe_data
load_light_curve
asks first · page and MCP server
Load a light curve (time, flux, error, optional airmass; CSV or whitespace columns, AAVSO and EXOTIC files, magnitudes, JD/BJD/MJD/BTJD) from an attached file. It replaces the loaded light curve, or with add_epoch=true is added as another night of the same planet. Give "planet" when the user names the target, so the system matches the data. Mid-transit time moves by whole periods onto the data.
| Argument | Type | Description |
|---|---|---|
file | string | Name of an attached file (see list_files). Preferred: the data never enters the conversation. |
text | string | The rows themselves as text, only for a few short lines typed by the user. |
planet | string | The planet the user says this file is of, copied from the user's own words (never from the state of the app). Its parameters are then taken from the catalogue so the system matches the data. |
name | string | Label for the data set. |
add_epoch | boolean | true: keep the loaded light curve and add this one as another epoch. |
exposure_min | number | Exposure time in minutes, when known (default: the cadence). |
Try load_light_curve
load_radial_velocities
page and MCP server
Add radial velocities (time, velocity m/s, error, optional instrument column) from an attached file. Each instrument becomes its own set with its own zero point and jitter (jit@rv1, ...). Turns velocities on in the fit and frees the planet mass.
| Argument | Type | Description |
|---|---|---|
file | string | Name of an attached file (see list_files). Preferred: the data never enters the conversation. |
text | string | The rows themselves as text, only for a few short lines typed by the user. |
name | string | Label, used when the file has no instrument column. |
Try load_radial_velocities
set_timings
page and MCP server
Set the list of mid-transit times of the planet on show (rows of "time, uncertainty" or "epoch, time, uncertainty", days). They feed fit_ephemeris and timing_periodogram, and the fit when choose_data turns timing on. Replaces that planet's list.
| Argument | Type | Description |
|---|---|---|
file | string | Name of an attached file (see list_files). Preferred: the data never enters the conversation. |
text | string | The rows themselves as text, only for a few short lines typed by the user. |
Try set_timings
simulate_light_curve
asks first · page and MCP server
Replace the light curve with a simulated observation of the first planet from the current parameters: white noise, optional airmass trend, one or several transits. For teaching, planning and testing a fit set-up.
| Argument | Type | Description |
|---|---|---|
noise_ppm | number | Scatter per point in parts per million (default 500). |
exposure_min | number | Exposure and cadence in minutes (default 2). |
baseline_hr | number | Out-of-transit time on each side, hours (default 2). |
airmass | boolean | Add an airmass trend (ground-based night). |
n_epochs | integer | Number of transits (default 1). |
epoch_step | integer | Orbits between simulated transits (default 1). |
seed | integer | Random seed (default 1). |
mid_transit | number,string | Simulate the transit of a given night: "planned" for the event chosen on the plan page (PROJECT), or its predicted mid-transit time as a BJD_TDB. T mid and its prior are moved there first. |
Try simulate_light_curve
edit_data
asks first · page and MCP server
Changes to the loaded data: set the exposure time, remove one epoch of the light curve, trim it to a time window, clip outliers against the current model, bin it; remove a radial-velocity set; clear the timing list. After a change to the data, evidences of earlier runs are no longer comparable.
| Argument | Type | Description |
|---|---|---|
exposure_min | number | Exposure time of the light curve in minutes. |
remove_epoch | integer | Number (1-based) of the light-curve epoch to remove. |
trim | array of number | Keep only the points between two times [t0, t1] (BJD, or days from the time reference). |
clip_sigma | number | Remove points further than this many robust standard deviations from the current model. |
bin_min | number | Bin the light curve into means over this many minutes. |
remove_velocities | string | Name of the radial-velocity set to remove. |
clear_timings | boolean | true: empty the timing list. |
Try edit_data
Fit
choose_data
page and MCP server
Choose which kinds of data enter the likelihood: the light curve, the radial velocities, the timing list. Give only the ones to change.
| Argument | Type | Description |
|---|---|---|
light_curve | boolean | Use the light curve. |
radial_velocity | boolean | Use the radial velocities. |
timing | boolean | Use the mid-transit times. |
Try choose_data
set_free
page and MCP server
Choose which parameters the fit samples. Keys in "free" become free (with a default prior if they had none); keys in "fixed" are held at their current value. Others are left as they are. ars (a/R*) can never be free.
| Argument | Type | Description |
|---|---|---|
free | array of string | Keys to free, e.g. ["ecc", "omega"]. Parameter key: rprs, inc, per, tmid, ecc, omega, mplanet, ars (never free), ld0..ld3, a2, rvlin, rvquad, jit@rv1, mstar, rstar, teff, feh. A second planet's keys carry its letter: per@c. |
fixed | array of string | Keys to hold fixed. |
Try set_free
set_prior
page and MCP server
Set the prior of one parameter. uniform: a = minimum, b = maximum. normal: a = mean, b = standard deviation. For tmid, a (and b when uniform) may be absolute dates. Changing a prior changes the evidence: compare only runs with the same priors on shared parameters.
| Argument | Type | Description |
|---|---|---|
key required | string | Parameter key: rprs, inc, per, tmid, ecc, omega, mplanet, ars (never free), ld0..ld3, a2, rvlin, rvquad, jit@rv1, mstar, rstar, teff, feh. A second planet's keys carry its letter: per@c. |
type required | "uniform" · "normal" | Prior family. |
a required | number | uniform: minimum. normal: mean. |
b required | number | uniform: maximum. normal: standard deviation. |
Try set_prior
set_sampler
page and MCP server
Nested-sampling budget. nlive: live points (default 400; 100 to 200 for a quick look, more for a final run). max_calls: stop after this many likelihood calls. max_seconds: wall-clock limit. A run that stops on a budget is not converged and its evidence is only a lower bound.
| Argument | Type | Description |
|---|---|---|
nlive | integer | Live points. |
frac_remain | number | Stop when this fraction of the evidence remains (default 0.01). |
max_calls | integer | Budget of likelihood calls. |
max_seconds | number | Wall-clock budget in seconds. |
seed | integer | Random seed. |
Try set_sampler
run_fit
long · page and MCP server
Run nested sampling with the current free parameters, priors and data, wait for it to finish, and return the result: evidence ln Z, convergence, each free parameter as median +/- interval, key derived quantities, warnings. Takes seconds to minutes. At least one parameter must be free.
| Argument | Type | Description |
|---|---|---|
label | string | Short name for this run in the comparison table, e.g. "circular". |
Try run_fit
fit_progress
read-only · page and MCP server
How far a running fit is: iterations, likelihood calls, the evidence so far and the fraction that remains.
No arguments.
Try fit_progress
stop_fit
page and MCP server
Stop a fit that is running. The partial posterior is kept but is not converged.
No arguments.
Try stop_fit
Results
get_results
read-only · page and MCP server
The current fit result: evidence, convergence, chi-squared, fitted parameters (median, +, -), warnings; with derived=true also every derived quantity (impact parameter b, duration t14, planet radius, K, a/R*, density, equilibrium temperature). Quote these numbers; never compute your own.
| Argument | Type | Description |
|---|---|---|
derived | boolean | Include all derived quantities. |
keys | array of string | Only these parameter or derived keys. |
Try get_results
explain_results
read-only · page and MCP server
The current fit explained in plain words by the software: what each main number means (radius ratio, depth in percent, planet radius, inclination and impact parameter, duration in hours, eccentricity, fit quality, evidence), with unit conversions already done, plus the warnings. Use this when the user asks what the results mean, and relay its sentences.
No arguments.
Try explain_results
get_derived
read-only · page and MCP server
The derived quantities of the system as the software computes them (impact parameter, durations, planet radius and mass, K, a/R*, densities, equilibrium temperature), with intervals when a fit exists. Quote them; never derive a quantity yourself.
| Argument | Type | Description |
|---|---|---|
planet | string | Planet letter (default: all planets). |
Try get_derived
list_runs
read-only · page and MCP server
The fits made so far (the run history): id, label, free parameters, ln Z with its error, whether each converged. restore_run brings one back.
No arguments.
Try list_runs
restore_run
page and MCP server
Bring an earlier run back: its set-up, values and posterior become the current ones (undo returns to where you were).
| Argument | Type | Description |
|---|---|---|
run required | integer,string | Run id from list_runs or compare_runs, e.g. 2. |
Try restore_run
compare_runs
read-only · page and MCP server
Compare the runs made on the current data: ln Z of each, its difference from the best run, and the reading in words (indistinguishable, weakly / moderately / strongly disfavoured) with the cautions that apply. Report the reading and cautions as returned; do not reinterpret the numbers.
No arguments.
Try compare_runs
run_experiment
long · page and MCP server
Run a queue of fits one after another on the current data and compare them: "eccentricity" (circular orbit against free e and omega), "limb_darkening" (coefficients fixed against free), "airmass" (with and without the airmass slope), "companion" (without and with one planet of the system), or "custom" with your own variants. Waits for every run, then returns the comparison table, the reading and cautions as the analyzer computes them, and writes a Markdown report file. Use this instead of calling run_fit several times.
| Argument | Type | Description |
|---|---|---|
kind required | "eccentricity" · "limb_darkening" · "airmass" · "companion" · "custom" | Which experiment. |
planet | string | For kind "companion": letter of the planet to fit with and without (default: the last one). |
variants | array of object | For kind "custom": the models to compare, each applied on top of the current set-up. |
report | string | File name of the report (default "experiment_report.md"). |
Try run_experiment
Timing
fit_ephemeris
read-only · page and MCP server
Fit a linear and a quadratic ephemeris to the mid-transit times of a planet: T0, period with uncertainties, chi-squared, BIC of each, the period change dP/dt, and the next predicted transits. Needs at least 2 times (4 for the quadratic).
| Argument | Type | Description |
|---|---|---|
planet | string | Planet letter (default: the first). |
upcoming | integer | How many future transits to predict (default 3). |
Try fit_ephemeris
timing_periodogram
read-only · page and MCP server
Search the timing residuals (O - C) for a periodic variation: highest periodogram peaks with false-alarm probabilities, the comparison of linear and sinusoidal models, and a verdict in words with its caveats. Needs at least 6 times. Report the verdict as returned.
| Argument | Type | Description |
|---|---|---|
planet | string | Planet letter (default: the first). |
bootstrap | integer | Bootstrap resamplings for the false-alarm level (0 = analytic only, default 0). |
Try timing_periodogram
compute_model
read-only · page and MCP server
Evaluate the model at the current parameter values: transit depth, duration, impact parameter, chi-squared against the loaded data and the scatter of the residuals. With file set, also writes the model curve (time, model flux, data, residual) as CSV for the user.
| Argument | Type | Description |
|---|---|---|
file | string | File name for the curve, e.g. "model.csv". Omit for the summary only. |
Try compute_model
View
set_view
in the page only
Change what the page shows: the side tab (system, data, fit, results, timing), the plot (light curve or radial velocities), folding on the period, all planets together, or which planet is on show.
| Argument | Type | Description |
|---|---|---|
tab | "system" · "data" · "fit" · "results" · "timing" | Side tab to open. |
plot | "lc" · "rv" | Lower plot. |
fold | boolean | Fold the plot on the period. |
all_planets | boolean | Show every planet's model. |
planet | string | Letter of the planet to show. |
Export
export_file
page and MCP server
Write one or several result files and give them to the user: session (the whole analysis as JSON, reloadable), report (Markdown: system, data, priors, results), python (a script that reproduces the fit), latex (tables), results_csv (fitted and derived values), samples_csv (posterior draws), light_curve_csv, velocities_csv, timing_csv.
| Argument | Type | Description |
|---|---|---|
kinds required | array of string | Every file to write in this call, e.g. ["report", "session"]. |
name | string | File name, only when a single file is written (a sensible default is used when omitted). |
Try export_file
write_report
in the page only
Write the standard project report and give it to the user: one Markdown file with, always in this order, a summary of the headline numbers, the target and observation (from the observing project), the data reduction (from the photometry page), the system, data, fit set-up and result, the comparison of the runs made in this conversation, a methods paragraph with citations, the figures, how to reproduce it, and the references; with it a BibTeX file, the session file, and the light-curve and corner figures. Call it at the end of an analysis, after run_fit (and run_experiment when models were compared).
| Argument | Type | Description |
|---|---|---|
title | string | Report title (default: the project or system name). |
author | string | Author line, only if the user gave a name. |
figures | boolean | Also write the figures (default true). |
get_figure
in the page only
Make a figure of the analysis as a PNG: it is shown in the chat and listed with the files for download. Figures: light_curve (with model and residuals), residuals, rv (radial velocities), corner (posterior; needs a fit), oc (timing O - C), phase (phase curve), map (brightness map), moon, system (the 3D view), periodogram and limb_darkening (these two must be on screen).
| Argument | Type | Description |
|---|---|---|
which required | "light_curve" · "residuals" · "rv" · "corner" · "oc" · "phase" · "map" · "moon" · "system" · "periodogram" · "limb_darkening" | Which figure. |
name | string | File name (default: <which>.png). |
dark | boolean | true: dark background (default: white, as for print). |
import_session
asks first · page and MCP server
Open an ESL session file (JSON written by export_file kind "session" or by the analyzer's Save) from the attached files. Replaces everything loaded, and restores the stored result if the file has one.
| Argument | Type | Description |
|---|---|---|
file required | string | Name of the attached session file. |
Try import_session
Saves
save_analysis
page and MCP server
Save the current analysis (system, data, set-up, result) under a name so it can be reopened later with open_saved.
| Argument | Type | Description |
|---|---|---|
name required | string | Name of the saved analysis. |
Try save_analysis
list_saved
read-only · page and MCP server
List the saved analyses (id, name, date).
No arguments.
Try list_saved
open_saved
asks first · page and MCP server
Reopen a saved analysis by its id from list_saved. Replaces what is loaded.
| Argument | Type | Description |
|---|---|---|
id required | string,number | Id from list_saved. |
Try open_saved
delete_saved
asks first · page and MCP server
Delete a saved analysis by its id. Permanent.
| Argument | Type | Description |
|---|---|---|
id required | string,number | Id from list_saved. |
Try delete_saved
undo
page and MCP server
Undo the last change to the analysis (or redo with redo=true).
| Argument | Type | Description |
|---|---|---|
redo | boolean | true: redo instead. |
Try undo
Files
list_files
read-only · page and MCP server
List the files available to this conversation: those the user attached and those you wrote (name, size, a one-line guess of what each holds).
No arguments.
Try list_files
read_file
read-only · page and MCP server
Look inside a file as text. Small files come back whole; large ones as a summary (lines, columns, numeric range of each column) plus the first lines. To use a data file, do not copy its rows: pass its name to load_light_curve, load_radial_velocities or set_timings.
| Argument | Type | Description |
|---|---|---|
name required | string | File name from list_files. |
max_chars | integer | Most characters of content to return (default 2000). |
offset | integer | Start at this character (to read on). |
Try read_file
write_file
page and MCP server
Write a text file (CSV, JSON, Markdown, a Python script) and give it to the user as a download. For standard outputs prefer export_file, which writes them from the analysis itself.
| Argument | Type | Description |
|---|---|---|
name required | string | File name with extension, e.g. "notes.md". |
content required | string | The whole text of the file. |