提到 MCP 中的工具，最被大家熟悉的是工具的三要素，分别是工具的名称、描述和输入参数的schema。这也是 MCP 协议最早的 2024-11-05 版本中对工具的定义。在 MCP 协议的 2025-03-26 和 2025-06-18 版本中对工具的定义进行了一些修改。

在 2025-03-26 版本中，工具增加了新的属性 annotations，表示工具的注解。MCP 协议中定义了如下工具注解。

• title，string 类型，工具的名称，方便界面展示。

• readOnlyHint，boolean 类型，默认值为 false，表明工具是否对环境造成影响。

• destructiveHint，boolean 类型，默认值为 true，表明工具是否进行破坏性的更新。

• idempotentHint，boolean 类型，默认值为 false，表明使用相同的参数值重复调用工具，是否会产生额外的副作用。也就是工具调用是否为幂等的。

• openWorldHint，boolean类型，默认值为 true，表明工具是否会和开放的外部世界进行交互。

在 2024-11-05 版本中，工具调用结果的内容可以是文本、图片和内嵌资源。在 2025-03-26 版本中，新增了一种音频内容。

在2025-06-18版本中，工具增加了 title 属性，表示工具的标题，适合于在界面上展示。

除此之外，最重要的改动是为工具的调用结果增加了结构化内容。

工具的调用结果可以包含非结构化和结构化的内容。

• 非结构化的内容包含在 content 属性中，可能的内容包括文本、图片、音频和内嵌资源等。这也是之前版本中的工具调用内容。

• 结构化的内容包含在 structuredContent 属性中，其中的内容是 JSON 对象。

结构化的内容与工具定义中的 outputSchema 搭配使用。使用 outputSchema 定义工具的调用结果所要满足的 JSON schema。调用结果的 structuredContent 属性会包含 JSON内容，并满足 outputSchema 所定义的 schema。为了保证向后兼容性，如果工具的调用结果中包含了结构化的内容，也同时应该把 JSON 对象序列化之后的 JSON 文本包含在 content 中。

Java MCP SDK 0.11.3 版本已经支持 2025-06-18 版本。表示工具的 Tool 对象，已经包含了新的属性。下面是一个工具的定义，该工具的作用是计算 HTTP Basic 认证中 Authentication header 的值。该工具的 annotations 的声明如下，其中 readOnlyHint 的值是 true，destructiveHint 的值是 false，idempotentHint 的值是 true，openWorldHint 的值是 false。这些注解的值符合该工具的使用场景。

new ToolAnnotations(null, true, false, true, false, false)

除了 inputSchema 之外，outputSchema 的定义如下。工具的调用结果只包含一个 string 类型的 value。

.outputSchema(Map.of(    "type", "object",    "properties", Map.of(        "value", new JsonSchema("string", Map.of(), List.of(),            false, Map.of(), Map.of())    )))

在实现该工具的调用逻辑时，得到作为结果的 header 值之后，使用 CallToolResult 的构建器来创建调用结果。结构化内容是一个 Map 对象，序列化之后的 JSON 文本，同时作为文本内容。

Map<String, Object> result = Map.of("value", header);CallToolResult.builder()    .structuredContent(result)    .addTextContent(toJson(result))    .build();

使用 MCP Inspector 进行测试，界面上会显示出工具的 outputSchema。MCP Inspector 会对工具的调用结果进行校验，判断是否符合 outputSchema 的要求。