whichtool

Wählt das Modell tatsächlich das richtige Tool von Ihrem MCP-Server?

Italiano

[!WARNUNG] Die Veröffentlichung ist vorübergehend pausiert. Automatisierte Releases sind deaktiviert, und das npm-Paket ist möglicherweise nicht verfügbar, während das öffentliche GitHub-Repository online bleibt. Die Registry- und Action-Anweisungen unten sind absichtlich für eine mögliche zukünftige Neuveröffentlichung beibehalten. Um den aktuellen Quellcode jetzt zu verwenden:

git clone https://github.com/mattagame/whichtool.git
cd whichtool
bun install
bun run ./src/cli/main.ts inspect ./tools.json

Ein MCP-Server kann gültige Schemas haben und für ein Modell dennoch unlesbar sein. Liefern Sie list_users und search_users mit ähnlichen Beschreibungen aus, und das Modell rät. Die Schema-Validierung besteht weiterhin. Auch Integrationstests bestehen, weil sie das richtige Tool konstruktionsbedingt aufrufen.

whichtool stellt diese Oberfläche einem echten Modell gegenüber und berichtet, welches Tool ausgewählt wird und welche Paare verwechselt werden.

whichtool führt niemals ein Tool aus. Es liest tools/list, zeichnet auf, was das Modell aufgerufen hätte, und stoppt.

Es ist bewusst ein Single-Turn-Routing-Benchmark. Es misst die Tool-Auswahlentscheidung des Modells bei einer vorbereiteten Reihe von Absichten; es bewertet keine mehrstufige Agentenausführung, semantische Argumentkorrektheit über eine oberflächliche Schema-Prüfung hinaus, Tool-Ergebnisse, Wiederherstellung oder die Qualität einer endgültigen Antwort.

Jeder in diesem Turn vorgeschlagene Aufruf wird im JSON-Bericht unter trials[].calls aufbewahrt; die First-Call-Felder bleiben eine Kompatibilitätsansicht, kein Grund, zusätzliche Aufrufe zu verwerfen.

Es erledigt zwei Aufgaben:

• inspect — Token-Budget, widersprüchliche Annotationen, nahezu identische Beschreibungen, ungültige x-mcp-header-Werte. Kein Modellaufruf oder Modellanbieter-Schlüssel; ein Live-Ziel kann dennoch eine eigene Autorisierung erfordern.

• run — Versuche, permutierte Tool-Reihenfolge, Konfusionsmatrix, Raten mit Wilson-95%-Intervallen.

inspect warnt, wenn eine Oberfläche mehr als 6 Tools offenlegt. Echte CLI-, MCP- und GitHub-Action- Läufe stoppen, bevor sie ein Modell über diesem Standardwert aufrufen. Nach Überprüfung der Oberfläche kann ein Operator die Grenze mit --max-tools N, trials.maxTools, dem MCP-Startflag oder dem max-tools-Eingabewert der Action erhöhen; 1.000 ist das harte Maximum. Sechs ist ein vorsichtiger Standardwert, nicht eine universelle Regel: Mehr Tools können die Mehrdeutigkeit und die Prompt-Größe erhöhen, aber die richtige Anzahl hängt vom Modell, den Schemas, Beschreibungen und Aufgaben ab. Setzen Sie außerdem --max-context-tokens, damit eine kleine Anzahl ungewöhnlich großer Tools das Kontextbudget nicht umgehen kann.

Diese Wilson-Intervalle beschreiben die Stabilität auf Versuchsebene für die Aufgaben in der Datei. Das Wiederholen einer Aufgabe misst, ob dieselbe Routing-Entscheidung stabil ist; es schätzt nicht, wie das Modell bei unbekannten Absichten abschneiden wird.

Installation

npx whichtool inspect ./tools.json
# or: bunx whichtool inspect ./tools.json

npm install --save-dev whichtool

Erfordert Node 20.11+ oder Bun 1.3+. Null Laufzeitabhängigkeiten.

Standalone-Binärdateien sind noch nicht veröffentlicht. Mit Bun kompilierte ausführbare Dateien betten Komponenten von Drittanbietern zur Laufzeit ein, daher bleibt die Verteilung deaktiviert, bis deren Weiterverbreitungshinweise geprüft wurden und mit jeder Binärdatei ausgeliefert werden können. Dies ist getrennt von der oben genannten vorübergehenden Paket- Veröffentlichungspause; verwenden Sie den Quellcode-Checkout, während diese Pause in Kraft ist.

Related MCP server: TowerWatch Ops Agent MCP Server

Schnellstart

