Wann ruft ein LLM ein Tool auf: tool_choice, CoT und Halluzinationen

Der Entwickler hat die Tool-Nutzung konfiguriert, mit Testanfragen überprüft – alles funktioniert. In der Produktion antwortet das Modell plötzlich ohne Tool-Aufruf, selbstbewusst und kohärent, aber mit Daten, die ein Jahr alt sind. Keine Fehler in den Logs. Einfach eine falsche Antwort. Spoiler: Das Modell ist nicht „kaputtgegangen“ – es hat eine rationale Entscheidung getroffen, nicht zu suchen, weil es sich für ausreichend informiert hielt. Und genau das ist der gefährlichste Fehlermodus.

📚 Inhalt des Artikels

• 📌 Drei Modi von tool_choice: auto, required, none
• 📌 Wie die Beschreibung des Tools die Modellentscheidung beeinflusst
• 📌 Chain-of-Thought im Inneren: Wie das Modell den Kontext analysiert
• 📌 Wo die Entscheidung fehlschlägt: Selbstvertrauen → Keine Suche → Halluzination
• 📌 Parallele Aufrufe: Wenn das Modell mehrere Tools gleichzeitig aufruft
• 💼 Praxis: Wie man eine Beschreibung schreibt, damit das Modell das Tool aufruft, wenn es nötig ist
• ❓ Häufig gestellte Fragen (FAQ)
• ✅ Schlussfolgerungen

Drei Modi von tool_choice: auto, required, none – und wann welcher zu verwenden ist

Der Parameter tool_choice ist nicht nur eine API-Einstellung. Es ist eine architektonische Entscheidung darüber, wer den Ablauf kontrolliert: das Modell oder Ihr Code. Die Wahl des Modus bestimmt, wo Probleme auftreten und wo man sie suchen muss.

auto: Das Modell als Richter

Der Standardmodus, wenn Tools übergeben werden. Das Modell entscheidet selbst: mit eigenem Wissen textlich antworten oder ein Tool aufrufen. Dies ist der flexibelste Modus – und der unvorhersehbarste.

# auto – das Modell entscheidet selbst
response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "auto"},   # kann weggelassen werden – das ist der Standard
    messages=[{"role": "user", "content": query}]
)

# Überprüfen, was das Modell entschieden hat
if response.stop_reason == "tool_use":
    # das Modell hat ein Tool aufgerufen
    tool_block = next(b for b in response.content if b.type == "tool_use")
    print(f"Tool: {tool_block.name}, Args: {tool_block.input}")
elif response.stop_reason == "end_turn":
    # das Modell hat ohne Suche geantwortet – das kann normal sein oder ein Problem
    text = next(b for b in response.content if b.type == "text")
    print(f"Direkte Antwort (kein Tool): {text.text[:100]}")

Das Protokollieren von stop_reason ist eine obligatorische Praxis in der Produktion. Dies ist der einzige Weg zu verstehen, ob das Modell nach Informationen gesucht hat oder mit eigenem Wissen geantwortet hat.

required / any: Erzwingen eines Aufrufs

Das Modell ist verpflichtet, mindestens ein Tool aufzurufen, unabhängig von der Anfrage. OpenAI nennt dies required, Anthropic – any.

# Anthropic: Erzwingen des Aufrufs eines beliebigen Tools
tool_choice={"type": "any"}

# Anthropic: Erzwingen des Aufrufs eines bestimmten Tools
tool_choice={"type": "tool", "name": "search_documents"}

# OpenAI-kompatible Syntax
tool_choice="required"

Wann gerechtfertigt: Structured Output, bei dem die Antwort immer über ein Tool erfolgen muss, obligatorische Protokollierung jeder Anfrage an ein externes System, deterministischer Pipeline, bei der der Abruf ein obligatorischer Schritt ist.

Wann schädlich: Konversationsmodus, bei dem der Benutzer nach „Hallo“ oder „Danke“ fragen kann. Das Modell wird trotzdem einen Tool-Aufruf formulieren, Ihr Code wird Token und Zeit für einen unnötigen Abruf verschwenden.

Kritische Einschränkung von Anthropic (Stand 2025): any und das erzwungene Aufrufen eines bestimmten Tools sind nicht kompatibel mit Extended Thinking. Wenn Thinking aktiviert ist, sind nur auto und none verfügbar. Der Versuch, any mit Thinking zu verwenden, gibt einen HTTP 400 zurück. Aktueller Status – docs.anthropic.com.

