/**
 * Shared Tool Utilities
 *
 * Common types, formatters, and error handlers used across all tool modules.
 * Eliminates duplication of formatResponse, handleError, and type definitions.
 *
 * CRITICAL: NEVER use console.log() - stdout is reserved for JSON-RPC protocol.
 * Use console.error() for all logging.
 *
 * @module tools/shared
 */
import { z } from 'zod';
/** MCP tool response format */
export type ToolResponse = {
    content: Array<{
        type: 'text';
        text: string;
    }>;
    isError?: boolean;
};
/** Tool handler function signature. Extra is the MCP SDK RequestHandlerExtra (optional). */
type ToolHandler = (params: Record<string, unknown>, extra?: any) => Promise<ToolResponse>;
/** Tool definition with description, schema, and handler */
export interface ToolDefinition {
    description: string;
    inputSchema: Record<string, z.ZodTypeAny>;
    handler: ToolHandler;
}
/**
 * Format tool result as MCP content response.
 * If the serialized JSON exceeds MAX_RESPONSE_BYTES, arrays are progressively
 * truncated and a `_response_truncated` warning is injected so the AI knows
 * to paginate.
 */
export declare function formatResponse(result: unknown): ToolResponse;
/**
 * Handle errors uniformly - FAIL FAST
 */
export declare function handleError(error: unknown): ToolResponse;
/**
 * Fetch provenance chain for a given provenance ID and attach to response object.
 * Returns the chain array on success. If provenanceId is null/undefined, returns undefined.
 *
 * FAIL FAST: If the provenance query fails, the error propagates up to the
 * tool handler's catch block where handleError() will produce a proper error
 * response. We do NOT silently swallow errors -- if include_provenance was
 * requested and the query fails, the tool should fail.
 *
 * Shared by clustering, comparison, file-management, and form-fill tools.
 */
export declare function fetchProvenanceChain(db: {
    getProvenanceChain: (id: string) => unknown[];
}, provenanceId: string | null | undefined, _logPrefix: string): unknown[] | undefined;
export {};
//# sourceMappingURL=shared.d.ts.map