Werkzeuge mit Claude nutzen: der Einstieg

TL;DR

Ein Werkzeug besteht aus Name, Beschreibung und JSON-Schema. Claude entscheidet, wann es aufgerufen wird — ausführen müssen Sie es selbst und das Ergebnis zurückgeben. Drei Fehler machen fast alle ersten Implementierungen, und alle drei sind still.

Die Werkzeugdefinition

werkzeuge = [{
    "name": "bestand_abfragen",
    "description": (
        "Gibt den verfügbaren Bestand eines Artikels in einem Werk zurück. "
        "Rufe dieses Werkzeug auf, wenn nach Verfügbarkeit, Lagerbestand oder "
        "Lieferfähigkeit eines konkreten Artikels gefragt wird. "
        "Nicht geeignet für Fragen nach Preisen oder Lieferterminen."
    ),
    "input_schema": {
        "type": "object",
        "properties": {
            "artikelnummer": {
                "type": "string",
                "description": "Die Artikelnummer, etwa 4711",
            },
            "werk": {
                "type": "string",
                "enum": ["W1", "W2", "W3"],
                "description": "Werkskennung",
            },
        },
        "required": ["artikelnummer", "werk"],
    },
}]

Die Beschreibung ist die einzige Information, die das Modell über das Werkzeug hat — sie entscheidet über die Trefferquote mehr als alles andere. Zwei Dinge gehören hinein, die häufig fehlen:

Wann es aufzurufen ist. Nicht nur, was es tut. "Rufe dieses Werkzeug auf, wenn nach Verfügbarkeit gefragt wird" wirkt messbar besser als "Gibt Bestand zurück".

Wann es nicht passt. Der Satz zur Abgrenzung reduziert Fehlaufrufe spürbar — gerade wenn mehrere ähnliche Werkzeuge zur Auswahl stehen.

Nutzen Sie enum überall, wo die Werte feststehen. Damit kann das Modell keine erfundene Werkskennung liefern.

Der einfache Weg: der Tool Runner

Das SDK übernimmt die Schleife, Sie schreiben nur die Funktion:

from anthropic import Anthropic, beta_tool

client = Anthropic()

@beta_tool
def bestand_abfragen(artikelnummer: str, werk: str) -> str:
    """Gibt den verfügbaren Bestand eines Artikels in einem Werk zurück.

    Rufe dieses Werkzeug auf, wenn nach Verfügbarkeit oder Lagerbestand
    eines konkreten Artikels gefragt wird.

    Args:
        artikelnummer: Die Artikelnummer, etwa 4711.
        werk: Werkskennung, eine von W1, W2, W3.
    """
    return f"{erp.bestand(artikelnummer, werk)} Stück verfügbar"

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=16000,
    tools=[bestand_abfragen],
    messages=[{"role": "user", "content": "Wie viele 4711 sind in Werk 2 da?"}],
)

for nachricht in runner:
    print(nachricht)

Das Schema entsteht aus Signatur und Docstring — Sie schreiben kein JSON. Für die meisten Anwendungen ist das der richtige Weg.

Der manuelle Weg

Wenn Sie die Schleife selbst führen wollen:

messages = [{"role": "user", "content": "Wie viele 4711 sind in Werk 2 da?"}]

while True:
    antwort = client.messages.create(
        model="claude-opus-5", max_tokens=16000,
        tools=werkzeuge, messages=messages,
    )

    if antwort.stop_reason == "end_turn":
        break

    # FEHLER 1 VERMEIDEN: vollständigen content anhängen, nicht nur den Text
    messages.append({"role": "assistant", "content": antwort.content})

    ergebnisse = []
    for block in antwort.content:
        if block.type == "tool_use":
            try:
                inhalt = werkzeug_ausfuehren(block.name, block.input)
                fehler = False
            except Exception as e:
                inhalt = f"Fehler: {e}"
                fehler = True
            ergebnisse.append({
                "type": "tool_result",
                "tool_use_id": block.id,      # muss zum Aufruf passen
                "content": inhalt,
                "is_error": fehler,
            })

    # FEHLER 2 VERMEIDEN: ALLE Ergebnisse in EINER Nachricht
    messages.append({"role": "user", "content": ergebnisse})

Die drei stillen Fehler

Fehler 1: Nur den Text anhängen. Wer antwort.content[0].text statt antwort.content an den Verlauf hängt, verliert die Werkzeugaufruf-Blöcke. Die nächste Anfrage ist dann strukturell ungültig, und die Fehlermeldung zeigt nicht auf die Ursache.