none: Verbieten von Aufrufen

Das Modell ruft kein Tool auf, es generiert nur Text. Nützlich für den letzten Schritt nach Erhalt aller Ergebnisse – wenn eine Antwort aus dem bereits gesammelten Kontext ohne zusätzliche Anfragen synthetisiert werden muss.

# Finale synthetisierende Antwort nach Datensammlung
final_response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=2048,
    tools=tools,                      # Tools werden trotzdem übergeben (API-Anforderung)
    tool_choice={"type": "none"},     # aber ihr Aufruf wird verboten
    messages=[
        *conversation_history,
        {"role": "user", "content": "Formuliere nun den Abschlussbericht basierend auf den gesammelten Daten."}
    ]
)

Wichtiger Hinweis: Wenn in messages tool_result-Blöcke vorhanden sind, müssen die Tools in der Anfrage trotzdem übergeben werden – andernfalls gibt die API einen Validierungsfehler zurück.

⚠️ Fallstrick #1: Die Illusion der Kontrolle durch tool_choice

tool_choice: auto bedeutet nicht, dass das Modell sucht, wenn es nötig ist. Es bedeutet, dass das Modell sucht, wenn es es für notwendig hält. Wenn Ihre Aufgabe bei jeder Anfrage aktuelle Daten erfordert – auto reicht nicht aus. Verwenden Sie entweder required oder gestalten Sie die Beschreibung so, dass das Modell die Suche für Ihre Anfragetypen immer für notwendig hält.

Wie die Beschreibung des Tools die Modellentscheidung beeinflusst: schlechte Beschreibung = Modell ruft kein Tool auf

Die Beschreibung ist keine Dokumentation für den Entwickler. Es ist Teil des Prompts, den das Modell sieht. Durch sie „versteht“ das Modell, was das Tool tut und wann es sich lohnt, es aufzurufen.

APXML (2025) beschreibt es so: Das Modell vergleicht die Absicht der Anfrage mit den Beschreibungen der verfügbaren Tools, wie ein Mensch eine Aufgabe mit den verfügbaren Werkzeugen in einer Kiste vergleicht. Wenn ein Hammer als „Gegenstand für physischen Einfluss“ beschriftet ist – kann es sein, dass der Mensch ihn nicht zum Nageln nimmt.

Offizielle OpenAI-Dokumentation empfiehlt: Schreiben Sie klare und detaillierte Funktionsnamen, Parameterbeschreibungen und Anweisungen. Beschreiben Sie explizit den Zweck der Funktion und jedes Parameters, und verwenden Sie einen System-Prompt, um zu erklären, wann (und wann nicht) jede Funktion verwendet werden soll.

Vergleich: schlechte vs. gute Beschreibung – Praxisbeispiel

Einer unserer Kunden hatte ein Problem: Das Modell folgte den Anweisungen schlecht und rief die Suche unregelmäßig auf. Ein Teil der Anfragen zu Preisen und Vertragsbedingungen lief ohne Abruf – das Modell antwortete selbstbewusst aus eigenem Wissen, aber veraltet. Als wir die Ursache analysierten, stellten wir fest, dass die Beschreibung des Tools minimal war. Nachdem wir die description mit Trigger-Szenarien neu geschrieben hatten, stabilisierte sich das Modellverhalten.

# ❌ WAR SO: minimale Beschreibung – das Modell rief das Tool oft nicht auf
{
    "name": "search_docs",
    "description": "Sucht Dokumente",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {"type": "string"}
        },
        "required": ["query"]
    }
}

# ✅ IST JETZT: ausführliche Beschreibung mit Triggern – das Modell versteht wann und wozu
{
    "name": "search_knowledge_base",
    "description": """Sucht aktuelle Informationen in der unternehmensinternen Wissensdatenbank.

    VERWENDE dieses Tool, wenn:
    - Die Anfrage betrifft Vertragsbedingungen, Preise, Vorschriften oder interne Verfahren
    - Aktuelle Informationen benötigt werden, die sich seit Ihrem Training geändert haben könnten
    - Spezifische Details zu einem bestimmten Kunden, Produkt oder Projekt abgefragt werden

    NICHT verwenden für:
    - Allgemeine Fragen zu Technologien oder allgemein bekannte Fakten
    - Mathematische Berechnungen
    - Formatieren oder Bearbeiten von Text""",

    "input_schema": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "Suchanfrage in natürlicher Sprache. Formuliere sie als Frage oder Schlüsselbegriffe."
            },
            "top_k": {
                "type": "integer",
                "description": "Anzahl der zurückzugebenden Fragmente. Standardmäßig 5. Erhöhe auf 10 für komplexe Vergleichsanfragen."
            }
        },
        "required": ["query"]
    }
}

