内容
# TDAS — 工具描述增强系统
TDAS 检测并改进用于模型上下文协议（MCP）工具的弱自然语言描述。MCP 代理从文本描述中选择和调用工具，因此模糊、不完整或误导性的描述可能导致错误的工具选择、不正确的参数、额外的重试和更高的 token 成本。
[](https://www.python.org/)
[](LICENSE)
## TDAS 解决的问题
LLM 代理通常会看到一个工具注册表，并且必须根据简短的自然语言描述来决定调用哪个工具。当这些描述模糊、省略约束、未能解释参数或缺乏示例时，代理可能会：
- 选择错误的工具，
- 传递无效参数，
- 重试失败的调用，
- 臆测工具不支持的功能，
- 在可避免的纠正循环上花费额外的 token。
TDAS 将工具描述视为质量关键的接口文本。它为团队提供了一种可重复的方法来检查描述、报告常见的弱点，并可选地在代理使用它们之前重写不良描述。
## 为什么它有用
- **对于 MCP 服务器维护者：** 在发布服务器之前捕获弱工具描述。
- **对于 AI 代理构建者：** 在不更改工具代码的情况下提高工具选择可靠性。
- **对于平台团队：** 在工具注册表上运行 TDAS 作为 CI 质量门控。
- **对于评估：** 将原始描述与增强描述进行比较，并使用包含的基准测试格式。
TDAS 支持两种工作流程：
| 工作流程 | 命令 | 使用场景 |
| --- | --- | --- |
| 包含基准测试报告 | `tdas report --annotations` | 您想要从包含的标记数据集获取流行度表 |
| 实时检查 | `tdas analyze`、`tdas report --heuristics`、`tdas run` | 您想要检查或改进新的 MCP 工具描述 |
它检查六种描述气味：
| ID | 气味 | 含义 | 包含的数据集流行度 |
| --- | --- | --- | ---: |
| S1 | 模糊意图 | 目的或领域不明确 | 61.3% |
| S2 | 缺失约束 | 缺失身份验证、速率限制、前置条件或失败 | 54.7% |
| S3 | 模糊参数 | 参数语义、类型或格式未指定 | 48.2% |
| S4 | 过于冗长 | 描述太长或填充了无关的文字 | 39.6% |
| S5 | 不完整的示例 | 缺失具体的输入/输出示例 | 72.4% |
| S6 | 误导范围 | 描述意味着工具不具备的功能 | 28.9% |
包含基准测试摘要：
| 指标 | 原始描述 | TDAS | 变化 |
| --- | ---: | ---: | ---: |
| 任务成功率 | 0.51 | 0.74 | +45.1% |
| 工具选择准确率 | 0.58 | 0.81 | +39.7% |
| token 成本，归一化 | 1.00 | 0.61 | -39% |
## 仓库内容
```text
tdas/
├── tdas/ # Python 包
│ ├── cli.py # 命令行接口
│ ├── core.py # TDAS 管道
│ ├── models.py # 数据模型和气味元数据
│ ├── detectors/ # 启发式和基于 LLM 的气味检测
│ ├── augmenters/ # 气味条件重写
│ ├── evaluation/ # 代理评估助手
│ └── utils/ # JSON 加载和报告助手
├── examples/
│ ├── tools.json # 小型演示数据集
│ ├── tools_553.json # 包含的注释数据集
│ └── demo.py # Python API 演示
├── tests/ # 测试套件
├── skills/tdas/SKILL.md # 本仓库的 AI 代理操作指南
├── pyproject.toml
└── README.md
```
## 分步设置
### 1. 克隆仓库
```bash
git clone https://github.com/codetherock/mcp-tool-description-quality.git
cd mcp-tool-description-quality
```
如果您已经在本地拥有该文件夹，只需 `cd` 进入即可。
### 2. 创建虚拟环境
macOS/Linux：
```bash
python3 -m venv .venv
source .venv/bin/activate
```
Windows PowerShell：
```powershell
py -m venv .venv
.\.venv\Scripts\Activate.ps1
```
不要提交 `.venv/`；它被 `.gitignore` 故意忽略。
### 3. 为开发安装 TDAS
```bash
pip install -e ".[dev]"
```
这安装了 TDAS 以及测试和质量工具：`pytest`、`black`、`ruff` 和 `mypy`。
### 4. 验证 CLI 可用
```bash
tdas --help
```
您应该看到：
```text
usage: tdas [-h] {analyze,run,report} ...
TDAS: 工具描述增强系统
```
## 运行包含的基准测试报告
使用注释模式报告包含的 553 工具标记数据集：
```bash
tdas report --file examples/tools_553.json --annotations
```
预期输出：
```text
TDAS Annotated Dataset Report
──────────────────────────────────────────────────
Tools analyzed: 553
Tools with smells: 400 (72.4%)
Clean tools: 153 (27.6%)
Smell Prevalence:
S5_incomplete_examples █████████████████████ 400/553 (72.4%)
S1_vague_intent ██████████████████ 339/553 (61.3%)
S2_missing_constraints ████████████████ 303/553 (54.7%)
S3_ambiguous_parameters ██████████████ 267/553 (48.2%)
S4_over_verbose ███████████ 219/553 (39.6%)
S6_misleading_scope ████████ 160/553 (28.9%)
```
`--annotations` 读取存储在 `examples/tools_553.json` 中的 `smells_expected` 标签。当您想要基准测试标签摘要时使用此模式，而不是使用启发式方法重新计算气味。
## 在没有 API 密钥的情况下运行实时检测
使用启发式模式进行离线检查：
```bash
tdas analyze \
--name "get_stock_price" \
--description "Gets price." \
--heuristics \
--verbose
```
您还可以对 JSON 文件运行启发式方法：
```bash
tdas report --file examples/tools.json --heuristics
```
当输入文件不包含注释标签时使用 `--heuristics`。
## 运行演示脚本
```bash
python examples/demo.py
```
演示始终首先运行离线示例。除非设置了 `ANTHROPIC_API_KEY`，否则基于 LLM 的增强示例将被跳过。
## 运行基于 LLM 的增强
增强使用特定于气味的提示重写有气味的描述。它需要一个 Anthropic API 密钥。
macOS/Linux：
```bash
export ANTHROPIC_API_KEY="sk-ant-..."
```
Windows PowerShell：
```powershell
$env:ANTHROPIC_API_KEY = "sk-ant-..."
```
然后运行：
```bash
tdas run \
--file examples/tools.json \
--output augmented_tools.json \
--verbose
```
为了控制成本，请先使用 `examples/tools.json`，然后再运行完整的 553 工具数据集。
## 运行测试和质量检查
在提交之前：
```bash
ruff check tdas/
black --check tdas/
mypy tdas
pytest tests -v
```
预期测试结果：
```text
20 passed
```
## 输入 JSON 格式
TDAS 接受工具列表：
```json
[
{
"name": "create_github_issue",
"description": "Creates a GitHub issue.",
"parameters": {
"owner": {"type": "string"},
"repo": {"type": "string"},
"title": {"type": "string"},
"body": {"type": "string"}
},
"server_name": "DevOpsMCP"
}
]
```
注释数据集还可以包括可选的元数据：
```json
{
"domain": "devops",
"server_prefix": "ToolBench",
"smells_expected": ["S1", "S5"],
"quality_notes": "Smells: S1, S5"
}
```
## Python API
离线分析：
```python
from tdas import TDAS, ToolDescription
pipeline = TDAS(use_heuristics_only=True)
tool = ToolDescription(
name="get_stock_price",
description="Gets price.",
parameters={"ticker": {"type": "string"}},
)
report = pipeline.analyze(tool)
print(report.quality_score.overall)
print([d.smell_type.value for d in report.detections])
```
LLM 增强：
```python
from anthropic import Anthropic
from tdas import TDAS, ToolDescription
pipeline = TDAS(client=Anthropic())
result = pipeline.run(ToolDescription(
name="get_stock_price",
description="Gets price.",
parameters={"ticker": {"type": "string"}},
))
print(result.augmented.description)
print(result.quality_delta)
```
## 工作原理
1. 从 JSON 或 Python 对象加载工具描述。
2. 检测器在 0-3 的范围内评估六个质量组件。
3. 低组件分数映射到 S1-S6 气味标签。
4. 低于质量阈值的描述可以被重写。
5. 增强器使用特定于气味的提示，而不是通用的改述。
6. 报告总结质量分数、气味流行度和增强结果。
质量分数：
```text
Q(d) = (0.22*C1 + 0.18*C2 + 0.17*C3 + 0.10*C4 + 0.21*C5 + 0.12*C6) / 3
```
`Q < 0.55` 的描述是增强的候选者。
## GitHub 注意事项
提交源代码、测试、文档和示例：
```text
.github/
examples/
skills/
tdas/
tests/
.gitignore
LICENSE
README.md
pyproject.toml
```
不要提交生成的或本地文件：
```text
.venv/
dist/
build/
*.egg-info/
__pycache__/
.pytest_cache/
.mypy_cache/
.ruff_cache/
.coverage
.DS_Store
```
## 相关工作和新颖性
TDAS 建立在代码气味、API 文档质量、提示质量和 LLM 工具使用基准测试的现有想法之上。这里的贡献是将气味分类法应用于 MCP 工具描述，并将气味检测与气味条件重写配对，用于面向代理的工具元数据。
## 许可证
MIT 许可证。参见 [LICENSE](LICENSE)。
连接信息
猜你喜欢
暂无推荐服务器