---
url: 'https://adk.nht.io/assembly/batteries-tools.md'
description: >-
  Catalogue of bundled tools — numeric, data, text, time, and ADK-native — plus
  the peer dependencies each requires.
---

# Tools batteries

## LLM summary — Tools batteries

* `@nhtio/adk/batteries` is the public batteries barrel for bundled tool batteries; batteries are not re-exported from the `@nhtio/adk` package root.
* Tools are pre-constructed [`Tool`](https://adk.nht.io/api/@nhtio/adk/forge/classes/Tool) instances. No factories or runtime configuration are required; register them directly.
* ADK-native categories (`memory`, `retrievables`, `standing_instructions`) are the most critical batteries. They delegate to active [`DispatchContext`](https://adk.nht.io/api/@nhtio/adk/types/interfaces/DispatchContext) callbacks, allowing the model to manage its own memory, retrievables, and instructions directly.
* `memoryTools`, `retrievableTools`, and `standingInstructionTools` are pre-assembled arrays of native tools. Standing instructions are `string | Tokenizable` rather than instances of a dedicated class.
* Peer dependencies are required per category (e.g., `mathjs` for `math`, `luxon` for `time`, `uuid` for `memory`). They are only loaded if you import the specific battery.
* Combine battery tools with custom tools by passing them as a flat array to the [`TurnRunner`](https://adk.nht.io/api/@nhtio/adk/turn_runner/classes/TurnRunner) constructor, or merge them using a [`ToolRegistry`](https://adk.nht.io/api/@nhtio/adk/forge/classes/ToolRegistry) instance.
* Battery tools do not override the default trust settings. They return untrusted content, meaning results default to untrusted rendering.
* Many battery tools omit `artifactConstructor` (which falls back to [`SpooledArtifact`](https://adk.nht.io/api/@nhtio/adk/spooled_artifact/classes/SpooledArtifact)), while structured JSON tools explicitly set [`SpooledJsonArtifact`](https://adk.nht.io/api/@nhtio/adk/spooled_artifact/classes/SpooledJsonArtifact).

Date math, CSV parsing, and memory CRUD are already covered. Import the battery and move on.

```typescript
import { calculateTool, memoryTools } from '@nhtio/adk/batteries'
```

ADK ships a catalogue of pre-constructed [`Tool`](https://adk.nht.io/api/@nhtio/adk/forge/classes/Tool) instances organized into categories. No factory calls, no configuration, and no hand-waving setup. You import them, register them, and get back to your actual business logic.

## Import Paths

Import battery tools from the batteries barrel:

```typescript
import { calculateTool, parseCsvTool, getCurrentTimeTool } from '@nhtio/adk/batteries'
```

You can still keep your own imports grouped by category for readability:

```typescript
import {
  calculateTool,
  evaluateKatexTool,
  parseCsvTool,
  parseYamlTool,
} from '@nhtio/adk/batteries'
```

Use the exported tool instances directly.

## Wiring into the Runner

Every battery tool is a fully constructed [`Tool`](https://adk.nht.io/api/@nhtio/adk/forge/classes/Tool) instance. Pass them directly to the [`TurnRunner`](https://adk.nht.io/api/@nhtio/adk/turn_runner/classes/TurnRunner) constructor. The storage callback spread below is a local placeholder; the ADK does not ship a drop-in no-op storage adapter, so your application must provide every required [`TurnRunner`](https://adk.nht.io/api/@nhtio/adk/turn_runner/classes/TurnRunner) storage callback:

```typescript
import { TurnRunner } from '@nhtio/adk'
import { calculateTool, formatTableTool, getCurrentTimeTool } from '@nhtio/adk/batteries'

const storageCallbacks = {
  // Provide every required TurnRunner storage callback here.
}

const runner = new TurnRunner({
  ...storageCallbacks,
  executorCallback: adapter.executor(),
  tools: [calculateTool, formatTableTool, getCurrentTimeTool],
})
```

`adapter` here refers to an LLM battery instance. The executor does not call `ctx.ack()` by default — the implementor owns turn completion. Pass `autoAck: true` when constructing the adapter to restore single-shot behavior; see [LLM batteries](./batteries-llm#autoack).

Compose battery tools with custom tools by passing a flat array:

```typescript
import { TurnRunner } from '@nhtio/adk'
import { parseCsvTool } from '@nhtio/adk/batteries'
import { getWeather, createTicket } from './tools'

const storageCallbacks = {
  // Provide every required TurnRunner storage callback here.
}

const runner = new TurnRunner({
  ...storageCallbacks,
  executorCallback: adapter.executor(),
  tools: [parseCsvTool, getWeather, createTicket],
})
```

If you need explicit control over collisions or are managing dynamic tools, construct a [`ToolRegistry`](https://adk.nht.io/api/@nhtio/adk/forge/classes/ToolRegistry) directly:

```typescript
import { ToolRegistry } from '@nhtio/adk'
import { memoryTools } from '@nhtio/adk/batteries/tools/memory'

// Do NOT look for ToolRegistry.fromTools — it does not exist. Use the constructor.
const baseRegistry = new ToolRegistry([...memoryTools, ...myCustomTools])
```

## Trust & Artifact Constructors

By design, all battery tools default to `trusted: false`. Tool executions are untrusted inputs, not developer-authored source code. Their output is routed through the untrusted content envelope automatically.

Furthermore, these tools do not share a single uniform artifact constructor. Many omit `artifactConstructor` entirely (falling back to the default [`SpooledArtifact`](https://adk.nht.io/api/@nhtio/adk/spooled_artifact/classes/SpooledArtifact)), while those processing structured outputs explicitly set [`SpooledJsonArtifact`](https://adk.nht.io/api/@nhtio/adk/spooled_artifact/classes/SpooledJsonArtifact). Their internal artifact types are not a guessing game; use the tools as exported.

## ADK-Native Batteries

These tools hook directly into the active [`DispatchContext`](https://adk.nht.io/api/@nhtio/adk/types/interfaces/DispatchContext). They delegate execution to the exact storage callbacks you wired into your runner. They are the most valuable batteries in the toolkit because they allow the model to manage its own persistent state.

::: details ADK-Native Tools (Memory, Retrievables, Standing Instructions)

### Memory Tools

Category: `memory`

Allows the model to run CRUD operations on its memory bank.

* `listMemoriesTool` — Lists memories returned by `ctx.fetchMemories()`.
* `storeMemoryTool` — Creates a new memory via `ctx.storeMemory()`.
* `updateMemoryTool` — Replaces an existing memory by ID via `ctx.mutateMemory()`.
* `deleteMemoryTool` — Removes a memory by ID via `ctx.deleteMemory()`.
* `memoryTools` — A pre-assembled array of all four memory tools.

Peer dependencies: `luxon`, `uuid`

```typescript
import { TurnRunner } from '@nhtio/adk'
import { calculateTool } from '@nhtio/adk/batteries'
import { memoryTools } from '@nhtio/adk/batteries/tools/memory'

const otherTools = [calculateTool]

const storageCallbacks = {
  // Provide every required TurnRunner storage callback here.
}

const runner = new TurnRunner({
  ...storageCallbacks,
  executorCallback: adapter.executor(),
  tools: [...memoryTools, ...otherTools],
})
```

### Retrievable Tools

Category: `retrievables`

Allows the model to control which document fragments or chunks are pinned to the context.

* `listRetrievablesTool` — Lists retrievables returned by `ctx.fetchRetrievables()`.
* `storeRetrievableTool` — Creates a retrievable via `ctx.storeRetrievable()`.
* `updateRetrievableTool` — Mutates a pinned retrievable.
* `deleteRetrievableTool` — Removes a pinned retrievable.
* `retrievableTools` — A pre-assembled array of all four retrievable tools.

Peer dependencies: `luxon`, `uuid`

### Standing Instructions Tools

Category: `standing_instructions`

Allows the model to inspect and update its own operational rules. There is no `StandingInstruction` class; instructions are stored and managed as `string | Tokenizable` values.

* `listStandingInstructionsTool` — Lists active standing instructions.
* `addStandingInstructionTool` — Adds a new standing instruction.
* `removeStandingInstructionTool` — Removes a standing instruction.
* `standingInstructionTools` — A pre-assembled array of all three standing instruction tools.
  :::

## Utility Tool Batteries

Below is the breakdown of utility tools shipped with the ADK. They are grouped into logical domains. If a category lists peer dependencies, you must install those packages yourself.

::: details Numeric Tools

### Mathematics

Category: `math`

* `calculateTool` — Evaluates a mathematical expression using a sandboxed subset of `mathjs`.
  ::: warning MathJS Sandbox Restrictions
  To prevent remote execution and environment pollution, the sandbox explicitly blocks dangerous `mathjs` capabilities, including `import`, `createUnit`, `simplify`, `derivative`, and `compile`. Refer to the source code for the full blocked list.
  :::
* `evaluateKatexTool` — Translates and evaluates a LaTeX/KaTeX math expression. In addition to arithmetic, trig, logs, and roots, it evaluates calculus **numerically**: definite integrals (`\int_{a}^{b} f \,dx`) via Simpson quadrature, derivatives at a point (`\frac{d}{dx} f \big|_{x=a}`) via finite difference, and limits (`\lim_{x \to a} f`, including `a = \pm\infty`). Numeric results are labelled `Result (numeric):`. Because the sandbox blocks symbolic `derivative` and `mathjs` has no symbolic integration, indefinite integrals, derivatives without a point, infinite integration bounds, and divergent limits are not computable and return a specific, guiding error.

Peer dependency: `mathjs`

### Statistics

Category: `statistics`

* `statsDescribeTool` — Computes descriptive statistics (mean, median, mode, standard deviation, variance, min, max, percentiles) over a numeric array.
* `statsCorrelateTool` — Computes the Pearson correlation coefficient between two numeric arrays.
* `statsTransformTool` — Applies numeric transformations such as min-max normalization, z-score normalization, percent-of-sum normalization, running totals, rolling averages, percent change, ranking, and outlier detection.
* `statsHistogramTool` — Bins a numeric array into a histogram dataset.

Peer dependency: `simple-statistics`

### Unit Conversion

Category: `unit_conversion`

* `convertUnitTool` — Converts physical units across dimensions (length, mass, volume, temperature, speed, etc.).
  :::

::: details Data Tools

### Data Structures

Category: `data_structure`

* `jsonTransformTool` — Applies a JSONPath or jq-style transformation to a JSON value.
* `setOperationsTool` — Computes union, intersection, difference, and symmetric difference over array sets.

### Structured Data

Category: `structured_data`

* `formatTableTool` — Formats a row array as a Markdown, CSV, or TSV table.
* `jsonFormatTool` — Pretty-prints or minifies a JSON value.
* `validateFormatTool` — Validates a string against known formats such as email, UUID, ISO date, hex color, semver, and related common scalar formats.

### Formatting

Category: `formatting`

* `formatNumberTool` — Formats a number with locale-aware separators, decimal places, and units.
* `formatListTool` — Formats an array as a natural-language list (e.g., "a, b, and c").
  :::

::: details Text Tools

### String Processing

Category: `string_processing`

* `stringTransformTool` — Converts strings between case styles such as `camel_case`, `snake_case`, `pascal_case`, `kebab_case`, `constant_case`, and `titlecase`.
* `stringExtractTool` — Extracts substrings using regular expressions or delimiter patterns.

Peer dependency: `case-anything`

### Text Analysis

Category: `text_analysis`

* `textAnalyzeTool` — Counts words, sentences, characters, paragraphs, and estimates reading times.
* `textLinesTool` — Splits text into lines, filters blank lines, and deduplicates rows.

### Text Comparison

Category: `text_comparison`

* `textDiffTool` — Produces a unified diff between two strings.
* `stringSimilarityTool` — Computes edit distance and similarity scores between two strings.

Peer dependencies: `diff`, `fastest-levenshtein`

### Encoding & Escaping

Category: `encoding`

* `encodeTextTool` — Encodes and decodes between Base64, Base64URL, hex, URL encoding, and UTF-8.
* `textEscapeTool` — Escapes and unescapes HTML, XML, JSON strings, and RegExp special characters.
* `unicodeNormalizeTool` — Normalizes a string to NFC, NFD, NFKC, or NFKD forms.

### Parsing

Category: `parsing`

* `parseCsvTool` — Parses a CSV string into an array of rows. Supports custom delimiters and header detection.
* `parseYamlTool` — Parses a YAML string into a JSON-serializable value.
* `parseKvTool` — Parses key=value or KEY: value pairs into an object.
* `detectDelimiterTool` — Detects the likely delimiter of a structured text file.

Peer dependencies: `js-yaml`, `papaparse`
:::

::: details Time Tools

### DateTime Math

Category: `datetime_math`

* `dateAddTool` — Adds or subtracts a duration from a date.
* `dateDiffTool` — Computes the duration between two dates.
* `durationFormatTool` — Formats a duration in human-readable form.

Peer dependency: `luxon`

### DateTime Extended

Category: `datetime_extended`

* `dateNthWeekdayTool` — Finds the Nth weekday in a month (e.g., "third Thursday of November").
* `dateCalendarInfoTool` — Returns calendar metadata for a date, including week number, quarter, and day of the year.
* `dateParseTool` — Parses a natural-language date expression (e.g., "next Monday", "in two weeks").
* `datePeriodTool` — Computes the start and end of a named period (e.g., "this quarter", "last month").
* `dateBusinessDaysTool` — Counts business days between two dates, optionally excluding specified holidays.

Peer dependencies: `chrono-node`, `luxon`

### Time

Category: `time`

* `getCurrentTimeTool` — Returns the current date and time in a specified timezone.
* `convertTimeTool` — Converts a datetime value from one timezone to another.

Peer dependency: `luxon`
:::

::: details Miscellaneous Tools

### Color

Category: `color`

* `colorContrastTool` — Computes the WCAG contrast ratio between two colors.
* `colorSchemeTool` — Generates complementary, analogous, or triadic color schemes.
* `colorAdjustTool` — Lightens or darkens a color by HSL lightness.

### Comparison

Category: `comparison`

* `compareValuesTool` — Performs a deep comparison of two values and returns relative order.
* `compareRecordsTool` — Diffs two objects and returns lists of added, removed, and modified keys.

### Geospatial Basics

Category: `geo_basics`

* `geoDistanceTool` — Computes the great-circle distance between two latitude/longitude points.
* `geoWithinRadiusTool` — Checks whether a point lies within a radius of another point.
* `geoBboxContainsTool` — Checks whether a coordinate point lies within a specified bounding box.
  :::

## Peer Dependencies

You only pay for peer dependencies if you import the battery category that requires them. If you attempt to use a tool without its peer dependency installed, your runtime will crash with a module resolution error. Install what you import; Node's resolver is not a charity.

| Peer dependency | Required Category |
| :--- | :--- |
| `mathjs` | `math` |
| `simple-statistics` | `statistics` |
| `js-yaml` | `parsing` |
| `papaparse` | `parsing` |
| `case-anything` | `string_processing` |
| `diff` | `text_comparison` |
| `fastest-levenshtein` | `text_comparison` |
| `chrono-node` | `datetime_extended` |
| `luxon` | `datetime_math`, `datetime_extended`, `time`, `memory`, `retrievables` |
| `uuid` | `memory`, `retrievables` |

Any category omitted from this table has zero external dependencies beyond `@nhtio/adk` itself.