在 Solon AI 中，函数工具（Function Tools）共有四种定制方式。其中 @ToolMapping 是最便捷的开发方式，它通过注解自动将普通的 Java 方法映射为大模型的 Tool 定义。虽然在极致的灵活性上略逊于手动构建，但足以覆盖 90% 的业务场景。


### 1、工具定义示例：

通过在类方法上添加 `@ToolMapping`，你可以快速定义可供 LLM 调用的功能。支持 Solon 原生的组件注解（如 `@Component`），从而支持依赖注入和 AOP 拦截。

```java
import org.noear.solon.ai.annotation.ToolMapping;
import org.noear.solon.annotation.Param;
import org.noear.solon.annotation.Body;
import org.noear.snack.annotation.ONodeAttr;

//可以加组件注解（支持注入和拦截）
public class Tools {
    //天气查询
    @ToolMapping(description = "获取指定城市的天气情况")
    public String get_weather(@Param(name = "location", description = "根据用户提到的地点推测城市") String location) {
        return "晴，24度"; //可使用 “数据库” 或 “网络” 接口根据 location 查询合适数据;
    }
    
    
    //订单查询
    @ToolMapping(description = "联网查询")
    public String web_search(@Body QueryDo queryDo) {
        return "..."; 
    }
    
    public static class QueryDo {
        @Param(name = "query", description = "查询关键字，多个词用空格隔开") 
        String query;
        
        @ONodeAttr(name = "limit", description = "返回的最大结果条数")
        int limit = 10;
    } 
}
```

### 2、 应用集成示例

使用 ChatModel 发起对话时，可以通过 options 将工具类动态添加（也可以要构建 ChatModel 作为默认工具添加）。

```java
public void testToolCall() throws IOException {
    chatModel.prompt("今天杭州的天气情况？")
             .options(o -> o
                 // 方式 A：显式通过 MethodToolProvider 包装
                 .toolAdd(new MethodToolProvider(new Tools()))
                 // 方式 B：直接传入实例（内部会自动识别注解并转换）
                 .toolAdd(new OtherTools()) 
             )
             .call();
}
```

### 3、@ToolMapping 属性说明

`@ToolMapping` 负责将 Java 方法元数据转换为 `FunctionTool` 接口属性。它会自动根据方法参数生成 `inputSchema`，根据返回类型生成 `outputSchema`。

| 属性   | 类型 | 描述 | 备注 |
| ----- | --- | -------- | -------- |
| name           | String    | 工具标识名称     |  缺省时默认使用方法名     |
| title             | String    | 工具显示标题     |   常用于 MCP Tool 管理界面展示    |
| description   | String    | 核心描述     |  告知 LLM 何时该调用此工具（极其重要）     |
| meta            | String   | 元数据     |  JSON 格式，用于扩展自定义属性     |
| returnDirect  | boolean  | 是否直接返回（默认为 false）     | 若为 true，LLM 执行完工具后不进行思考，直接返回结果给用户      |
|                   |    |   |       |
| resultConverter   |  Class |  结果转换器     |   用于对工具执行结果进行二次加工    |


### 4、参数注解说明：@Param、@Body


Solon AI 沿用了 [Solon MVC 的通用注解](/article/590)，降低了学习成本。

#### a) `@Param` 属性描述:

可用于修饰方法参数或实体字段。

| 属性名 | 默认值 |  描述 | 
| -------- | ----- | ------ | 
| `value`  / `name`  |  /  | 参数名称（若缺省，自动取参数变量名）     | 
| `description`        | /   | 参数语义描述，帮助 LLM 理解参数含义     | 
| `required`            | `true`   | 是否必填。若为 `true`，LLM 必须提取出该参数     | 
| `defaultValue`      |  /   | 默认值     | 
| `format`              |  /  | 类型格式描述（建议符合 json-schema 规范，有些 llm 会比较严格）     | 


#### b) 参数提取逻辑

方法参数层面：

* 只有带 `@Param` 或 `@Body` 的参数才会进入 inputSchema。
* 不带注解的参数将被忽略（通常用于注入 “工具上下文” 对象）。

实体类（POJO）对象层面：

* 实体内的字段默认全部进入 `inputSchema`。
* 字段没有注解时，默认为“非必填”。
* 支持使用 `@ONodeAttr`（Snack4 注解）或自定义注解来定义字段描述。