Tool-Nutzung mit Prompt-Caching

Diese Seite behandelt Prompt-Caching für Tool-Definitionen: wo du cache_control-Breakpoints platzierst, wie defer_loading deinen Cache erhält und was ihn invalidiert. Für allgemeines Prompt-Caching siehe Prompt-Caching.



cache_control bei Tool-Definitionen

Platziere cache_control: {"type": "ephemeral"} beim letzten Tool in deinem tools-Array. Dadurch wird das gesamte Tool-Definitions-Präfix gecacht, vom ersten Tool bis zum markierten Breakpoint:

{
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": { "type": "string" }
        },
        "required": ["location"]
      }
    },
    {
      "name": "get_time",
      "description": "Get the current time in a given time zone",
      "input_schema": {
        "type": "object",
        "properties": {
          "timezone": { "type": "string" }
        },
        "required": ["timezone"]
      },
      "cache_control": { "type": "ephemeral" }
    }
  ]
}

Bei mcp_toolset landet der cache_control-Breakpoint auf dem letzten Tool im Set. Du kontrollierst die Tool-Reihenfolge innerhalb eines MCP-Toolsets nicht, also platziere den Breakpoint auf dem mcp_toolset-Eintrag selbst, und die API wendet ihn auf das letzte expandierte Tool an.



defer_loading und Cache-Erhaltung

Verzögert geladene Tools sind nicht im System-Prompt-Präfix enthalten. Wenn das Modell ein verzögertes Tool über die Tool-Suche entdeckt, wird die Definition inline als tool_reference-Block im Konversationsverlauf angehängt. Das Präfix bleibt unberührt, sodass das Prompt-Caching erhalten bleibt.

Das bedeutet, dass das dynamische Hinzufügen von Tools über die Tool-Suche deinen Cache nicht beschädigt. Du kannst eine Konversation mit einem kleinen Set von immer geladenen Tools (gecacht) beginnen, das Modell bei Bedarf zusätzliche Tools entdecken lassen und denselben Cache-Hit über jeden Turn hinweg beibehalten.

defer_loading wirkt außerdem unabhängig von der Grammatik-Konstruktion für den Strict-Modus. Die Grammatik wird aus dem vollständigen Toolset erstellt, unabhängig davon, welche Tools verzögert geladen werden, sodass sowohl Prompt-Caching als auch Grammatik-Caching erhalten bleiben, wenn Tools dynamisch geladen werden.



Was deinen Cache invalidiert

Der Cache folgt einer Präfix-Hierarchie (tools → system → messages), sodass eine Änderung auf einer Ebene diese Ebene und alles danach invalidiert:



Server-Tool-Ergebnisse werden automatisch gecacht

Wenn deine Anfrage Prompt-Caching aktiviert hat und Claude ein Server-Tool wie Websuche, Web-Fetch oder Code-Ausführung verwendet, platziert die API automatisch einen Cache-Breakpoint auf dem Server-Tool-Ergebnis, bevor die nächste Iteration der agentischen Schleife ausgeführt wird. Dadurch können spätere Iterationen innerhalb derselben Anfrage das wachsende Präfix aus dem Cache lesen, anstatt es erneut zu verarbeiten.

Dieser automatische Breakpoint verwendet immer die standardmäßige 5-Minuten-TTL, unabhängig von jeder TTL, die du auf deinen eigenen cache_control-Markern setzt. In der usage-Antwort erscheinen diese Schreibvorgänge unter cache_creation.ephemeral_5m_input_tokens, sodass du möglicherweise 5-Minuten-Cache-Schreibvorgänge siehst, selbst wenn jedes von dir gesetzte cache_control eine 1-Stunden-TTL verwendet.

Dieses Verhalten gilt nur, wenn deine Anfrage bereits mindestens einen cache_control-Marker hat. Anfragen ohne Prompt-Caching erhalten den automatischen Breakpoint nicht.



Interaktionstabelle pro Tool



Nächste Schritte