К основному содержанию
скилл CX Codex

eval-mcp — скилл для Claude Code: что делает и как установить

Скилл eval-mcp проверяет схемы MCP-сервера и точность выбора инструментов моделью. Находит пересечения в описаниях и тестирует вызовы на синтетических запросах.

MIT 234 установок ★ 227 обновлён 2026-08-15

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add pproenca/dot-skills --skill eval-mcp -a claude-code
Открыть на GitHub

Что делает eval-mcp

Скилл оценивает описания инструментов в MCP-сервере и помогает понять, почему агент выбирает не те функции. Работа разбита на этапы: сбор схем через MCP Inspector CLI, детерминированный статический анализ без обращений к LLM и параллельное тестирование выбора методов на наборе пользовательских намерений.

Для каждого инструмента генерируются позитивные и негативные сценарии, а также фразы для разграничения схожих вызовов. Результаты сводятся в отчёт с метриками точности, полноты и списком частых подмен одного инструмента другим.

Без установленных Node.js версии не ниже 18 и утилиты jq аналитические скрипты скилла не запустятся. Сервер должен быть уже поднят и отвечать на вызовы tools/list по HTTP, SSE или stdio.

Какие задачи решает

  • найти смысловые пересечения в описаниях похожих инструментов MCP-сервера
  • измерить точность выбора нужного инструмента на тестовых запросах
  • проверить схемы параметров статическим анализом без расхода токенов
  • обнаружить неверные срабатывания и ложные отказы от вызова инструментов

Примеры запросов агенту

  • Проверь схемы инструментов моего MCP-сервера
  • Протестируй выбор инструментов для MCP-сервера на http://localhost:3000/mcp
  • Оцени качество описаний инструментов в локальном сервере через node dist/server.js

Как установить eval-mcp

1Через Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill eval-mcp -a claude-code

2Вручную: положить файлы

~/.claude/skills/eval-mcp/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/eval-mcp/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об eval-mcp

Как установить eval-mcp в Claude Code?

Выполните в терминале команду npx skills add pproenca/dot-skills --skill eval-mcp -a claude-code.

Что делает скилл eval-mcp?

Он подключается к MCP-серверу, находит ошибки в схемах параметров и запускает синтетические тесты, чтобы замерить точность выбора инструментов моделью.

Что нужно подготовить перед запуском eval-mcp?

Требуются Node.js 18 или новее, утилита jq и работающий MCP-сервер, отвечающий на запрос tools/list.

Исходный текст

SKILL.md · MIT
---
name: eval-mcp
description: Measures whether Claude uses an MCP server's tools correctly — tests tool selection accuracy, analyzes schema quality, and iteratively optimizes descriptions. Triggers when the user asks to "evaluate MCP tools", "test tool selection", "improve tool descriptions", "check MCP schema quality", or "eval my MCP server". Companion to build-mcp-server.
---
# Evaluate MCP Tools

Tool descriptions are prompt engineering — they land directly in Claude's context window and determine whether Claude picks the right tool with the right arguments. This skill makes tool quality **measurable and improvable** instead of guesswork.

Three levels of testing, each building on the last:
1. **Static Analysis** — deterministic schema quality checks (no Claude calls)
2. **Selection Testing** — does Claude pick the right tool for each intent?
3. **Description Optimization** — iterative improvement based on confusion patterns

## When to Apply

- User wants to check if their MCP tool schemas are well-designed
- User wants to test whether Claude selects the right tools for user intents
- User is debugging tool confusion (Claude picks the wrong tool)
- User wants to optimize tool descriptions for better selection accuracy
- User has finished scaffolding with `build-mcp-server` and wants to validate quality

## Workflow Overview

```
Phase 1: Connect → Phase 2: Static Analysis → Phase 3: Selection Testing → Phase 4: Optimize
                                                            ↑__________________________|
```

Phase 4 loops back: apply rewrites → refetch schemas → retest → compare accuracy.

## Prerequisites

- **Node.js >= 18** — required for the MCP Inspector CLI (`npx`)
- **jq** — required for schema analysis scripts
- **A running MCP server** — the server must respond to `tools/list`. Use `build-mcp-server/scripts/test-server.sh` to verify connectivity first.

---

## Phase 1 — Connect & Inventory

Connect to the user's MCP server and fetch the tool schemas.

### 1a: Get connection details

Ask the user how to reach their server:
- **HTTP/SSE**: URL (e.g., `http://localhost:3000/mcp`)
- **stdio**: spawn command (e.g., `node dist/server.js`)

### 1b: Fetch tool schemas

```bash
bash scripts/fetch-tools.sh <url-or-command> <transport> <workspace>/tools.json
```

This calls `tools/list` via the MCP Inspector CLI and saves the schemas.

### 1c: Display inventory

Show a summary table:

```markdown
| # | Tool | Description (preview) | Params | Annotations |
|---|------|-----------------------|--------|-------------|
| 1 | search_issues | Search issues by keyword... | 3 | readOnlyHint |
| 2 | create_issue | Create a new issue... | 4 | — |
```

