alma-corpus-mcp

dynamical_mass

Calculate enclosed dynamical mass using Keplerian rotation or virial dispersion inputs, with linear propagation of velocity, radius, and inclination errors.

Instructions

Enclosed dynamical mass.

kind='keplerian': M = v_rot^2 r / G with v_rot = v_obs / sin(i) when velocity_is_projected (needs inclination). kind='virial': M_vir = (5 / a) sigma^2 R / G, a = (1 - k/3) / (1 - 2k/5) for rho ~ r^-k (k = density_index; k = 0 gives 5 sigma^2 R / G, k = 1 gives 1040 sigma^2 R in Msun, km/s, pc). sigma is the 1D dispersion; set velocity_is_fwhm to pass a FWHM (sigma = FWHM / 2.3548). velocity_is_fwhm applies to kind='virial' only; a Keplerian rotation velocity is never a line width and is used as given. Errors are propagated linearly from velocity, radius and inclination errors. Limits: M scales with distance (r in arcsec); the mass-inclination degeneracy dominates for low i; pressure support and self-gravity are not separated from the central mass.

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": {
      "velocity_kms": "<velocity_kms>",
      "radius": "<radius>"
    },
    "name": "dynamical_mass"
  }
}

Input Schema

Name	Required	Default
`kind`	No	keplerian
`radius`	Yes
`radius_err`	No
`distance_pc`	No
`radius_unit`	No	au
`velocity_kms`	Yes
`density_index`	No
`inclination_deg`	No
`velocity_err_kms`	No
`velocity_is_fwhm`	No
`inclination_err_deg`	No
`velocity_is_projected`	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 supplied, the description carries the full burden and does substantial work: it discloses error handling (linear propagation from velocity, radius and inclination errors) and three concrete limitations (mass scales with distance, mass-inclination degeneracy at low i, pressure support not separated from central mass). It does not state required permissions or failure modes (e.g. what happens if velocity_is_projected=true but inclination is null), which leaves a small gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the one-line purpose, then groups content by computation mode, then noise flags, error propagation, and limits — each sentence carries distinct information with no filler despite the density of the physics. Given 12 parameters and two regimes, the length is justified.

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

Completeness3/5

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

Formulas, conventions and caveats are covered well, but with no output schema the description should state what is returned (mass and its uncertainty, and in which unit for the general case — only the k=1 Msun case is spelled out). The unexplained unit interaction between radius, radius_unit and distance_pc is also a completeness gap for a 12-parameter tool.

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 12 parameters, so the description has to compensate and largely does: it defines kind's allowed values (the schema only declares an untyped string default), explains density_index with worked limits (k=0 and k=1), and clarifies velocity_is_fwhm (sigma = FWHM/2.3548) and velocity_is_projected. Gaps remain: radius_unit and distance_pc are never explained, and the phrase 'r in arcsec' conflicts with radius_unit's default of 'au', leaving the unit contract ambiguous.

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 'Enclosed dynamical mass' and immediately specifies the two computation modes (kind='keplerian' vs kind='virial') with their governing formulas, which is specific enough to distinguish this from siblings like virial_parameter or rotational_diagram. It never says explicitly that it computes/returns a mass estimate versus just a parameter, but the resource and scope are unmistakable.

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?

The description implicitly routes the agent by kind: Keplerian for rotation curves, virial for dispersion-supported systems, plus an explicit exclusion ('velocity_is_fwhm applies to kind='virial' only'). However there is no explicit when-to-use/when-not guidance relative to virial_parameter, rotational_diagram or keplerian_mask, so selection between siblings is left to inference.

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