Tool Search: Alternate Approaches

Why it matters

Loading every tool definition into every request costs tokens and context; discovering tools later can cost the prompt cache. 3.8 asks you to choose what each request loads; this notebook shows discovery without search that keeps the cache.

What to practise

Put every tool name in the system prompt and send only a describe_tool tool. When Claude calls it, return a tool_reference block and append that tool’s definition to tools with defer_loading: true, so the cached prefix is unchanged. Run the single-tool and multi-tool queries and watch which definitions each request carries. The notebook sends the advanced-tool-use-2025-11-20 beta header for these features.

How it fits

The name list in the system prompt with on-demand definitions is 3.8.1’s hybrid strategy, and the deferred tool is one of 3.8.2’s disclosure paths. The notebook prints only how many tools each request carries; measure the saving as 3.8.3 does, from the input and cache-read tokens in usage. Because your client decides what describe_tool may load, it is also where 3.8.4’s policy applies.