Skip to main content
Glama
alma-corpus-mcp

alma-corpus-mcp

by adamzacharia

moment_maps

Computes moment 0/1/2, peak intensity, and quadratic peak velocity maps from a FITS cube, with velocity-range channel selection, masking, and optional clipping.

Instructions

Moment 0/1/2, peak intensity and a quadratic peak velocity from a FITS cube.

Velocity range v_min_kms..v_max_kms selects channels. rms per channel comes from rms, or the robust (MAD) rms of line_free_channels ([[start, end], ...], inclusive indices after the cube is sorted by increasing velocity), or of channels outside the velocity range, or of the whole cube (warned). Masking: an optional mask cube (non-zero = keep, same shape), else clip_sigma_m0 (None = no clip, the unbiased default for moment 0) and clip_sigma_m12 (default 3 sigma) for moments 1 and 2. M0 = sum I dv (BUNIT km/s); noise map = rms dv sqrt(N_chan in mask); M1 = sum I v / sum I; M2 = sqrt(sum I (v - M1)^2 / sum I); peak = max I; v_peak from a parabola through the peak channel and its neighbours (Teague and Foreman-Mackey 2018, bettermoments-style). Writes FITS maps ..fits into out_dir (default: the cube's folder). All paths must lie inside the allowed folder (env ALMA_MCP_WORKDIR, default the server's working directory); existing map files are refused unless overwrite=true. Limits: hard clips bias M0 low and M1 toward bright gas; M2 includes beam smearing and channel width, not only turbulence; one centroid averages multi-component lines; interferometer-only maps miss extended flux.

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>"
    },
    "name": "moment_maps"
  }
}

Input Schema

NameRequiredDescriptionDefault
rmsNo
out_dirNo
fits_pathYes
mask_pathNo
overwriteNo
v_max_kmsNo
v_min_kmsNo
clip_sigma_m0No
rest_freq_ghzNo
clip_sigma_m12No
line_free_channelsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

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 declares file-writing side effects, the exact output naming convention (<stem>.<map>.fits), refusal of existing files, sandbox path restriction, warning behavior, and a limits section covering bias from hard clips, beam smearing in M2, and missing extended flux. This is unusually rich behavioral disclosure for a compute-and-write tool.

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 with the purpose and output list, then parameters, then side effects, then caveats — a sensible order. It is dense and jargon-heavy (dv, v_peak, MAD) and delivered as one continuous block without line breaks, which costs some readability, but almost every clause carries actionable information.

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?

For an 11-parameter, no-output-schema, file-writing tool, the description covers inputs, defaults, masking precedence, output artifacts and naming, failure modes, and scientific limitations. An agent could call this correctly and set expectations about the results without consulting anything else.

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% across 11 parameters, yet the description explains nearly all of them: v_min_kms/v_max_kms channel selection, rms vs line_free_channels ([[start,end]] inclusive, indices after velocity sorting), optional mask cube semantics (non-zero = keep, same shape), clip_sigma_m0 (None = no clip), clip_sigma_m12 default 3, out_dir default, and overwrite. The only notable omission is rest_freq_ghz, whose role is never mentioned.

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 set: 'Moment 0/1/2, peak intensity and a quadratic peak velocity from a FITS cube.' It is clearly distinguishable from siblings like rms_from_line_free or keplerian_mask, and the product list tells an agent exactly what it produces.

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?

The description gives concrete operating context: velocity range selects channels, three alternative rms sources with a warning for the whole-cube fallback, masking precedence (mask cube over clip_sigma), and explicit overwrite/path policy (refused unless overwrite=true, paths must be inside ALMA_MCP_WORKDIR). It stops short of naming sibling alternatives or stating when not to use this tool (e.g. use rms_from_line_free to compute rms separately).

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