Flag tool count: 1-15 optimal, 15-30 warning, 30+ excessive (consider search+execute pattern).

### 1d: Create workspace

Create workspace at `{server-name}-eval/` adjacent to the skill directory or in the user's project:

```
{server-name}-eval/
├── tools.json
├── evals/
│   └── evals.json
└── iteration-N/
```

---

## Phase 2 — Static Analysis

Run deterministic quality checks — no Claude calls needed. This gives immediate feedback during development.

### 2a: Run analysis

```bash
bash scripts/analyze-schemas.sh <workspace>/tools.json <workspace>/iteration-N/static-analysis.json
```

### 2b: Display results

Show per-tool quality scores. Read [`references/quality-checklist.md`](references/quality-checklist.md) for the criteria being checked.

```markdown
| Tool | Desc | Params | Schema | Annotations | Overall | Issues |
|------|------|--------|--------|-------------|---------|--------|
| search_issues | 3/3 | 3/3 | 2/3 | 2/3 | 2.5 | No negation |
| create_issue | 1/3 | 1/3 | 0/3 | 0/3 | 0.5 | 4 issues |
```

### 2c: Flag sibling pairs

If the analysis found tools with high description overlap, highlight them as confusion risks:

```markdown
### Sibling Pairs (confusion risk)
| Tool A | Tool B | Overlap | Risk |
|--------|--------|---------|------|
| search_issues | list_issues | 52% | HIGH |
```

### 2d: Decision point

If critical issues exist (missing descriptions, zero annotations), recommend fixing them before Phase 3. Static issues create noise in selection testing — fix the obvious problems first, then measure the subtle ones.

If all tools score well, proceed to Phase 3.

---

## Phase 3 — Selection Testing

Test whether Claude picks the right tool for each user intent. This is the core eval.

### 3a: Generate test intents

Read [`references/eval-patterns.md`](references/eval-patterns.md) for intent generation patterns.

For each tool, generate:
- **3 should-trigger intents** — direct, implicit, and casual phrasings
- **2 should-not-trigger intents** — near-miss and keyword overlap

For each sibling pair flagged in Phase 2:
- **1 disambiguation intent per tool** — tests whether Claude picks the RIGHT sibling

Present all intents to the user for review. Ask if any should be added, removed, or modified.

### 3b: Save intents

Save to `{workspace}/evals/evals.json`:

```json
{
  "server_name": "my-server",
  "generated_from": "tools.json",
  "intents": [
    {
      "id": 1,
      "intent": "Are there any open bugs related to checkout?",
      "expected_tool": "search_issues",
      "type": "should_trigger",
      "target_tool": "search_issues",
      "notes": "Implicit intent — doesn't name the action"
    }
  ]
}
```

### 3c: Run selection tests

For each intent, spawn a subagent that receives:
1. The full tool schemas from tools.json (formatted as they'd appear in Claude's context)
2. The user intent text
3. Instructions to select exactly one tool and provide arguments, or decline if no tool fits

The subagent prompt:

```
You have access to the following MCP tools:

{tool schemas as JSON}

A user sends this message:
"{intent text}"

Which tool would you call? Respond with JSON:
{
  "selected_tool": "tool_name" or null,
  "arguments": { ... } or {},
  "reasoning": "One sentence explaining your choice"
}

If no tool fits the user's request, set selected_tool to null.
Select exactly ONE tool. Do not suggest calling multiple tools.
```

Save each result to `{workspace}/iteration-N/selection/intent-{ID}/result.json`.

Launch all selection tests in parallel for efficiency.

### 3d: Grade results

```bash
bash scripts/grade-selection.sh \
  <workspace>/iteration-N/selection \
  <workspace>/evals/evals.json \
  <workspace>/iteration-N/benchmark.json
```

### 3e: Display results

```markdown
## Selection Results — Iteration N

**Accuracy:** 82% (41/50 correct)

| Metric | Count |
|--------|-------|
| Correct | 41 |
| Wrong tool | 5 |
| False accept | 2 |
| False reject | 2 |

### Per-Tool Accuracy
| Tool | Precision | Recall |
|------|-----------|--------|
| search_issues | 0.90 | 0.85 |
| create_issue | 1.00 | 1.00 |

### Worst Confusions
| Expected | Selected Instead | Times |
|----------|-----------------|-------|
| list_issues | search_issues | 3 |
| get_user | find_user_by_email | 2 |
```

---

## Phase 4 — Optimize & Iterate

Analyze confusion patterns and suggest description improvements. Read [`references/optimization.md`](references/optimization.md) for rewrite patterns.

### 4a: Analyze confusions

For each confused pair (from worst_confusions):
1. Read both tools' current descriptions
2. Identify why they're confusing (missing negation, overlapping scope, no cross-reference)
3. Draft a specific rewrite following the disambiguation patterns in optimization.md

### 4b: Present suggestions

```markdown
## Suggested Improvements

### search_issues ↔ list_issues (confused 3 times)

**search_issues — Before:**
> Search issues by keyword.

**search_issues — After:**
> Search issues by keyword across title and body. Returns up to `limit` results ranked by relevance. Does NOT filter by status, assignee, or date — use list_issues for structured filtering.

**Reason:** Adding scope boundary and cross-reference to disambiguate from list_issues.
```