Der Hauptunterschied: Eine gute Beschreibung enthält Trigger-Szenarien – eine explizite Liste von Situationen, in denen das Tool benötigt wird. Das Modell verwendet diese Liste als Kriterium in seiner internen Entscheidung.

Wichtig, wenn Sie Ollama mit einem lokalen Modell verwenden: Schwächere Modelle (7B–13B) folgen möglicherweise auch einer detaillierten Beschreibung nicht stabil – das ist eine Einschränkung des Modells, nicht der Beschreibung. In unserem Produktions-Stack verwenden wir AskYourDocs über OpenRouter mit deepseek/deepseek-chat als Standardmodell (${SPRING_AI_OPENAI_CHAT_MODEL:deepseek/deepseek-chat}) – und es gibt keine Probleme mit der Ausführung der Beschreibung auf dieser Ebene.

Für Ollama in der Entwicklungs-/Staging-Umgebung empfehlen wir, die Trigger-Anweisungen zusätzlich zu duplizieren im System-Prompt – dies erhöht die Stabilität bei schwächeren Modellen. Mehr über die Konfiguration von Ollama in einer Produktionskonfiguration: RAG mit Ollama: Wie man KI beibringt, anhand Ihrer Dokumente zu antworten .

Einfluss der Beschreibung auf die Wahl zwischen mehreren Tools

Wenn ein System mehrere Tools mit ähnlicher Funktionalität hat, wird die Qualität der Beschreibung noch kritischer. APXML betont: vage oder überlappende Beschreibungen zwingen das Modell entweder, das falsche Tool zu wählen, oder gar keines.

# Problem: Zwei ähnliche Tools mit unklaren Beschreibungen
tools = [
    {"name": "search_contracts", "description": "Sucht Verträge"},
    {"name": "search_documents", "description": "Sucht Dokumente"}
]
# Das Modell kennt den Unterschied nicht – die Wahl ist unvorhersehbar

# Lösung: Klare Abgrenzung der Verantwortungsbereiche
tools = [
    {
        "name": "search_contracts",
        "description": "Sucht NUR unterzeichnete Rechtsverträge und deren Anhänge. "
                       "Verwenden Sie es für Anfragen zu Bedingungen, Fristen, Verpflichtungen der Parteien."
    },
    {
        "name": "search_documents",
        "description": "Sucht interne Vorschriften, Anleitungen, technische Dokumentationen und Berichte. "
                       "Enthält KEINE Rechtsverträge."
    }
]

⚠️ Fallstrick #2: Mehr Tools = Mehr Wahlfehler

Laurent Kubaski (2025) stellt fest: Die meisten Anbieter veröffentlichen die maximale Anzahl von Tools, die das Modell technisch unterstützt, aber sie sagen nicht, dass in der Praxis mit zunehmender Anzahl von Tools die Wahrscheinlichkeit einer falschen Wahl steigt. Nach 10-15 Tools nimmt die Qualität der Auswahl merklich ab. Nach 50+ – ist ein Tool-RAG erforderlich (detailliert in TU-6).

Chain-of-Thought im Inneren: Wie das Modell den Kontext analysiert und eine Entscheidung trifft

Die Entscheidung für einen Tool-Aufruf ist kein Ergebnis einfacher Mustererkennung. Im Inneren findet ein Prozess statt, der dem Chain-of-Thought-Reasoning ähnelt, bei dem das Modell mehrere Faktoren sequenziell abwägt, bevor es eine Antwort zurückgibt.

Raina (2025) beschreibt dies aus der Perspektive neuronaler Schichten: Eingabe-Embedding-Schichten wandeln die Anfrage und die Tool-Beschreibungen in numerische Vektoren um – wie Text zu einem Vektor wird und warum semantisch ähnliche Anfragen in denselben Bereich des Raumes fallen, lesen Sie in Embeddings in einfachen Worten: Wie KI Sinn versteht, nicht nur Wörter . Mittlere Schichten führen abstraktes Denken und Tool-Auswahl-Logik durch, und wie die Suche anhand dieser Vektoren das relevanteste Tool oder Fragment findet – detailliert in Vektorsuche für Anfänger: Wie RAG die benötigten Informationen findet . Ausgabe-Schichten generieren die endgültige Entscheidung – Text oder Tool-Aufruf.

