alma-corpus-mcp

rotational_diagram

Fit LTE line intensities to estimate rotational temperature and total column density, optionally correcting for opacity and using partition tables.

Instructions

LTE rotational (population) diagram: fit ln(N_u/g_u) = ln(N_tot/Q(T_rot)) - E_u/T_rot.

Each line dict: freq_ghz, a_ul (s^-1), e_u_k (K), g_u, w_k_kms (integrated intensity, K km/s) and w_err_k_kms. Instead of w_k_kms you can give flux_jy_kms with bmaj_arcsec, bmin_arcsec (converted with the RJ 1.222e6 factor). flux_jy_kms must be the per-beam integrated intensity in Jy/beam km/s (moment 0 at the position), not a spatially integrated flux in Jy km/s, unless the source is smaller than the beam. For tau_correction also give fwhm_kms per line. N_u = 8 pi k nu^2 W / (h c^3 A_ul) / beam_filling (thin, RJ, background neglected). Errors on W get flux_cal_frac in quadrature. Q(T) from partition_table (log-log interpolation; include vibrational states) or a linear rotor approximation Q = kT/(hB) + 1/3. tau_correction fits ln N_tot and T_rot jointly with each line's thin-assumption column modelled as N_u (1 - exp(-tau))/tau, tau the Gaussian peak opacity from N_u, T_rot and fwhm_kms (Goldsmith and Langer 1999 C_tau). Limits: needs >= 3 lines over a range of E_u; T_rot is a lower limit to T_kin for subthermal gas; beam filling < 1 and opacity make N a lower limit; blends bias it.

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": {
      "lines": "<lines>"
    },
    "name": "rotational_diagram"
  }
}

Input Schema

Name	Required	Description	Default
`lines`	Yes
`beam_filling`	No
`flux_cal_frac`	No
`tau_correction`	No
`partition_table`	No
`linear_rotor_b_ghz`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 9, 2026

TDQS

A3.8/5.0

Behavior4/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 well: it discloses unit conventions, the RJ 1.222e6 conversion, per-beam vs spatially integrated flux caveats, error propagation via flux_cal_frac in quadrature, the partition-function interpolation scheme, and the Goldsmith & Langer tau treatment. The main gap is that it never says what the tool returns (fitted N_tot, T_rot, uncertainties, fit quality) and there is no output schema to cover that.

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 text is dense and front-loaded with the governing equation, and essentially every clause carries technical content — no filler. It is written as one long run-on paragraph without line breaks or bullets, which makes scanning harder than it needs to be, but nothing is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a six-parameter computational tool with zero schema descriptions, no annotations, and no output schema, the description covers inputs, physics assumptions, and failure modes thoroughly. The remaining shortfall is the absent return-value description and the lack of routing guidance among the many sibling fitting tools.

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 0% and the lines array is untyped (additionalProperties: true), yet the description enumerates its expected keys (freq_ghz, a_ul, e_u_k, g_u, w_k_kms, w_err_k_kms, plus the flux_jy_kms/bmaj/bmin alternative and fwhm_kms under tau_correction) with units. It also explains flux_cal_frac and partition_table roles; only linear_rotor_b_ghz is described obliquely via 'Q = kT/(hB) + 1/3' and beam_filling's default meaning is unstated.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/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 implicitly through the defining equation 'fit ln(N_u/g_u) = ln(N_tot/Q(T_rot)) - E_u/T_rot', making it unambiguous that this builds an LTE population/rotational diagram and fits N_tot and T_rot. It is clearly distinct from physical siblings like lte_column_density in practice, but it never names or contrasts an alternative, so differentiation is left to inference.

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

Usage Guidelines3/5

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

It gives a hard precondition ('needs >= 3 lines over a range of E_u') and flags when the derived quantities are limits rather than measurements, which is useful usage context. However, there is no explicit statement of when to choose this over lte_column_density or fit_gaussian_lines, nor any guidance on preparing inputs from moment maps versus Gaussian fits.

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