Anthropic 0.128.0: addTools Maximizes Cache Reuse

Anthropic introduces addTools() in its SDK 0.128.0 to add tools at runtime without modifying the tools[] array. This method allows for the reuse of up to 98.7% of the prefix of the next request thanks to caching, provided a specific beta header is enabled. However, some limitations remain, with certain cases still potentially leading to a complete cache miss.

A mandatory beta header and persistent cache miss cases

Using this feature requires adding the beta header or parameter inline-tools-2026-09-15, which is not automatically included by the runner. Therefore, this beta flag must be specified explicitly. Despite the expected improvement in cache reuse, there are still limitations related to the model, as well as a particular case that can still cause a complete cache miss. Additionally, a pause in execution delays the recognition of tool changes, even though adding or removing a tool is immediate on the agent's side.

Why modifying tools[] invalidates the cache and how addTools() avoids it

In the prompt cache, tool definitions are placed at the beginning of the prefix. Any modification to tools[] thus results in a complete cache miss. The addTools() function circumvents this issue by leaving the tools[] array unchanged and adding a system message containing a tool_addition block, which limits processing to only the newly added part. This capability is available in the Anthropic SDK 0.128.0 in TypeScript, launched with Claude Opus 5.5, and allows for the addition of a tool at runtime without modifying the base tools.

Up to 98.7% of prefix reused with addTools(), nearly none with tools[]

Using addTools() allows for the reuse of up to 98.7% of the prefix of the next request via caching, while a direct modification of tools[] allows for virtually no reuse. A reproducible Node script has measured the reuse of the request JSON, showing a shared prefix of up to 98.7% with addTools() and close to zero after modifying tools[]. The reuse gap widens with the length of the conversation. Therefore, it is advisable to keep the initial tools[] array and use addTools(), enabling the beta flag for compatible models.