Interner Entscheidungsprozess (vereinfachtes Modell)

# Was intern im Modell bei tool_choice: auto passiert (konzeptionell):

# 1. Analyse der Absicht der Anfrage
intent = analyze_query(user_message)
# → "Anfrage zu den Bedingungen der Vertragsauflösung"

# 2. Bewertung des eigenen Wissens
confidence_in_own_knowledge = estimate_confidence(intent)
# → "Es gibt allgemeines Wissen über Verträge, aber nicht über den spezifischen Vertrag dieses Kunden"

# 3. Vergleich mit verfügbaren Tools
tool_relevance = match_intent_to_tools(intent, tool_descriptions)
# → search_knowledge_base: hohe Relevanz (Trigger-Szenario: "Vertragsbedingungen")

# 4. Entscheidung
if tool_relevance > threshold AND confidence_in_own_knowledge < threshold:
    return tool_call(name="search_knowledge_base", args={...})
else:
    return text_response(...)

Der entscheidende Punkt: Das Modell prüft nicht nur, ob ein relevantes Tool vorhanden ist. Es bewertet auch, ob eigenes Wissen ausreicht. Wenn das Modell sich für sachkundig hält – kann es eine Textantwort wählen auch wenn ein relevantes Tool vorhanden ist.

Wie das Modell lernt zu entscheiden, wann es suchen soll

Die Fähigkeit zur richtigen Entscheidung ist das Ergebnis von Fine-Tuning auf synthetischen Beispielen. Simplicity is SOTA (2025) beschreibt den Ansatz: Anbieter generieren Tausende von Beispielen Anfrage → CoT-Reasoning-Trace → Tool-Aufruf, bei denen das Modell lernt, nicht nur eine Funktion aufzurufen, sondern zu begründen, warum. Ein Beispiel für einen Reasoning-Trace sieht so aus:

# Interner CoT-Reasoning-Trace (wie er während des Trainings gebildet wird):
"""
Anfrage: "Welche Bedingungen gelten für die vorzeitige Kündigung unseres Vertrags?"

Analyse: Die Anfrage bezieht sich auf einen spezifischen Vertrag ("unseren") –
das bedeutet, dass spezifische Informationen benötigt werden, die nicht in meinem allgemeinen Wissen vorhanden sind.
Das verfügbare Tool search_knowledge_base beschreibt die Suche in der Unternehmensdatenbank
mit dem Trigger-Szenario "Vertragsbedingungen". Dies ist eine exakte Übereinstimmung.
Selbstvertrauen: niedrig (Spezifität des spezifischen Vertrags).
Entscheidung: search_knowledge_base aufrufen.
"""
→ tool_call("search_knowledge_base", {"query": "Bedingungen für vorzeitige Vertragsauflösung"})

Deshalb zeigen Reasoning-fähige Varianten von Modellen (Claude mit Extended Thinking, o-Serie von OpenAI) bessere Ergebnisse in komplexen Tool-Use-Szenarien – WildToolBench (2026) bestätigt: Reasoning-fähige Modelle übertreffen nicht-reasoning Varianten stabil bei Aufgaben, die eine korrekte Orchestrierung sequenzieller Tool-Aufrufe erfordern.

Einfluss des System-Prompts auf die Entscheidung

Der System-Prompt ist ein mächtiges Werkzeug zur Steuerung der Modellentscheidung. Wenn dort explizit angegeben ist, wann gesucht werden soll, folgt das Modell dieser Anweisung auch bei tool_choice: auto:

Die Kombination aus einer hochwertigen description + einer klaren Anweisung im System-Prompt erhöht die Zuverlässigkeit der Modellentscheidungen erheblich im Vergleich zu jedem Ansatz einzeln.

Wo die Lösung bricht: Das Modell ist zuversichtlich, aber die Antwort ist veraltet → sucht nicht → halluziniert

Dies ist der gefährlichste Fehlermodus in Systemen mit Tool-Nutzung. Kein Codefehler, kein leeres Ergebnis – sondern eine zuversichtliche, kohärente, grammatikalisch korrekte Antwort, die veraltet oder falsch ist.

Mechanik der „stillen“ Halluzination

