> ## Documentation Index
> Fetch the complete documentation index at: https://agentheya.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# calculate

> Deterministic arithmetic, percentages, and unit conversions.

# calculate

Evaluates a mathematical expression deterministically. The agent should call this for any numeric calculation rather than computing in its head — this is the platform's primary defence against arithmetic hallucinations.

A safe, deterministic expression evaluator (using [mathjs](https://mathjs.org/) syntax) restricted to the operators, functions, constants, unit conversions, and percentages listed below. Code execution, imports, and symbolic operations are not available.

## Parameters

| Name         | Type                 | Required | Description        |
| ------------ | -------------------- | -------- | ------------------ |
| `expression` | string (1-500 chars) | yes      | A math expression. |

Supported:

* Operators: `+`, `-`, `*`, `/`, `^`, `%`, parentheses
* Functions: `sqrt`, `log`, `log2`, `log10`, `sin`, `cos`, `tan`, `abs`, `round`, `floor`, `ceil`, `min`, `max`, factorial (`!`)
* Constants: `pi`, `e`
* Unit conversions: `"5 km to miles"`, `"32 degF to degC"`, `"1.5 hours to minutes"`
* Percentages: `"15% of 4200"` or `"4200 * 15%"`

## Returns

```json theme={null}
{
  "ok": true,
  "expression": "15% of 4200",
  "result": "630",
  "result_type": "number"
}
```

`result_type` is one of `"number"`, `"unit"`, `"string"`, `"boolean"`, `"object"`.

On failure:

```json theme={null}
{
  "error": "calculate failed: ...",
  "details": {
    "expression": "...",
    "expression_length": 42,
    "underlying_error": "...",
    "hint": "..."
  }
}
```

## Call from your own custom tool

```js theme={null}
export async function handle(input, ctx) {
  const tax = await ctx.tools.calculate({
    expression: `${input.subtotal} * 0.2`,
  });
  return { tax };
}
```

```python theme={null}
async def handle(input, ctx):
    tax = await ctx.tools.calculate({
        'expression': f"{input['subtotal']} * 0.2",
    })
    return { 'tax': tax }
```

## Notes

* Evaluation is bounded by a 1-second wall-clock deadline.
* Division by zero, `log` of non-positive, and `sqrt` of negative all return an error envelope (NaN/undefined are treated as failure).
* Always registered.