Skip to content
Skills Library
AI & agents · Building & coding

langchain4j-tool-function-calling-patterns

/langchain4j-tool-function-calling-patterns

Provides and generates LangChain4j tool and function calling patterns: annotates methods as tools with @Tool, configures tool executors, registers tools with AiServices, validates tool parameters, and handles tool execution errors. Use when building AI agents that call tools, define function specifications, manage tool responses, or integrate external APIs with LLM-driven applications.

Licence
MIT
Last repository change
10.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
9
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 10.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Provides and generates LangChain4j tool and function calling patterns: annotates methods as tools with @Tool, configures tool executors, registers tools with AiServices, validates tool parameters, and handles tool execution errors. Use when building AI agents that call tools, define function specifications, manage tool responses, or integrate external APIs with LLM-driven applications.

Original author description

Provides and generates LangChain4j tool and function calling patterns: annotates methods as tools with @Tool, configures tool executors, registers tools with AiServices, validates tool parameters, and handles tool execution errors. Use when building AI agents that call tools, define function specifications, manage tool responses, or integrate external APIs with LLM-driven applications.

How it works

  1. Overview
  2. When to Use
  3. Instructions
  4. Examples
  5. Best Practices
  6. Common Issues and Solutions
  7. Quick Reference
  8. Constraints and Warnings
  9. Related Skills
  10. References
Original SKILL.md headings · 214 lines, 1,035 words
SKILL.md preview
---
name: langchain4j-tool-function-calling-patterns
description: "Provides and generates LangChain4j tool and function calling patterns: annotates methods as tools with @Tool, configures tool executors, registers tools with AiServices, validates tool parameters, and handles tool execution errors. Use when building AI agents that call tools, define function specifications, manage tool responses, or integrate external APIs with LLM-driven applications."
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch
---

# LangChain4j Tool & Function Calling Patterns

Provides patterns for annotating methods as tools, configuring tool executors, registering tools with AI services, validating parameters, and handling tool execution errors in LangChain4j applications.

## Overview

LangChain4j uses the `@Tool` annotation to expose Java methods as callable functions for AI agents. The `AiServices` builder registers tools with a chat model, enabling LLMs to perform actions beyond text generation: database queries, API calls, calculations, and business system integrations. Parameters use `@P` for descriptions that guide the LLM.

## When to Use

- Building AI agents that call external tools (weather, stocks, database queries)
- Defining function specifications for LLM tool use (`@Tool`, `@P` annotations)
- Registering and managing tool sets with `AiServices.builder().tools()`
- Handling tool execution errors, timeouts, and hallucinated tool names
- Implementing context-aware tools that inject user state via `@ToolMemoryId`
- Configuring dynamic tool providers for large or conditional tool sets

## Instructions

### 1. Annotate Methods with `@Tool`

Define a tool class with methods annotated `@Tool`. Provide a description as the first parameter. Use `@P` for each parameter description.

```java
public class WeatherTools {
    private final WeatherService weatherService;

    public WeatherTools(WeatherService weatherService) {
        this.weatherService = weatherService;
    }

    @Tool("Get current weather for a city")
    public String getWeather(
            @P("City name") String city,
            @P("Temperature unit: celsius or fahrenheit") String unit) {
        return weatherService.getWeather(city, unit);
    }
}
```

**Validate**: Create an instance and confirm the class loads without errors.

### 2. Register Tools with AiServices

Use `AiServices.builder()` to register tool instances with the chat model.

```java
MathAssistant assistant = AiServices.builder(MathAssistant.class)
    .chatModel(chatModel)
    .tools(new Calculator(), new WeatherTools(weatherService))
    .build();
```

**Validate**: Call `assistant.chat("What is 2 + 2?")` and verify the LLM responds without throwing.

### 3. Test Tool Invocation End-to-End

Send a prompt that triggers tool usage and verify the tool executes and its result is incorporated.

```java
String response = assistant.chat("What is the weather in Rome?");
System.out.println(response);
```

**Validate**: Check logs for tool invocation and confirm the response uses the tool output.

