Tool Catalog

For creating your own toolkits, see Custom Tools. For which primitive to pick, see Actions vs Tools.

Quick Start

The compile-safe path is BuiltInTool — pass enum constants and the framework instantiates the backing POJO for you. AgentBuilder.build() also requires the accountability trio (TNS-298); focused snippets later on this page omit those three calls.

package com.example.tnsai.docs;

import com.tnsai.accountability.AuthorityScope;
import com.tnsai.accountability.LiabilitySink;
import com.tnsai.agents.Agent;
import com.tnsai.agents.AgentBuilder;
import com.tnsai.enums.BuiltInTool;
import com.tnsai.identity.AgentPrincipal;
import com.tnsai.llm.providers.OpenAIClient;
import com.tnsai.roles.Role;

public final class ToolsCatalogBuilderExample {
    private ToolsCatalogBuilderExample() {}

    public static Agent build(
        Role myRole,
        AgentPrincipal principal,
        LiabilitySink sink,
        AuthorityScope scope
    ) {
        return AgentBuilder.create()
            .llm(new OpenAIClient("gpt-4o"))
            .role(myRole)
            .builtInTools(
                BuiltInTool.WEB_SEARCH_TOOLS,
                BuiltInTool.UTILITY_TOOLS,
                BuiltInTool.PDF_TOOLS
            )
            .principal(principal)
            .liabilitySink(sink)
            .authorityScope(scope)
            .build();
    }
}

String response = agent.chat("What is the population of Tokyo? Triple it.");

The LLM sees every @Tool method on every registered toolkit as a callable function and dispatches by method name (brave_search, calculator, pdf_extract_text, …). Most toolkits read credentials from environment variables on first use:

export BRAVE_API_KEY=your-key
export OPENAI_API_KEY=your-key

How toolkits are organised

Each BuiltInTool enum entry maps a stable toolName to the FQCN of a POJO in tnsai-tools. The POJO's public @Tool-annotated methods are the actual functions exposed to the LLM. For example, BuiltInTool.CSV_TOOLS backs com.tnsai.tools.file.CsvTools, which exposes csv_summary, csv_columns, csv_filter, csv_head, csv_search.

Tables below list each toolkit's enum constant, backing class, the methods it exposes, and any required environment variables. Method names are what the LLM will see and call.

search

Web search, scraping, and specialised lookups.

academic

Free / freemium scholarly databases.

file

Text and structured-document parsing.

CSV_TOOLS — example

CsvTools is the canonical example for the function-shape pattern. The five methods below are independent — the LLM picks the one it needs.

Agent agent = AgentBuilder.create()
    .llm(new OpenAIClient("gpt-4o"))
    .role(myRole)
    .builtInTools(BuiltInTool.CSV_TOOLS)
    .principal(principal)
    .liabilitySink(sink)
    .authorityScope(scope)
    .build();

agent.chat("Summarise /data/sales.csv and list the column headers.");
// LLM emits two tool calls: csv_summary("/data/sales.csv") then csv_columns(...)

The methods accept typed parameters (path, column name, etc.). Each method is a regular Java method whose signature defines the LLM-facing schema (via @Tool and @ToolParam).

communication

Email, chat, and SMS sending.

fintech

Payment and BNPL platforms.

commerce

Storefront APIs.

crm

Customer-relationship platforms.

database

Relational, document, key-value, and vector stores.

sql_query is read-only. It rejects modifying CTEs and SELECT INTO (write tokens outside string literals, not a leading-keyword check) and opens the JDBC session Connection.setReadOnly(true) inside a read-only transaction so a WITH … DELETE prefix cannot commit even if a dialect accepts it. Dialects without read-only SQL still get setReadOnly plus auto-commit-off and rollback.

developer

Repo, dependency, and project introspection.

productivity

Calendars, task trackers, docs.

media

OpenAI audio and Chatterbox TTS.

audio

Non-OpenAI speech synthesis and transcription.

social

Social-network APIs.

ai

Multimodal helpers.

code

Code execution through the framework's Sandbox SPI. Both built-in tools route through SandboxFactory.byId("process") by default with ResourceLimits.standard() + NetPolicy.denyAll(). Pass an explicit SandboxFactory + image-bearing SandboxSpec via the full-control constructors for container / WASM / Firecracker isolation.

utility

Math, hashing, datetime, encoding.

diagram

Diagram-as-code rendering.

document

DOCX / Office / image conversion.

visualization

Charts, tables, infographics.

realtime

Live FX, crypto, weather feeds.

finance

Borsa Istanbul market data.

trading

Prediction markets.

scraping

Apify actor execution.

knowledge

In-memory knowledge graph. Live triples are also the bundled GraphRAG backend when tnsai-intelligence is installed — see KnowledgeTools as GraphRAG.

memory

Persistent recall.

goose

Desktop automation.

project

Repo-level read helpers.

agentsmd_parse returns an AgentsMdContent record (intro + ordered sections: [{level, title, body}]) parsed from AGENTS.md, with case-variant + CLAUDE.md + README.md fallback. Use this when an agent needs to route on individual sections (e.g. pull the "Setup" body) rather than the whole document. agentsmd_generate produces a draft AGENTS.md by detecting the build system from pom.xml / package.json / pyproject.toml / Cargo.toml / go.mod and filling in language-appropriate setup + test commands — returns the markdown string, the caller decides whether to write it.

system

HTTP and tool discovery.

Direct instantiation

If you need to register a toolkit outside the AgentBuilder.builtInTools(...) path — for example, from a plugin loader — every entry has a no-arg instantiate() method that returns a fresh POJO ready for ToolMethodRegistry:

Object csvToolkit = BuiltInTool.CSV_TOOLS.instantiate();
// csvToolkit is a com.tnsai.tools.file.CsvTools instance

instantiate() throws BuiltInToolInstantiationException if tnsai-tools is missing from the classpath (the FQCN string isn't resolvable) or if the POJO's public no-arg constructor fails.

Authoritative source

The full per-toolkit Javadoc — including every @Tool method's exact signature and the corresponding @ToolParam constraints — lives in com.tnsai.enums.BuiltInTool and the backing POJOs under com.tnsai.tools.*.