langchain4j-tool-function-calling-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

LangChain4j Tool & Function Calling Patterns

LangChain4j 工具与函数调用模式

Define tools and enable AI agents to interact with external systems, APIs, and services using LangChain4j's annotation-based and programmatic tool system.

使用LangChain4j基于注解和程序化的工具系统，定义工具并让AI Agent能够与外部系统、API及服务进行交互。

Overview

概述

LangChain4j's tool system enables AI agents to execute external functions through declarative annotations and programmatic interfaces. Tools are defined using the

@Tool

annotation and automatically registered with AI services, allowing LLMs to perform actions beyond text generation such as database queries, API calls, and calculations.

LangChain4j的工具系统允许AI Agent通过声明式注解和程序化接口执行外部函数。使用

@Tool

注解定义工具，工具会自动注册到AI服务中，让LLM能够执行除文本生成之外的操作，例如数据库查询、API调用和计算。

When to Use This Skill

何时使用该技能

Use this skill when:

Building AI applications that need to interact with external APIs and services
Creating AI assistants that can perform actions beyond text generation
Implementing AI systems that need access to real-time data (weather, stocks, etc.)
Building multi-agent systems where agents can use specialized tools
Creating AI applications with database read/write capabilities
Implementing AI systems that need to integrate with existing business systems
Building context-aware AI applications where tool availability depends on user state
Developing production AI applications that require robust error handling and monitoring

在以下场景中使用本技能：

构建需要与外部API和服务交互的AI应用
创建能够执行文本生成之外操作的AI助手
实现需要访问实时数据（如天气、股票等）的AI系统
构建Agent可使用专用工具的多Agent系统
创建具备数据库读写能力的AI应用
实现需要与现有业务系统集成的AI系统
构建工具可用性依赖用户状态的上下文感知AI应用
开发需要强大错误处理和监控能力的生产级AI应用

Instructions

操作步骤

Follow these steps to implement tools with LangChain4j:

按照以下步骤使用LangChain4j实现工具：

1. Define Tool Methods

1. 定义工具方法

Create methods annotated with

@Tool

in a class:

java

public class WeatherTools {
    @Tool("Get current weather for a city")
    public String getWeather(
        @P("City name") String city,
        @P("Temperature unit (celsius or fahrenheit)", required = false) String unit) {
        // Implementation
        return weatherService.getWeather(city, unit);
    }
}

在类中创建带有

@Tool

注解的方法：

java

public class WeatherTools {
    @Tool("Get current weather for a city")
    public String getWeather(
        @P("City name") String city,
        @P("Temperature unit (celsius or fahrenheit)", required = false) String unit) {
        // Implementation
        return weatherService.getWeather(city, unit);
    }
}

2. Configure Parameter Descriptions

2. 配置参数描述

Use

@P

annotation for clear parameter descriptions that help the LLM understand how to call the tool:

java

@Tool("Calculate total order amount")
public double calculateOrderTotal(
    @P("List of product IDs") List<String> productIds,
    @P("Customer discount percentage", required = false) Double discount) {
    // Implementation
}

使用

@P

注解添加清晰的参数描述，帮助LLM理解如何调用工具：

java

@Tool("Calculate total order amount")
public double calculateOrderTotal(
    @P("List of product IDs") List<String> productIds,
    @P("Customer discount percentage", required = false) Double discount) {
    // Implementation
}

3. Register Tools with AI Service

3. 向AI服务注册工具

Connect tools to an AI service using the AiServices builder:

java

MathAssistant assistant = AiServices.builder(MathAssistant.class)
    .chatModel(chatModel)
    .tools(new Calculator(), new WeatherService())
    .build();

使用AiServices构建器将工具连接到AI服务：

java

MathAssistant assistant = AiServices.builder(MathAssistant.class)
    .chatModel(chatModel)
    .tools(new Calculator(), new WeatherService())
    .build();

4. Handle Tool Execution Errors

4. 处理工具执行错误

Implement error handling for tool failures:

java

AiServices.builder(Assistant.class)
    .chatModel(chatModel)
    .tools(new ExternalServiceTools())
    .toolExecutionErrorHandler((request, exception) -> {
        log.error("Tool execution failed: {}", exception.getMessage());
        return "An error occurred while processing your request";
    })
    .build();

为工具执行失败实现错误处理：

java

AiServices.builder(Assistant.class)
    .chatModel(chatModel)
    .tools(new ExternalServiceTools())
    .toolExecutionErrorHandler((request, exception) -> {
        log.error("Tool execution failed: {}", exception.getMessage());
        return "An error occurred while processing your request";
    })
    .build();