### 4. Handle Tool Execution Errors

Add error handlers to gracefully manage failures without exposing stack traces.

```java
AiServices.builder(Assistant.class)
    .chatModel(chatModel)
    .tools(new ExternalServiceTools())
    .toolExecutionErrorHandler((request, exception) -> {
        logger.error("Tool '{}' failed: {}", request.name(), exception.getMessage());
        return "An error occurred while processing your request";
    })
    .hallucinatedToolNameStrategy(request ->
        ToolExecutionResultMessage.from(request,
            "Error: tool '" + request.name() + "' does not exist"))
    .toolArgumentsErrorHandler((error, context) ->
        ToolErrorHandlerResult.text("Invalid arguments: " + error.getMessage()))
    .build();
```

**Validate**: Trigger an error condition and confirm the LLM receives a safe error message.

### 5. Optimize for Performance and Scale

Enable concurrent tool execution and set timeouts for long-running tools.

```java
AiServices.builder(Assistant.class)
    .chatModel(chatModel)
    .tools(new DbTools(), new HttpTools())
    .executeToolsConcurrently(Executors.newFixedThreadPool(5))
    .toolExecutionTimeout(Duration.ofSeconds(30))
    .build();
```

**Validate**: Run concurrent requests and confirm no thread contention or deadlocks.

## Examples

### Calculator Tool with Full Class

```java
public class Calculator {
    @Tool("Perform basic arithmetic")
    public double calculate(
            @P("Expression like 2+2 or 10*5") String expression) {
        // Parse and evaluate expression
        return eval(expression);
    }
}

Assistant assistant = AiServices.builder(Assistant.class)
    .chatModel(ChatModel.builder()
        .apiKey(System.getenv("API_KEY"))
        .model("gpt-4o")
        .build())
    .tools(new Calculator())
    .build();
```

### Immediate Return Tool (No LLM Response)

```java
@Tool(value = "Send email notification", returnBehavior = ReturnBehavior.IMMEDIATELY)
public void sendEmail(@P("Recipient email address") String to,
                     @P("Email subject") String subject,
                     @P("Email body") String body) {
    emailService.send(to, subject, body);
}
```

### Dynamic Tool Provider

```java
ToolProvider provider = request -> {
    if (request.userContext().contains("admin")) {
        return List.of(new AdminTools());
    }
    return List.of(new UserTools());
};

AiServices.builder(Assistant.class)
    .chatModel(chatModel)
    .toolProvider(provider)
    .build();
```

## Best Practices

- **Descriptive `@Tool` names**: Use imperative verbs ("Get", "Send", "Calculate") with clear scope
- **Precise `@P` descriptions**: Include format, constraints, and valid values — vague descriptions cause incorrect LLM calls
- **Safe error handling**: Never expose stack traces; return user-friendly error strings
- **Timeout configuration**: Always set `.toolExecutionTimeout()` for external service calls
- **Concurrent execution**: Enable `.executeToolsConcurrently()` when tools are independent
- **Input validation**: Validate parameters inside the tool method; return descriptive errors
- **Permission checks**: Perform authorization inside the tool, not at the AI service level
- **Audit logging**: Log tool name, parameters, and execution result for debugging and compliance

## Common Issues and Solutions

| Issue | Solution |
|-------|----------|
| LLM calls non-existent tool | Add `.hallucinatedToolNameStrategy()` returning a safe error message |
| Tools receive wrong parameters | Refine `@P` descriptions; add `.toolArgumentsErrorHandler()` |
| Tool execution hangs | Set `.toolExecutionTimeout(Duration.ofSeconds(N))` |
| Rate limit errors from external API | Add retry logic or rate limiter inside the tool method |
| LLM ignores tool output | Ensure the tool returns a string the LLM can interpret |

See [references/error-handling.md](references/error-handling.md) for resilience patterns and [references/core-patterns.md](references/core-patterns.md) for parameter and return type details.

## Quick Reference

