Was ist Tool-Nutzung?
Deine bestehenden Workflows basieren auf vielen verschiedenen Technologien — Projektmanagement-Software, Datenbanken, Dateien. Claude kann diese Dinge nicht einfach selbst überprüfen. Stattdessen verlässt es sich auf Tools, die Claude Zugriff auf externe Daten und Aktionen geben.
Was ein Tool ist
Einfach ausgedrückt ist ein Tool eine Funktion, die du definierst und Claude zur Verfügung stellst. Du beschreibst, was sie tut und welche Eingaben sie benötigt, und Claude entscheidet, wann es sie aufruft.
Hier ist der entscheidende Punkt, den du verinnerlichen solltest: Claude führt das Tool nicht aus — dein Code tut das. Der Ablauf sieht so aus:
- Claude fordert einen Tool-Aufruf an.
- Dein Code führt die Funktion aus.
- Das Ergebnis geht zurück an Claude, und es macht weiter.
Wie Tools definiert werden
Tools sind JSON-Schemas mit drei Teilen: einem Namen, einer Beschreibung und einem Eingabeschema. Du übergibst sie Claude im Request-Body als tools-Array.
Die Beschreibung ist das, was Claude liest, um zu entscheiden, ob es das Tool aufruft. Wenn du eine vage Beschreibung schreibst, bekommst du eine schlechte Tool-Nutzung. Das ist der Hauptgrund, warum Agenten Fehlverhalten zeigen oder nicht auf die ihnen zur Verfügung stehenden Tools zugreifen. Sei spezifisch.
So sieht eine Tool-Definition aus:
{
"name": "lookup_building_code",
"description": "Look up a specific building code section by its identifier. Returns the full text of that code section.",
"input_schema": {
"type": "object",
"properties": {
"section": {
"type": "string",
"description": "The building code section to look up"
}
},
"required": ["section"]
}
}Was passiert also, wenn wir das verwenden? Angenommen, wir senden einem Agenten einen Compliance-Bericht. In der ersten Runde antwortet Claude mit stop_reason: "tool_use" — das ist unser Signal. So sieht diese Antwort aus:

Unsere Schleife ruft lookup_building_code mit dem von Claude angeforderten Parameter auf und gibt das Ergebnis dann als Tool-Ergebnis zurück — eine Benutzernachricht, die einen tool_result-Block enthält, der an die ID des Tool-Aufrufs gebunden ist:

Und Claude macht weiter. An diesem Punkt können wir weiterhin Tools aufrufen und Ergebnisse an Claude zurückgeben, bis es hat, was es braucht.
Mehrere Tools: Claude auswählen lassen
Ein Tool ist nützlich, aber der interessante Teil ist, Claude mehrere Tools zu geben und zu beobachten, welches es auswählt und in welcher Reihenfolge.
Stell dir folgendes Szenario vor: Du packst für eine dreitägige Reise nach Denver und möchtest sowohl das heutige Wetter als auch die Vorhersage für die nächsten Tage. Also deklarieren wir zwei Tools statt eines:
const tools = [
{
name: "get_weather",
description: "Get today's current weather for a city.",
input_schema: {
type: "object",
properties: {
city: { type: "string", description: "The city to check" }
},
required: ["city"]
}
},
{
name: "get_forecast",
description: "Get the weather forecast for the next few days for a city.",
input_schema: {
type: "object",
properties: {
city: { type: "string", description: "The city to check" }
},
required: ["city"]
}
}
];Die Schleife ist identisch mit den Agentenschleifen, die wir bereits gesehen haben. Das einzig Neue ist eine runTool-Funktion, die anhand des Tool-Namens per switch-Anweisung verzweigt — dieser Codeblock ist genau der Ort, an dem dein Code tatsächlich ausgeführt wird. Sie fügt außerdem zwei fest codierte Lookups und die Eröffnungsnachricht hinzu, damit du sie ausführen kannst, und sie verwendet den client aus „Dein erster API-Aufruf“:
// Zwei hartcodierte Lookups. In einer echten App würden diese einen Wetterdienst aufrufen.
const getWeather = (city) => `${city} today: 34F, snow flurries`;
const getForecast = (city) => `${city}, next three days: 38F, 45F, and 52F, sunny`;
const messages = [
{
role: "user",
content:
"I'm packing for a three-day trip to Denver. What's the weather today and over the next few days?",
},
];
function runTool(name, input) {
switch (name) {
case "get_weather":
return getWeather(input.city);
case "get_forecast":
return getForecast(input.city);
}
}
while (true) {
const response = await client.messages.create({
model: "claude-sonnet-5",
max_tokens: 1024,
messages,
tools,
});
if (response.stop_reason !== "tool_use") {
// Claude ist fertig — das ist die finale Antwort
for (const block of response.content) {
if (block.type === "text") console.log(block.text);
}
break;
}
messages.push({ role: "assistant", content: response.content });
const toolResults = response.content
.filter((block) => block.type === "tool_use")
.map((block) => ({
type: "tool_result",
tool_use_id: block.id,
content: runTool(block.name, block.input),
}));
messages.push({ role: "user", content: toolResults });
}Und das ist das ganze Muster. Möchtest du ein drittes Tool? Füge es dem Array hinzu, füge einen case zum switch hinzu, und fertig.
Führe das aus, und du wirst sehen, dass Claude get_weather und dann get_forecast aufruft — manchmal in derselben Runde, manchmal nacheinander. Dann antwortet es: Schichten packen, heute Schneeschauer erwarten, im Laufe der Woche wird es wärmer.
Beachte jetzt, wie Claude ausgewählt hat. Es hat die Beschreibungen gelesen, deinen Prompt auf „das heutige Wetter“ und „die nächsten Tage“ abgebildet und für jedes das passende Tool ausgewählt. Deshalb sind deine Tool-Beschreibungen wirklich wichtig.
Der Tool-Runner: Boilerplate überspringen
Wahrscheinlich sind dir bei dem, was wir gerade geschrieben haben, schon zwei Warnsignale aufgefallen:
- Das ist eine Menge Code für zwei einfache Lookups.
- In einer echten Codebasis möchtest du nicht für jede Funktion, die du hast, JSON-Schemas von Hand schreiben. Das ist, als würdest du deinen Code zweimal schreiben.
Hier kommt der Tool-Runner ins Spiel. Er wird in Beta in den Claude SDKs ausgeliefert: TypeScript, Python, Ruby, C#, Go, Java und PHP. Du definierst jedes Tool einmal, und der Runner übernimmt intern die gesamte Tool-Use-/Tool-Result-Schleife.
In TypeScript beschreibt der empfohlene Helfer des Runners, betaZodTool(), jedes Tool mit einem kurzen Schema, das in Zod geschrieben ist, einer TypeScript-Bibliothek zum Deklarieren und Validieren der Form von Daten. Der Helfer benötigt Zod 3.25.0 oder höher, was eine frische Installation dir liefert:
npm install zodDein Code schrumpft auf: das Tool beschreiben, den Prompt senden, auf das Ergebnis warten. Hier ist dieselbe Zwei-Tool-Wetterdemo, verdrahtet durch den Tool-Runner:
import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod";
import { z } from "zod";
// Verpacke die gleichen zwei Lookups, die wir manuell ausgeführt haben, jeweils mit einem kurzen Zod-Schema
const weatherTool = betaZodTool({
name: "get_weather",
description: "Get today's current weather for a city.",
inputSchema: z.object({
city: z.string().describe("The city to check"),
}),
run: async ({ city }) => getWeather(city),
});
const forecastTool = betaZodTool({
name: "get_forecast",
description: "Get the weather forecast for the next few days for a city.",
inputSchema: z.object({
city: z.string().describe("The city to check"),
}),
run: async ({ city }) => getForecast(city),
});
const runner = client.beta.messages.toolRunner({
model: "claude-sonnet-5",
max_tokens: 1024,
messages: [
{
role: "user",
content:
"I'm packing for a three-day trip to Denver. What's the weather today and over the next few days?",
},
],
tools: [weatherTool, forecastTool],
});
// Warte auf den Runner, um die finale Nachricht zu erhalten, nachdem sich das Tool-Hin-und-Her gelegt hat
const finalMessage = await runner;
for (const block of finalMessage.content) {
if (block.type === "text") console.log(block.text);
}Gleiches Szenario, ein Bruchteil des Codes:
- Keine while-Schleife, kein Switch für den Stop-Grund, kein manuelles Zurückschieben von Tool-Ergebnissen in Nachrichten — der Runner übernimmt das alles.
- Keine handgeschriebenen JSON-Schemas, nur ein kurzes Zod-Schema pro Tool, das auch die von Claude gesendete Eingabe validiert.
- Jede
run-Funktion umschließt denselben Lookup, den wir eben von Hand ausgeführt haben. - Das Abwarten des Runners gibt die finale Assistant-Nachricht zurück, sobald sich alles erledigt hat.
Führe es aus, und du erhältst dieselbe Antwort.
Echte Tools umschließen deinen bestehenden Code
In der Praxis wären deine Tools keine fest codierten Wetterdaten. Sie würden tatsächliche Funktionen umschließen, die du bereits in deiner Anwendung hast.
Nimm einen Compliance-Review-Agenten: Seine Tools sind dünne Wrapper um lookup_building_code- und search_building_code-Funktionen, die bereits in der Codebasis existieren. Mit dem Tool-Runner umschließt du jede dieser Funktionen in einer kurzen Tool-Definition mit einem eigenen Zod-Schema, und der Agent zitiert in jedem Befund, den er verfasst, bestimmte Code-Abschnitte:

Zusammenfassung
- Tools geben Claude Zugriff auf deine Systeme. Ein Tool ist eine Funktion, die du definierst und zur Verfügung stellst; Claude entscheidet, wann es sie aufruft, und dein Code führt sie aus.
- Tools sind JSON-Schemas mit einem Namen, einer Beschreibung und einem Eingabeschema, die im Request als
tools-Array übergeben werden. - Schreibe spezifische Beschreibungen. Vage Beschreibungen sind der Hauptgrund, warum Agenten Fehlverhalten zeigen.
stop_reason: "tool_use"ist dein Signal, das Tool auszuführen und das Ergebnis als Tool-Ergebnis zurückzugeben.- Bei mehreren Tools verzweige anhand des Tool-Namens. Ein Tool hinzuzufügen bedeutet, es zum Array hinzuzufügen und einen case hinzuzufügen.
- Der Tool-Runner des SDK (in Beta über alle Claude SDKs verfügbar) übernimmt die gesamte Schleife, und in TypeScript ist jedes Tool eine kurze Definition mit einem Zod-Schema. Oder du führst die Schleife selbst aus.
- Du führst aus, oder du delegierst die Schleife. Am äußersten Ende dieses Spektrums delegieren managed agents den gesamten Agenten an Anthropic.