Tools definieren



Ein Modell auswählen

Verwende das neueste Claude Opus (4.8) Modell für komplexe Tools und mehrdeutige Anfragen; es handhabt mehrere Tools besser und fragt bei Bedarf nach Klärung.

Verwende Claude Haiku Modelle für einfache Tools, beachte aber, dass sie fehlende Parameter möglicherweise ableiten.



Client-Tools spezifizieren

Client-Tools (sowohl Anthropic-Schema- als auch benutzerdefinierte Tools) werden im Top-Level-Parameter tools der API-Anfrage angegeben. Jede Tool-Definition enthält:

Die vollständige Liste der optionalen Eigenschaften, die für jede Tool-Definition verfügbar sind, einschließlich cache_control, strict, defer_loading und allowed_callers, findest du in der Tool-Referenz.



System-Prompt für Tool-Nutzung

Wenn du die Claude API mit dem tools-Parameter aufrufst, konstruiert die API einen speziellen System-Prompt aus den Tool-Definitionen, der Tool-Konfiguration und jedem vom Benutzer angegebenen System-Prompt. Der konstruierte Prompt ist darauf ausgelegt, das Modell anzuweisen, die angegebenen Tools zu verwenden und den notwendigen Kontext bereitzustellen, damit das Tool ordnungsgemäß funktioniert:

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}



Best Practices für Tool-Definitionen

Um die beste Leistung von Claude bei der Verwendung von Tools zu erzielen, befolge diese Richtlinien:

• Stelle extrem detaillierte Beschreibungen bereit. Dies ist bei weitem der wichtigste Faktor für die Tool-Leistung. Deine Beschreibungen sollten jedes Detail über das Tool erklären, einschließlich:
  • Was das Tool macht
  • Wann es verwendet werden sollte (und wann nicht)
  • Was jeder Parameter bedeutet und wie er das Verhalten des Tools beeinflusst
  • Alle wichtigen Vorbehalte oder Einschränkungen, z. B. welche Informationen das Tool nicht zurückgibt, falls der Tool-Name unklar ist. Je mehr Kontext du Claude über deine Tools geben kannst, desto besser kann es entscheiden, wann und wie es sie verwenden soll. Strebe mindestens 3–4 Sätze pro Tool-Beschreibung an, mehr, wenn das Tool komplex ist.
• Priorisiere Beschreibungen, aber erwäge die Verwendung von input_examples für komplexe Tools. Klare Beschreibungen sind am wichtigsten, aber für Tools mit komplexen Eingaben, verschachtelten Objekten oder formatabhängigen Parametern kannst du das Feld input_examples verwenden, um schema-validierte Beispiele bereitzustellen. Siehe Beispiele für Tool-Nutzung bereitstellen für Details.
• Fasse verwandte Operationen in weniger Tools zusammen. Anstatt für jede Aktion ein separates Tool zu erstellen (create_pr, review_pr, merge_pr), gruppiere sie in einem einzigen Tool mit einem action-Parameter. Weniger, aber leistungsfähigere Tools reduzieren Mehrdeutigkeit bei der Auswahl und machen es Claude leichter, sich in deiner Tool-Oberfläche zurechtzufinden.
• Verwende aussagekräftiges Namespacing in Tool-Namen. Wenn deine Tools mehrere Dienste oder Ressourcen umfassen, stelle den Namen den Dienst voran (z. B. github_list_prs, slack_send_message). Dies macht die Tool-Auswahl eindeutig, wenn deine Bibliothek wächst, und ist besonders wichtig bei der Verwendung der Tool-Suche.
• Gestalte Tool-Antworten so, dass sie nur relevante Informationen zurückgeben. Gib semantische, stabile Bezeichner zurück (z. B. Slugs oder UUIDs) statt undurchsichtiger interner Referenzen, und schließe nur die Felder ein, die Claude benötigt, um über seinen nächsten Schritt nachzudenken. Aufgeblähte Antworten verschwenden Kontext und erschweren es Claude, das Wesentliche zu extrahieren.

Die gute Beschreibung erklärt klar, was das Tool macht, wann es zu verwenden ist, welche Daten es zurückgibt und was der ticker-Parameter bedeutet. Die schlechte Beschreibung ist zu kurz und lässt Claude mit vielen offenen Fragen über das Verhalten und die Verwendung des Tools zurück.



Beispiele für Tool-Nutzung bereitstellen

Du kannst konkrete Beispiele für gültige Tool-Eingaben bereitstellen, um Claude zu helfen, deine Tools effektiver zu nutzen. Dies ist besonders nützlich für komplexe Tools mit verschachtelten Objekten, optionalen Parametern oder formatabhängigen Eingaben.



Grundlegende Verwendung