Save to `{workspace}/iteration-N/suggestions.json` (format defined in optimization.md).

### 4c: Apply and retest

After the user applies the rewrites to their server code:

1. Restart the server
2. Re-run Phase 1 to refetch tools.json (descriptions may have changed)
3. Re-run Phase 2 for updated static analysis
4. Re-run Phase 3 into `iteration-N+1` using the same evals.json
5. Compare accuracy:

```markdown
## Iteration Comparison

| Metric | Iteration 1 | Iteration 2 | Delta |
|--------|------------|------------|-------|
| Accuracy | 82% | 94% | +12% |
| search↔list confusion | 3 | 0 | -3 |
```

### 4d: Iteration guidance

- Change **one sibling pair per iteration** so you can attribute improvements
- If accuracy plateaus, the remaining confusions may need architectural changes (merging tools, renaming, or restructuring the tool surface)
- Stop when accuracy exceeds 90% or when remaining confusions are in ambiguous edge cases that humans would also struggle with

---

## Reference Files

Read these when you reach the relevant phase — not upfront:

- [`references/quality-checklist.md`](references/quality-checklist.md) — Testable quality criteria for tool schemas (Phase 2)
- [`references/eval-patterns.md`](references/eval-patterns.md) — How to write tool selection test intents (Phase 3)
- [`references/optimization.md`](references/optimization.md) — How to improve descriptions from eval results (Phase 4)

## Related Skills

- `build-mcp-server` — Design and scaffold MCP servers (run this first, then eval-mcp to validate)
- `build-mcp-app` — MCP servers with interactive UI widgets

© pproenca · MIT · pproenca/dot-skills

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →
bmad-eval bmad-code-org Скилл bmad-eval для Claude Code, Codex, Cursor и Copilot, который прогоняет тесты другого скилла и отчитывается о результатах. Запускается, когда нужно проверить триггеры описания, сравнить версии или оценить качество по рубрике. CX Codex +1 9 100установок agent-eval affaan-m Скилл agent-eval сравнивает кодинг-агентов на ваших задачах по точности, стоимости и времени. Помогает выбрать инструмент на реальных тестах без опоры на субъективные впечатления. CX Codex +1 6 200установок eval-runner haabe Скилл eval-runner для Claude Code запускает eval-сценарии из YAML через reflexion-цикл и записывает результаты в JSON. Фиксирует время, число итераций и статус критериев успеха. CX Codex +1 ★ 54звёзд репо llm-eval-harness daymade Скилл llm-eval-harness для Claude Code, Codex, Cursor и других платформ: проверяет сторонний LLM-эндпоинт на доступность, скорость, точность следования system prompt и соответствие протоколу. CX Codex +1 438установок eval-engineer VoltAgent Субагент eval-engineer для Codex, который проектирует оценку качества промптов, поиска, вызова инструментов и сложных агентов. CX Codex ★ 6 505звёзд репо google-agents-cli-eval официальный Google Скилл google-agents-cli-eval оценивает качество ИИ-агентов через agents-cli, находит ошибки и сравнивает прогоны. Включается при отладке датасетов и проверке метрик в проектах на базе Gemini. CX Codex +1 586 000установок

Из того же набора139

Весь набор →
exec-plan Скилл exec-plan организует жизненный цикл автономных планов разработки в Markdown для задач длиннее одной сессии или с правками более трёх файлов. CX Codex +1 239установок graph-schema Скилл graph-schema для Claude Code помогает проектировать, проверять и перерабатывать схемы графовых баз данных. Он включается при моделировании узлов и связей или переносе предметной области в граф. CX Codex +1 239установок clean-code-ts-react Скилл clean-code-ts-react переносит принципы Clean Code Роберта Мартина на TypeScript 5.x и React 19. Помогает на код-ревью, при рефакторинге и проектировании компонентов или функций. CX Codex +1 238установок cli-for-agents Скилл cli-for-agents для Claude Code помогает проектировать и проверять CLI, которым пользуются ИИ-агенты и автоматизация. Он включается при работе с подкомандами, флагами, справкой и сообщениями об ошибках. CX Codex +1 237установок threat-patch Скилл threat-patch берёт находки сканера или модель угроз и превращает их в небольшие патчи кода с описанием правок и шагами проверки. CX Codex +1 232установок diagram-quality Скилл diagram-quality задаёт правила отрисовки PlantUML на холсте agent-uml, предотвращая ошибки HTTP 400 и пустые схемы при работе с инструментами дизайна. CX Codex +1 230установок drizzle-sqlite Скилл drizzle-sqlite помогает писать и проверять Drizzle ORM для SQLite: схемы, миграции, запросы, транзакции и типы. Подходит для рефакторинга SQLite-кода. CX Codex +1 221установок cli-review-runner Скилл cli-review-runner для Claude Code проверяет CLI-команду по 45 правилам каталога cli-for-agents и оценивает, может ли агент безопасно использовать её в пайплайне. CX Codex +1 219установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой