FunctionTools

FunctionTools is the marker SPI for contributing host-managed tools and prompts to a Genai provider.

FunctionToolsLoader

FunctionToolsLoader is the bootstrap component that discovers FunctionTools implementations and applies compatible ones to a provider.

ToolFunction

ToolFunction is the functional callback contract used by the provider when invoking a host-managed tool or prompt.

Object apply(JsonNode params, File projectDir, Configurator config) throws IOException

@Tool

@Tool is a method-level annotation that marks a public method on a FunctionTools implementation as a callable tool.

@Tool(name = "read_file", description = "Reads the content of a file.")
public String readFile(@Param(name = "path", description = "File path to read") String path) {
    // ...
}

@Param

@Param is a parameter-level annotation used to describe method parameters for tool and prompt schema generation.

@Prompt

@Prompt is a method-level annotation that marks a public method on a FunctionTools implementation as a reusable prompt.

@Prompt(name = "summarize_instructions", description = "Instruction prompt for summarization.", role = Role.ASSISTANT)
public String summarizeInstructions() {
    return "Summarize the provided content concisely.";
}

Role

Role is the enum used by @Prompt to specify the conversation role associated with a prompt.

ParamDescriptor

ParamDescriptor is a simple metadata holder for a single tool or prompt parameter.

new ParamDescriptor(String name, String type, boolean required, String description)

@SupportedFor

@SupportedFor restricts a FunctionTools implementation to one or more application classes.

@SupportedFor({ ActProcessor.class })
public class ActSpecFunctionTools implements FunctionTools {
    // ...
}

Tool registration flow

When provider.addTools(functionTools) is called:

• the provider scans public methods of the implementation class,
• it selects methods annotated with @Tool,
• it resolves the exposed tool name from @Tool.name or falls back to the Java method name,
• it collects @Param metadata from method parameters,
• it converts parameter Java types through the internal type converter,
• it marks parameters as required when defaultValue is not declared,
• and it wraps reflective method invocation into a ToolFunction callback.

Prompt registration flow

When provider.addPrompts(functionTools) is called:

• the provider scans public methods annotated with @Prompt,
• it resolves the prompt name from @Prompt.name or the method name,
• it captures the prompt role from @Prompt.role,
• it builds parameter descriptors in the same way as for tools,
• and it wraps the method in a ToolFunction callback for prompt execution.

Invocation and parameter resolution

At invocation time, the provider:

• reads JSON arguments into a Jackson JsonNode,
• resolves explicit tool parameters from JSON by annotated name,
• applies @Param.defaultValue when no argument was supplied,
• supports placeholder substitution between earlier resolved argument values and later default values,
• injects Configurator for unannotated parameters of that type,
• injects File for unannotated file-context parameters,
• auto-fills the reserved project_dir parameter from the configured provider project directory,
• and applies placeholder substitution to string return values before returning them.

This means a custom tool method can combine model-supplied arguments with application runtime context without manual parsing boilerplate.

How addWebSearch(...) behaves

• It creates a UserLocation builder and always sets the location type to approximate.
• If type equals the provider alias default, the method translates it to web_search_preview.
• It optionally fills city, country, and region when values are present.
• It builds an OpenAI WebSearchTool instance.
• The resulting tool is wrapped as a provider Tool and stored in the provider tool map.

Configuration

Web search is enabled when WebSearchTool.type is present in configuration. The base registration flow lives in AbstractAIProvider.addWebSearch(), which reads the configured values and calls the OpenAI-specific addWebSearch(...) implementation.

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

WebSearchTool.type=default

How MCP server loading works

The base implementation in AbstractAIProvider.addMcpServers() looks for configuration groups in this order:

• MCP.* for the first server,
• MCP_1.* for the second server,
• MCP_2.* and higher for additional servers.

For each group:

• .url provides the MCP endpoint,
• .name provides the visible server label,
• .authorization is optional,
• .description is optional.

A server is registered when the group has a non-null .name value.

How addMcpServer(...) behaves

• It creates an OpenAI MCP tool builder.
• name is mapped to serverLabel.
• url is mapped to serverUrl.
• description is mapped to serverDescription when present.
• authorization is attached when present.
• The resulting MCP tool is stored in the provider tool map.

Configuration properties for the first MCP server

• MCP.url
• MCP.name
• MCP.description
• MCP.authorization

Configuration properties for additional MCP servers

The provider also supports numbered groups such as:

• MCP_1.url
• MCP_1.name
• MCP_1.description
• MCP_1.authorization
• MCP_2.url
• MCP_2.name
• MCP_2.description
• MCP_2.authorization

Each numbered group with a non-null .name can register another MCP server.

Property reference