Fehler 2: Ergebnisse auf mehrere Nachrichten aufteilen. Claude kann mehrere Werkzeuge in einer Antwort aufrufen. Alle zugehörigen Ergebnisse gehören in eine Nutzernachricht. Wer sie aufteilt, gewöhnt dem Modell parallele Aufrufe ab — es ruft dann nur noch einzeln auf, wird langsamer, und niemand weiß warum.

Fehler 3: Ein fehlgeschlagenes Werkzeug weglassen. Für jeden tool_use-Block muss ein tool_result zurückkommen. Bei einem Fehler geben Sie ihn mit is_error: true und einer aussagekräftigen Meldung zurück — dann kann das Modell reagieren. Ein weggelassenes Ergebnis lässt die Anfrage scheitern.

Ein vierter, weniger häufiger: Werkzeugeingaben als Zeichenkette abgleichen. Die Serialisierung kann sich in der Zeichen-Maskierung unterscheiden. Greifen Sie immer auf das geparste block.input zu, nie auf eine serialisierte Form.

Die Auswahl steuern

tool_choice={"type": "auto"}                       # Claude entscheidet (Standard)
tool_choice={"type": "any"}                        # mindestens ein Werkzeug
tool_choice={"type": "tool", "name": "bestand_abfragen"}   # genau dieses
tool_choice={"type": "none"}                       # keines

Jede Variante nimmt zusätzlich "disable_parallel_tool_use": true, wenn höchstens ein Aufruf je Antwort erwünscht ist.

Wenn das Modell zu selten aufruft

Ein Verhalten, das beim Modellwechsel auffällt: Neuere Modelle greifen zurückhaltender zu Werkzeugen und beantworten mehr aus dem Kontext. Zwei Hebel:

Aufwandsstufe erhöhen. high oder xhigh zeigen deutlich mehr Werkzeugnutzung als medium oder low.

Auslösebedingung in die Beschreibung schreiben. Nicht in den Systemprompt, sondern in die description des Werkzeugs selbst — dort wirkt sie am stärksten.

Und ein Sonderfall, der Zeit kostet: Mit abgeschaltetem Denkmodus landet ein Werkzeugaufruf gelegentlich als reiner Text in der Antwort statt als strukturierter Aufruf. Der Durchlauf endet normal, der Aufruf läuft nie — ohne Fehler. Lassen Sie den Denkmodus an und steuern Sie über eine niedrigere Aufwandsstufe.

Häufig gestellte Fragen

Führt Claude Werkzeuge selbst aus?

Nein, bei selbst definierten Werkzeugen nicht. Claude liefert einen tool_use-Block mit Name und Parametern; die Ausführung und die Rückgabe des Ergebnisses als tool_result übernehmen Sie. Anders ist es bei serverseitigen Werkzeugen wie Web-Suche oder Code-Ausführung — die laufen bei Anthropic.

Warum ruft Claude mein Werkzeug nicht auf?

Meist wegen der Beschreibung. Schreiben Sie hinein, wann das Werkzeug aufzurufen ist, nicht nur was es tut — und ergänzen Sie einen Satz zur Abgrenzung gegenüber ähnlichen Werkzeugen. Zusätzlich hilft eine höhere Aufwandsstufe: high und xhigh zeigen deutlich mehr Werkzeugnutzung.

Muss ich alle Werkzeugergebnisse in einer Nachricht zurückgeben?

Ja. Claude kann mehrere Werkzeuge in einer Antwort aufrufen, und alle zugehörigen Ergebnisse gehören in eine einzige Nutzernachricht. Wer sie auf mehrere Nachrichten aufteilt, gewöhnt dem Modell parallele Aufrufe stillschweigend ab — es wird langsamer, ohne dass ein Fehler auftritt.

Wie gebe ich einen Werkzeugfehler zurück?

Als tool_result mit is_error: true und einer aussagekräftigen Meldung im Inhalt, etwa "Werk 'W9' existiert nicht. Gültige Werte: W1, W2, W3." Das Modell kann darauf reagieren und einen anderen Weg wählen. Ein weggelassenes Ergebnis lässt dagegen die gesamte Anfrage scheitern.

Brauche ich für Werkzeuge eine eigene Schleife?

In den meisten Fällen nicht. Der Tool Runner des SDK übernimmt die Schleife, erzeugt Schemata aus Funktionssignatur und Docstring und lässt Sie je Runde eingreifen — etwa für Freigaben oder Fehlerbehandlung. Eine eigene Schleife lohnt nur bei Ablauflogik, die der Runner nicht abbildet.

Der nächste Schritt

Schreiben Sie Ihr erstes Werkzeug eng: eine Aufgabe, Pflichtparameter, enum wo möglich, und eine Beschreibung, die die Auslösebedingung nennt. Breite Werkzeuge mit optionalen Parametern sind die häufigste Ursache für Fehlaufrufe. Beim Zuschnitt helfen wir gern.