Self-improving AI Employees for everyone
Calculator Tool (calculatorTool)
| Field | Value |
|---|---|
| Category | ai_tools (dedicated AI tool, group ("tool", "ai")) |
| Backend handler | server/nodes/tool/calculator_tool/__init__.py — CalculatorToolNode, dispatched via BaseNode.execute() + the @Operation("calculate") method |
| Tests | server/tests/nodes/test_ai_tools.py |
| Skill (if any) | None (referenced directly by AI agents via tool-calling) |
| Dual-purpose tool | tool-only — ToolNode exposed to the LLM as calculator (tool_name class attr) |
Purpose
Exposes basic arithmetic as a structured tool that an AI Agent can call during
reasoning. The LLM fills the operation + operand arguments and the operation
returns the numeric result. Supports the eight operations listed below; no
external calls, no state. The CalculatorParams Pydantic model is the
LLM-visible tool schema (via ToolNode.as_tool_schema()).
Inputs (handles)
| Handle | Connection type | Required | Purpose |
|---|---|---|---|
input-main |
main | no | Passive node - connect output-tool to an AI Agent's input-tools |
Parameters
The CalculatorParams model fields ARE the LLM-provided tool args (no separate
toolName / toolDescription node params — those live on the class as
tool_name / tool_description).
| Name | Type | Default | Required | displayOptions.show | Description |
|---|---|---|---|---|---|
operation |
enum | (required) | yes | - | One of add, subtract, multiply, divide, power, sqrt, mod, abs |
a |
float | (required) | yes | - | First operand (or the sole input for sqrt / abs) |
b |
float? | None |
no | - | Second operand; required for add/subtract/multiply/divide/power/mod, unused for sqrt / abs |
Outputs (handles)
| Handle | Shape | Description |
|---|---|---|
output-tool |
object | CalculatorOutput model, serialized per BaseNode._serialize_result |
Output payload (TypeScript shape)
On success (matches the CalculatorOutput model):
{
operation: string;
a: number;
b: number | null;
result: number; // float('inf') for x/0, 0 for x mod 0
}
Errors are not produced inside the op (the Literal schema rejects unknown
operations at Pydantic validation before the op runs; a validation failure
surfaces as the framework's standard error envelope from BaseNode.execute()).
Logic Flow
flowchart TD
A[BaseNode.execute -> calculate ctx params] --> B[fn = _OPERATIONS params.operation<br/>b_value = params.b if not None else 0.0]
B --> D{Invoke op lambda}
D -- divide with b==0 --> Finf[result = float inf]
D -- mod with b==0 --> Fmod[result = 0]
D -- sqrt --> Fsqrt[result = sqrt of abs a]
D -- other --> Fok[result = a op b_value]
Finf --> R[Return CalculatorOutput operation/a/b/result]
Fmod --> R
Fsqrt --> R
Fok --> R
Decision Logic
- Unknown operation: cannot occur —
operationis aLiteral[...]so an out-of-set value fails Pydantic validation before the op runs. - Division by zero (
divide): returnsfloat('inf')instead of erroring. - Mod by zero (
mod): returns0instead of erroring. - Negative sqrt: silently calls
math.sqrt(abs(a)), sosqrt(-9)returns3.0(not an error). - Missing
b: whenparams.b is None,b_valuedefaults to0.0before the lambda runs (soadd/multiply/etc. with noboperate against 0). poweroverflow: raised asOverflowErrorbymath.pow; bubbles up toBaseNode.execute()'s generic exception path (full traceback envelope).
Side Effects
- Database writes: none.
- Broadcasts: none.
- External API calls: none.
- File I/O: none.
- Subprocess: none.
External Dependencies
- Credentials: none.
- Services: none.
- Python packages:
math(stdlib only). - Environment variables: none.
Edge cases & known limits
dividereturnsfloat('inf')for division by zero - downstream JSON serializers may choke onInfinity(not strict JSON).modreturns0for modulo-by-zero, which is mathematically wrong but matches the op lambda. Document this for agents that might reason about it.sqrtof a negative number silently returns the sqrt of the absolute value rather than erroring or returning NaN.ais typedfloat(required) — a non-numeric LLM argument fails Pydantic coercion and produces a validation error the LLM can correct.- Operation names are case-sensitive (
Literalexact match; no.lower()).
Related
- Sibling tools:
currentTimeTool,duckduckgoSearch,taskManager,writeTodos,agentBuilder - Architecture docs: Agent Architecture, Tool Building Pipeline, Node Creation Guide