Tool Service

The ToolService provides access to IBM watsonx.ai Utility Agent Tools, a set of server-side tools that can be invoked directly or integrated with ChatService, DeploymentService, or ModelGatewayChatService for agentic workflows. Each built-in tool also implements the ExecutableTool interface, enabling automatic dispatch when a foundation model requests a tool call.

Quick Start

ToolService toolService = ToolService.builder()
    .apiKey(WATSONX_API_KEY)
    .baseUrl(CloudRegion.DALLAS)
    .build();

// Use a built-in tool directly
GoogleSearchTool googleSearch = new GoogleSearchTool(toolService);
List<GoogleSearchResult> results = googleSearch.search("watsonx.ai java sdk");

// Or run any tool by name using the generic API
String output = toolService.run(
    ToolRequest.structuredInput("Weather", Map.of("location", "Rome"))
);

Overview

The ToolService enables you to:

List all available utility tools and inspect their metadata, input schema, and config schema.
Retrieve metadata for a specific tool by name.
Execute any tool generically via run() using structured or unstructured input.
Use built-in tool wrappers (GoogleSearchTool, WeatherTool, etc.) for type-safe invocations.
Integrate built-in tools with ChatService via the ExecutableTool interface for agentic tool-call dispatch.

Service Configuration

Basic Setup

ToolService toolService = ToolService.builder()
    .apiKey(WATSONX_API_KEY)
    .baseUrl("https://us-south.wx.ml.cloud.ibm.com") // or use CloudRegion
    .build();

Builder Parameters

Parameter	Type	Required	Description
`apiKey`	String	Conditional	API key for IBM Cloud authentication
`authenticator`	Authenticator	Conditional	Custom authentication (alternative to `apiKey`)
`baseUrl`	String/CloudRegion	Yes	watsonx.ai service URL
`timeout`	Duration	No	Request timeout (default: 60 seconds)
`logRequests`	Boolean	No	Enable request logging (default: false)
`logResponses`	Boolean	No	Enable response logging (default: false)
`httpClient`	HttpClient	No	Custom HTTP client
`verifySsl`	Boolean	No	SSL certificate verification (default: true)

Either apiKey or authenticator must be provided. No projectId, spaceId, or modelId is required.

Service Methods

List All Tools

ToolService.Resources resources = toolService.getAll();

for (UtilityTool tool : resources.resources()) {
    System.out.println(tool.name() + " - " + tool.description());
}

Get Tool by Name

UtilityTool tool = toolService.getByName("GoogleSearch");

System.out.println(tool.name());
System.out.println(tool.description());
System.out.println(tool.agentDescription());  // system prompt guidance for LLM agents
System.out.println(tool.inputSchema());        // JSON schema for the input
System.out.println(tool.configSchema());       // JSON schema for config options

Run a Tool Generically

// Structured input - for tools with a defined input schema
String output = toolService.run(
    ToolRequest.structuredInput(
        "GoogleSearch",
        Map.of("q", "watsonx.ai"),          // input map
        Map.of("maxResults", 5)             // config map
    )
);

// Unstructured input - for tools that accept a plain string
String output = toolService.run(
    ToolRequest.unstructuredInput("RAGQuery", "What is this project about?")
);

The run() method always returns the output field from the tool's JSON response as a String.

UtilityTool

The UtilityTool record represents the metadata returned by getAll() and getByName():

Field	Type	Description
`name()`	String	Unique tool identifier used in requests
`description()`	String	Human-readable description of the tool
`agentDescription()`	String	System prompt guidance for LLM agents
`inputSchema()`	Map<String, Object>	JSON schema for the tool's input payload
`configSchema()`	Map<String, Object>	JSON schema for the tool's configuration options

Built-in Tools

All built-in tools implement the ExecutableTool interface, which exposes:

name() - the tool schema name used by the LLM
schema() - the Tool definition to pass to ChatService
execute(ToolArguments args) - called automatically during tool-call dispatch

There are several built-in tools in watsonx.ai that can be used to add functionality to an LLM.

GoogleSearchTool

Search for online trends, news, current events, real-time information, or research topics.

GoogleSearchTool googleSearch = new GoogleSearchTool(toolService);

// Default: up to 10 results
List<GoogleSearchResult> results = googleSearch.search("watsonx.ai java sdk");

// Custom max results
List<GoogleSearchResult> results = googleSearch.search("watsonx.ai java sdk", 3);

for (GoogleSearchResult r : results) {
    System.out.println(r.title());
    System.out.println(r.description());
    System.out.println(r.url());
}

TavilySearchTool

Search for online trends, news, current events, and research topics using the Tavily API. Requires a Tavily API key.

TavilySearchTool tavilySearch = new TavilySearchTool(toolService, TAVILY_API_KEY);

List<TavilySearchResult> results = tavilySearch.search("watsonx.ai java sdk");
List<TavilySearchResult> results = tavilySearch.search("watsonx.ai java sdk", 5);

for (TavilySearchResult r : results) {
    System.out.println(r.title());
    System.out.println(r.url());
    System.out.println(r.content());
    System.out.println(r.score());   // relevance score (Double)
}