| Annotation / API | Purpose |
|-----------------|---------|
| `@Tool` | Marks a method as a callable tool |
| `@P` | Describes a tool parameter for the LLM |
| `@ToolMemoryId` | Injects conversation/user ID into the tool |
| `AiServices.builder()` | Creates AI service with registered tools |
| `ReturnBehavior.IMMEDIATELY` | Execute tool without waiting for LLM response |
| `ToolProvider` | Dynamic tool provisioning based on context |
| `executeToolsConcurrently()` | Run independent tool calls in parallel |
| `toolExecutionTimeout()` | Timeout for individual tool calls |

## Constraints and Warnings

- **Sensitive data**: Never pass API keys, passwords, or credentials in `@Tool` or `@P` descriptions
- **Side effects**: Tools that modify data should warn in their description; AI models may call them multiple times
- **Large tool sets**: Excessive tools confuse LLM models — use `ToolProvider` for conditional registration
- **Blocking operations**: Tools should not perform long synchronous I/O without timeout configuration
- **Stack trace exposure**: Always route exceptions through error handlers that return safe strings
- **Parameter precision**: Vague `@P` descriptions directly cause incorrect tool calls — be specific about formats and constraints
- **Concurrent safety**: Ensure tool classes are stateless or thread-safe when using `executeToolsConcurrently()`

## Related Skills

- `langchain4j-ai-services-patterns` — High-level AI service configuration
- `langchain4j-rag-implementation-patterns` — RAG retrieval with tool integration
- `langchain4j-spring-boot-integration` — Tool registration in Spring Boot applications

## References

- **[references/setup-configuration.md](references/setup-configuration.md)** — Maven setup, chat model configuration, first tool registration
- **[references/core-patterns.md](references/core-patterns.md)** — Basic tool definition, complex parameters, return types
- **[references/advanced-features.md](references/advanced-features.md)** — Memory context, dynamic tool providers, streaming, immediate return
- **[references/error-handling.md](references/error-handling.md)** — Error handlers, retry logic, monitoring
- **[references/integration-examples.md](references/integration-examples.md)** — Database, REST API, and context-aware tool examples
Files in this package (9)
  • SKILL.md 9 KB
  • references/advanced-features.md 2 KB
  • references/core-patterns.md 2 KB
  • references/error-handling.md 3 KB
  • references/examples.md 16 KB
  • references/implementation-patterns.md 14 KB
  • references/integration-examples.md 5 KB
  • references/references.md 9 KB
  • references/setup-configuration.md 2 KB

Versions

The database has no other skills named langchain4j-tool-function-calling-patterns.

Database snapshot: 13.11.2026 · package version 573f20dace34 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100tool-use-schema-design
    Design tool schemas (function-calling definitions) that LLMs can use reliably. Use when the user is defining tools for Claude, GPT, Gemini, or any function-calling agent and mentions tool definitions, function calling, JSON schema, tool descriptions, parameters, structured…
  • 100tool-design
    Design tool interfaces for LLM agents — descriptions, parameter schemas, error messages, granularity, and composition. Use when creating function calling tools, building MCP servers, designing agent tool interfaces, writing tool descriptions, or debugging why a model calls the…
  • 100langchain4j-mcp-server-patterns
    Provides LangChain4j patterns for implementing MCP (Model Context Protocol) servers, creating Java AI tools, exposing tool calling capabilities, and integrating MCP clients with AI services. Use when building a Java MCP server, implementing tool calling in Java, connecting…
  • 100spring-ai-mcp-server-patterns
    Provides Spring Boot MCP server patterns that create Model Context Protocol servers with Spring AI by defining tool handlers, exposing resources, configuring prompt templates, and setting up transports for AI function calling and tool calling. Use when building MCP servers to…
  • 100tool-calling-principles
    Use this skill when the user says 'tool calling', 'function calling', 'tool schema', 'JSON schema for tools', 'agent picks wrong tool', 'tool error handling', 'structured outputs', 'tool_use / tool_result'. Designs tool interfaces for LLM agents: naming, descriptions, strict…
  • 100agent-tool-use-function-calling
    Use this skill when implementing reliable tool invocation using OpenAI-compatible JSON schema function calling specifications.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.