5. Monitor Tool Usage

5. 监控工具使用情况

Track tool calls for debugging and analytics:

java

Result<String> result = assistant.chat(question);
result.toolExecutions().forEach(execution ->
    log.info("Executed tool: {} in {}ms",
        execution.request().name(),
        execution.duration().toMillis())
);

跟踪工具调用情况用于调试和分析：

java

Result<String> result = assistant.chat(question);
result.toolExecutions().forEach(execution ->
    log.info("Executed tool: {} in {}ms",
        execution.request().name(),
        execution.duration().toMillis())
);

Setup and Configuration

安装与配置

Basic Tool Registration

基础工具注册

java

// Define tools using @Tool annotation
public class CalculatorTools {
    @Tool("Add two numbers")
    public double add(double a, double b) {
        return a + b;
    }
}

// Register with AiServices builder
interface MathAssistant {
    String ask(String question);
}

MathAssistant assistant = AiServices.builder(MathAssistant.class)
    .chatModel(chatModel)
    .tools(new CalculatorTools())
    .build();

java

// Define tools using @Tool annotation
public class CalculatorTools {
    @Tool("Add two numbers")
    public double add(double a, double b) {
        return a + b;
    }
}

// Register with AiServices builder
interface MathAssistant {
    String ask(String question);
}

MathAssistant assistant = AiServices.builder(MathAssistant.class)
    .chatModel(chatModel)
    .tools(new CalculatorTools())
    .build();

Builder Configuration Options

构建器配置选项

java

AiServices.builder(AssistantInterface.class)

    // Static tool registration
    .tools(new Calculator(), new WeatherService())

    // Dynamic tool provider
    .toolProvider(new DynamicToolProvider())

    // Concurrent execution
    .executeToolsConcurrently()

    // Error handling
    .toolExecutionErrorHandler((request, exception) -> {
        return "Error: " + exception.getMessage();
    })

    // Memory for context
    .chatMemoryProvider(userId -> MessageWindowChatMemory.withMaxMessages(20))

    .build();

java

AiServices.builder(AssistantInterface.class)

    // Static tool registration
    .tools(new Calculator(), new WeatherService())

    // Dynamic tool provider
    .toolProvider(new DynamicToolProvider())

    // Concurrent execution
    .executeToolsConcurrently()

    // Error handling
    .toolExecutionErrorHandler((request, exception) -> {
        return "Error: " + exception.getMessage();
    })

    // Memory for context
    .chatMemoryProvider(userId -> MessageWindowChatMemory.withMaxMessages(20))

    .build();

Core Patterns

核心模式

Basic Tool Definition

基础工具定义

Use

@Tool

annotation to define methods as executable tools:

java

public class BasicTools {

    @Tool("Add two numbers")
    public int add(@P("first number") int a, @P("second number") int b) {
        return a + b;
    }

    @Tool("Get greeting")
    public String greet(@P("name to greet") String name) {
        return "Hello, " + name + "!";
    }
}

使用

@Tool

注解将方法定义为可执行工具：

java

public class BasicTools {

    @Tool("Add two numbers")
    public int add(@P("first number") int a, @P("second number") int b) {
        return a + b;
    }

    @Tool("Get greeting")
    public String greet(@P("name to greet") String name) {
        return "Hello, " + name + "!";
    }
}

Parameter Descriptions and Validation

参数描述与验证

Provide clear parameter descriptions using

@P

annotation:

java

public class WeatherService {

    @Tool("Get current weather conditions")
    public String getCurrentWeather(
        @P("City name or coordinates") String location,
        @P("Temperature unit (celsius, fahrenheit)", required = false) String unit) {

        // Implementation with validation
        if (location == null || location.trim().isEmpty()) {
            return "Location is required";
        }

        return weatherClient.getCurrentWeather(location, unit);
    }
}

使用

@P

注解提供清晰的参数描述：

java

public class WeatherService {

    @Tool("Get current weather conditions")
    public String getCurrentWeather(
        @P("City name or coordinates") String location,
        @P("Temperature unit (celsius, fahrenheit)", required = false) String unit) {

        // Implementation with validation
        if (location == null || location.trim().isEmpty()) {
            return "Location is required";
        }

        return weatherClient.getCurrentWeather(location, unit);
    }
}

Complex Parameter Types

复杂参数类型

Use Java records and descriptions for complex objects:

