/**
 * Tool search: an agent with hundreds of tools marks most of them `deferred`, and the model finds the
 * few a task needs with `search_tools` instead of reading every definition on every call.
 *
 * The search ranks tools by BM25 over their names, descriptions, and argument names and descriptions,
 * and answers with the tools it found as `tool_reference` parts. A provider with tool references,
 * such as Anthropic, expands each reference into the tool's definition where it stands, so the tool
 * list at the front of the prompt never changes; every other provider is sent a found tool from then
 * on. Either way the model calls a found tool on its next turn.
 */
import type { ToolDefinition } from '../types/messages.js';
/** The name of the search tool an agent with deferred tools offers. */
export declare const TOOL_SEARCH_NAME = "search_tools";
/** Options for `toolSearchTool()`. */
export interface ToolSearchOptions {
    /** How many tools a search returns unless the model asks for another number. Defaults to 5. */
    limit?: number;
    /** The most a model may ask for. Defaults to 20. */
    maxLimit?: number;
}
/** One tool a search found, with its score. */
export interface ToolSearchHit {
    /** The tool. */
    tool: ToolDefinition;
    /** Its BM25 score for the query; higher is closer. */
    score: number;
}
/**
 * Ranks tools against a query by BM25 over their names, descriptions, and arguments. A tool's name
 * counts twice, so a query that names a tool finds it first. Returns the tools that match at all,
 * best first, at most `limit`.
 */
export declare function searchTools(tools: readonly ToolDefinition[], query: string, limit?: number): ToolSearchHit[];
/**
 * The tool an agent offers when it has deferred tools: `search_tools`, which finds deferred tools by
 * what a task needs and answers with them as tool references. `createAgent()` adds it on its own; an
 * application's own loop can offer it the same way.
 */
export declare function toolSearchTool(tools: readonly ToolDefinition[], options?: ToolSearchOptions): ToolDefinition;