Füge deiner Tool-Definition ein optionales input_examples-Feld mit einem Array von Beispiel-Eingabeobjekten hinzu. Jedes Beispiel muss gemäß dem input_schema des Tools gültig sein:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature",
                    },
                },
                "required": ["location"],
            },
            "input_examples": [
                {"location": "San Francisco, CA", "unit": "fahrenheit"},
                {"location": "Tokyo, Japan", "unit": "celsius"},
                {
                    "location": "New York, NY"  # 'unit' is optional
                },
            ],
        }
    ],
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

print(response)

Beispiele werden zusammen mit deinem Tool-Schema in den Prompt aufgenommen und zeigen Claude konkrete Muster für wohlgeformte Tool-Aufrufe. Dies hilft Claude zu verstehen, wann optionale Parameter einzuschließen sind, welche Formate zu verwenden sind und wie komplexe Eingaben zu strukturieren sind.



Anforderungen und Einschränkungen

• Schema-Validierung – Jedes Beispiel muss gemäß dem input_schema des Tools gültig sein. Ungültige Beispiele geben einen 400-Fehler zurück
• Nicht unterstützt für serverseitige Tools – Eingabebeispiele funktionieren bei benutzerdefinierten und Anthropic-Schema-Client-Tools, aber nicht bei Server-Tools wie Websuche oder Code-Ausführung
• Token-Kosten – Beispiele erhöhen die Prompt-Token: ~20–50 Token für einfache Beispiele, ~100–200 Token für komplexe verschachtelte Objekte



Claudes Ausgabe steuern



Tool-Nutzung erzwingen

In manchen Fällen möchtest du vielleicht, dass Claude ein bestimmtes Tool verwendet, um die Frage des Benutzers zu beantworten, auch wenn Claude sonst direkt antworten würde, ohne ein Tool aufzurufen. Du kannst dies tun, indem du das Tool im tool_choice-Feld der Anfrage angibst. Die hervorgehobenen Zeilen sind der einzige Unterschied zu einer Standard-Tool-Nutzungs-Anfrage:

import anthropic

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA",
                }
            },
            "required": ["location"],
        },
    }
]

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

print(response)

Bei der Arbeit mit dem tool_choice-Parameter gibt es vier mögliche Optionen:

• auto erlaubt Claude zu entscheiden, ob es eines der bereitgestellten Tools aufruft oder nicht. Dies ist der Standardwert, wenn tools bereitgestellt werden.
• any teilt Claude mit, dass es eines der bereitgestellten Tools verwenden muss, erzwingt aber kein bestimmtes Tool.
• tool zwingt Claude, immer ein bestimmtes Tool zu verwenden.
• none verhindert, dass Claude Tools verwendet. Dies ist der Standardwert, wenn keine tools bereitgestellt werden.

Dieses Diagramm veranschaulicht, wie jede Option funktioniert:

Beachte, dass die API, wenn du tool_choice auf any oder tool setzt, die Assistenten-Nachricht vorausfüllt, um die Verwendung eines Tools zu erzwingen. Das bedeutet, dass die Modelle keine natürlichsprachliche Antwort oder Erklärung vor tool_use-Inhaltsblöcken ausgeben, selbst wenn sie ausdrücklich dazu aufgefordert werden.

Tests haben gezeigt, dass dies die Leistung nicht beeinträchtigen sollte. Wenn du möchtest, dass das Modell natürlichsprachlichen Kontext oder Erklärungen liefert und gleichzeitig ein bestimmtes Tool verwendet, kannst du {"type": "auto"} für tool_choice (der Standard) verwenden und explizite Anweisungen in einer user-Nachricht hinzufügen. Zum Beispiel: What's the weather like in London? Use the get_weather tool in your response.



Modellantworten mit Tools

Bei der Verwendung von Tools kommentiert Claude oft, was es tut, oder antwortet dem Benutzer auf natürliche Weise, bevor es Tools aufruft.

Zum Beispiel könnte Claude auf den Prompt „Wie ist das Wetter gerade in San Francisco und wie spät ist es dort?" wie folgt antworten:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll help you check the current weather and time in San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" }
    }
  ]
}

Dieser natürliche Antwortstil hilft Benutzern zu verstehen, was Claude tut, und schafft eine konversationellere Interaktion. Du kannst den Stil und Inhalt dieser Antworten durch deine System-Prompts und durch die Bereitstellung von <examples> in deinen Prompts steuern.

Es ist wichtig zu beachten, dass Claude verschiedene Formulierungen und Ansätze verwenden kann, wenn es seine Aktionen erklärt. Dein Code sollte diese Antworten wie jeden anderen vom Assistenten generierten Text behandeln und sich nicht auf bestimmte Formatierungskonventionen verlassen.



Nächste Schritte