java

public class OrderService {

    @Description("Customer order information")
    public record OrderRequest(
        @Description("Customer ID") String customerId,
        @Description("List of items") List<OrderItem> items,
        @JsonProperty(required = false) @Description("Delivery instructions") String instructions
    ) {}

    @Tool("Create customer order")
    public String createOrder(OrderRequest order) {
        return orderService.processOrder(order);
    }
}

使用Java记录和描述处理复杂对象：

java

public class OrderService {

    @Description("Customer order information")
    public record OrderRequest(
        @Description("Customer ID") String customerId,
        @Description("List of items") List<OrderItem> items,
        @JsonProperty(required = false) @Description("Delivery instructions") String instructions
    ) {}

    @Tool("Create customer order")
    public String createOrder(OrderRequest order) {
        return orderService.processOrder(order);
    }
}

Advanced Features

高级功能

Memory Context Integration

内存上下文集成

Access user context using

@ToolMemoryId

java

public class PersonalizedTools {

    @Tool("Get user preferences")
    public String getPreferences(
        @ToolMemoryId String userId,
        @P("Preference category") String category) {

        return preferenceService.getPreferences(userId, category);
    }
}

使用

@ToolMemoryId

访问用户上下文：

java

public class PersonalizedTools {

    @Tool("Get user preferences")
    public String getPreferences(
        @ToolMemoryId String userId,
        @P("Preference category") String category) {

        return preferenceService.getPreferences(userId, category);
    }
}

Dynamic Tool Provisioning

动态工具提供

Create tools that change based on context:

java

public class ContextAwareToolProvider implements ToolProvider {

    @Override
    public ToolProviderResult provideTools(ToolProviderRequest request) {
        String message = request.userMessage().singleText().toLowerCase();
        var builder = ToolProviderResult.builder();

        if (message.contains("weather")) {
            builder.add(weatherToolSpec, weatherExecutor);
        }

        if (message.contains("calculate")) {
            builder.add(calcToolSpec, calcExecutor);
        }

        return builder.build();
    }
}

创建基于上下文变化的工具：

java

public class ContextAwareToolProvider implements ToolProvider {

    @Override
    public ToolProviderResult provideTools(ToolProviderRequest request) {
        String message = request.userMessage().singleText().toLowerCase();
        var builder = ToolProviderResult.builder();

        if (message.contains("weather")) {
            builder.add(weatherToolSpec, weatherExecutor);
        }

        if (message.contains("calculate")) {
            builder.add(calcToolSpec, calcExecutor);
        }

        return builder.build();
    }
}

Immediate Return Tools

即时返回工具

Return results immediately without full AI response:

java

public class QuickTools {

    @Tool(value = "Get current time", returnBehavior = ReturnBehavior.IMMEDIATE)
    public String getCurrentTime() {
        return LocalDateTime.now().format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);
    }
}

无需完整AI响应即可立即返回结果：

java

public class QuickTools {

    @Tool(value = "Get current time", returnBehavior = ReturnBehavior.IMMEDIATE)
    public String getCurrentTime() {
        return LocalDateTime.now().format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);
    }
}

Error Handling

错误处理

Tool Error Handling

工具错误处理

Handle tool execution errors gracefully:

java

AiServices.builder(Assistant.class)
    .chatModel(chatModel)
    .tools(new ExternalServiceTools())
    .toolExecutionErrorHandler((request, exception) -> {
        if (exception instanceof ApiException) {
            return "Service temporarily unavailable: " + exception.getMessage();
        }
        return "An error occurred while processing your request";
    })
    .build();

优雅处理工具执行错误：

java

AiServices.builder(Assistant.class)
    .chatModel(chatModel)
    .tools(new ExternalServiceTools())
    .toolExecutionErrorHandler((request, exception) -> {
        if (exception instanceof ApiException) {
            return "Service temporarily unavailable: " + exception.getMessage();
        }
        return "An error occurred while processing your request";
    })
    .build();

Resilience Patterns

弹性模式

Implement circuit breakers and retries:

java

public class ResilientService {

    private final CircuitBreaker circuitBreaker = CircuitBreaker.ofDefaults("external-api");

    @Tool("Get external data")
    public String getExternalData(@P("Data identifier") String id) {
        return circuitBreaker.executeSupplier(() -> {
            return externalApi.getData(id);
        });
    }
}

实现断路器和重试机制：

java

public class ResilientService {

    private final CircuitBreaker circuitBreaker = CircuitBreaker.ofDefaults("external-api");

