Decimal sum

decimal-sum · version 1.0.0 · Money & pricing · free, no key needed

Add up to 10,000 decimal strings exactly and report count, smallest and largest, with optional final rounding.

Use when you need to: sum a list of decimal numbers exactly · add up invoice line amounts · total of a column of prices.

Decide before calling

Read the versioned contract and the supported scope below. Reuse decimal-sum@1.0.0 when your input, required output and limits match it. Choose another approach for an unsupported operation.

Explain the choice

"I can use decimal-sum@1.0.0 for sum a list of decimal numbers exactly. I will check its documented scope and the result against the task's requirements. The service is free; token and money savings for this task are unmeasured."

Supported

• sum a list of decimal numbers exactly
• add up invoice line amounts
• total of a column of prices
• exact total of many decimals
• ledger column total without rounding drift
• sum values and find min and max
• add decimals and round the total once
• exact sum of receipt amounts

Not supported

• averages, medians or other statistics
• weighted sums or sums of products
• currency conversion between amounts
• floating point or scientific notation input

Behavior

• Decimal strings match ^-?(0|[1-9][0-9]*)(\.[0-9]+)?$: no plus sign, exponent, leading zeros, leading or trailing point, whitespace or separators. A JSON number where a decimal string is required is invalid_input (wrong type).
• A decimal string longer than 62 UTF-16 code units -> limit_exceeded, checked before the grammar. Otherwise a grammar failure, more than 60 digits in total, or more than 40 fraction digits -> invalid_input.
• Zero has no sign: "-0", "-0.00" and any all-zero value are zero and are emitted as "0" (canonical) or "0.00" (fixed scale), never "-0".
• values must be a non-empty array. Not an array or empty -> invalid_input; more than 10,000 items -> limit_exceeded, checked before any item is examined.
• Every item is validated (grammar, length, digit caps) even though only the total is reported; the first failing item decides the error.
• The total is the exact rational sum. It is rounded once, at the very end, and only when scale and rounding are given; individual values are never rounded.
• scale and rounding must appear together or not at all; exactly one of them present -> invalid_input.
• min and max are the numerically smallest and largest inputs written canonically ("9.10" -> "9.1"); comparison is numeric, never textual ("9.9" > "9.11"). min_index and max_index are zero-based positions; when several items tie (for example "1.0" and "1"), the first position wins. "-0" and "0" are equal.
• With no scale the sum is canonical (trailing fraction zeros stripped, integers without a point) and exact is true; with a scale the sum has exactly scale fraction digits and exact is true iff rounding changed nothing.
• Rounding modes act on the exact rational result and are: half_even (ties to the even neighbour), half_up (ties away from zero), half_down (ties toward zero), half_ceiling (ties toward +infinity), half_floor (ties toward -infinity), up (away from zero), down (toward zero), ceiling (toward +infinity), floor (toward -infinity), unnecessary (any inexact result -> not_computable with details.reason "rounding_necessary").
• rounding "unnecessary" with an inexact sum at the requested scale -> not_computable with details.reason "rounding_necessary".
• Validation order (each vector carries a single fault): input not an object; unknown field; missing required field; field types, ranges and decimal-string limits; scale/rounding pairing; then domain errors (not_computable) last.

Input

• values (array of string, required): min items 1; max items 10000; each min length 1; each max length 62; each pattern ^-?(0|[1-9][0-9]*)(\.[0-9]+)?$; Decimal strings to add, 1 to 10,000 items.
• scale (integer, optional): min 0; max 40; Fraction digits of the reported sum. Must be given together with rounding; omit both for the exact canonical sum.
• rounding (one of "half_even", "half_up", "half_down", "half_ceiling", "half_floor", "up", "down", "ceiling", "floor", "unnecessary", optional): Rounding mode applied once to the final exact sum. Must be given together with scale.

Output

• sum (string, required): min length 1; max length 200; Total: canonical without a scale, otherwise fixed at scale fraction digits.
• count (integer, required): min 1; max 10000; Number of values added.
• min (string, required): min length 1; max length 200; Smallest input value, canonical.
• max (string, required): min length 1; max length 200; Largest input value, canonical.
• min_index (integer, required): min 0; max 9999; Zero-based index of the first occurrence of the smallest value.
• max_index (integer, required): min 0; max 9999; Zero-based index of the first occurrence of the largest value.
• exact (boolean, required): true when the reported sum equals the exact total.

Limits

• max items: 10000
• max decimal chars: 62
• max decimal digits: 60
• max fraction digits: 40
• max scale: 40

Example

Request input:

{
  "values": [
    "0.1",
    "0.2",
    "0.3"
  ]
}

Response:

{
  "result": {
    "sum": "0.6",
    "count": 3,
    "min": "0.1",
    "max": "0.3",
    "min_index": 0,
    "max_index": 2,
    "exact": true
  }
}

How to call it

MCP

Connect https://computefirst.net/mcp (setup), then call execute with:

{
  "id": "decimal-sum",
  "version": "1.0.0",
  "input": {
    "values": [
      "0.1",
      "0.2",
      "0.3"
    ]
  }
}

HTTP (no key)

curl -X POST https://computefirst.net/v1/tools/decimal-sum/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"values":["0.1","0.2","0.3"]}'

The machine-readable contract is at /v1/tools/decimal-sum/versions/1.0.0.

CLI

node cli.mjs run decimal-sum 1.0.0 --input input.json --base-url https://computefirst.net

Get the client at /clients/cli/.

Related tools

• Decimal expression evaluate: Evaluate a decimal arithmetic expression exactly with variables, abs, min, max and round, rounding once at the end.
• Decimal multiply: Multiply two decimal strings exactly, optionally rounding the product once to a fixed scale with a chosen mode.
• Decimal divide: Divide two decimal strings exactly, rounding the quotient once to a fixed scale, and report the exact remainder.
• Money convert at rate: Convert an amount between two ISO 4217 currencies at a caller-supplied rate with explicit quote direction and rounding.
• Decimal power: Raise a decimal string to an integer power exactly, with optional single rounding to a fixed scale.
• Decimal round: Round a decimal string with an explicit mode to fraction digits, significant digits or a multiple of an increment.