TOOLS.md 模板

TOOLS.md 定义了 Agent 可以调用的自定义工具。工具定义会被注入系统提示词，让 LLM 了解可用工具的功能和调用方式。

模板

# Tools

## web_search
Search the web for current information.
- **Parameters**:
  - query (string, required): Search query
  - maxResults (number, optional): Maximum results to return, default 5
- **Returns**: Array of search results with title, url, and snippet

## knowledge_search
Search the internal knowledge base.
- **Parameters**:
  - query (string, required): Search query
  - category (string, optional): Filter by category
- **Returns**: Array of matching documents

## send_notification
Send a notification to a specified channel.
- **Parameters**:
  - channel (string, required): Target channel (email, slack, webhook)
  - message (string, required): Notification content
  - priority (string, optional): low, normal, high
- **Returns**: Delivery status

工具定义格式

每个工具定义包含以下部分：

字段	说明	是否必填
工具名称	作为二级标题，英文下划线命名	✅
描述	标题下的文本段落	✅
Parameters	参数列表，包含类型和说明	✅
Returns	返回值描述	推荐

好的工具描述

LLM 通过工具描述决定何时调用工具。描述越准确，Agent 的工具选择越合理。

参数类型

## my_tool
Tool description here.
- **Parameters**:
  - name (string, required): 用户姓名
  - age (number, optional): 年龄，默认 0
  - tags (array, optional): 标签列表
  - active (boolean, optional): 是否激活，默认 true
  - config (object, optional): 额外配置项

实际示例

CRM 查询工具

## crm_query
Query customer information from CRM system.
- **Parameters**:
  - customerId (string, required): Customer ID or phone number
  - fields (array, optional): Specific fields to return
- **Returns**: Customer profile object with name, contact, orders

### Usage Notes
- Use this tool when user asks about customer or order information
- Always confirm customer identity before sharing details

数据库查询工具

## db_query
Execute a read-only SQL query on the business database.
- **Parameters**:
  - query (string, required): SQL SELECT query
  - database (string, optional): Target database name, default "main"
- **Returns**: Query results as array of objects

### Usage Notes
- Only SELECT queries are allowed
- Limit results to 100 rows maximum
- Do not query tables containing sensitive personal data

文件操作工具

## file_read
Read the contents of a file.
- **Parameters**:
  - path (string, required): File path relative to workspace
  - encoding (string, optional): File encoding, default "utf-8"
- **Returns**: File content as string

## file_write
Write content to a file.
- **Parameters**:
  - path (string, required): File path relative to workspace
  - content (string, required): Content to write
  - append (boolean, optional): Append instead of overwrite, default false
- **Returns**: Write confirmation with file size

高级定义

工具约束

## dangerous_tool
Perform a potentially dangerous operation.
- **Parameters**:
  - target (string, required): Operation target
  - force (boolean, optional): Skip confirmation, default false
- **Returns**: Operation result
- **Policy**: ask (always require user confirmation)
- **Rate Limit**: 5 calls per minute

工具分组

# Tools

## Data Tools

### db_query
...

### db_stats
...

## Communication Tools

### send_email
...

### send_sms
...

与代码工具的关系

TOOLS.md 中定义的工具需要有对应的代码实现：

TOOLS.md (声明)          →  插件代码 (实现)
                          
## my_tool               →  handler: async (params) => {
  description...              return result
  parameters...            }

双重定义

工具同时在 TOOLS.md（供 LLM 理解）和插件代码（供系统执行）中定义。两者的参数描述应保持一致。

最佳实践

1. 命名清晰 — 使用 snake_case 命名，如 order_query 而非 oq
2. 描述精确 — 说明工具的具体功能和使用场景
3. 参数完整 — 标注类型、是否必填、默认值
4. 限制明确 — 说明工具的使用限制和注意事项
5. 按需加载 — 只定义 Agent 真正需要的工具，减少 Token 开销