Skip to main content
Glama
laszlopere

mcp-molecules

by laszlopere
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

elemental_analysis

Infer a chemical formula from elemental mass percentages (inverse analysis).

Instructions

Infer a chemical formula from elemental mass percentages (inverse analysis).

The inverse of percent composition: given each element's mass percent -- what a combustion / CHN elemental analyzer reports -- recover the best-fit empirical formula, and, when molar_mass is also known, the molecular formula. Masses come from the bundled NIST standard atomic weights, so the computation is offline and deterministic.

Assumes a 100 g sample, converts each percentage to relative moles via the atomic weights, normalises to whole-number atom ratios (searching integer multipliers up to max_multiplier), and reduces to the empirical formula. Use balance to assign an unmeasured element (typically oxygen) the remainder up to 100%.

Returns the resolved_percentages (including any balance element), the empirical_formula and its weight, the molecular_formula (null without a molar mass) with its molecular_multiplier, and a fit block -- the predicted_percentages the returned formula actually implies, the per-element residuals, and the rms_error / max_abs_error in percentage points. Any data-quality warnings (percentages not summing to 100%, a poor fit, a molar mass far from a whole multiple) are listed.

Raises ValueError on an unknown element, a non-positive percentage, or percentages leaving no remainder for the balance element.

Input Schema

NameRequiredDescriptionDefault
balanceNoElement assigned the remainder up to 100%. CHN analysis measures only carbon, hydrogen and nitrogen, so oxygen is found by difference: pass balance='O'. Must not also appear in percentages.
molar_massNoKnown molar mass in g/mol. When given, the empirical formula is scaled to the nearest whole multiple to report the molecular formula. Omit to get only the empirical formula.
percentagesYesPer-element mass percentages, mapping element symbols to their percent by mass, e.g. {'C': 40.0, 'H': 6.71, 'O': 53.29}. These are the numbers a combustion / CHN analyzer reports. Values must be positive.
max_multiplierNoLargest integer the mole ratios are scaled by when searching for whole-number atom counts (handles ratios like 1:1.5 that need doubling). Raise it for formulae with large subscripts.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

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 well: it discloses the offline/deterministic nature, the 100 g sample assumption, the integer-multiplier search, and the exact ValueError conditions (unknown element, non-positive percentage, no remainder for balance). It also previews data-quality warnings, giving an agent a realistic picture of failure modes.

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-loads the core purpose in the first line, then layers algorithm, parameter guidance and returns in a logical order. It is somewhat long, and the detailed returns paragraph is partly driven by the absence of an output schema, but little of it is wasted.

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?

With no output schema and no annotations, the description must explain returns and errors itself, and it does: resolved_percentages, empirical/molecular formula, the fit block with residuals and error metrics, and warnings. Nothing an agent needs to call and interpret the tool is missing.

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 100% so the baseline is 3, but the description adds real meaning by explaining how parameters interact in the workflow — balance supplying oxygen by difference, molar_mass triggering molecular-formula scaling, and max_multiplier handling fractional ratios. It complements rather than repeats the schema.

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?

States a specific verb+resource ('Infer a chemical formula from elemental mass percentages') and immediately frames it as the inverse of percent composition, which cleanly separates it from siblings like molecular_weight_calculator and find_chemical_compound. An agent can identify the operation 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 Guidelines4/5

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

Gives clear context for use ('what a combustion / CHN elemental analyzer reports') and explains the balance parameter's role for unmeasured elements. It does not explicitly name alternative tools or state when not to use it, so it falls short of full when/when-not/alternatives guidance.

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

Deploy Server

Other Tools