# Szenario: Das Modell verfügt über parametrisches Wissen über das Produkt,
# aber die Preise haben sich vor 3 Monaten geändert.

user: "Was ist der Preis für den Enterprise-Plan?"

# Interner Prozess:
# - Das Modell sieht den Tool-Aufruf search_pricing
# - Es schätzt sein eigenes Wissen ein: "Ich weiß etwas über den Enterprise-Plan, er kostete 500 $/Monat"
# - confidence: hoch → es wird beschlossen, ohne Suche zu antworten

assistant: "Der Enterprise-Plan kostet 500 $ pro Monat und beinhaltet..."
# stop_reason: "end_turn"  ← kein tool_use

# Tatsächlicher Preis: 650 $/Monat nach einer Preiserhöhung vor 3 Monaten
# Ergebnis: Der Kunde hat einen falschen Preis erhalten, nichts in den Protokollen signalisiert ein Problem

OpenAI (2025) erklärt, warum dies geschieht: Standardtraining belohnt zuversichtliche Antworten, nicht die Anerkennung von Unsicherheit. Das Modell ist darauf trainiert zu antworten, nicht sich zurückzuhalten. Daher neigen selbst fortschrittliche Modelle dazu, zuversichtlich zu antworten, wo sie frische Daten abfragen sollten.

Überblick über Halluzinationen in LLMs (2026) unterscheidet einen separaten Typ: temporal misalignment — das Modell generiert eine Antwort, die zum Zeitpunkt des Trainings korrekt war, aber zum Zeitpunkt der Anfrage veraltet ist. Dies ist besonders kritisch für Preise, Vorschriften, Vertragsbedingungen, Personaländerungen.

Arten von Situationen, in denen dies gefährlich ist

Wie man ein Problem erkennt, bevor es zu einem Vorfall wird

import anthropic

def safe_query(client, query, tools, require_search_keywords=None):
    """
    Anfrage mit Kontrolle, ob das Modell die Suche verwendet hat.
    require_search_keywords: Liste von Wörtern, die eine obligatorische Suche erfordern
    """
    response = client.messages.create(
        model="claude-opus-4-6",
        max_tokens=1024,
        tools=tools,
        messages=[{"role": "user", "content": query}]
    )

    used_tool = response.stop_reason == "tool_use"

    # Überprüfen, ob die Anfrage eine Suche erforderte
    if require_search_keywords:
        needs_search = any(kw in query.lower() for kw in require_search_keywords)
        if needs_search and not used_tool:
            # Protokollieren einer verdächtigen Antwort ohne Suche
            log_warning(f"Query requires search but model answered directly: {query[:100]}")
            # Optional: Erzwingen einer erneuten Anfrage mit erforderlich
            return retry_with_required(client, query, tools)

    return response

# Verwendung
response = safe_query(
    client, query, tools,
    require_search_keywords=["ціна", "вартість", "договір", "умови", "регламент"]
)

⚠️ Fallstrick #3: Zuversichtlicher Ton = Verdacht, kein Vertrauen

Je zuversichtlicher das Modell auf eine Anfrage antwortet, bei der aktuelle Informationen erwartet werden – desto mehr Gründe gibt es zu prüfen, ob es überhaupt gesucht hat. Eine unsichere Antwort mit „Ich bin mir nicht sicher“ ist oft zuverlässiger als eine zuversichtliche Antwort ohne Suche. In der Produktion: Protokollieren Sie immer stop_reason. Eine Antwort mit end_turn ohne vorheriges tool_use bei einer „sensiblen“ Anfrage ist ein Grund zur Überprüfung.

Parallele Tool-Aufrufe: Wenn das Modell mehrere Tools gleichzeitig aufruft

Moderne Modelle unterstützen parallele Tool-Aufrufe – mehrere Aufrufe in einem Zug für unabhängige Anfragen. Dies ist eine leistungsstarke Funktion, die eine korrekte Verarbeitung erfordert.

Wann das Modell parallele Aufrufe generiert

Das Modell beschließt, parallele Aufrufe zu tätigen, wenn:

• Die Anfrage mehrere Entitäten explizit vergleicht („vergleiche Verträge A und B“)
• Daten aus mehreren unabhängigen Quellen gleichzeitig benötigt werden
• Teilanfragen voneinander unabhängig sind und parallel ausgeführt werden können