• MCP.url: URL of the first MCP server endpoint.
• MCP.name: label of the first MCP server. This is the value passed into addMcpServer(...) and mapped to the OpenAI MCP serverLabel.
• MCP.description: optional description for the first MCP server.
• MCP.authorization: optional authorization value attached to the MCP server definition.
• MCP_1.url, MCP_2.url, and higher: endpoint URLs for additional MCP servers.
• MCP_1.name, MCP_2.name, and higher: labels for additional MCP servers.
• MCP_1.description, MCP_2.description, and higher: optional descriptions for additional MCP servers.
• MCP_1.authorization, MCP_2.authorization, and higher: optional authorization values for additional MCP servers.

Example for one MCP server

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

Example for multiple MCP servers

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

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

When to use it

Use MCP integration when the provider should expose tools from external Model Context Protocol servers instead of implementing those tools directly in the local Java process.

Annotation-based registration

The preferred approach is to implement FunctionTools, annotate methods with @Tool, and let the provider register them.

provider.addTools(new MyFunctionTools());
provider.addPrompts(new MyFunctionTools());

In practice, FunctionToolsLoader usually handles this automatically for discovered implementations.

The provider scans public methods on the instance, finds those annotated with @Tool, generates parameter descriptors from @Param annotations, and registers each one. Methods annotated with @Prompt are registered as prompts in the same setup flow.

Programmatic registration

For situations where annotation-based registration is not suitable, the provider exposes an explicit API:

addTool(String name, String description, ToolFunction function, ParamDescriptor... paramsDesc)

In OpenAIProvider, addTool(...) converts ParamDescriptor entries into an object-style JSON schema and creates an OpenAI FunctionTool.

The generated parameter schema includes:

• a properties object built from parameter descriptors,
• a top-level type value of object,
• and a required array for parameters whose isRequired() returns true.

Parameters whose name equals project_dir are excluded from the schema and are injected by the provider at runtime instead.

The tool is created with strict(false) and stored together with its ToolFunction callback.

Runtime invocation flow in OpenAIProvider

When the model calls a host-managed function tool in OpenAIProvider:

1. The provider receives the tool call from the OpenAI response.
2. The JSON arguments are parsed into a Jackson JsonNode.
3. The provider searches registered tools by normalized function name.
4. The matching ToolFunction is invoked with parsed parameters, the current projectDir, and the provider Configurator.
5. The returned value is serialized if necessary and attached as function output.
6. The provider sends a follow-up request so the model can continue using the tool result.

If JSON argument parsing fails, the provider throws an IllegalArgumentException.

Step 1: Create a tool bundle

package com.example.tools;

import org.machanism.macha.core.commons.configurator.Configurator;
import org.machanism.machai.ai.tools.FunctionTools;
import org.machanism.machai.ai.tools.Param;
import org.machanism.machai.ai.tools.Tool;

public class ExampleFunctionTools implements FunctionTools {

    @Tool(name = "example_tool", description = "Processes an input value and returns a simple response.")
    public String exampleTool(
            @Param(name = "input", description = "Text value to process") String input,
            Configurator config) {
        String prefix = config != null ? config.get("example.prefix", "") : "";
        return prefix + (input != null ? input : "");
    }
}

Step 2: Register the implementation with ServiceLoader

Create this file:

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

Add the fully qualified class name:

com.example.tools.ExampleFunctionTools

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

Step 3: Apply tools during provider setup

Genai provider = ...;
Class<?> appClass = MyProcessor.class;

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

Step 4: Optionally add prompts

If your bundle should contribute reusable prompts, add public methods annotated with @Prompt.

@Prompt(name = "example_prompt", description = "Reusable helper prompt", role = Role.ASSISTANT)
public String examplePrompt() {
    return "Follow the project conventions and keep the answer concise.";
}

Step 5: Design the tool carefully

When creating a custom tool, follow these recommendations:

• use a short, stable tool name,
• write a description that clearly explains the tool purpose,
• annotate parameters with accurate descriptions,
• use defaultValue on @Param for optional parameters,
• use the reserved project_dir parameter name when the tool needs the provider working directory path,
• use an unannotated Configurator parameter when the tool needs runtime configuration,
• use an unannotated File parameter when the tool needs direct access to the current project directory object,
• return simple structured output when possible,
• register the implementation through META-INF/services so it can be discovered automatically,
• and apply security restrictions before exposing file, network, or command capabilities.

Step 6: Restrict the tool when necessary

Use @SupportedFor when a tool bundle should be active only for specific application classes.

@SupportedFor({ ActProcessor.class })
public class ActSpecFunctionTools implements FunctionTools {
    // ...
}

If @SupportedFor is omitted, the tool bundle is treated as globally compatible.