v3.2.0 后，原 Function 概念改为 Tool 概念。新的调整，与 MCP 里的工具可以更好的对应起来。

---

Tool call（或 Function call）能够让大语言模型在生成时，“按需”调用外部的工具，进而连接外部的数据和系统。通过定义一组函数作为模型可访问的工具（也叫函数工具），并根据对话历史在适当的时候使用它们。然后在应用端执行这些函数，并将结果反馈给模型。

可以实现最新的数据状态（比如，联网查询时实天气）或者指令交互（比如，做运维操作）。是 AI 交互系统的基础技术。



相关接口：



| 接口或类                  | 描述                    | 备注          |
| ---------------- | -------------- | -------- |
| FunctionTool             | 函数工具接口             |  为 ChatModel 提供工具               |
| ToolProvider             | 工具提供者接口        | 为 ChatModel 提供批量工具                |
| | | |
| FunctionToolDesc      | 函数工具描述类          |           |
| | | |
| AbsTool                    | 虚拟工具类             |           |
| | | |
| MethodFunctionTool   | 方法工具              |         |
| MethodToolProvider    | 方法工具提供者     | 分析出对象中的 `@ToolMapping` 函数，并构建出方法工具集合    |
| `@ToolMapping`         | 工具映射注解        |         |
| `@Param`                  |  参数映射注解        |         |




### 1、工具的主要属性与处理方法



| 属性或方法 | 描述 | 备注 |
| -------- | -------- | -------- |
| name     | 名字     |       |
| title     | 标题     |   对接 mcp tool 的 title 属性（用于管理侧展示）    |
| description     | 描述     |       |
| meta     | 元信息     |       |
| returnDirect     | 是否直接返回给调用者     | 如果为 true，llm 调用工具后直接返回结果      |
| inputSchema     | 输入架构     |       |
| outputSchema     | 输出架构     |       |
|       |       |       |
| handle(args)     |  工具处理     |       |



#### （1）inputSchema / outputSchema 规范要求

原则上，支持任意参数类型（jsonSchema 能描述的类型）。尽量，使用基础类型和数据实体类型组合描述；像 Socket、Session 这类的不适合。


#### （2）关于 returnDirect （直接返回）的作用

默认状态时，Tool 处理的结果是交给大模型，大模型加工后再返回。通过 returnDirect 可以跳过大模型直接返回。


* returnDirect=false（默认）

```
user -> llm -> tool -> llm -> user
```

* returnDirect=true

```
user -> llm -> tool -> user
```

MCP 协议目前不支持这个特性透传。但当 server 和 client 都是 solon-ai-mcp 时，可支持此特性透传。



### 2、FunctionTool （函数工具）接口参考

工具，目前主要是指函数工具 FunctionTool（未来可能有不同类型的工具）。接口需要声明工具的类型和名字，描述，输入架构（由输入参数的名字、描述、类型，组合构成），及以处理方法。

```java
//工具接口（未来可能会有别的类型）
public interface Tool {
    //工具类型
    String type();
}

//函数工具接口
public interface FunctionTool extends Tool {
    //工具类型
    default String type() {
        return "function";
    }

    //名字
    String name();

    //标题
     String title() ;

    //描述
    String description();

    //带有元信息的描述（用于注入到模型）
    default String descriptionAndMeta() { ... }

    //元信息
    default Map<String, Object> meta() { ... }

    default void metaPut(String key, Object value) {  }

    //是否直接返回给调用者
    boolean returnDirect();

    //输入架构
    String inputSchema();

    //输出架构
    default String outputSchema() { ... }

    //处理
    String handle(Map<String, Object> args) throws Throwable;

    //异步处理
    default CompletableFuture<String> handleAsync(Map<String, Object> args) { ... }
}
```

### 3、ToolMapping 工具映射注解参考

开发时，也可以使用注解简化工具声明（不需要 Bean 容器驱动）：


```java
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface ToolMapping {
    //名字
    String name() default "";

    //标题
    String title() default "";

    //描述
    String description();

    //元数据（json）
    String meta() default "{}";

    //是否直接返回给调用者
    boolean returnDirect() default false;

    //结果转换器
    Class<? extends ToolCallResultConverter> resultConverter() default ToolCallResultConverterDefault.class;
}
```