How do you implement a custom Tool with complex parameter types in LangChain4j?

LangChain4j tools support complex parameter types beyond simple strings and primitives. When a tool method accepts a custom POJO, enum, or collection, LangChain4j automatically generates a JSON schema from the parameter type and includes it in the tool specification sent to the LLM. The model uses this schema to understand what JSON structure it should produce for the tool call arguments, and LangChain4j deserializes them via Jackson before invoking the method.

// Enum parameter
enum Priority { LOW, MEDIUM, HIGH, CRITICAL }

// Complex POJO parameter
record TaskFilter(
    String assignee,
    Priority minPriority,
    @P("Filter to tasks due before this date (ISO-8601)") String dueBefore,
    boolean includeCompleted
) {}

class ProjectTools {

    @Tool("Search project tasks by multiple filter criteria")
    List<Task> searchTasks(
        @P("Filter criteria for the task search") TaskFilter filter
    ) {
        return taskRepository.search(
            filter.assignee(),
            filter.minPriority(),
            LocalDate.parse(filter.dueBefore()),
            filter.includeCompleted()
        );
    }

    @Tool("Update the priority of a specific task")
    void updatePriority(
        @P("Task ID to update") String taskId,
        @P("New priority level") Priority newPriority
    ) {
        taskRepository.updatePriority(taskId, newPriority);
    }
}

The LLM sees the fully expanded JSON schema for TaskFilter including field types and the @P descriptions. Good @P descriptions on nested fields are critical — without them the model may misinterpret the date format, the priority semantics, or which fields are required vs. optional. The return type of tool methods is also automatically serialized to JSON before being added to the conversation as a tool result.

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.