    @Tool("Get external data")
    public String getExternalData(@P("Data identifier") String id) {
        return circuitBreaker.executeSupplier(() -> {
            return externalApi.getData(id);
        });
    }
}

Integration Examples

集成示例

Multi-Domain Tool Service

多领域工具服务

java

@Service
public class MultiDomainToolService {

    public String processRequest(String userId, String request, String domain) {
        String contextualRequest = String.format("[Domain: %s] %s", domain, request);

        Result<String> result = assistant.chat(userId, contextualRequest);

        // Log tool usage
        result.toolExecutions().forEach(execution ->
            analyticsService.recordToolUsage(userId, domain, execution.request().name()));

        return result.content();
    }
}

java

@Service
public class MultiDomainToolService {

    public String processRequest(String userId, String request, String domain) {
        String contextualRequest = String.format("[Domain: %s] %s", domain, request);

        Result<String> result = assistant.chat(userId, contextualRequest);

        // Log tool usage
        result.toolExecutions().forEach(execution ->
            analyticsService.recordToolUsage(userId, domain, execution.request().name()));

        return result.content();
    }
}

Streaming with Tool Execution

工具执行流

java

interface StreamingAssistant {
    TokenStream chat(String message);
}

StreamingAssistant assistant = AiServices.builder(StreamingAssistant.class)
    .streamingChatModel(streamingChatModel)
    .tools(new Tools())
    .build();

TokenStream stream = assistant.chat("What's the weather and calculate 15*8?");

stream
    .onToolExecuted(execution ->
        System.out.println("Executed: " + execution.request().name()))
    .onPartialResponse(System.out::print)
    .onComplete(response -> System.out.println("Complete!"))
    .start();

java

interface StreamingAssistant {
    TokenStream chat(String message);
}

StreamingAssistant assistant = AiServices.builder(StreamingAssistant.class)
    .streamingChatModel(streamingChatModel)
    .tools(new Tools())
    .build();

TokenStream stream = assistant.chat("What's the weather and calculate 15*8?");

stream
    .onToolExecuted(execution ->
        System.out.println("Executed: " + execution.request().name()))
    .onPartialResponse(System.out::print)
    .onComplete(response -> System.out.println("Complete!"))
    .start();

Best Practices

最佳实践

Tool Design Guidelines

工具设计指南

Descriptive Names: Use clear, actionable tool names
Parameter Validation: Validate inputs before processing
Error Messages: Provide meaningful error messages
Return Types: Use appropriate return types that LLMs can understand
Performance: Avoid blocking operations in tools

描述性名称：使用清晰、可操作的工具名称
参数验证：处理前验证输入
错误消息：提供有意义的错误消息
返回类型：使用LLM能够理解的合适返回类型
性能：避免在工具中使用阻塞操作

Security Considerations

安全注意事项

Permission Checks: Validate user permissions before tool execution
Input Sanitization: Sanitize all tool inputs
Audit Logging: Log tool usage for security monitoring
Rate Limiting: Implement rate limiting for external APIs

权限检查：工具执行前验证用户权限
输入清理：清理所有工具输入
审计日志：记录工具使用情况用于安全监控
速率限制：为外部API实现速率限制

Performance Optimization

性能优化

Concurrent Execution: Use
```
executeToolsConcurrently()
```
for independent tools
Caching: Cache frequently accessed data
Monitoring: Monitor tool performance and error rates
Resource Management: Handle external service timeouts gracefully

并发执行：对独立工具使用
```
executeToolsConcurrently()
```
缓存：缓存频繁访问的数据
监控：监控工具性能和错误率
资源管理：优雅处理外部服务超时

Examples

示例

Simple Calculator Tool

简单计算器工具

java

public class CalculatorTools {

    @Tool("Add two numbers")
    public double add(@P("First number") double a,
                      @P("Second number") double b) {
        return a + b;
    }

    @Tool("Multiply two numbers")
    public double multiply(@P("First number") double a,
                           @P("Second number") double b) {
        return a * b;
    }
}

// Usage
interface MathAssistant {
    String ask(String question);
}

MathAssistant assistant = AiServices.builder(MathAssistant.class)
    .chatModel(chatModel)
    .tools(new CalculatorTools())
    .build();

String result = assistant.ask("What is 15 times 7 plus 3?");

java

public class CalculatorTools {

    @Tool("Add two numbers")
    public double add(@P("First number") double a,
                      @P("Second number") double b) {
        return a + b;
    }

