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 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

{
  "ok": true,
  "expression": "15% of 4200",
  "result": "630",
  "result_type": "number"
}

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

On failure:

{
  "error": "calculate failed: ...",
  "details": {
    "expression": "...",
    "expression_length": 42,
    "underlying_error": "...",
    "hint": "..."
  }
}

Call from your own custom tool

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

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.