Calculator Tool

The calculator toolset gives agents one tool, calculate, for reliable arithmetic. It uses exact rational numbers rather than floating-point arithmetic: 0.1 + 0.2 returns exactly 0.3, and large integers do not silently overflow.

Calculations run locally, with no code execution, filesystem access, network access, or side effects. The tool is read-only and available in native and browser (WASM) builds.

Configuration

agents:
  root:
    model: openai/gpt-5-mini
    instruction: Use calculate for all numerical calculations.
    toolsets:
      - type: calculator

No toolset-specific configuration is required. See examples/calculator.yaml for a complete agent.

Arguments

calculate takes one required argument:

Supported syntax:

• Decimal integers and fractions, including .5, 1., and scientific notation (1.5e3). Leading zeros are decimal, not octal.
• Addition (+), subtraction (-), multiplication (*), and division (/).
• Integer remainder (%), with the sign of the dividend: -17 % 5 is -2. This is not a percentage operator; write 15 / 100 for 15%.
• Powers (^) with integer exponents, including negative exponents (2^-3).
• Parentheses, whitespace, and unary + and -.

Powers bind before unary signs, then multiplication/division/remainder, then addition/subtraction. Powers associate right-to-left: 2^3^2 is 512; -2^2 is -4, while (-2)^2 is 4.

Variables, functions, units, commas, implicit multiplication, and programming language syntax are not supported. Convert quantities to compatible units before calculating; the calculator cannot verify that the expression models the user's problem correctly.

Results and precision

For terminating decimals, both result and decimal are exact:

{"result":"0.3","decimal":"0.3","approximate":false}

For repeating decimals, result is an exact reduced fraction and decimal is rounded to 20 decimal places:

{"result":"1/3","decimal":"0.33333333333333333333","approximate":true}

All numbers are returned as strings, preserving precision across JSON clients. Use result, not a rounded decimal, in subsequent expressions. Intermediate calculations remain exact: 1 / 3 * 3 returns 1.

Errors and limits

Malformed expressions, division or remainder by zero, non-integer remainder operands or power exponents, and 0^0 return tool errors rather than guessed answers. To bound resource use, expressions are limited to 8192 bytes, nesting to 64 levels, scientific and power exponents to -1024 through 1024, and intermediate numerators and denominators to 4096 bits. Oversized powers can be rejected before calculation using a conservative size estimate.