工具棉绒
用于AI工具定义的生产就绪的过梁。验证并评分MCP工具定义、OpenAI函数调用模式和Anthropic工具使用块,以提高清晰度、完整性和代理友好性。
为什么使用工具棉绒?
人工智能代理的性能取决于它们所提供的工具。定义不清的工具会导致:
- 代理人困惑 --模糊的描述导致工具选择不正确
- 浪费的代币 --名称不明确和缺少上下文会增加重试次数
- 运行时错误 --缺少或无效的参数会中断执行
- 用户体验不佳 --代理失败会损害用户信任
工具棉绒 通过执行工具定义的最佳实践,在这些问题到达生产环境之前发现它们。
特性
✅ 多格式支持 --MCP、OpenAI和Anthropic工具模式\
✅ 12+综合规则 --捕捉常见的反模式\
✅ 智能评分系统 --每个工具0-100分,输出颜色编码\
✅ 多种输出格式 --用于CI集成的文本、JSON和SARIF\
✅ 灵活的输入 --文件、目录、globs或stdin\
✅ 可配置的 --忽略规则,设置最低分数,自定义严重程度\
✅ 生产就绪 --TypeScript,严格模式,全面测试
安装
全局安装(推荐)```bash
npm install -g tool-lint
### 本地安装```bash
npm install --save-dev tool-lint
无需安装即可运行```bash
npx tool-lint check tools.json
______________________________________________________________________
## 快速开始
### 基本用法```bash
# Check a single file
tool-lint check tools.json
# Check multiple files
tool-lint check tools/*.json
# Check with minimum score threshold
tool-lint check tools.json --min-score 80
# Output as JSON
tool-lint check tools.json --format json
# Output SARIF for CI integration
tool-lint check tools.json --format sarif > results.sarif
查看可用规则```bash
tool-lint rules
### 示例输出```
$ tool-lint check tools.json
✓ get_user_profile [92/100]
• 3 rules passed
• Well-structured tool definition
✗ search_products [64/100]
⚠ vague-tool-description: Missing concrete action verbs
⚠ too-many-params: 7 parameters (max 5 recommended)
Overall Score: 78/100
2 tools checked, 1 needs attention
棉绒规则
tool-lint执行12条综合规则:
工具级别规则
| 规则 | 描述 | 严重性 |
|---|---|---|
missing-tool-name |
工具必须有名称 | 错误 |
missing-tool-description |
工具必须有描述 | 错误 |
vague-tool-description |
描述应使用具体动作动词(例如,“检索”、“创建”) | 警告 |
oversized-description |
描述应简洁(建议\<200个字符) | 警告 |
参数规则
| 规则 | 描述 | 严重性 |
|---|---|---|
missing-param-description |
所有参数都应该有描述 | 警告 |
vague-param-name |
参数名称应清晰(避免 x, data, input) |
警告 |
no-type-specified |
所有参数都必须指定类型 | 错误 |
too-many-params |
工具应具有≤5个代理理解参数 | 警告 |
duplicate-param-names |
参数名称必须唯一 | 错误 |
架构规则
| 规则 | 描述 | 严重性 |
|---|---|---|
ambiguous-enum |
枚举值应该不言自明 | 警告 |
nested-object-schema |
避免深嵌套对象(最多2级) | 警告 |
missing-required-field |
应明确标记必需的参数 | 错误 |
支持格式
MCP(模型上下文协议)```json
{
"name": "get_weather",
"description": "Retrieves current weather data for a specific location",
"inputSchema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City name or ZIP code"
},
"units": {
"type": "string",
"description": "Temperature units",
"enum": ["celsius", "fahrenheit"]
}
},
"required": ["location"]
}
}
### OpenAI函数调用```json
{
"name": "get_weather",
"description": "Retrieves current weather data for a specific location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City name or ZIP code"
}
},
"required": ["location"]
}
}
人工工具使用```json
{
"name": "get_weather",
"description": "Retrieves current weather data for a specific location",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City name or ZIP code"
}
},
"required": ["location"]
}
}
______________________________________________________________________
## 配置
创建一个 `.toollintrc.json` 项目根目录中的文件:```json
{
"rules": {
"vague-tool-description": "warn",
"too-many-params": "off"
},
"minScore": 75,
"ignore": [
"legacy-tools.json"
]
}
配置选项
rules--设置规则严重性:"error","warn",或"off"minScore--最低分数阈值(0-100)ignore--要跳过的文件/模式format--默认输出格式:"text","json",或"sarif"
CI/CD集成
GitHub操作```yaml
name: Lint AI Tools
on: [push, pull_request]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '18'
- run: npm install -g tool-lint
- run: tool-lint check tools/ --format sarif --min-score 80
### 预提交钩子```bash
#!/bin/bash
# .git/hooks/pre-commit
tool-lint check tools.json --min-score 75 || {
echo "❌ Tool linting failed. Fix issues or use --no-verify to skip."
exit 1
}
例子
请参阅 examples/ 示例工具定义目录:
mcp-tools.json--MCP格式示例openai-functions.json--OpenAI函数调用示例anthropic-tools.json--拟人工具使用示例
运行linting示例:```bash
tool-lint check examples/*.json
______________________________________________________________________
## 命令行命令
### `check`
抓取一个或多个工具定义文件。```bash
tool-lint check [options]
Options:
--format Output format: text, json, sarif (default: text)
--min-score Minimum score threshold (0-100)
--config Path to config file
--ignore Patterns to ignore (comma-separated)
--strict Treat warnings as errors
rules
列出所有可用的lint规则及其说明。```bash
tool-lint rules [options]
Options:
--verbose Show detailed rule descriptions
### `init`
创建一个 `.toollintrc.json` 默认配置文件。```bash
tool-lint init
评分系统
每个工具根据以下因素获得0-100的分数:
- 错误 ---每个20分(缺少名称、无效架构等)
- 警告 ---每个得5分(描述模糊、参数太多等)
- 奖金 --+10表示描述良好,参数名称清晰
分数解释
分数 · 状态 · 含义
90-100 · 🟢 优秀 · 生产就绪,遵循最佳实践
75-89 · 🟡 良好 · 建议稍作改进
60-74 · 🟠 需要解决的几个问题
0-59 · 🔴 差 · 主要问题,未准备好生产
最佳实践
✅ 良好的工具定义```json
{
"name": "send_email",
"description": "Sends an email to a recipient with subject and body content",
"inputSchema": {
"type": "object",
"properties": {
"to": {
"type": "string",
"description": "Recipient email address"
},
"subject": {
"type": "string",
"description": "Email subject line"
},
"body": {
"type": "string",
"description": "Email message content"
}
},
"required": ["to", "subject", "body"]
}
}
**为什么它很好:**
- 具体动作动词(“发送”)
- 明确、具体的参数名称
- 所有参数都有描述
- 明确标记的必填字段
- ≤5个参数(在这种情况下为3个)
### ❌ 工具定义不佳```json
{
"name": "email",
"description": "Does email stuff",
"inputSchema": {
"type": "object",
"properties": {
"data": { "type": "string" },
"opts": { "type": "object" }
}
}
}
问题:
- 名称模糊(什么样的电子邮件操作?)
- 描述模糊(“东西”没有帮助)
- 通用参数名称(
data,opts) - 缺少参数说明
- 未指定必填字段
- 没有架构的嵌套对象
发展
从源代码构建```bash
git clone https://github.com/jeevesbot-io/tool-lint.git
cd tool-lint
npm install
npm run build
npm link
### 运行测试```bash
npm test
项目结构```
tool-lint/
├── bin/
│ └── tool-lint.ts # CLI entry point
├── src/
│ ├── cli.ts # Command handlers
│ ├── parser.ts # Schema parser
│ ├── scorer.ts # Scoring engine
│ ├── types.ts # TypeScript types
│ ├── formatters/ # Output formatters
│ │ ├── text.ts
│ │ ├── json.ts
│ │ └── sarif.ts
│ └── rules/ # Lint rules
│ ├── missing-tool-description.ts
│ ├── vague-tool-description.ts
│ └── ... (12 rules total)
├── tests/ # Test suite
├── examples/ # Example tool definitions
└── README.md
______________________________________________________________________
## 常见问题解答
### Q: 我为什么需要这个?
**A.** 如果你正在构建使用工具(MCP服务器、OpenAI函数、Anthropic工具)的AI代理,定义不清的工具会浪费令牌、混淆代理并导致运行时错误。工具棉绒在生产前就发现了这些问题。
### Q: 我可以在CI/CD中使用它吗?
**A.** 对!使用 `--format sarif` GitHub Actions与GitLab CI集成的输出,或设置 `--min-score` 构建失败阈值。
### Q: 如何禁用规则?
**A.** 创建一个 `.toollintrc.json` 文件并将规则设置为 `"off"`:```json
{
"rules": {
"too-many-params": "off"
}
}
Q: MCP、OpenAI和Anthropic格式之间有什么区别?
A. 它们是定义工具参数的不同模式约定:
- 主控程序 用途
inputSchema - 开放人工智能 用途
parameters - Anthropic 用途
input_schema
tool-lint支持这三种工具,并在内部对其进行规范化。
Q: 我可以延长规则吗?
A. 还没有,但计划在v2.0中支持自定义规则。现在,您可以分叉仓库并在其中添加自己的规则 src/rules/.
建造于
铸造厂 --自主建设者代理\
管道:Scout(3m)→ 研究员(3m)→ 规格(1m)→ 建筑商(9m)
构建统计信息:
- 时长:约9分钟
- 测试:23/23通过
- 成本:0.57美元
- 建造时间:2026-03-02
许可证
麻省理工学院
贡献
欢迎投稿!请打开问题或PR。
- 分叉回购
- 创建要素分支(
git checkout -b feature/amazing-rule) - 提交更改(
git commit -m 'Add amazing rule') - 推送到分支(
git push origin feature/amazing-rule) - 打开拉取请求
链接
- github: https://github.com/jeevesbot-io/tool-lint
- 问题: https://github.com/jeevesbot-io/tool-lint/issues
- NPM: (即将推出)
制作🤖 铸造厂
