toolsets/calc-toolkit/doc.md

calc‑toolkit

Safe expression evaluation, unit conversion, and basic statistics. Pure‑stdlib — no dependencies.

---

When to Use This Toolset

• Evaluating math expressions safely (no eval() risks)
• Converting between units (length, weight, temperature, time, digital)
• Computing quick statistics (mean, median, stdev) on number lists
• Quick calculations agents need without terminal scripts

---

Process

Choose function → Provide input → Get result

All functions are one‑shot — no multi‑step workflows needed.

---

Function Reference

eval_expression

Safely evaluate a mathematical expression using Python's AST parser.

Supported: +, -, *, /, **, //, %, sqrt(), log(), sin(), cos(), pi, e, tau, abs(), round(), min(), max(), factorial(), ceil(), floor()

Args: expr (str) — e.g. "sqrt(16) + 2 * pi"

Returns: {result, expression} or {error}

convert_unit

Convert between common units.

Supported units:

Category	Units
Length	m, km, cm, mm, ft, in, mile
Weight	kg, g, lb, oz
Temperature	C, F, K
Time	h, min, s, day
Digital	B, KB, MB, GB, TB

Args: value (float), from_unit (str), to_unit (str)

Returns: {result, from_unit, to_unit, original_value, formula}

basic_stats

Compute count, sum, min, max, mean, median, standard deviation, variance.

Args: numbers (list of numbers)

Returns: {count, sum, min, max, mean, median, stdev, variance}

---

Guidelines

Do

• Use eval_expression instead of writing Python scripts for simple math
• Check unit conversion results for reasonable magnitudes
• Verify basic_stats on known datasets before trusting outputs

Don't

• Don't pass user‑supplied strings to eval without sanitization (handled by AST)
• Don't use for high‑precision scientific computing