# Anfrage: "Vergleiche die Vertragsbedingungen mit den Kunden Alpha und Beta"
# Das Modell gibt zwei parallele Aufrufe in einer Antwort zurück:

{
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01A",
      "name": "search_knowledge_base",
      "input": {"query": "Vertragsbedingungen Kunde Alpha", "top_k": 5}
    },
    {
      "type": "tool_use",
      "id": "toolu_01B",
      "name": "search_knowledge_base",
      "input": {"query": "Vertragsbedingungen Kunde Beta", "top_k": 5}
    }
  ],
  "stop_reason": "tool_use"
}

Korrekte Verarbeitung paralleler Aufrufe

import anthropic
import json
from concurrent.futures import ThreadPoolExecutor

def handle_parallel_tool_calls(response, tools_map):
    """
    Verarbeitet parallele Tool-Aufrufe und gibt Ergebnisse für alle zurück.
    tools_map: dict {tool_name: callable}
    """
    tool_blocks = [b for b in response.content if b.type == "tool_use"]

    # Führt alle Aufrufe aus – kann parallel erfolgen, wenn sie unabhängig sind
    def execute_tool(block):
        fn = tools_map.get(block.name)
        if not fn:
            return {"tool_use_id": block.id, "content": f"Tool {block.name} not found", "is_error": True}
        try:
            result = fn(**block.input)
            return {
                "type": "tool_result",
                "tool_use_id": block.id,   # ← kritisch: id aus dem tool_use-Block
                "content": json.dumps(result, ensure_ascii=False)
            }
        except Exception as e:
            return {
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": str(e),
                "is_error": True            # ← Fehler explizit kennzeichnen
            }

    with ThreadPoolExecutor() as executor:
        results = list(executor.map(execute_tool, tool_blocks))

    return results

# Zweite Anfrage mit den Ergebnissen ALLER parallelen Aufrufe
tool_results = handle_parallel_tool_calls(response, {
    "search_knowledge_base": search_knowledge_base
})

follow_up = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=2048,
    tools=tools,
    messages=[
        {"role": "user", "content": original_query},
        {"role": "assistant", "content": response.content},
        {"role": "user", "content": tool_results}  # ← alle Ergebnisse zusammen
    ]
)

Self-conditioning: Ein verstecktes Problem langer Sitzungen

WildToolBench (2026) hat einen wichtigen Effekt aufgedeckt: Modelle zeigen self-conditioning — wenn das Modell in der aktuellen Sitzung kürzlich parallele Aufrufe verwendet hat, neigt es dazu, diese zu wiederholen, auch wenn dies nicht ratsam ist. Grund: Der große Kontext der vorherigen Nachrichten „verstopft“ die Aufmerksamkeit des Modells auf die aktuelle Anfrage.

Praktische Konsequenz: In langen Agentensitzungen kann sich das Verhalten des Modells verschieben. Wenn Sie sehen, dass das Modell in späteren Sitzungsnachrichten unnötige parallele Aufrufe tätigt – das ist kein Zufall, sondern ein akkumulierter Kontext-Bias. Lösung: Fassen Sie den Gesprächsverlauf regelmäßig zusammen und komprimieren Sie ihn, oder teilen Sie lange Agentensitzungen in unabhängige auf.

⚠️ Fallstrick #4: Nicht geschlossene parallele Aufrufe

Wenn die Antwort des Modells zwei Tool-Call-Blöcke enthält, Sie aber nur für einen einen tool_result zurückgegeben haben – gibt die nächste API-Anfrage einen Validierungsfehler zurück. Jede tool_use_id muss einen entsprechenden tool_result haben. Wenn einer der Aufrufe mit einem Fehler beendet wurde – übergeben Sie is_error: true, aber lassen Sie die Antwort für diese ID nicht aus.

Praxis: Wie man eine Beschreibung schreibt, damit das Modell bei Bedarf ein Tool aufruft

Statsig (2025) formuliert es klar: Die Dokumentation eines Tools sollte wie ein Vertrag gelesen werden – eine Zweckangabe, einige konkrete Beispiele und Argumenttypen, die keinen Raum für Rätsel lassen.

Vorlage für eine effektive Beschreibung

VORLAGE:
"""[Was das Tool tut – ein Satz, konkret]

VERWENDEN, wenn:
- [Trigger-Szenario 1]
- [Trigger-Szenario 2]
- [Relevanzkriterium: "wenn frische/aktuelle Informationen benötigt werden"]

NICHT verwenden für:
- [Anti-Anwendungsfall 1]
- [Anti-Anwendungsfall 2]

Beispiele für Anfragen, die dieses Tool auslösen sollten:
- "[Konkretes Beispiel 1]"
- "[Konkretes Beispiel 2]"
"""