# 1. Look at the surface (no model-provider key)
whichtool inspect ./tools.json
whichtool inspect https://example.com/mcp
whichtool inspect --transport stdio "bun run ./src/server.ts"

# Capture once, work offline afterwards
whichtool inspect --transport stdio "npx -y @modelcontextprotocol/server-filesystem ." \
  --save-snapshot ./tools.json

Snapshots können { "tools": [ … ] }, ein JSON-RPC-tools/list-Umschlag oder ein bloßes Array sein.

# 2. Write a task set (whichtool.tasks.yaml)
version: 1
tasks:
  - id: users.list.basic
    prompt: 'Show me all the users in the workspace'
    expected: list_users
  - id: users.search.byname
    prompt: "Find the user whose name contains 'rossi'"
    expected: search_users
  - id: distractor.delete
    prompt: 'Permanently delete the account belonging to Rossi'
    expected: null

expected muss auch dann geschrieben werden, wenn es null ist. Vollständiges Format: docs/task-sets.md.

# Or draft one instead of writing step 2 by hand, then edit and commit the result
# (do not regenerate on every run). It refuses to overwrite without --force.
whichtool tasks generate ./tools.json --provider ollama --model qwen3:4b --out whichtool.tasks.yaml

# Seeded robustness variants, no model
whichtool tasks mutate --out whichtool.tasks.mutated.yaml --seed 0

# 3. Lint before spending anything
whichtool tasks lint ./tools.json --tasks ./whichtool.tasks.yaml

# 4. Preview the workload (no model call)
whichtool run ./tools.json --provider ollama --model qwen3:4b --repeat 5 --dry-run

# 5. Measure
whichtool run ./tools.json --provider ollama --model qwen3:4b --repeat 5
OPENAI_API_KEY=sk-… whichtool run ./tools.json --provider openai --model gpt-4.1-mini

--repeat ist standardmäßig 5 pro ausgewählter Aufgabe, sodass die Gesamtzahl der Versuche die Aufgaben nach --only / --skip multipliziert mit repeat ist. Ein echter Lauf lehnt standardmäßig mehr als 50 Gesamtversuche ab. Nach Überprüfung von --dry-run erhöhen Sie dieses Budget mit --max-trials N oder trials.maxTrials; 1.000 ist ein absolutes, nicht überschreibbares Maximum.

Die Prompt-Token-Zahl im Trockenlauf ist eine Untergrenze, keine Preisschätzung. Ausgabe- und Reasoning- Tokens kommen hinzu und können viel größer sein. Automatische Wiederholungen sind für die eingebauten HTTP-Anbieter standardmäßig deaktiviert.

Während whichtool run drücken Sie Ctrl+C, um laufende Anbieteranfragen abzubrechen. Der Befehl wird mit Code 130 beendet und schreibt keinen Teilbericht. MCP-Auswertungen bleiben über das MCP-Protokoll abbrechbar.

Exit-Codes: 0 Ausführung war fehlerfrei und Schwellenwerte wurden eingehalten, 1 ein Qualitätsschwellenwert wurde nicht erreicht, 2 ein Ausführungsfehler (einschließlich eines unvollständigen Laufs oder zu vieler Anbieterfehler). Standardmäßig benötigt ein Lauf mindestens einen bewerteten Versuch und erlaubt höchstens eine Anbieterfehlerrate von 10 %; überschreiben Sie diese mit --min-scored und --max-error-rate.

# 6. Re-render, gate, compare
whichtool run … --format json --out run.json
whichtool report run.json --format markdown
whichtool report run.json --format html --out report.html
whichtool diff base-run.json head-run.json --max-accuracy-drop 0.05

diff weigert sich, Läufe zu subtrahieren, die ein anderes Modell, einen anderen Endpunkt, einen nicht-geheimen Anbieter- anforderungs-Fingerabdruck, eine andere Temperatur, einen anderen Seed, eine andere Wiederholungsanzahl, eine andere Permutationseinstellung oder einen anderen Aufgabensatz verwendet haben. Es gleicht Ergebnisse nach Aufgabe und Versuchsindex ab und verwendet dann einen exakten zweiseitigen gepaarten Vorzeichentest (p <= 0.05), um zu entscheiden, ob eine Bewegung unterscheidbar ist. Eine unterscheidbare Zunahme von unerwartetem Multi-Call-Verhalten ist eine Regression, selbst wenn sich die ersten Auswahlen nicht bewegt haben.

Befehle

whichtool <command> --help listet Flags auf. Hauptflags für run:

