Tools definieren

Voraussetzungen

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

Client-Tools festlegen

Client-Tools werden im Top-Level-Parameter tools der API-Anfrage angegeben. Client-Tools mit Anthropic-Schema, wie das Bash- und das Texteditor-Tool, werden über einen datumsversionierten type deklariert; die jeweils akzeptierten Felder findest du auf der Seite des jeweiligen Tools, die in der Tool-Referenz verlinkt ist. Die Tools für Computer Use und Browser Use sind Client-Toolsets: ein einzelner Eintrag ohne name, der einen festen Satz von Mitglieds-Tools deklariert. Eine benutzerdefinierte Tool-Definition umfasst:

Den vollständigen Satz optionaler Eigenschaften, die für jede einzelne Tool-Definition verfügbar sind, einschließlich cache_control, strict, defer_loading und allowed_callers, findest du in der Tool-Referenz. Ein Client-Toolset-Eintrag akzeptiert cache_control und allowed_callers auf dem Eintrag und setzt defer_loading pro Mitglied; siehe Client-Toolsets.

{
  "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, either 'celsius' or 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

System-Prompt für die Tool-Nutzung

Wenn du die Claude API mit dem Parameter tools aufrufst, erstellt die API einen speziellen „system prompt“ (System-Prompt) aus den Tool-Definitionen, der Tool-Konfiguration und einem etwaigen vom Benutzer angegebenen System-Prompt. Der erstellte Prompt ist darauf ausgelegt, das Modell anzuweisen, das bzw. 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 bei der Verwendung von Tools die beste Leistung aus Claude herauszuholen, befolge diese Richtlinien:

• Stelle äußerst 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 Vorbehalte oder Einschränkungen, etwa 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 verwendet. Strebe mindestens 3–4 Sätze pro Tool-Beschreibung an, mehr, wenn das Tool komplex ist.
• Priorisiere Beschreibungen, ziehe aber für komplexe Tools input_examples in Betracht. Klare Beschreibungen sind am wichtigsten, aber für Tools mit komplexen Eingaben, verschachtelten Objekten oder formatsensiblen Parametern kannst du das Feld input_examples verwenden, um schemavalidierte Beispiele bereitzustellen. Details findest du unter Beispiele für die Tool-Nutzung bereitstellen.
• 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, dafür leistungsfähigere Tools verringern die Mehrdeutigkeit bei der Auswahl und machen deine Tool-Oberfläche für Claude leichter navigierbar.
• Verwende aussagekräftige Namensräume 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). Das 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 Signalgehalt zurückgeben. Gib semantische, stabile Bezeichner (zum Beispiel Slugs oder UUIDs) statt undurchsichtiger interner Referenzen zurück 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 herauszufiltern.

{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

{
  "name": "get_stock_price",
  "description": "Gets the stock price for a ticker.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}

Die gute Beschreibung erklärt klar, was das Tool tut, wann es verwendet werden soll, welche Daten es zurückgibt und was der Parameter ticker bedeutet. Die schlechte Beschreibung ist zu kurz und lässt für Claude viele offene Fragen zum Verhalten und zur Verwendung des Tools.

Beispiele für die Tool-Nutzung bereitstellen

Du kannst konkrete Beispiele gültiger Tool-Eingaben bereitstellen, um Claude zu helfen, deine Tools effektiver zu verwenden. Dies ist besonders nützlich für komplexe Tools mit verschachtelten Objekten, optionalen Parametern oder formatsensiblen 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-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. Das 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

• Schemavalidierung - 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 oder Client-Toolsets - Eingabebeispiele funktionieren bei benutzerdefinierten Tools und Client-Tools mit Anthropic-Schema mit Ausnahme der Toolsets für Computer Use und Browser Use, jedoch nicht bei Server-Tools wie Websuche oder Codeausfü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, selbst wenn Claude andernfalls direkt antworten würde, ohne ein Tool aufzurufen. Das erreichst du, indem du das Tool im Feld tool_choice der Anfrage angibst.

Nicht jedes Modell und jede Einstellung unterstützt erzwungene Tool-Nutzung. Wo sie nicht unterstützt wird, schlagen tool_choice: {"type": "any"} und tool_choice: {"type": "tool", "name": "..."} fehl, während tool_choice: {"type": "auto"} (der Standard) und tool_choice: {"type": "none"} weiterhin funktionieren:

Bei Modellen, die dies unterstützen, sind die hervorgehobenen Zeilen der einzige Unterschied zu einer Standardanfrage mit Tool-Nutzung:

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 Parameter tool_choice 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 bei tool_choice mit dem Wert any oder tool die Assistant-Nachricht vorab befüllt, um die Verwendung eines Tools zu erzwingen. Das bedeutet, dass die Modelle vor tool_use-Inhaltsblöcken keine natürlichsprachliche Antwort oder Erklärung ausgeben, selbst wenn sie ausdrücklich dazu aufgefordert werden.

Tests haben gezeigt, dass dies die Leistung nicht verringern sollte. Wenn du möchtest, dass das Modell natürlichsprachlichen Kontext oder Erklärungen liefert und dennoch ein bestimmtes Tool verwendet, kannst du {"type": "auto"} für tool_choice (den 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 häufig, was es gerade tut, oder antwortet dem Benutzer auf natürliche Weise, bevor es Tools aufruft.

Bei dem Prompt „What's the weather like in San Francisco right now, and what time is it there?“ könnte Claude zum Beispiel so 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ächsähnlichere Interaktion. Du kannst Stil und Inhalt dieser Antworten über deine System-Prompts und durch die Bereitstellung von <examples> in deinen Prompts steuern.

Es ist wichtig zu beachten, dass Claude beim Erklären seiner Aktionen verschiedene Formulierungen und Ansätze verwenden kann. Dein Code sollte diese Antworten wie jeden anderen vom Assistant generierten Text behandeln und sich nicht auf bestimmte Formatierungskonventionen verlassen.

Nächste Schritte