Reales Beispiel für AskYourDocs

tools = [
    {
        "name": "search_knowledge_base",
        "description": """Sucht nach aktuellen Informationen in der unternehmensinternen Wissensdatenbank des Unternehmens.
Die Datenbank enthält: Verträge, Anhänge, Spezifikationen, Preislisten, Vorschriften, interne Anweisungen.

VERWENDEN, wenn:
- Anfrage zu Preisen, Tarifen, Kosten von Dienstleistungen oder Produkten
- Anfrage zu Vertragsbedingungen, Verpflichtungen, Fristen, Sanktionen
- Anfrage zu internen Verfahren, Vorschriften, Anweisungen
- Spezifische Details zu einem bestimmten Kunden, Projekt oder Produkt benötigt werden
- Die Anfrage enthält die Wörter: "unser", "Ihr", "aktuell", "letzte"

NICHT verwenden für:
- Allgemeine Fragen zu Technologien (was ist PDF, wie funktioniert API)
- Mathematische Berechnungen
- Anfragen zu allgemein bekannten Fakten, die unabhängig vom Unternehmen sind

Beispiele für Anfragen, die dieses Tool auslösen SOLLTEN:
- "Was ist der Preis für den Enterprise-Plan?"
- "Was sind die Bedingungen für eine vorzeitige Kündigung?"
- "Wer ist für das Onboarding neuer Kunden verantwortlich?"
- "Was ist die Frist für den Vertrag mit Alfa Corp?"
""",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "Suchanfrage in natürlicher Sprache. "
                                   "Fügen Sie Kontext hinzu: Namen von Kunden, Produkten, Dokumenttypen."
                },
                "top_k": {
                    "type": "integer",
                    "description": "Anzahl der Fragmente (1-10). Standard: 5. "
                                   "Verwenden Sie 8-10 für Vergleichsanfragen."
                }
            },
            "required": ["query"]
        }
    }
]

Testen der Beschreibungqualität

Eine gute Beschreibung zu schreiben reicht nicht aus – es muss überprüft werden, ob das Modell das Tool tatsächlich für die richtigen Anfragen aufruft und für unnötige nicht.

def test_tool_description(client, tools, test_cases):
    """
    Testet, ob das Modell das Tool für die richtigen Anfragen aufruft.

    test_cases: Liste von Dictionaries:
    [
        {"query": "Was kostet es?", "should_call_tool": True},
        {"query": "Was ist RAG?", "should_call_tool": False},
    ]
    """
    results = []
    for case in test_cases:
        response = client.messages.create(
            model="claude-opus-4-6",
            max_tokens=256,
            tools=tools,
            messages=[{"role": "user", "content": case["query"]}]
        )
        called_tool = response.stop_reason == "tool_use"
        passed = called_tool == case["should_call_tool"]
        results.append({
            "query": case["query"],
            "expected": case["should_call_tool"],
            "actual": called_tool,
            "passed": passed
        })
        if not passed:
            print(f"❌ FEHLER: '{case['query']}' – "
                  f"erwartetes Tool={'ja' if case['should_call_tool'] else 'nein'}, "
                  f"erhalten {'ja' if called_tool else 'nein'}")

    passed_count = sum(1 for r in results if r["passed"])
    print(f"\n{passed_count}/{len(results)} Testfälle bestanden")
    return results

# Nach jeder Änderung der Beschreibung ausführen
test_tool_description(client, tools, [
    {"query": "Was ist der Preis für den Enterprise-Plan?", "should_call_tool": True},
    {"query": "Was sind die Bedingungen für die Kündigung?", "should_call_tool": True},
    {"query": "Wer kümmert sich um das Onboarding?", "should_call_tool": True},
    {"query": "Was ist eine Vektordatenbank?", "should_call_tool": False},
    {"query": "Hallo, wie geht es dir?", "should_call_tool": False},
    {"query": "Wie viel sind 15% von 1000?", "should_call_tool": False},
])

Checkliste für die Tool-Beschreibung

