Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Atoti Intelligence SDK

This is part of the Atoti Intelligence SDK offer.
This guide explains how to add custom tools to the Atoti MCP server.

​
What are custom tools?

Custom tools are user-defined functions that extend the MCP server’s capabilities. They appear alongside built-in Atoti tools and can be called by LLM clients. Custom tools are useful for extending the MCP server to support workflows beyond those provided by the default Atoti toolset.

​
Why add custom tools?

Adding custom tools provides several benefits:
  • Extend MCP server functionality for specific use cases
  • Expose domain-specific operations to LLM clients
  • Integrate business logic with AI interactions
  • Create specialized data analysis capabilities

​
How custom tools work

Custom tools follow this process:
  1. Create a service class with methods annotated with @Tool
  2. Use @ToolParam to describe parameters for the LLM
  3. Create a ToolCallbackProvider bean that references the service
  4. The tools are automatically exposed through the MCP server

​
Prerequisites

Before adding custom tools, ensure the following requirements are met:
  • Atoti MCP server is set up
  • Spring Framework knowledge for creating beans and services
  • Understanding of Spring AI tool annotations

​
Implementation example

The following example shows how to add a custom greeting tool. Add the following code to the main application class or a configuration class: 
import org.springframework.ai.tool.ToolCallbackProvider;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.ai.tool.method.MethodToolCallbackProvider;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Service;
/**
 * @author ActiveViam
 */
@Service
public class CustomTools {
  @Tool(name = "greet", description = "Greets a person with the given name.")
  public String greet(@ToolParam(description = "Name of the person to greet") final String name) {
    return "Hello, " + name + "!";
  }
  @Bean
  public ToolCallbackProvider toolCallbackCustomToolProvider(final CustomTools customTool) {
    return MethodToolCallbackProvider.builder().toolObjects(customTool).build();
  }
}

​
Key components

The implementation includes the following components:
  • @Service: Marks the class as a Spring service
  • @Tool: Marks a method as an MCP tool with name and description
  • @ToolParam: Describes parameters to help the LLM understand usage
  • ToolCallbackProvider bean: Registers the tool with the MCP server
  • MethodToolCallbackProvider: Wraps the service methods as tools

​
Tool method requirements

Tool methods must follow these requirements:
  • Return a value (non-void)
  • Use simple parameter types (String, int, boolean, or simple objects)
  • Provide clear descriptions for the LLM
  • Handle errors appropriately

​
Best practices

Follow these practices when creating custom tools:
  • Use descriptive names that indicate the tool’s purpose
  • Write clear descriptions for both tools and parameters
  • Keep tool logic focused and simple
  • Return structured data when appropriate
  • Log tool invocations for debugging
  • Handle edge cases and errors gracefully

​
Verify custom tools

After implementing custom tools, verify they are available:
  1. Start the Atoti application
  2. Connect to the MCP server with Claude or Postman
  3. Check that the custom tool appears in the tool list
  4. Test the tool by calling it with appropriate parameters

​
Troubleshooting

If custom tools do not appear, check the following:
  • The service class has the @Service annotation
  • Methods have the @Tool annotation
  • The ToolCallbackProvider bean is properly configured
  • The application starts without errors
  • The MCP server is properly initialized
After adding custom tools, consider: