Tool catalog

To write your own, see Custom tools. To choose between an action, a tool and an MCP server, see Actions and tools.

Register toolkits

Pass BuiltInTool constants, and the framework creates each toolkit for you. build() requires principal and authorityScope; liabilitySink is optional.

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 model sees every @Tool method of every registered toolkit, and calls each by its @Tool 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.

Each category is the toolkit's package under com.tnsai.tools:

The tables below list each toolkit's constant, its tools and the environment variables it needs. The tool names are what the model calls.

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, and 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.

image

Image generation. See Images and speech.

code

Code execution through the framework's Sandbox SPI. The Python and Node toolkits run through the process sandbox by default, with ResourceLimits.standard() and NetPolicy.denyAll(). For container isolation, pass a SandboxFactory and a SandboxSpec with an image to their full constructors. E2B runs code remotely, in E2B's cloud.

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-rag is installed. See Graph stores.

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. It returns the markdown string, and the caller decides whether to write it.

system

HTTP and tool discovery.

Direct instantiation

To register a toolkit another way, for example from a plugin loader, call instantiate(). It returns a new instance of the toolkit class:

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

for (BuiltInTool entry : BuiltInTool.values()) {
    System.out.println(entry.getToolName() + " -> " + entry.getClassName());
}

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.*.