The ToolSearch wrapper in the Laravel 13 AI SDK is designed to solve a specific scaling problem: when an agent has too many tools, sending every single tool definition with every request becomes expensive and can actually confuse the model.
The Core Purpose: Deferring Tool Definitions
Normally, when you build an agent, every tool you register is sent to the AI provider (like OpenAI or Anthropic) on every single request. For an agent with four or five tools, this is fine. However, if your agent has thirty or more tools (for example, a back-office assistant that can issue refunds, change plans, resend invoices, etc.), this creates two problems :
Token Cost: Tool schemas consume input tokens. Sending thirty definitions on every call adds a fixed, unnecessary cost.
Accuracy: The model has more options to choose from, which can make its tool selection less accurate.
ToolSearch wraps the tools you want to defer. Instead of sending their full definitions upfront, the provider receives a "search" entry. The model then loads a tool is full definition only when it decides it actually needs to use it .
How to Use It?
You simply wrap the tools you want to defer as the first argument. Anything left outside the wrapper is sent to the provider as usual (which is useful for frequently used tools) .
use LaravelAiProvidersToolsToolSearch;
public function tools(): iterable
{
return [
new LookupAccount, // Sent immediately (frequently used)new ToolSearch(tools: [
new IssueRefund,
new ChangePlan,
new ResendInvoice,
// ...the rest of the large catalog
]),
];
}