--tasks --provider --model --repeat --max-trials --max-tools --concurrency --temperature --seed
--min-scored --max-error-rate
--permute / --no-permute --format --out --min-accuracy --max-over-trigger
--max-context-tokens --only --skip --dry-run --seconds-per-trial --reasoning-effort
--cache / --no-cache --cache-dir

Formate: terminal, json, markdown, html, junit, badge.

Umgebung: Eine HTTP-Ziel-Anmeldeinformation benötigt sowohl WHICHTOOL_HTTP_AUTHORIZATION als auch den genauen erlaubten Ursprung in WHICHTOOL_HTTP_AUTHORIZATION_ORIGIN (z. B. https://mcp.example). Remote-Anmeldeinformationen erfordern HTTPS. Anbieterschlüssel stammen aus ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, TOGETHER_API_KEY und WHICHTOOL_PROVIDER_API_KEY für einen openai-compatible-Endpunkt. NO_COLOR / FORCE_COLOR werden berücksichtigt.

Anbieter: anthropic, ollama, openai, openai-chat, openrouter, together, vllm, jeder openai-compatible-Endpunkt und ein deterministisches mock. openai verwendet die OpenAI Responses API. Wählen Sie openai-chat explizit für OpenAI Chat Completions; die anderen OpenAI-kompatiblen Voreinstellungen verwenden weiterhin ihre Chat-Completions-Endpunkte.

anthropic spricht die Messages API und keinen Chat-Completions-Dialekt. Dieser Anbieter sendet keine Temperatur oder keinen Seed und zeichnet diese Fähigkeiten als nicht unterstützt auf, sodass seine Läufe sich auf --repeat und die Intervalle auf Versuchsebene stützen.

Konfiguration

import { defineConfig } from 'whichtool'

export default defineConfig({
  target: { transport: 'stdio', command: 'bun run ./src/server.ts' },
  tasks: './whichtool.tasks.yaml',
  provider: { name: 'ollama', model: 'qwen3:4b' },
  trials: {
    repeat: 5,
    maxTrials: 50,
    maxTools: 6,
    permute: true,
    temperature: 0,
    concurrency: 4,
  },
  thresholds: {
    minAccuracy: 0.9,
    maxOverTrigger: 0.05,
    maxContextTokens: 4000,
    maxErrorRate: 0.1,
    minScored: 1,
  },
  report: { formats: ['terminal', 'json'], out: './whichtool-report' },
})

whichtool.config.json funktioniert ebenfalls. API-Schlüssel sind niemals ein Konfigurationsfeld. Die normale CLI kann auch JavaScript- oder TypeScript-Konfiguration entdecken; der MCP-Server tut dies bewusst nicht, wie unten erläutert.

CI

- uses: mattagame/whichtool@v0.1.0
  with:
    target: ./tools.json
    tasks: ./whichtool.tasks.yaml
    provider: openai
    model: gpt-4.1-mini
    max-trials: '50'
    max-tools: '6'
    min-accuracy: '0.9'
    max-over-trigger: '0.05'

Das Versuchs-Caching in der Composite-Action ist standardmäßig deaktiviert, da ein Cache Prompts, Tool-Definitionen und Anbieterantworten enthalten kann. Setzen Sie cache: 'true' nur, wenn dieses Material nicht sensibel ist und die von GitHub gehostete Persistenz akzeptabel ist.

Die Action blockiert einen gemessenen Aufruf mit mehr als 6 Tools standardmäßig; max-tools kann die Grenze nur bis auf 1.000 erhöhen. Ihr max-trials-Budget gilt für jeden gemessenen Aufruf. Ein Vergleichs-Workflow, der sowohl die Head- als auch die Base-Revision misst, kann das Versuchsbudget daher einmal pro Lauf verwenden; mit dem Standardwert sind das höchstens 50 Versuche für Head und 50 für Base.

Lassen Sie provider weg, um nur den kostenlosen statischen Durchlauf auszuführen: inspect, plus tasks lint, wenn ein Aufgabensatz vorhanden ist. Ein vollständiger Workflow (einschließlich eines Basis-Branch-Vergleichs, der in die Job-Zusammenfassung geschrieben wird) befindet sich in examples/github-action.

Als MCP-Server:

{
  "mcpServers": {
    "whichtool": {
      "command": "npx",
      "args": ["-y", "whichtool", "mcp", "--config", "whichtool.config.json"]
    }
  }
}

Der MCP-Server ist bewusst durch seine Startargumente in seinen Fähigkeiten eingeschränkt. Er entdeckt oder führt keine JavaScript/TypeScript-Konfiguration automatisch aus: Übergeben Sie eine überprüfte JSON-Datei explizit mit --config. Tool-Aufrufe verwenden das konfigurierte Ziel und können es nicht durch einen beliebigen Pfad, eine URL oder einen Unterprozess ersetzen. Vom Agenten ausgewählte Aufgaben-/Berichtseingaben müssen im Arbeitsverzeichnis bleiben.

Der beabsichtigte Agenten-Workflow beginnt mit Auswertungsartefakten, die Sie bereits vorbereitet und überprüft haben: inspect_surface, validate_task_file, run_evaluation, dann diff_saved_results für gespeicherte Läufe. Die MCP-Oberfläche generiert oder mutiert keine Aufgabensätze. Sie stellt denselben Single-Turn-Routing-Benchmark bereit; sie ist kein Bewerter oder Ausführer für einen vollständigen Agenten-Workflow. run_evaluation kann immer einen Trockenlauf-Plan erstellen, aber keinen Anbieter kontaktieren, es sei denn, der Operator startet den Server mit --allow-paid-runs. Das operator-eigene Budget für echte Läufe beträgt standardmäßig 50 Gesamtversuche; nur das Start---max-trials-Flag oder trials.maxTrials in der überprüften Konfiguration kann es erhöhen, bis zum absoluten Maximum von 1.000. Der Agent kann dieses Budget nicht überschreiben. Dieselbe operator-eigene Regel gilt für den 6-Tool-Standardwert über das Start- --max-tools oder trials.maxTools, mit einem absoluten Maximum von 1.000. repeat und Parallelität haben ebenfalls Obergrenzen. Ein vollständiger Lauf gibt eine kompakte Zusammenfassung zurück. Fügen Sie --result-file ./latest-run.json hinzu, um den vollständigen Bericht außerhalb des Modellkontexts zu behalten. --allow-dynamic-targets existiert für isolierte Entwicklungssetups und sollte als unsicheres Opt-in behandelt werden. Anbieter-/Modellüberschreibungen sind ebenfalls nur konfigurationsbasiert, es sei denn, der Operator fügt --allow-provider-overrides hinzu. Persistentes Versuchs-Caching ist im MCP-Modus deaktiviert; der Operator muss --cache explizit hinzufügen, nachdem er entschieden hat, dass Prompts, Aufrufe und Antworten auf die Festplatte geschrieben werden dürfen.

Beispiele

Bei Reasoning-Modellen wie qwen3 kann ein einzelner Versuch zig Sekunden an Denk-Tokens dauern, die whichtool nie liest. Messen Sie einen Versuch und übergeben Sie dann --dry-run --seconds-per-trial. Seine Prompt-Token-Gesamtzahl bleibt eine Untergrenze, keine Preisschätzung; Ausgabe- und Reasoning-Tokens kommen hinzu.

Entwicklung

Bun ist die Toolchain; Node ist das Verteilungsziel. src/core/ ist portables TypeScript (keine Bun/Node-Builtins).

bun install
bun test
bun run typecheck
bun run lint
bun run build

docker run --rm -v "$PWD:/work" ghcr.io/mattagame/whichtool inspect ./tools.json

Patches willkommen: CONTRIBUTING.md listet die Einschränkungen auf, die Tests eher durchsetzen als Reviewer.

Design-Dokument: SPEC.md. Sicherheit: SECURITY.md. JSON-Vertrag: docs/report-schema.md. Änderungen: CHANGELOG.md.

Haftungsausschluss

Die Software wird ohne Gewährleistung bereitgestellt. Siehe LICENSE.md.

• run kostet Geld bei gehosteten Anbietern. Tool-Definitionen und Prompts werden an das von Ihnen konfigurierte Modell gesendet. Verwenden Sie zuerst --dry-run, aber behandeln Sie die darin angegebene Prompt-Token-Zahl als Untergrenze und nicht als Kostenschätzung. Ollama und andere lokale Endpunkte bleiben auf Ihrem Rechner.

• Tools auf dem Server unter Test werden niemals aufgerufen. stdio startet den von Ihnen übergebenen Befehl mit Ihren Rechten – behandeln Sie diesen Befehl als Code.

• Eigenständige Binärdateien werden noch nicht verteilt. Die Veröffentlichung bleibt deaktiviert, bis die Drittanbieter-Hinweise der eingebetteten Laufzeitumgebung geprüft wurden und neben jeder Binärdatei mitgeliefert werden können.

• Kein Sicherheitsscanner. Eine Oberfläche kann inspect bestehen und dennoch gefährlich sein. Details: SECURITY.md.

Lizenz

MIT — LICENSE.md.