### 1、工具输出给 llm 的描述形态

这个形态下 `parameters` 属性是一个 jsonSchema 规范的结构。也就是工具的“输入架构”（mcp 里的叫法）

```json
{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "获取指定城市的天气情况",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "根据用户提到的地点推测城市"
                }
            },
            "required": [
                "location"
            ],
            "additionalProperties": False
        },
        "strict": True
    }
}
```


### 2、工具注册给 mcp 的描述形态

这个形态下多了 `outputSchema` （符合 jsonSchema 规范的输出架构）属性，且 `parameters` 属性变成了 `inputSchema`（可以与 outputSchema 呼应上）。

```json
{
    "name": "get_weather",
    "description": "获取指定城市的天气情况",
    "inputSchema": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "根据用户提到的地点推测城市"
            }
        },
        "required": [
            "location"
        ],
        "additionalProperties": False
    },
    "outputSchema": {
        "type": "string"
    }
}
```

### 3、构建工具的 outputSchema（输出架构）定义

（v3.2.2 后支持）

使用 FunctionToolDesc 描述工具时（即手动构建），通过 returnType 声明

```java
import org.noear.solon.ai.chat.tool.FunctionToolDesc;

FunctionToolDesc toolDesc = new FunctionToolDesc("get_weather")
    .description("获取指定城市的天气情况")
    .stringParamAdd("location", "根据用户提到的地点推测城市")
    .returnType(String.class)
    .doHandle(args -> {
        return "晴，24度"; // + weatherService.get(location);
    })
```

使用 MethodFunctionTool 描述工具时（即 `@ToolMapping` 注解函数构建），通过方法返回类型自动声明

```java
import org.noear.solon.annotation.Param;
import org.noear.solon.ai.annotation.ToolMapping;
import org.noear.solon.ai.mcp.server.annotation.McpServerEndpoint;

@McpServerEndpoint(sseEndpoint = "/mcp/sse")
public class Tools {
    @ToolMapping(description = "获取指定城市的天气情况")
    public String get_weather(@Param(name = "location", description = "根据用户提到的地点推测城市") String location) {
        return "晴，24度"; // + weatherService.get(location);
    }
}
```

如果返回的是实体结果时，还可以通过 `@Param` 注解增加描述

```java
import org.noear.solon.annotation.Param;
import org.noear.solon.ai.annotation.ToolMapping;
import org.noear.solon.ai.mcp.server.annotation.McpServerEndpoint;

public class UserInfo {
    @Param(description = "用户名")
    private String name;

    @Param(description = "年龄")
    private Integer age;

    @Param(description = "性别。0表示女，1表示男")
    private Integer gender;
}

@McpServerEndpoint(sseEndpoint = "/mcp/sse")
public class Tools {
    @Inject
    UserService userService;

    @ToolMapping(description = "获取用户信息")
    public UserInfo getUserInfo(@Param(description = "用户ID") Long userId) {
        return userService.getUser(userId);
    }
}
```


### 4、Tool 的 JsonSchema 生成类 ToolSchemaUtil

现有的工具架构是由 ToolSchemaUtil 提供支持

| 方法 | 描述 | 备注 |
| -------- | -------- | -------- |
| buildInputParams     | 构建 tool 的输出参数描述     |  支持 `@Body` 实体自动分解字段     |
| buildInputSchema     | 构建 tool 输入架构     |       |
| buildOutputSchema     | 构建 tool 输出架构     |   |
|  isIgnoreOutputSchema     |    检测 tool 需要乎略的输出架构   | 比如单值类型      |
|       |       |       |
|  createSchema     |   生成一个类型的 JsonSchema    |  通用方法     |
|       |       |       |
| addBodyDetector     | 添加主体注解探测器     | 第三方框架使用时，可用它扩展     |
| addParamResolver     | 添加参数注解分析器     | 同上     |
| addNodeDescribe     | 添加节点描述处理     | 同上     |