import type { JSONSchema } from 'zod/v4/core';
export interface ToolDefinition {
    name: string;
    description: string;
    inputSchema: JSONSchema.ObjectSchema;
}
export interface RegisteredTool {
    definition: ToolDefinition;
    /**
     * @param args Tool arguments (already zod-validated against the schema).
     * @returns A JSON-stringifiable value to return to the LLM.
     * @throws Any error; the host (MCP `registerToolList` / the cloud loop)
     * catches it and surfaces it as an error tool-result.
     */
    handler: (args: unknown) => Promise<unknown>;
}
/**
 * Define a tool with a single inputSchema (JSON Schema) as the source of truth.
 * The handler receives args already parsed and type-narrowed via a Zod schema
 * derived from that same JSON Schema — so the description sent to the client
 * and the validation applied to inbound args cannot drift.
 */
export declare function defineTool<TArgs>(definition: ToolDefinition, handler: (args: TArgs) => Promise<unknown>): RegisteredTool;
/**
 * Render a tool-handler error as the text every host shows the LLM.
 * Boom errors carrying an RFC 9457 problem include its `detail`; anything
 * else falls back to the plain message.
 */
export declare function errorAsToolText(err: unknown): string;
/**
 * Adapt a tool to a host by WIDENING its input schema — add properties, mark
 * some required, optionally override the description — without touching the
 * handler. A host maps whichever shared tools it needs through this (for
 * example, the MCP adds its `captureId` session handle + the credential-aware
 * `run_proof` contract). Args parse loosely, so the extra fields flow through
 * to the handler (its backend resolver reads them); the base tool stays
 * untouched for hosts that don't need them.
 */
export declare function extendTool(tool: RegisteredTool, extra: {
    description?: string;
    properties?: JSONSchema.ObjectSchema['properties'];
    required?: string[];
}): RegisteredTool;