/**
 * Typed tool helper: one `ToolSpec` object is the single source of truth for a
 * tool's name, description, schemas, annotations and worked examples — the
 * same object that registers the tool is the one a description lint can grade,
 * so model-facing docs can't drift from what's enforced.
 *
 * Pattern adapted from @mcp-kit/core (github.com/palimkarakshay/mcp-kit, MIT).
 */
import type { McpServer, ToolCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
import type { ZodRawShape } from "zod";
export interface ToolExample {
    /** One line on why you would make this call. */
    description: string;
    /** Concrete arguments, matching the tool's input schema. */
    arguments: Record<string, unknown>;
}
export interface ToolSpec<InputShape extends ZodRawShape = ZodRawShape> {
    /** Verb-first, snake_case, unique within the server. */
    name: string;
    title?: string;
    /** What it operates on, "Use this when …", and what it does NOT handle. */
    description: string;
    /** Zod raw shape; every field `.describe(...)`d. */
    inputSchema: InputShape;
    outputSchema?: ZodRawShape;
    annotations?: ToolAnnotations;
    /** At least one worked example — examples are documentation. */
    examples?: ToolExample[];
    handler: ToolCallback<InputShape>;
}
export type AnyToolSpec = ToolSpec<any>;
/** Identity helper that pins the generic so handler args are typed. */
export declare function defineTool<InputShape extends ZodRawShape>(spec: ToolSpec<InputShape>): ToolSpec<InputShape>;
export declare function registerTool(server: McpServer, spec: AnyToolSpec): void;
export declare function registerTools(server: McpServer, specs: readonly AnyToolSpec[]): void;