---
id: "mnrqnr5v-v75drf"
name: "LLM友好工具描述格式最佳实践"
type: "reference"
project: "null"
tags: [llm-prompt, tool-description, agent, best-practice]
created: "2026-04-09"
---
为 AI Agent 扩展工具设计 LLM 友好提示词格式的最佳实践：

**核心原则：**
1. **使用场景描述** - 告诉 LLM 何时应该调用该工具，而非仅描述工具功能
2. **真实可运行的示例** - 生成可直接复制使用的代码示例
3. **参数清晰标注** - 必填/可选标记、类型、默认值三要素
4. **枚举值透明** - Enum 类型必须列出所有可选值

**实现要点：**
- 使用 `_inferUseCases()` 根据插件/工具名称自动推断使用场景
- 使用 `_generateExampleValue()` 根据参数名和类型生成合理示例
- 表格化参数描述，用 ✅❌ 标记必填
- 示例代码添加中文注释说明意图

**格式结构：**
1. 插件级：名称 + 功能描述 + 使用场景
2. 工具级：工具名 + 功能 + 参数表 + 调用示例
3. 参数级：参数名 + 类型 + 必填标记 + 描述

**Why 重要：**
- 模糊的工具描述导致 LLM 乱传参数或在不必要场景调用
- 没有示例时 LLM 容易生成格式错误的调用
- 不标注必填/可选导致 LLM 遗漏关键参数

**How to apply：**
参考 .agent/plugins/agent-core/agent.js 中 `_buildExtensionToolsDescription()` 函数的实现，该函数已整合了上述所有最佳实践。