> ## 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.

# How to add custom tools

> How to extend the Atoti MCP Server with user-defined tools using Spring AI `@Tool`, `@ToolParam`, and `MethodToolCallbackProvider`, including an implementation example, tool method requirements, and verification steps.

<Info>
  ### Atoti Intelligence SDK

  This is part of the Atoti Intelligence SDK offer.
</Info>

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:

```java theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
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

## Related reading

After adding custom tools, consider:

* [Connect with Postman](./setup/connect-with-postman) to test the tools without an LLM
* [Connect with Claude](./setup/connect-with-claude) to test the tools with an LLM