Tool schemas

📝 学习笔记：工具函数 JSON Schema 编写

一、核心概念：JSON Schema

• 定义： JSON Schema 是一种数据验证规范 (Data Validation Specification)。
• 作用： 它是一套用于验证任何 JSON 数据的规则集合。
• 定位： 它本身不局限于语言模型 (LLM) 或工具调用，但 LLM 社区将其用作处理工具调用的便捷方式。

二、工具配置结构

• 整体配置： 包含工具的名称 (Name) 和描述 (Description)。
• 输入定义： 核心部分是 input schema 键，它承载了实际的 JSON Schema 规范。
• 工具描述 (Tool Description)：
• 目的：告知 LLM 工具的功能、何时使用以及返回的数据类型。
• 最佳实践：描述应详细，建议 3 到 4 句话。
• 输入参数描述 (Argument Description)：
• 目的：描述函数所需的各个参数（arguments）。
• 最佳实践：每个参数的描述也应详细（建议 3 到 4 句话），帮助 LLM 理解参数的作用和对函数调用的影响。

三、最佳实践与自动化

• 生成策略： 不建议手动编写所有配置。应利用 LLM（如 Claude）结合 API 文档和最佳实践来自动生成高质量的 JSON Schema。
• 命名约定： 建议使用一致的命名模式，例如：工具函数名 → 工具函数名_schema。
• 类型安全： 建议使用 tool_param (来自 anthropic. types) 将整个 Schema 字典包裹起来，以防止后续代码出现类型错误。

Takeaways

• JSON Schema 是一种数据验证规范，用于定义和验证 JSON 数据的规则集合。
• 工具配置的核心在于 input schema，同时工具描述和参数描述都必须详细（建议 3 到 4 句话）。
• 最佳实践是利用 LLM 结合 API 文档来自动生成高质量的 JSON Schema，避免手动编写。
• 建议遵循一致的命名约定（例如：工具函数名 → 工具函数名_schema）。
• 为确保代码类型安全，应使用 tool_param 等机制将整个 Schema 字典包裹起来。