FunctionTools

FunctionTools is the service-provider interface for installing host-managed function tools into a provider.

FunctionToolsLoader

FunctionToolsLoader is the runtime loader responsible for discovering and applying all available FunctionTools implementations.

ToolFunction

ToolFunction is the functional interface for executable host-managed tool logic.

Object apply(JsonNode params, File workingDir) throws IOException;

How it works

The method reads these properties from the provider Configurator:

• WebSearchTool.type
• WebSearchTool.city
• WebSearchTool.country
• WebSearchTool.region

If WebSearchTool.type is configured, OpenAIProvider creates a WebSearchTool, sets its type, creates an approximate UserLocation, and adds the tool to the provider tool map. The location object is always created when web search is enabled, while city, country, and region are included only when provided.

TOML configuration

WebSearchTool.type = "web_search_preview"
WebSearchTool.city = "Prague"
WebSearchTool.country = "CZ"
WebSearchTool.region = "Prague"

Property reference

• WebSearchTool.type: required to enable web search; defines the OpenAI web search tool type.
• WebSearchTool.city: optional city value added to the approximate user location.
• WebSearchTool.country: optional country value added to the approximate user location.
• WebSearchTool.region: optional region or state value added to the approximate user location.

Use case

Enable web search when the model should be able to work with current public web information instead of relying only on training-time knowledge.

How it works

The method supports a base property group and indexed property groups.

TOML configuration for one MCP server

MCP.url = "https://example.org/mcp"
MCP.label = "Project MCP"
MCP.description = "MCP server for project-specific tools"
MCP.authorization = "Bearer your-token"

TOML configuration for multiple MCP servers

MCP.url = "https://example.org/mcp"
MCP.label = "Primary MCP"
MCP.description = "Primary project tools"
MCP.authorization = "Bearer primary-token"

MCP_1.url = "https://example.org/mcp-admin"
MCP_1.label = "Admin MCP"
MCP_1.description = "Administrative MCP tools"
MCP_1.authorization = "Bearer admin-token"

Property reference

• MCP.url: required for the first MCP server; enables that server entry.
• MCP.label: optional human-readable label for the first MCP server.
• MCP.description: optional description for the first MCP server.
• MCP.authorization: optional authorization value for the first MCP server.
• MCP_1.url, MCP_2.url, and so on: required for additional MCP server entries.
• MCP_1.label, MCP_2.label, and so on: optional labels for additional MCP server entries.
• MCP_1.description, MCP_2.description, and so on: optional descriptions for additional MCP server entries.
• MCP_1.authorization, MCP_2.authorization, and so on: optional authorization values for additional MCP server entries.

Use case

Use MCP support when the OpenAI provider should connect to external Model Context Protocol servers that expose tools outside the local Java process.

What this does

OpenAIProvider.addTool(...) converts the parameter descriptions into a JSON Schema object of type object, creates an OpenAI FunctionTool, and stores the tool together with its ToolFunction callback.

Parameter descriptor format

Each descriptor string uses this format:

name:type:required:description

Examples:

path:string:required:File path to read
limit:integer:optional:Maximum number of items

Any parameter whose third segment is required is added to the JSON Schema required list.

Step 1: Create the tool installer

package com.example.tools;

import java.io.File;

import com.fasterxml.jackson.databind.JsonNode;

import org.machanism.macha.core.commons.configurator.Configurator;
import org.machanism.machai.ai.provider.Genai;
import org.machanism.machai.ai.tools.FunctionTools;

public class ExampleFunctionTools implements FunctionTools {

    private Configurator configurator;

    @Override
    public void setConfigurator(Configurator configurator) {
        this.configurator = configurator;
    }

    @Override
    public void applyTools(Genai provider) {
        provider.addTool(
            "example_tool",
            "Processes an input value and returns a simple response.",
            (JsonNode params, File workingDir) -> {
                String input = params != null && params.has("input") ? params.get("input").asText() : "";
                String prefix = configurator != null ? configurator.get("example.prefix", "") : "";
                return prefix + input;
            },
            "input:string:required:Text value to process"
        );
    }
}

This pattern is the standard approach:

• keep any needed Configurator reference,
• register tools in applyTools(...),
• use clear names and descriptions,
• and implement the behavior with a ToolFunction lambda or method reference.

Step 2: Register the implementation

Create this file:

src/main/resources/META-INF/services/org.machanism.machai.ai.tools.FunctionTools

Add the fully qualified class name of the implementation:

com.example.tools.ExampleFunctionTools

If the file contains multiple class names, all of them can be discovered and applied.

Step 3: Apply tools at runtime

Configurator conf = ...;
Genai provider = ...;

FunctionToolsLoader loader = new FunctionToolsLoader();
loader.applyTools(provider, conf);

Step 4: Understand runtime invocation

When the model selects a registered function tool:

1. OpenAIProvider receives the tool call.
2. The JSON arguments are parsed into a JsonNode.
3. The matching tool is found by name.
4. The associated ToolFunction is called with the parsed parameters and current working directory.
5. The returned value is sent back as tool output.

If the tool throws an IOException, the provider returns a readable error message to the model instead of failing silently.