Supernova Cosmology MCP Server

compare_sn_samples

Compare Type Ia supernova samples by overlaying binned Hubble residuals or cosmology contours and pairwise tensions to assess whether datasets agree.

Instructions

Compare SN samples: binned residual Hubble diagrams, or cosmology contours + tension.

Use to see whether Pantheon+, DES-SN5YR and Union3 agree. `residuals` overlays each
sample's full-covariance binned mu residuals vs the SAME flat LCDM fiducial (each sample's
offset removed separately - only shapes are comparable). `contours` runs fit_sn_cosmology
per sample, overlays the 2D contours (Om-w for wcdm, w0-wa for w0wacdm, 1D for lcdm) and
reports pairwise Gaussian tensions. CAUTION: the samples share SNe (low-z CfA/CSP/Foundation;
Union3 contains much of Pantheon+), so they are NOT independent. The quoted tension uses
Cov(diff) = C1 + C2, ignoring the positive cross-correlation, so it UNDER-states the
significance of a real difference - treat it as indicative, not a formal test.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "output_dir": "<output_dir>"
    },
    "name": "compare_sn_samples"
  }
}

Input Schema

Name	Required	Description	Default
`mode`	No	residuals: overlay binned Hubble residuals vs one fiducial (fast). contours: fit each sample (model) and overlay 68/95% contours + tension (heavy).	residuals
`model`	No	Model for mode=contours.	wcdm
`fid_Om`	No	Fiducial flat-LCDM Om for residuals.
`n_bins`	No	Bins per sample for residuals.
`n_grid`	No	Grid per parameter for contours (0 = model default).
`datasets`	No	Samples to compare.
`output_dir`	Yes	Directory for PNG + CSV/JSON outputs.

Output Schema

Name	Required	Description	Default
`files`	Yes
`status`	Yes
`message`	Yes
`metadata`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 6, 2026

TDQS

A4.6/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 burden and does so: it discloses cost asymmetry (residuals fast vs contours heavy), that each sample's offset is removed so only shapes are comparable, that contours internally calls fit_sn_cosmology per sample, and that the Gaussian tension ignores cross-correlation and therefore understates significance. These are exactly the caveats an agent needs to interpret results and avoid overclaiming.

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 purpose sentence followed by mode-by-mode detail and then the caution, so an agent can stop reading early if it only needs the gist. Heavy use of parentheticals makes it dense, and the non-independence caveat could be tightened, but no sentence is filler.

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 need not be explained. For a complex multi-mode comparison tool with 7 parameters, the description covers mode semantics, the internal fit dependency, comparability constraints, and the statistical caveat on the tension metric — nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: fid_Om is applied as the SAME fiducial across all samples for shape comparability, and the contour dimensions depend on model (Om-w for wcdm, w0-wa for w0wacdm, 1D for lcdm). That mapping is not in the schema.

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?

Opens with a specific verb and resource ('Compare SN samples') and immediately enumerates the two products: binned residual Hubble diagrams, or cosmology contours plus tension. This clearly separates it from siblings like plot_sn_contours and fit_sn_cosmology, which handle a single sample/dataset.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States the motivating question ('see whether Pantheon+, DES-SN5YR and Union3 agree') and scopes each mode: residuals for fast shape comparison against a shared fiducial, contours for per-sample fits and tension. It stops short of naming explicit alternatives such as 'for one dataset use plot_sn_contours' or 'for a single fit use fit_sn_cosmology', but the routing intent is clear.

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