    @Tool("Multiply two numbers")
    public double multiply(@P("First number") double a,
                           @P("Second number") double b) {
        return a * b;
    }
}

// Usage
interface MathAssistant {
    String ask(String question);
}

MathAssistant assistant = AiServices.builder(MathAssistant.class)
    .chatModel(chatModel)
    .tools(new CalculatorTools())
    .build();

String result = assistant.ask("What is 15 times 7 plus 3?");

Database Access Tool

数据库访问工具

java

@Component
public class DatabaseTools {

    private final CustomerRepository repository;

    @Tool("Get customer information by ID")
    public Customer getCustomer(@P("Customer ID") Long customerId) {
        return repository.findById(customerId)
            .orElseThrow(() -> new IllegalArgumentException("Customer not found"));
    }

    @Tool("Update customer email address")
    public String updateEmail(
        @P("Customer ID") Long customerId,
        @P("New email address") String newEmail) {
        Customer customer = repository.findById(customerId)
            .orElseThrow(() -> new IllegalArgumentException("Customer not found"));
        customer.setEmail(newEmail);
        repository.save(customer);
        return "Email updated successfully";
    }
}

java

@Component
public class DatabaseTools {

    private final CustomerRepository repository;

    @Tool("Get customer information by ID")
    public Customer getCustomer(@P("Customer ID") Long customerId) {
        return repository.findById(customerId)
            .orElseThrow(() -> new IllegalArgumentException("Customer not found"));
    }

    @Tool("Update customer email address")
    public String updateEmail(
        @P("Customer ID") Long customerId,
        @P("New email address") String newEmail) {
        Customer customer = repository.findById(customerId)
            .orElseThrow(() -> new IllegalArgumentException("Customer not found"));
        customer.setEmail(newEmail);
        repository.save(customer);
        return "Email updated successfully";
    }
}

REST API Tool

REST API工具

java

@Component
public class ApiTools {

    private final WebClient webClient;

    @Tool("Get current stock price")
    public String getStockPrice(@P("Stock symbol") String symbol) {
        return webClient.get()
            .uri("/api/stocks/{symbol}", symbol)
            .retrieve()
            .bodyToMono(String.class)
            .block();
    }
}

java

@Component
public class ApiTools {

    private final WebClient webClient;

    @Tool("Get current stock price")
    public String getStockPrice(@P("Stock symbol") String symbol) {
        return webClient.get()
            .uri("/api/stocks/{symbol}", symbol)
            .retrieve()
            .bodyToMono(String.class)
            .block();
    }
}

Context-Aware Tool with Memory ID

带内存ID的上下文感知工具

java

public class UserPreferencesTools {

    @Tool("Get user preferences for a category")
    public String getPreferences(
        @ToolMemoryId String userId,
        @P("Preference category (e.g., theme, language)") String category) {
        return preferencesService.getPreferences(userId, category);
    }

    @Tool("Set user preference")
    public String setPreference(
        @ToolMemoryId String userId,
        @P("Preference category") String category,
        @P("Preference value") String value) {
        preferencesService.setPreference(userId, category, value);
        return "Preference saved";
    }
}

java

public class UserPreferencesTools {

    @Tool("Get user preferences for a category")
    public String getPreferences(
        @ToolMemoryId String userId,
        @P("Preference category (e.g., theme, language)") String category) {
        return preferencesService.getPreferences(userId, category);
    }

    @Tool("Set user preference")
    public String setPreference(
        @ToolMemoryId String userId,
        @P("Preference category") String category,
        @P("Preference value") String value) {
        preferencesService.setPreference(userId, category, value);
        return "Preference saved";
    }
}

Dynamic Tool Provider

动态工具提供器

java

public class DynamicToolProvider implements ToolProvider {

    private final Map<String, Object> availableTools = new HashMap<>();

    public void registerTool(String name, ToolSpecification spec, ToolExecutor executor) {
        availableTools.put(name, new ToolWithSpec(spec, executor));
    }

    @Override
    public ToolProviderResult provideTools(ToolProviderRequest request) {
        var builder = ToolProviderResult.builder();
        String message = request.userMessage().singleText().toLowerCase();

        // Dynamically filter tools based on user message
        if (message.contains("weather")) {
            builder.add(weatherToolSpec, weatherExecutor);
        }
        if (message.contains("calculate") || message.contains("math")) {
            builder.add(calculatorToolSpec, calculatorExecutor);
        }

        return builder.build();
    }
}

