import { z } from 'zod';
import type { GSCClient } from '../lib/gsc-client.js';

/**
 * Tool annotations for MCP protocol hints
 */
export interface ToolAnnotations {
  /** Tool does not modify any data */
  readOnlyHint?: boolean;
  /** Tool performs destructive operations (deletions, etc.) */
  destructiveHint?: boolean;
  /** Tool can be safely called multiple times with same result */
  idempotentHint?: boolean;
  /** Tool may access external/open-world data beyond GSC */
  openWorldHint?: boolean;
}

/**
 * Tool result content block
 */
export interface ToolResultContent {
  type: 'text' | 'image' | 'resource';
  text?: string;
  data?: string;
  mimeType?: string;
}

/**
 * Tool execution result
 */
export interface ToolResult {
  content: ToolResultContent[];
  structuredContent?: Record<string, any>; // For MCP Apps
  isError?: boolean;
}

/**
 * Complete tool definition with handler
 */
export interface ToolDefinition {
  name: string;
  description: string;
  category: 'discovery' | 'analytics' | 'intelligence' | 'indexing' | 'sitemaps' | 'management';
  annotations: ToolAnnotations;
  inputSchema: z.ZodType<any>;
  _meta?: {
    labels: {
      category: string;
      access: "read" | "write" | "delete";
      complexity: "simple" | "complex" | "batch";
    };
  };
  handler: (args: any, gscClient: GSCClient) => Promise<ToolResult>;
}

/**
 * Tool module export interface
 * Every tool file must export an object conforming to this interface
 */
export interface ToolModule {
  tools: ToolDefinition[];
}
