Tools definieren



Voraussetzungen

• Vertrautheit mit der Tool-Nutzung-Übersicht
• Ein Claude API-Key und ein funktionierendes SDK- oder cURL-Setup



Ein Modell wählen

Verwende das neueste Claude Opus Modell, Claude Opus 5, 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 unkomplizierte Tools, beachte aber, dass sie fehlende Parameter möglicherweise ableiten.



Client-Tools spezifizieren

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

Für den vollständigen Satz optionaler Eigenschaften, die für jede Tool-Definition verfügbar sind, einschließlich cache_control, strict, defer_loading und allowed_callers, siehe die 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 benutzerdefinierten 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 aus Claude bei der Verwendung von Tools herauszuholen, 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 tut
  • Wann es verwendet werden sollte (und wann nicht)
  • Was jeder Parameter bedeutet und wie er das Verhalten des Tools beeinflusst
  • Alle wichtigen Einschränkungen oder Limitierungen, wie z. B. welche Informationen das Tool nicht zurückgibt, wenn der Tool-Name unklar ist. Je mehr Kontext du Claude über deine Tools geben kannst, desto besser wird es darin sein zu entscheiden, wann und wie sie zu verwenden sind. Strebe mindestens 3–4 Sätze für jede 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 formatsensitiven Parametern kannst du das Feld input_examples verwenden, um schema-validierte Beispiele bereitzustellen. Siehe Beispiele für Tool-Nutzung bereitstellen für Details.
• Konsolidiere verwandte Operationen in weniger Tools. 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, leistungsfähigere Tools reduzieren die Auswahlmehrdeutigkeit und machen deine Tool-Oberfläche für Claude einfacher zu navigieren.
• Verwende aussagekräftiges Namespacing in Tool-Namen. Wenn deine Tools mehrere Dienste oder Ressourcen umfassen, stelle den Namen den Dienst voran (zum Beispiel 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 Informationen mit hohem Signalwert zurückgeben. Gib semantische, stabile Bezeichner zurück (zum Beispiel 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 tut, 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 formatsensitiven Eingaben.



Grundlegende Verwendung

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    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 einigen 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 Feld tool_choice der Anfrage angibst. Die hervorgehobenen Zeilen sind der einzige Unterschied zu einer Standard-Tool-Nutzung-Anfrage:

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-5",
    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 eines der bereitgestellten Tools aufgerufen wird 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 Assistant-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 "What's the weather like in San Francisco right now, and what time is it there?" 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 gesprächigere Interaktion. Du kannst den Stil und Inhalt dieser Antworten über deine System-Prompts und durch 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