Math Tool

A safe mathematical expression evaluation tool with variable support for the Fractal Synapse agent system.

Overview

The Math Tool provides secure mathematical computation capabilities for AI agents, featuring:

• Safe Expression Evaluation: Uses mathjs with security restrictions to prevent code injection
• Variable Support: Define and use descriptive variable names in calculations
• Comprehensive Math Functions: Arithmetic, trigonometry, logarithms, constants (π, e), and more
• Unit Support: Basic unit conversions and calculations with units
• Precision Control: Configurable decimal precision for results
• Input Validation: Prevents dangerous patterns and validates mathematical expressions

Features

• ✅ Basic arithmetic operations (+, -, *, /, ^)
• ✅ Mathematical functions (sqrt, sin, cos, log, abs, ceil, floor)
• ✅ Mathematical constants (pi, e)
• ✅ Variable definitions with descriptive names
• ✅ Unit support (5 cm, 90 deg)
• ✅ Security validation against code injection
• ✅ Comprehensive error handling
• ✅ Configurable precision (1-15 decimal places)

Usage with Agent

The Math Tool is automatically available in agents that include it in their tool definitions:

import { mathToolDefinition } from 'math-tool';

// The agent will use descriptive variable names like:
// "Calculate the area of a circle with radius 5 meters"
// Uses: equation = "pi * radius_m^2", variables = { radius_m: 5 }

// Instead of generic names:
// equation = "pi * r^2", variables = { r: 5 }

Encouraged Usage Patterns

The tool description guides LLMs to use descriptive variable names:

• ✅ distance_km, time_hours, speed_mps
• ✅ width_m, height_m, area_m2
• ✅ temperature_celsius, pressure_pa
• ❌ a, b, c, x, y, z

Example Calculations

// Physics: Kinetic energy
{
  equation: "0.5 * mass_kg * velocity_mps^2",
  variables: { mass_kg: 2, velocity_mps: 10 }
}
// Result: 100

// Geometry: Pythagorean theorem
{
  equation: "sqrt(leg_a^2 + leg_b^2)",
  variables: { leg_a: 3, leg_b: 4 }
}
// Result: 5

// Finance: Compound interest
{
  equation: "principal * (1 + rate)^years",
  variables: { principal: 1000, rate: 0.05, years: 3 }
}
// Result: 1157.625

Development

Building

npm run build

Testing

The package uses vitest for comprehensive testing:

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests once (CI mode)
npm run test:run

Test Coverage

• 101 total tests across 4 test suites:
  • math-evaluator.test.ts - Core functionality (24 tests)
  • variables.test.ts - Variable handling (17 tests)
  • equations.test.ts - Equation types and syntax (25 tests)
  • error-handling.test.ts - Error cases and security (35 tests)

End-to-End Evaluations

The package includes 20 real-world evaluation scenarios in src/math-evals.ts for testing with actual agent workflows.

Security

The tool implements multiple security layers:

• Pattern Detection: Blocks dangerous patterns like eval(), function, require()
• Input Sanitization: Prevents code injection through mathematical expressions
• Restricted Math Instance: Uses mathjs with security-focused configuration
• Result Validation: Ensures outputs are valid finite numbers

Architecture

• src/index.ts - Main tool definition and exports
• src/math-evaluator.ts - Core mathematical evaluation engine
• src/math-evals.ts - End-to-end evaluation scenarios
• tests/ - Comprehensive test suite with vitest
• vitest.config.ts - Test configuration

Dependencies

• mathjs: Mathematical expression evaluation engine
• zod: Input schema validation
• agent-core: Fractal Synapse agent system integration
• ai: Vercel AI SDK tool integration