FunctionTools

FunctionTools is the marker SPI for contributing host-managed tools, prompts, and resources to a ProcessProvider.

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, prompt, or resource.

Object apply(JsonNode params, Object... paramsByType) throws Exception

@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.";
}

@Resource

@Resource marks a public method that provides content at one or more URI endpoints. Resource support is useful for exposing schemas, project instructions, configuration documents, or other contextual assets that a provider can load during a run.

@Resource(
        uri = { "file:///schemas/project.json" },
        description = "Project validation schema.",
        mimeType = "application/json")
public String projectSchema() {
    return loadSchema();
}

ErrorResultException

ErrorResultException is a runtime exception for returning structured tool errors. An object passed to its constructor is serialized as JSON; a string is used as-is. The overload accepting an Exception includes both the underlying error and serialized details, making it suitable when the model needs machine-readable failure information.

ToolExecutionException

ToolExecutionException is a checked exception for a tool callback that cannot complete its requested operation. Create it with a descriptive message or the underlying cause. Because ToolFunction.apply(...) can throw Exception, a programmatic ToolFunction can use this type to make an expected execution failure explicit; the provider's normal safety handling then returns the failure to the model when conversational error handling is enabled.

SpecialException

SpecialException signals a deliberate, non-recoverable tool condition, such as ending the current task. Provider safety handling rethrows it instead of converting it into the normal conversational error text, so use it only when ordinary tool failure recovery should be bypassed.

Role

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

ParamDescriptor

ParamDescriptor is a metadata holder for a single tool, prompt, or resource parameter. It is used when a provider registers a capability programmatically or when the provider converts an annotated method signature into a provider schema.

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

@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. The loader always evaluates MCP and MCP_1; it evaluates MCP_2 and every later group only when the immediately preceding group's .url was non-null. Keep numbered groups contiguous and provide a URL for each group that should allow discovery to continue. A group with a name but no URL is still passed to addMcpServer(...), so it is invalid configuration even though the registration check itself is based on .name.

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 when the sequential scan reaches it. Supply both .name and .url: the loader uses .name as its registration check, while addMcpServer(...) passes .url directly to the OpenAI SDK as serverUrl.

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. (The OpenAI provider documentation may call this field label; this implementation reads .name.)
• 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.

Note: The implementation reads .name, not .label, for every MCP configuration group. MCP.label and MCP_1.label are therefore not used by this loader.

MCP.authorization is supplied to the OpenAI MCP-tool builder unchanged. Store and provide the value in the format expected by the target MCP service (for example, a complete Bearer ... value); this configuration does not construct an authorization header for you.

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.

MyFunctionTools tools = new MyFunctionTools();
provider.addTools(tools, null);
provider.addPrompts(tools);
provider.addResources(tools);

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 provider implementations or subclasses where annotation-based registration is not suitable, the protected provider API exposes an explicit registration hook:

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. Application code using only the ProcessProvider interface should normally use a FunctionTools implementation; it cannot call this protected hook directly.

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.

For annotation-based registration, a parameter named project-dir is excluded from the schema when a project directory has been configured and is injected by the provider at runtime instead. The OpenAI programmatic addTool(...) implementation excludes a descriptor with that name unconditionally, so do not list it as a model-supplied parameter.

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 logs the parsing failure and returns the exception text as the function output, allowing the model conversation to continue.

Step 1: Create a tool bundle

package com.example.tools;

import org.machanism.macha.core.commons.configurator.Configurator;
import org.machanism.machai.process.tools.FunctionTools;
import org.machanism.machai.process.tools.Param;
import org.machanism.machai.process.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.process.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

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

FunctionToolsLoader loader = new FunctionToolsLoader();
loader.applyTools(provider, null, 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 every model-supplied parameter with an explicit name and accurate description,
• 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: Handle failures intentionally

Throw an exception when the requested operation cannot be completed. With the default provider error handling enabled, ordinary failures are converted into a model-visible error result, allowing the model to adjust its next call. Use ToolExecutionException to make an expected execution failure explicit, or ErrorResultException when the error details should be returned as a structured JSON message. Reserve SpecialException for a deliberate control-flow condition that must bypass normal conversational error handling.

Step 7: 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.