java

public class DynamicToolProvider implements ToolProvider {

    private final Map<String, Object> availableTools = new HashMap<>();

    public void registerTool(String name, ToolSpecification spec, ToolExecutor executor) {
        availableTools.put(name, new ToolWithSpec(spec, executor));
    }

    @Override
    public ToolProviderResult provideTools(ToolProviderRequest request) {
        var builder = ToolProviderResult.builder();
        String message = request.userMessage().singleText().toLowerCase();

        // Dynamically filter tools based on user message
        if (message.contains("weather")) {
            builder.add(weatherToolSpec, weatherExecutor);
        }
        if (message.contains("calculate") || message.contains("math")) {
            builder.add(calculatorToolSpec, calculatorExecutor);
        }

        return builder.build();
    }
}

Reference Documentation

参考文档

For detailed API reference, examples, and advanced patterns, see:

API Reference - Complete API documentation
Implementation Patterns - Advanced implementation examples
Examples - Practical usage examples

如需详细API参考、示例和高级模式，请查看：

API参考 - 完整的API文档
实现模式 - 高级实现示例
示例 - 实际使用示例

Common Issues and Solutions

常见问题与解决方案

Tool Not Found

工具未找到

Problem: LLM calls tools that don't exist

Solution: Implement hallucination handler:

java

.hallucinatedToolNameStrategy(request -> {
    return ToolExecutionResultMessage.from(request,
        "Error: Tool '" + request.name() + "' does not exist");
})

问题：LLM调用不存在的工具

解决方案：实现幻觉处理程序：

java

.hallucinatedToolNameStrategy(request -> {
    return ToolExecutionResultMessage.from(request,
        "Error: Tool '" + request.name() + "' does not exist");
})

Parameter Validation Errors

参数验证错误

Problem: Tools receive invalid parameters

Solution: Add input validation and error handlers:

java

.toolArgumentsErrorHandler((error, context) -> {
    return ToolErrorHandlerResult.text("Invalid arguments: " + error.getMessage());
})

问题：工具收到无效参数

解决方案：添加输入验证和错误处理程序：

java

.toolArgumentsErrorHandler((error, context) -> {
    return ToolErrorHandlerResult.text("Invalid arguments: " + error.getMessage());
})

Performance Issues

性能问题

Problem: Tools are slow or timeout

Solution: Use concurrent execution and resilience patterns:

java

.executeToolsConcurrently(Executors.newFixedThreadPool(5))
.toolExecutionTimeout(Duration.ofSeconds(30))

问题：工具运行缓慢或超时

解决方案：使用并发执行和弹性模式：

java

.executeToolsConcurrently(Executors.newFixedThreadPool(5))
.toolExecutionTimeout(Duration.ofSeconds(30))

Related Skills

References

参考资料

LangChain4j Tool & Function Calling - API References
LangChain4j Tool & Function Calling - Implementation Patterns
LangChain4j Tool & Function Calling - Examples

LangChain4j 工具与函数调用 - API参考
LangChain4j 工具与函数调用 - 实现模式
LangChain4j 工具与函数调用 - 示例

Constraints and Warnings

约束与警告

Tools with side effects should have clear descriptions warning about potential impacts.
AI models may call tools in unexpected orders or with unexpected parameters.
Tool execution can be expensive; implement rate limiting and timeout handling.
Never pass sensitive data (API keys, passwords) in tool descriptions or responses.
Large tool sets can confuse AI models; consider using dynamic tool providers.
Tool execution errors should be handled gracefully; never expose stack traces to AI models.
Be cautious with tools that modify data; AI models may call them multiple times.
Parameter descriptions should be precise; vague descriptions lead to incorrect tool usage.
Tools with long execution times should implement timeout handling.
Test tools thoroughly before exposing them to AI models to prevent unexpected behavior.

带有副作用的工具应添加清晰描述，警告潜在影响。
AI模型可能会以意外顺序或参数调用工具。
工具执行成本可能较高；实现速率限制和超时处理。
切勿在工具描述或响应中传递敏感数据（API密钥、密码）。
大量工具会让AI模型困惑；考虑使用动态工具提供器。
应优雅处理工具执行错误；切勿向AI模型暴露堆栈跟踪。
对修改数据的工具需谨慎；AI模型可能会多次调用它们。
参数描述应精确；模糊描述会导致工具使用错误。
执行时间长的工具应实现超时处理。
在将工具暴露给AI模型前需彻底测试，防止意外行为。