/**
 * Tool definition helper.
 *
 * Single source of truth: Zod input/output shapes carry parameter descriptions,
 * enums, and validation rules. JSON Schema for the MCP protocol is derived
 * from those shapes via `z.toJSONSchema`, so the wire-level schema and the
 * runtime parser can never drift.
 */
import { z } from "zod";
export type ZodRawShape = Record<string, z.ZodTypeAny>;
export interface ToolAnnotations {
    readonly readOnlyHint?: boolean;
    readonly destructiveHint?: boolean;
    readonly idempotentHint?: boolean;
    readonly openWorldHint?: boolean;
}
/**
 * Branded JSON Schema type. Anything emitted by `defineTool` is guaranteed
 * to have passed through `z.toJSONSchema` and had wire-incompatible keys
 * (`$schema`, `additionalProperties`) stripped.
 */
export type JsonSchema = Readonly<Record<string, unknown>> & {
    readonly __jsonSchemaBrand: unique symbol;
};
export interface ToolDefinition {
    readonly name: string;
    readonly description: string;
    readonly annotations: ToolAnnotations;
    readonly inputSchema: JsonSchema;
    readonly outputSchema: JsonSchema;
}
export interface ToolSpec<I extends ZodRawShape, O extends ZodRawShape> {
    name: string;
    description: string;
    annotations: ToolAnnotations;
    inputShape: I;
    outputShape: O;
}
export interface BuiltTool<I extends ZodRawShape, O extends ZodRawShape> extends ToolSpec<I, O> {
    readonly definition: ToolDefinition;
    readonly inputParser: z.ZodObject<I>;
}
/**
 * Build a tool from Zod shapes. Returns the spec plus a derived JSON Schema
 * `definition` (for library consumers) and an `inputParser` (for safe parsing).
 */
export declare function defineTool<I extends ZodRawShape, O extends ZodRawShape>(spec: ToolSpec<I, O>): BuiltTool<I, O>;