Utility tools | SoAI Documentation

SoAI provides eight utility tools. Seven operate on values supplied in their arguments, while message_parse reads a file. None is destructive, so Plan mode permits any of them when selected. The default Plan list includes only calculator and datetime_current from this family.

In the SoAI WebUI, use one in a chat by selecting Chat configuration in the chat header, then Tools. Turn on Tools enabled, choose the tool for the required mode, and select Save. The account needs MCP usage (MCP_USE) and the selected model must support tool calling. The tool runtime must be enabled (TOOLS.MCP.ENABLED).

These tools improve accuracy. A language model can answer what is 17.5% of 84,300 without help but can return a plausible wrong result. Handing the arithmetic to code removes that failure mode.

Calculations and data transforms

calculator evaluates an expression in numeric mode by default. Set mode to symbolic for exact algebra, calculus, and matrices. Expressions accept supported mathematical operators and functions; arbitrary code is rejected. For tool arguments, see the Built-in tool reference.

unit_convert converts a value between units across temperature, length, weight, and data sizes. It works out the category from the units unless you set category yourself.

Numeric calculations

Integers stay exact for results up to 4000 digits; decimals use floating-point arithmetic. Use arithmetic, floor division, modulo, ** or ^ for powers, comparisons, and, or, not, and a if condition else b. Common notation such as ×, ÷, π, ≤, and superscript powers is accepted. Separate statements with semicolons or new lines. Assignments can be reused, as in r = 3; pi * r^2. The optional variables object supplies named values.

Constants are pi, e, and tau. Supported functions include:

Elementary: abs, sign, round, floor, ceil, trunc, sqrt, cbrt, exp, expm1, log, ln, log10, log2, log1p, hypot, min, max, pct(p, x), and clamp(x, low, high). log accepts an optional base other than 0 or 1.
Angles: trigonometric and hyperbolic functions and their inverses, atan2, degrees/deg, and radians/rad.
Integers and special functions: factorial, comb, perm, gcd, lcm, isqrt, gamma, lgamma, erf, and erfc.
Statistics: sum, prod, mean, median, stdev, pstdev, variance, and pvariance. Multi-value functions also accept a list, such as mean([1, 2, 3]).

Symbolic calculations

In symbolic mode, unassigned names become symbols and decimals become exact fractions: 0.1 + 0.2 returns 3/10. Use I for the imaginary unit and oo for infinity. Most numeric functions accept symbols. round, trunc, expm1, log1p, lgamma, isqrt, median, and deviation/variance functions are numeric only; gcd and lcm require whole numbers.

Algebra: simplify, expand, factor, cancel, apart, together, trigsimp, subs, and solve. For example, solve(x^2 - 4, x) finds roots. Systems accept a list of equations and infer unknowns when omitted, as in solve([x + y == 3, x - y == 1]).
Calculus: diff, integrate with optional bounds, limit, series, summation, and product. Limits are two-sided by default; a fourth argument of 1 or -1 selects approach from above or below. With finite complex bounds, integration follows the straight line between them.
Matrices: Matrix([[1, 2], [3, 4]]), det, inv, transpose, rank, and eigenvals. Index lists from 0 with s[0], solved values with s[0][x], and matrix entries with M[1, 0].
Approximation: N(expression, digits), up to 4000 digits. Apply N last to avoid losing accuracy in intermediate calculations.

Symbolic results retain conditions where the original expression is defined, including after simplification or indexing. Solutions can be complete, partial, empty, unrestricted, infinite families, or conditional on parameters. Check outcome, note, constraints, and cases before using them; a partial result does not prove that no other solutions exist. If convergence or a condition cannot be established, substitute parameter values or split the calculation. Symbolic calculations have a 10-second time limit and a 1 GiB memory limit; simplify the expression or use smaller steps if either is reached.

Read calculator results

Field	Meaning
`result_text`, `exact`	Text representation and whether it is exact. Quote this text to preserve large integers; a JSON number can lose integer precision beyond `2^53`.
`result_type`	`integer`, `real`, `boolean`, `rational`, `complex`, `expression`, `list`, `matrix`, `solutions`, `solution`, `infinity`, or `undefined`.
`result`	JSON number for a real value; large integers can be approximate here.
`working_digits`	Decimal precision carried by an approximate value, without a guarantee that every digit is accurate.
`outcome`, `note`	Solution completeness or a special result, with its explanation.
`constraints`, `cases`	Conditions on a value or solution, and conditional results. Each solved system can have its own constraints.
`items`, `values`	List or solution entries, and the unknowns in a solved system.
`entries`, `components`	Matrix rows, or the real and imaginary parts of a complex value.
`assignments`	Assigned names and values in statement order.

An invalid expression returns an error identifying the problem and, where possible, a correction. In a calculation with several statements, the error identifies the failed statement and the call returns no results.

Hashing and encoding

hash returns MD5, SHA1, SHA256, or SHA512 of a string. base64 encodes or decodes, with a variant for standard Base64, URL-safe Base64, or Base32.

Both take text as an argument, which limits them to short strings that fit in a prompt. To hash a file, use the shell or the Files page instead.

Random values

random_generate produces one of five things depending on type: an integer in a range, a float, a uuid, a random string from a charset, or a choice from a list you supply. count asks for several at once.

Use random_generate because models are poor random number generators. Asked for a number between 1 and 100, they overproduce a small set of values. Use the tool for a lottery draw, sample, or shuffle.

With type: string and charset: password, the tool uses a cryptographic random source, but the generated value is returned to the model as ordinary tool output. Do not confuse it with the protected vault path. See Passwords and credential tools before using it for a live credential.

Time, text, and chat exports

datetime_current covers four operations. now returns the current time in a timezone, convert moves a timestamp between zones, add_days does date arithmetic, and format renders a timestamp with a custom pattern. It accepts IANA zone names and epoch milliseconds.

A model response has no reliable clock. Use now for anything relative to the current date or time. datetime_current is included in the default Chat mode tool list.

Text and chat exports

text_stats counts characters, words, tokens, sentences, and estimated reading time for a block of text.

message_parse reads an exported chat log and returns structured messages. It handles WhatsApp, Telegram, Discord, Signal, Facebook Messenger, and MSN Messenger exports in .txt, .json, .xml, .csv, .html, and .zip form. Point it at a file with file_path, a stored file with file_id, or an indexed document with document_id. It usually detects the platform on its own, and max_messages caps how much comes back, which matters for a group chat with years of history in it.

Upload the export through the Files page first, or attach it to the conversation, and the agent can read it from there. See Attachments and file context for the available Chat attachment methods.