/**
 * On-demand tool discovery (`tools.discovery: true`).
 *
 * Instead of sending every external MCP tool's full schema on every request,
 * the model receives the hot set (built-in tools, per-call tools, explicitly
 * requested tools, and previously discovered tools) plus ONE `search_tools`
 * meta-tool whose description embeds a compact name+summary catalog of the
 * deferred tools. Calling `search_tools` loads matching tools:
 *  - immediately into the live tool record (providers that re-read the tools
 *    record between agent-loop steps — the AI SDK path — can call them on the
 *    very next step), and
 *  - into the session pin set (all providers include them in full on every
 *    subsequent call of the session).
 *
 * Evidence for this design: catalogs past ~30-50 tools measurably degrade
 * tool-selection accuracy, and deferral+search both cuts definition tokens by
 * ~85% and RAISES selection accuracy (Anthropic MCP-eval 49%→74% on Opus 4).
 * The catalog construction (byte-stable, name-sorted, char-budgeted with a
 * degradation ladder) mirrors the proven skills-index pattern in
 * src/lib/skills/skillTools.ts.
 */
import type { Tool } from "../types/index.js";
/**
 * Above this many tools, a WARN suggests enabling `tools.discovery` when it
 * is off. Chosen from the measured degradation range (30-50 tools).
 */
export declare const LARGE_CATALOG_WARN_THRESHOLD = 40;
/** True when the value is a search_tools meta-tool generated by this module. */
export declare function isDiscoveryMetaTool(tool: unknown): boolean;
/**
 * Partition a (post-gate) tools record for discovery: deferrable tools that
 * are not pinned are removed from the record and replaced by one
 * `search_tools` meta-tool. Returns the hot record; when nothing is
 * deferrable the input record is returned unchanged.
 *
 * The returned record is mutated by search_tools on hydration (call-scoped —
 * BaseProvider builds a fresh merged record per call), which is what makes
 * discovered tools callable on subsequent steps of the same agent loop on
 * providers that re-read the record between steps.
 */
export declare function partitionToolsForDiscovery(tools: Record<string, Tool>, args: {
    /** External-tool names present in `tools` that are allowed to defer. */
    deferrableNames: string[];
    /** Session-pinned names (previously discovered) — never deferred. */
    pinnedNames: ReadonlySet<string>;
    /** Called with newly discovered names — persists session pins. */
    onHydrate: (names: string[]) => void;
}): Record<string, Tool>;
