Tool Lint

工具棉绒

用于AI工具定义的生产就绪的过梁。验证并评分MCP工具定义、OpenAI函数调用模式和Anthropic工具使用块，以提高清晰度、完整性和代理友好性。

   

______________________________________________________________________

为什么使用工具棉绒？

人工智能代理的性能取决于它们所提供的工具。定义不清的工具会导致：

• 代理人困惑 --模糊的描述导致工具选择不正确
• 浪费的代币 --名称不明确和缺少上下文会增加重试次数
• 运行时错误 --缺少或无效的参数会中断执行
• 用户体验不佳 --代理失败会损害用户信任

工具棉绒 通过执行工具定义的最佳实践，在这些问题到达生产环境之前发现它们。

______________________________________________________________________

特性

✅ 多格式支持 --MCP、OpenAI和Anthropic工具模式\ ✅ 12+综合规则 --捕捉常见的反模式\ ✅ 智能评分系统 --每个工具0-100分，输出颜色编码\ ✅ 多种输出格式 --用于CI集成的文本、JSON和SARIF\ ✅ 灵活的输入 --文件、目录、globs或stdin\ ✅ 可配置的 --忽略规则，设置最低分数，自定义严重程度\ ✅ 生产就绪 --TypeScript，严格模式，全面测试

______________________________________________________________________

安装

全局安装（推荐）

npm install -g tool-lint

本地安装

npm install --save-dev tool-lint

无需安装即可运行

npx tool-lint check tools.json

______________________________________________________________________

快速开始

基本用法

# 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

查看可用规则

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条综合规则：

工具级别规则

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规则及其说明。

tool-lint rules [options]

Options: --verbose Show detailed rule descriptions

### `init`

创建一个 `.toollintrc.json` 默认配置文件。

tool-lint init

______________________________________________________________________

## 评分系统

每个工具根据以下因素获得0-100的分数：

- **错误** ---每个20分（缺少名称、无效架构等）
- **警告** ---每个得5分（描述模糊、参数太多等）
- **奖金** --+10表示描述良好，参数名称清晰

### 分数解释

|分数|状态|含义|
|-------|--------|---------|
| 90-100 | 🟢 优秀|生产就绪，遵循最佳实践|
| 75-89 | 🟡 良好|建议稍作改进|
| 60-74 | 🟠 需要解决的几个问题|
| 0-59 | 🔴 差|主要问题，未准备好生产|

______________________________________________________________________

## 最佳实践

### ✅ 良好的工具定义

{ "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个）

### ❌ 工具定义不佳

{ "name": "email", "description": "Does email stuff", "inputSchema": { "type": "object", "properties": { "data": { "type": "string" }, "opts": { "type": "object" } } } }

**问题：**

- 名称模糊（什么样的电子邮件操作？）
- 描述模糊（“东西”没有帮助）
- 通用参数名称(`data`, `opts`)
- 缺少参数说明
- 未指定必填字段
- 没有架构的嵌套对象

______________________________________________________________________

## 发展

### 从源代码构建

git clone https://github.com/jeevesbot-io/tool-lint.git cd tool-lint npm install npm run build npm link

### 运行测试

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"`:

{ "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。

1. 分叉回购
1. 创建要素分支(`git checkout -b feature/amazing-rule`)
1. 提交更改(`git commit -m 'Add amazing rule'`)
1. 推送到分支(`git push origin feature/amazing-rule`)
1. 打开拉取请求

______________________________________________________________________

## 链接

- **github：** https://github.com/jeevesbot-io/tool-lint
- **问题：** https://github.com/jeevesbot-io/tool-lint/issues
- **NPM：** （即将推出）

______________________________________________________________________

**制作🤖 铸造厂**