WeatherTool

Fetch current weather information for a location.

WeatherTool weather = new WeatherTool(toolService);

// Location only
String result = weather.find("Rome");

// Location and country
String result = weather.find("Naples", "Italy");

WebCrawlerTool

Fetch and extract the text content of a specific web page. Use when you know the URL and need to read its content, not for discovering new URLs.

WebCrawlerTool crawler = new WebCrawlerTool(toolService);
String content = crawler.process("https://github.com/IBM/watsonx-ai-java-sdk");

WikipediaTool

Search Wikipedia and retrieve article summaries.

WikipediaTool wikipedia = new WikipediaTool(toolService);
String result = wikipedia.search("watsonx.ai");

PythonInterpreterTool

Execute Python code in a remote IBM watsonx.ai deployment runtime and return the console output. Requires a deployment ID for the Python interpreter.

PythonInterpreterTool python = new PythonInterpreterTool(toolService, PYTHON_DEPLOYMENT_ID);
String result = python.run("print('Hello World!')");
// → Hello World!

RAGQueryTool

Query one or more vector indexes using semantic similarity to retrieve relevant document passages. Requires a Project ID or Space ID and at least one vector index ID.

RAGQueryTool ragQuery = RAGQueryTool.builder()
    .toolService(toolService)
    .projectId("project-id")
    .vectorIndexIds("index-1")
    .description("The document contains information about the watsonx.ai Java SDK.")
    .build();

String result = ragQuery.query("What is the Maven groupId?");

Integration with ChatService

All built-in tools implement ExecutableTool and can be passed directly to ChatService to enable agentic tool-call dispatch. When the model requests a tool call, your code dispatches it and feeds the result back.

Manual Dispatch

GoogleSearchTool googleSearch = new GoogleSearchTool(toolService);
WebCrawlerTool webCrawler = new WebCrawlerTool(toolService);

var chatService = ChatService.builder()
    .baseUrl(CloudRegion.DALLAS)
    .apiKey(WATSONX_API_KEY)
    .projectId(WATSONX_PROJECT_ID)
    .modelId("ibm/granite-4-h-small")
    .tools(googleSearch.schema(), webCrawler.schema())
    .build();

List<ChatMessage> messages = new ArrayList<>();
messages.add(SystemMessage.of("You are a helpful assistant."));
messages.add(UserMessage.text("Is there a watsonx.ai Java SDK? If yes, give me the Maven groupId."));

var assistantMessage = chatService.chat(messages).toAssistantMessage();
messages.add(assistantMessage);

if (assistantMessage.hasToolCalls()) {
    var toolMessages = assistantMessage.processTools((toolName, toolArgs) ->
        switch (toolName) {
            case "google_search" -> googleSearch.search(toolArgs.get("query")).toString();
            case "webcrawler"    -> webCrawler.process(toolArgs.get("url"));
            default -> throw new IllegalArgumentException("Unknown tool: " + toolName);
        }
    );
    messages.addAll(toolMessages);
    assistantMessage = chatService.chat(messages).toAssistantMessage();
}

System.out.println(assistantMessage.content());

Using ToolRegistry

ToolRegistry simplifies multi-tool dispatch by registering tools by name and optionally adding lifecycle hooks:

RAGQueryTool ragQuery = RAGQueryTool.builder()
    .toolService(toolService)
    .projectId(WATSONX_PROJECT_ID)
    .vectorIndexIds(VECTOR_INDEX_ID)
    .description("Documents contain information about our internal project.")
    .build();

ToolRegistry registry = ToolRegistry.builder()
    .register(ragQuery)
    .build();

var chatService = ChatService.builder()
    ...
    .tools(registry.tools())
    .build();

// During tool-call dispatch:
var toolMessages = assistantMessage.processTools(registry::execute);

Built-in Tools Summary

Tool class	Schema name	Requires	Returns
`GoogleSearchTool`	`google_search`	-	`List<GoogleSearchResult>`
`TavilySearchTool`	`tavily_search`	Tavily API key	`List<TavilySearchResult>`
`WeatherTool`	`weather`	-	`String` (plain text)
`WebCrawlerTool`	`webcrawler`	-	`String` (page content)
`WikipediaTool`	`wikipedia`	-	`String` (article summary)
`PythonInterpreterTool`	`python_interpreter`	Deployment ID	`String` (console output)
`RAGQueryTool`	`rag_query`	Project/Space ID + vector index IDs	`String` (retrieved passages)

Quick Start​

Overview​

Service Configuration​

Basic Setup​

Builder Parameters​

Service Methods​

List All Tools​

Get Tool by Name​

Run a Tool Generically​

UtilityTool​

Built-in Tools​

GoogleSearchTool​

TavilySearchTool​

WeatherTool​

WebCrawlerTool​

WikipediaTool​

PythonInterpreterTool​

RAGQueryTool​

Integration with ChatService​

Manual Dispatch​

Using ToolRegistry​

Built-in Tools Summary​

Related Resources​