alma-corpus-mcp

co_gas_mass

Computes molecular gas mass from CO line luminosity, converting to CO(1-0) via line ratios and applying alpha_CO or X_CO factors, with optional uncertainty inputs.

Instructions

Molecular gas mass from a CO line luminosity.

L'_CO(1-0) = L'_CO(J-[J-1]) / r_J1, where r_J1 is the brightness-temperature (L') ratio. If you only have a flux-density ratio S_J/S_1, set ratio_is_flux_density=True: r_J1 = (S_J/S_1) / J^2 (CO). M_mol = alpha_CO L'_CO(1-0). alpha_CO in Msun (K km/s pc^2)^-1: 4.35 Galactic INCLUDING helium (x1.36; 3.2 without), 0.8 ULIRG/SMG convention (stated with helium in most papers; check). Or give x_co (cm^-2 (K km/s)^-1, e.g. 2e20, H2 only): alpha_H2 = X_CO x 2 m_H / (Msun pc^-2), about 3.2 for 2e20, and x1.36 for M_mol with helium. Returns both M_mol (with He) and M_H2 (without) with the factor used. alpha_co_err is an absolute error on the factor in use: on alpha_co, or on the derived alpha_mol when x_co is given (the default alpha_co is ignored then). Limits: alpha_CO depends on metallicity and environment (factors of several); r_J1 for mid-J lines is a large assumed term; a flux ratio used as r_J1 underestimates the mass by J^2.

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": {
      "l_prime_k_kms_pc2": "<l_prime_k_kms_pc2>"
    },
    "name": "co_gas_mass"
  }
}

Input Schema

Name	Required	Description	Default
`r_j1`	No
`x_co`	No
`j_upper`	No
`alpha_co`	No
`l_prime_err`	No
`alpha_co_err`	No
`l_prime_k_kms_pc2`	Yes
`alpha_includes_helium`	No
`ratio_is_flux_density`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 9, 2026

TDQS

A4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations at all, the description carries the full burden and does so well: it states the default alpha_co = 4.35 is Galactic and INCLUDES helium (x1.36 vs 3.2 without), explains that alpha_co_err is an absolute error on whichever factor is in use, and flags the non-obvious override that 'the default alpha_co is ignored' when x_co is supplied. It also discloses return behavior ('Returns both M_mol (with He) and M_H2 (without) with the factor used') and real caveats — metallicity dependence of factors of several, assumed r_J1 for mid-J, and a J^2 mass underestimate from using a flux ratio.

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?

Four short paragraphs, front-loaded with the definition and then the alternative input path and limits; every sentence carries units, defaults, or a caveat rather than filler. Density occasionally hurts scanability — hedge fragments like 'stated with helium in most papers; check' and 'about 3.2 for 2e20' slow parsing — but no line is expendable.

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 9-parameter, 0%-coverage, annotation-free tool with no output schema, the description is unusually complete: it gives equations, unit conventions for alpha_CO and X_CO, a default-plus-override rule, error semantics, and a partial statement of return values. The missing pieces are l_prime_err and an explicit account of what alpha_includes_helium toggles, which is what keeps it from a 5.

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 description coverage is 0%, so the description must compensate and largely does: r_j1, ratio_is_flux_density, alpha_co, x_co, j_upper (via the J-[J-1] and J^2 relations), alpha_co_err and the helium convention behind alpha_includes_helium all get substantive meaning. Two gaps remain — l_prime_err (presumably propagated error on the luminosity) is never mentioned, and alpha_includes_helium is only inferable from the 'x1.36' discussion rather than stated as a switch.

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?

Opens with a precise verb-and-resource statement: 'Molecular gas mass from a CO line luminosity', followed immediately by the governing equations (L'_CO = L'_CO(J-[J-1])/r_J1, M_mol = alpha_CO L'_CO). An agent can tell this is the CO-based mass derivation rather than a dust or dynamical mass tool. It never names a sibling (dust_mass_from_flux, dynamical_mass) to reinforce that boundary, so it stops short of a 5.

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?

Strong guidance exists at the input level: 'If you only have a flux-density ratio S_J/S_1, set ratio_is_flux_density=True' and 'Or give x_co ... instead' route the caller between the two conversion paths. However there is no tool-level routing — nothing says when to pick this over dust_mass_from_flux or line_luminosity, nor any prerequisite (e.g. that L'_CO must be computed first by line_luminosity). Usage is implied rather than prescribed.

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