• ☑ Der erste Satz beantwortet „Was macht dieses Tool?“ konkret und ohne allgemeine Worte
• ☑ Es gibt eine klare Liste von Trigger-Szenarien (VERWENDEN, wenn)
• ☑ Es gibt eine klare Liste von Anti-Anwendungsfällen (NICHT verwenden für)
• ☑ Es gibt ein Relevanzkriterium („wenn frische/aktuelle Informationen benötigt werden“)
• ☑ Wenn es mehrere Tools gibt – sind die Beschreibungen nicht überlappend und klar abgegrenzt
• ☑ Die Beschreibung wurde mit einem Satz von Anfragen getestet (sowohl positive als auch negative Fälle)
• ☑ Der System-Prompt verstärkt die Beschreibung durch klare Anweisungen, wann gesucht werden soll

❓ Häufig gestellte Fragen

Wie entscheidet die LLM, ob sie ein Tool aufrufen soll?

Über einen internen CoT: Das Modell wägt die Absicht der Anfrage gegen die Tool-Beschreibung ab und bewertet, ob seine eigenen Kenntnisse ausreichen. Wenn die Beschreibung ein Trigger-Szenario enthält, das mit der Anfrage übereinstimmt – und das Modell sich nicht für ausreichend kenntnisreich hält – generiert es einen Tool-Aufruf.

Warum ruft das Modell das Tool nicht auf, auch wenn es notwendig ist?

Drei Gründe: (1) ein unklares oder fehlendes Trigger-Szenario in der Beschreibung; (2) das Modell hält sich aufgrund seiner eigenen parametrischen Kenntnisse für ausreichend informiert; (3) tool_choice: auto garantiert naturgemäß keinen Aufruf. Lösung: Verbessern Sie die Beschreibung, fügen Sie klare Anweisungen im System-Prompt hinzu, oder verwenden Sie required für kritische Anfragetypen.

Was ist eine Halluzination aus Überzeugung?

Das Modell antwortet ohne Tool-Aufruf – überzeugend und kohärent – weil die parametrischen Kenntnisse die Anfrage abdecken, diese Kenntnisse aber veraltet sind. Besonders gefährlich für Preise, Vertragsbedingungen, Vorschriften. Diagnose: stop_reason == "end_turn" ohne vorheriges tool_use bei einer „sensiblen“ Anfrage.

Wie verarbeitet man parallele Tool-Aufrufe korrekt?

Führen Sie die Funktion für jeden tool_use-Block aus und übergeben Sie tool_result für jede tool_use_id in der nächsten Anfrage. Das Auslassen mindestens einer ID führt zu einem API-Validierungsfehler. Wenn der Aufruf mit einem Fehler endet – übergeben Sie is_error: true, lassen Sie die Antwort aber nicht aus.

✅ Schlussfolgerungen

• tool_choice: auto – keine Garantie für eine Suche. Es ist das Recht des Modells zu entscheiden. Protokollieren Sie stop_reason.
• Die Beschreibung ist Teil des Prompts, nicht der Dokumentation. Trigger-Szenarien und Anti-Anwendungsfälle sind entscheidend.
• Der gefährlichste Fehlerfall: eine überzeugte Antwort ohne Suche auf veralteten parametrischen Kenntnissen.
• Reasoning-enabled Modelle sind besser in komplexen Tool-Use-Szenarien – WildToolBench (2026) bestätigt dies.
• Parallele Aufrufe erfordern die Rückgabe eines Ergebnisses für jede tool_use_id.
• Self-Conditioning in langen Sitzungen kann die Entscheidungen des Modells verzerren – achten Sie auf Context Drift.
• Testen Sie die Beschreibung nach jeder Änderung mit einer Reihe von positiven und negativen Beispielen.

Nächster Schritt: Wie das Modell die Qualität der von einem Tool zurückgegebenen Ergebnisse bewertet – und warum selbst ein korrekter Aufruf zu einer falschen Antwort führen kann – in Grounding und Vertrauen in Quellen.

Quellen

WildToolBench — Benchmarking LLM Tool-Use in the Wild (2026) · Simplicity is SOTA — How LLMs are trained for function calling (2025) · OpenAI — Why language models hallucinate (2025) · Raina — Inside the Black Box: LLM Neural Layers and Tool Calling (2025) · APXML — Agent Tool Selection Logic · OpenAI Docs — Function Calling Best Practices · Kubaski — Tool Calling Best Practices (2025) · Statsig — Tool calling optimization (2025) · Survey — Large Language Models Hallucination (2026) · Anthropic Docs — How to implement tool use