/**
 * MCP Tool Annotations System
 *
 * Enhanced tool annotations for MCP tools providing hints to AI models
 * about tool behavior, safety, and execution characteristics.
 *
 * Implements MCP 2024-11-05 specification tool annotations including:
 * - readOnlyHint: Tool only reads data
 * - destructiveHint: Tool performs destructive operations
 * - idempotentHint: Tool can be safely retried
 * - requiresConfirmation: Tool needs user confirmation
 *
 * @module mcp/toolAnnotations
 * @since 8.39.0
 */
import type { JsonObject } from "../types/common.js";
import type { NeuroLinkExecutionContext, ToolResult } from "../types/mcpTypes.js";
/**
 * Tool annotation metadata for MCP tools
 * Provides hints to AI models about tool behavior and safety
 */
export type MCPToolAnnotations = {
    /**
     * Human-readable title for the tool
     */
    title?: string;
    /**
     * Whether the tool only reads data without side effects
     * When true, AI models may call more freely for information gathering
     */
    readOnlyHint?: boolean;
    /**
     * Whether the tool performs destructive operations
     * When true, requires additional confirmation before execution
     */
    destructiveHint?: boolean;
    /**
     * Whether the tool can be safely retried without side effects
     * When true, automatic retry is safe on failure
     */
    idempotentHint?: boolean;
    /**
     * Whether the tool requires user confirmation before execution
     * When true, triggers HITL confirmation flow
     */
    requiresConfirmation?: boolean;
    /**
     * Whether the tool operates on an open world of resources
     * From the MCP protocol specification
     */
    openWorldHint?: boolean;
    /**
     * Custom tags for categorization and filtering
     */
    tags?: string[];
    /**
     * Estimated execution time in milliseconds
     */
    estimatedDuration?: number;
    /**
     * Rate limit hint (calls per minute)
     */
    rateLimitHint?: number;
    /**
     * Cost hint (arbitrary units for comparison)
     */
    costHint?: number;
    /**
     * Complexity level for UI display
     */
    complexity?: "simple" | "medium" | "complex";
    /**
     * Whether tool execution should be audited/logged
     */
    auditRequired?: boolean;
    /**
     * Security classification for the tool
     */
    securityLevel?: "public" | "internal" | "restricted";
};
/**
 * Enhanced tool definition with annotations
 */
export type MCPServerTool = {
    /**
     * Tool name (must be unique within server)
     */
    name: string;
    /**
     * Tool description for AI models
     */
    description: string;
    /**
     * JSON Schema for tool input parameters
     */
    inputSchema?: JsonObject;
    /**
     * Output schema for result validation
     */
    outputSchema?: JsonObject;
    /**
     * Tool behavior annotations
     */
    annotations?: MCPToolAnnotations;
    /**
     * Tool execution function
     */
    execute: (params: unknown, context?: NeuroLinkExecutionContext) => Promise<ToolResult | unknown>;
    /**
     * Additional metadata
     */
    metadata?: Record<string, unknown>;
};
/**
 * Infer annotations from tool definition
 * Uses heuristics based on tool description and name
 */
export declare function inferAnnotations(tool: Pick<MCPServerTool, "name" | "description">): MCPToolAnnotations;
/**
 * Merge multiple annotation objects with precedence
 * Later annotations override earlier ones
 */
export declare function mergeAnnotations(...annotationSets: (MCPToolAnnotations | undefined)[]): MCPToolAnnotations;
/**
 * Validate tool annotations
 * Returns list of validation errors (empty if valid)
 */
export declare function validateAnnotations(annotations: MCPToolAnnotations): string[];
/**
 * Create a tool with default annotations inferred
 */
export declare function createAnnotatedTool(tool: Omit<MCPServerTool, "annotations"> & {
    annotations?: MCPToolAnnotations;
}): MCPServerTool;
/**
 * Check if a tool requires confirmation based on annotations
 */
export declare function requiresConfirmation(tool: MCPServerTool): boolean;
/**
 * Check if a tool is safe for automatic retry
 */
export declare function isSafeToRetry(tool: MCPServerTool): boolean;
/**
 * Get tool safety level based on annotations
 */
export declare function getToolSafetyLevel(tool: MCPServerTool): "safe" | "moderate" | "dangerous";
/**
 * Filter tools by annotation predicates
 */
export declare function filterToolsByAnnotations(tools: MCPServerTool[], predicate: (annotations: MCPToolAnnotations) => boolean): MCPServerTool[];
/**
 * Get human-readable summary of tool annotations
 */
export declare function getAnnotationSummary(annotations: MCPToolAnnotations): string;
