alma-corpus-mcp

keplerian_mask

Build a 0/1 FITS mask cube for a thin rotating disk on a template cube grid, using mass, inclination, position angle, and velocity to select voxels.

Instructions

Build a Keplerian mask cube for a thin disk on the grid of a template FITS cube.

Disk coordinates: x_d = dRA sin(PA) + dDec cos(PA), y_d = (-dRA cos(PA) + dDec sin(PA)) / cos(i), r = sqrt(x_d^2 + y_d^2) with dRA (east) and dDec offsets in arcsec from the disk centre (default: the reference pixel of the cube). PA is east of north to the REDSHIFTED major axis. v_los = v_sys + sqrt(G M / r) sin(i) x_d / r. A voxel is in the mask if r_min <= r <= r_max and |v_chan - v_los| <= line_width_kms + dv/2. Each channel is then dilated by an elliptical beam (dilate_beams x beam FWHM). Writes a 0/1 FITS cube (spectral axis increasing) to out_path (default .keplerian_mask.fits next to the cube). Paths must lie inside the allowed folder (env ALMA_MCP_WORKDIR, default the server's working directory); an existing file is refused unless overwrite=true. Limits: thin disk only (no elevated emission surface, so 12CO back sides can fall outside); a mask built from assumed M*, i, PA biases weak-line maps toward that model.

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": {
      "fits_path": "<fits_path>",
      "m_star_msun": "<m_star_msun>",
      "inclination_deg": "<inclination_deg>",
      "pa_deg": "<pa_deg>",
      "distance_pc": "<distance_pc>",
      "v_sys_kms": "<v_sys_kms>",
      "r_max_au": "<r_max_au>"
    },
    "name": "keplerian_mask"
  }
}

Input Schema

Name	Required	Description	Default
`pa_deg`	Yes
`out_path`	No
`r_max_au`	Yes
`r_min_au`	No
`fits_path`	Yes
`overwrite`	No
`v_sys_kms`	Yes
`distance_pc`	Yes
`m_star_msun`	Yes
`dilate_beams`	No
`center_ra_deg`	No
`rest_freq_ghz`	No
`center_dec_deg`	No
`line_width_kms`	No
`inclination_deg`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 9, 2026

TDQS

A4.3/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 well: it discloses that the tool writes a 0/1 FITS cube, that the spectral axis increases, that an existing file is refused unless overwrite=true, and that paths must lie inside the allowed work folder. It also documents important limitations like thin-disk assumptions and model bias.

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 description is front-loaded with purpose and then moves into formulas and operational constraints. It is dense but every section is relevant to correct invocation; the formula block is heavy, but for a complex mask-building tool it largely earns its place.

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?

Given 15 parameters, no annotations, no output schema, and a file-writing side effect, the description is substantially complete: it covers the output file, overwrite semantics, path restrictions, assumed geometry, and model limitations. A few parameter meanings remain only implicit, preventing a perfect score.

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% across 15 parameters, so the description must compensate, and it does for many key inputs by explaining PA orientation, disk-centre defaults, r_min/r_max, line_width_kms, dilate_beams, out_path, and overwrite behavior. It still leaves distance_pc and rest_freq_ghz largely unexplained, so it is strong but not complete.

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?

The description states a specific verb and resource: 'Build a Keplerian mask cube for a thin disk on the grid of a template FITS cube.' This is precise enough that an agent can distinguish it from generic spectral or moment-map tools without opening the schema.

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?

Usage is implied by the operation and by the stated limits, such as thin-disk-only applicability and model-bias caveats. However, it does not explicitly say when to choose this tool over siblings like moment_maps or fit_uv_model, so the guidance remains implicit rather than directive.

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