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 bewahrt und was ihn invalidiert. Für allgemeines Prompt-Caching siehe Prompt-Caching.



cache_control bei Tool-Definitionen

Platziere cache_control: {"type": "ephemeral"} auf dem letzten Tool in deinem tools-Array. Dies cached das gesamte Tool-Definitions-Präfix, 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, platziere den Breakpoint daher auf dem mcp_toolset-Eintrag selbst, und die API wendet ihn auf das letzte expandierte Tool an.



defer_loading und Cache-Erhaltung

Zurückgestellte Tools sind nicht im System-Prompt-Präfix enthalten. Wenn das Modell ein zurückgestelltes Tool über die Tool-Suche entdeckt, wird die Definition inline als tool_reference-Block in den Gesprächsverlauf 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 bricht. Du kannst ein Gespräch mit einem kleinen Set immer geladener Tools (gecached) beginnen, das Modell bei Bedarf zusätzliche Tools entdecken lassen und denselben Cache-Hit über jeden Turn hinweg behalten.

defer_loading agiert außerdem unabhängig von der Grammatik-Konstruktion für den Strict Mode. Die Grammatik wird aus dem vollständigen Toolset aufgebaut, unabhängig davon, welche Tools zurückgestellt sind, 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 gecached

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 Standard-TTL von 5 Minuten, unabhängig von jeder TTL, die du auf deinen eigenen cache_control-Markern setzt. In der Antwort-usage 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