interface ToolDefinition {
  // Required
  id: string;                    // lowercase-hyphen-separated
  name: string;                  // Display name (max 50)
  description: string;           // What it does (max 500)
  category: Category;            // See categories below
  tags: string[];                // Search tags (min 1)
  method: 'GET' | 'POST';        // HTTP method
  parameters: Parameter[];       // Input params
  outputDescription: string;     // Output description
  example: { input: object; output: object };

  // Optional
  version?: string;              // Semver "1.0.0"
  icon?: string;                 // Emoji or icon ID
  aiInstructions?: string;       // AI guidance
  executionMode?: 'client' | 'server' | 'hybrid';
  requiresAuth?: boolean;
  rateLimit?: { requests: number; window: number };
}

interface Parameter {
  name: string;              // camelCase
  type: ParameterType;       // See types above
  label: string;             // Display label
  description: string;       // Help text
  required: boolean;

  // Optional
  defaultValue?: any;
  placeholder?: string;
  options?: Option[];        // For select
  validation?: Validation;
  dependsOn?: Dependency[];
  aiHint?: string;
  group?: string;
  order?: number;
  hidden?: boolean;
}

// Success
{
  success: true,
  data: { /* result */ },
  metadata?: { executionTime?: number; warnings?: string[] }
}

// Error
{
  success: false,
  error: "Message",
  errorCode: "ERROR_CODE",
  suggestion?: "How to fix"
}

interface Validation {
  minLength?: number;     // String min
  maxLength?: number;     // String max
  pattern?: string;       // Regex pattern
  min?: number;           // Number min
  max?: number;           // Number max
  step?: number;          // Number step
  accept?: string[];      // File types
  maxSize?: number;       // File bytes
}

dependsOn: [
  { field: 'mode', condition: 'equals', value: 'advanced' }
]

options: [
  { value: 'opt1', label: 'Option 1' },
  { value: 'opt2', label: 'Option 2', description: 'With description' },
  { value: 'opt3', label: 'Option 3', disabled: true }
]

const fn: ToolFunction = (params) => {
  return { success: true, data: result };
};

const fn: ToolFunction = async (params) => {
  const result = await asyncOp();
  return { success: true, data: result };
};

if (!params.input) {
  return { success: false, error: 'Required', errorCode: 'MISSING_REQUIRED' };
}

return {
  success: true,
  data: result,
  metadata: { executionTime: Date.now() - start }
};