feat(pulse-ai): revamp RPCs, fix availability/filtering bugs, add ranked slices and token compression

misc/pulse_ai_revamped_rpcs.sql

@@ -0,0 +1,1175 @@
+-- ============================================================================
+-- PULSE AI BACKEND REVAMP: CORRECTNESS, CONTRACT STRICTNESS & TOKEN OPTIMIZATION
+-- ============================================================================
+-- Each block contains explicit DROP FUNCTION IF EXISTS statements followed by
+-- CREATE OR REPLACE FUNCTION and GRANT EXECUTE permissions.
+-- Copy and paste each block individually into the Supabase SQL Editor.
+-- ============================================================================
+
+
+-- ============================================================================
+-- 1. get_market_snapshot
+-- ============================================================================
+DROP FUNCTION IF EXISTS public.get_market_snapshot(text, date, date);
+
+CREATE OR REPLACE FUNCTION public.get_market_snapshot(
+  p_market text,
+  p_start_date date,
+  p_end_date date
+)
+RETURNS json
+LANGUAGE sql
+STABLE SECURITY DEFINER
+AS $function$
+  WITH market_props AS (
+    SELECT DISTINCT ON (property_id)
+      property_id,
+      is_available,
+      is_active
+    FROM public.v_rate_volatility
+    WHERE LOWER(market) = LOWER(p_market)
+    ORDER BY property_id, recorded_at DESC
+  )
+  SELECT json_build_object(
+    'status', 'success',
+    'market', p_market,
+    'period', json_build_object('start', p_start_date, 'end', p_end_date),
+    'active_properties', (SELECT COUNT(*) FILTER (WHERE is_active = true) FROM market_props),
+    'total_tracked', (SELECT COUNT(*) FROM market_props),
+    'available_count', (SELECT COUNT(*) FILTER (WHERE is_available = true AND is_active = true) FROM market_props),
+    'unavailable_count', (SELECT COUNT(*) FILTER (WHERE is_available = false AND is_active = true) FROM market_props),
+    'availability_rate_pct', (
+      SELECT ROUND(
+        100.0 * COUNT(*) FILTER (WHERE is_available = true AND is_active = true)
+        / NULLIF(COUNT(*) FILTER (WHERE is_active = true), 0), 2
+      )
+      FROM market_props
+    ),
+    'avg_nightly_rate', ROUND(AVG(rh.nightly_rate)::numeric, 2),
+    'min_nightly_rate', ROUND(MIN(rh.nightly_rate)::numeric, 2),
+    'max_nightly_rate', ROUND(MAX(rh.nightly_rate)::numeric, 2),
+    'volatility_events', (
+      SELECT COUNT(*)
+      FROM public.v_rate_volatility v
+      WHERE LOWER(v.market) = LOWER(p_market)
+        AND ABS(v.pct_above_trailing_avg) >= 25
+        AND v.recorded_at::date BETWEEN p_start_date AND p_end_date
+    )
+  )
+  FROM public.rate_history rh
+  JOIN public.properties p ON p.id = rh.property_id
+  WHERE LOWER(p.market) = LOWER(p_market)
+    AND p.is_active = true
+    AND rh.stay_date::date BETWEEN p_start_date AND p_end_date;
+$function$;
+
+GRANT EXECUTE ON FUNCTION public.get_market_snapshot(text, date, date) TO anon, authenticated, service_role;
+
+
+-- ============================================================================
+-- 2. get_market_averages
+-- ============================================================================
+-- Dropping previous TABLE(...) signature to avoid PostgreSQL Error 42P13
+DROP FUNCTION IF EXISTS public.get_market_averages(text);
+DROP FUNCTION IF EXISTS public.get_market_averages();
+
+CREATE OR REPLACE FUNCTION public.get_market_averages(
+  market_param text DEFAULT NULL::text
+)
+RETURNS json
+LANGUAGE sql
+STABLE SECURITY DEFINER
+AS $function$
+  WITH latest_props AS (
+    SELECT DISTINCT ON (property_id)
+      property_id,
+      market,
+      nightly_rate,
+      trailing_avg_rate,
+      is_available,
+      is_active
+    FROM public.v_rate_volatility
+    WHERE (market_param IS NULL OR LOWER(market) = LOWER(market_param))
+      AND is_active = true
+      AND nightly_rate IS NOT NULL
+    ORDER BY property_id, recorded_at DESC
+  )
+  SELECT json_build_object(
+    'status', 'success',
+    'market', COALESCE(market_param, 'All Markets'),
+    'active_properties_with_rates', COUNT(*),
+    'avg_nightly_rate', ROUND(AVG(nightly_rate)::numeric, 2),
+    'avg_trailing_7d_rate', ROUND(AVG(trailing_avg_rate)::numeric, 2),
+    'min_nightly_rate', ROUND(MIN(nightly_rate)::numeric, 2),
+    'max_nightly_rate', ROUND(MAX(nightly_rate)::numeric, 2)
+  )
+  FROM latest_props;
+$function$;
+
+GRANT EXECUTE ON FUNCTION public.get_market_averages(text) TO anon, authenticated, service_role;
+
+
+-- ============================================================================
+-- 3. search_properties
+-- ============================================================================
+-- Dropping previous TABLE(...) signature and overloads
+DROP FUNCTION IF EXISTS public.search_properties(text, text, text, integer, boolean, integer);
+DROP FUNCTION IF EXISTS public.search_properties(text, text, text, integer, boolean, boolean, text, text, integer);
+
+CREATE OR REPLACE FUNCTION public.search_properties(
+  p_search text DEFAULT NULL::text,
+  p_market text DEFAULT NULL::text,
+  p_platform text DEFAULT NULL::text,
+  p_bedrooms integer DEFAULT NULL::integer,
+  p_available boolean DEFAULT NULL::boolean,
+  p_is_active boolean DEFAULT true,
+  p_rank_position text DEFAULT 'top'::text,
+  p_sort_by text DEFAULT 'rate'::text,
+  p_limit integer DEFAULT 6
+)
+RETURNS json
+LANGUAGE sql
+STABLE SECURITY DEFINER
+AS $function$
+  WITH latest_state AS (
+    SELECT DISTINCT ON (rvv.property_id)
+      rvv.property_id,
+      rvv.property_name,
+      rvv.market,
+      rvv.platform,
+      rvv.bedrooms,
+      ROUND(rvv.avg_rating::numeric, 2) AS avg_rating,
+      rvv.review_count,
+      ROUND(rvv.nightly_rate::numeric, 2) AS nightly_rate,
+      ROUND(rvv.pct_above_trailing_avg::numeric, 2) AS pct_above_trailing_avg,
+      rvv.is_available,
+      rvv.is_active,
+      rvv.recorded_at
+    FROM public.v_rate_volatility rvv
+    WHERE
+      (p_market IS NULL OR LOWER(rvv.market) = LOWER(p_market))
+      AND (p_platform IS NULL OR LOWER(rvv.platform) = LOWER(p_platform))
+      AND (p_bedrooms IS NULL OR rvv.bedrooms = p_bedrooms)
+      AND (
+        p_search IS NULL
+        OR rvv.property_name ILIKE '%' || p_search || '%'
+        OR rvv.property_id::text = p_search
+      )
+    ORDER BY rvv.property_id, rvv.recorded_at DESC
+  ),
+  filtered AS (
+    SELECT *
+    FROM latest_state
+    WHERE (p_available IS NULL OR is_available = p_available)
+      AND (p_is_active IS NULL OR is_active = p_is_active)
+  ),
+  ranked AS (
+    SELECT
+      *,
+      COUNT(*) OVER () AS total_matching,
+      ROW_NUMBER() OVER (
+        ORDER BY
+          CASE WHEN p_sort_by = 'deviation' THEN ABS(COALESCE(pct_above_trailing_avg, 0)) END DESC NULLS LAST,
+          CASE WHEN p_sort_by = 'rate' THEN nightly_rate END DESC NULLS LAST,
+          property_name ASC
+      ) AS rank_asc,
+      ROW_NUMBER() OVER (
+        ORDER BY
+          CASE WHEN p_sort_by = 'deviation' THEN ABS(COALESCE(pct_above_trailing_avg, 0)) END ASC NULLS LAST,
+          CASE WHEN p_sort_by = 'rate' THEN nightly_rate END ASC NULLS LAST,
+          property_name DESC
+      ) AS rank_desc
+    FROM filtered
+  ),
+  sliced AS (
+    SELECT
+      property_id,
+      property_name,
+      market,
+      platform,
+      bedrooms,
+      avg_rating,
+      review_count,
+      nightly_rate,
+      pct_above_trailing_avg,
+      is_available,
+      is_active,
+      recorded_at,
+      total_matching
+    FROM ranked
+    WHERE
+      CASE
+        WHEN LOWER(p_rank_position) = 'bottom' THEN
+          rank_desc <= LEAST(GREATEST(p_limit, 1), 20)
+        WHEN LOWER(p_rank_position) = 'middle' THEN
+          rank_asc > GREATEST(0, (total_matching - LEAST(GREATEST(p_limit, 1), 20)) / 2)
+          AND rank_asc <= GREATEST(0, (total_matching - LEAST(GREATEST(p_limit, 1), 20)) / 2) + LEAST(GREATEST(p_limit, 1), 20)
+        ELSE -- 'top'
+          rank_asc <= LEAST(GREATEST(p_limit, 1), 20)
+      END
+    ORDER BY
+      CASE WHEN LOWER(p_rank_position) = 'bottom' THEN rank_desc ELSE rank_asc END ASC
+  )
+  SELECT json_build_object(
+    'status', 'success',
+    'total_matching_count', COALESCE((SELECT MAX(total_matching) FROM sliced), (SELECT COUNT(*) FROM filtered)),
+    'returned_count', (SELECT COUNT(*) FROM sliced),
+    'rank_position', LOWER(COALESCE(p_rank_position, 'top')),
+    'items', COALESCE(
+      json_agg(
+        json_build_object(
+          'property_id', property_id,
+          'property_name', property_name,
+          'market', market,
+          'platform', platform,
+          'bedrooms', bedrooms,
+          'avg_rating', avg_rating,
+          'review_count', review_count,
+          'nightly_rate', nightly_rate,
+          'pct_above_trailing_avg', pct_above_trailing_avg,
+          'is_available', is_available,
+          'is_active', is_active,
+          'recorded_at', recorded_at
+        )
+      ), '[]'::json
+    )
+  )
+  FROM sliced;
+$function$;
+
+GRANT EXECUTE ON FUNCTION public.search_properties(text, text, text, integer, boolean, boolean, text, text, integer) TO anon, authenticated, service_role;
+
+
+-- ============================================================================
+-- 4. get_property_rate_changes
+-- ============================================================================
+-- Dropping previous TABLE(...) signatures and 3-parameter overload
+DROP FUNCTION IF EXISTS public.get_property_rate_changes(text, integer, integer);
+DROP FUNCTION IF EXISTS public.get_property_rate_changes(text, integer, integer, date, date);
+DROP FUNCTION IF EXISTS public.get_property_rate_changes(text, integer, integer, date, date, integer);
+
+CREATE OR REPLACE FUNCTION public.get_property_rate_changes(
+  property_search text,
+  days_param integer DEFAULT 14,
+  compare_window_days integer DEFAULT 1,
+  start_date date DEFAULT NULL::date,
+  end_date date DEFAULT NULL::date,
+  p_limit integer DEFAULT 14
+)
+RETURNS json
+LANGUAGE sql
+STABLE SECURITY DEFINER
+AS $function$
+  WITH target_prop AS (
+    SELECT id, name, market, platform, is_active
+    FROM public.properties
+    WHERE (id::text = property_search OR LOWER(name) = LOWER(property_search) OR LOWER(name) LIKE '%' || LOWER(property_search) || '%')
+    LIMIT 1
+  ),
+  daily_dedup AS (
+    SELECT DISTINCT ON (rh.stay_date::date)
+      rh.property_id,
+      tp.name AS property_name,
+      tp.market,
+      tp.platform,
+      tp.is_active,
+      rh.stay_date::date AS stay_date,
+      ROUND(rh.nightly_rate::numeric, 2) AS nightly_rate,
+      ROUND(rh.trailing_avg_rate::numeric, 2) AS trailing_avg_rate,
+      ROUND(rh.pct_above_trailing_avg::numeric, 2) AS pct_above_trailing_avg,
+      rh.recorded_at
+    FROM public.v_rate_volatility rh
+    JOIN target_prop tp ON tp.id = rh.property_id
+    WHERE
+      (
+        (start_date IS NOT NULL AND end_date IS NOT NULL AND rh.stay_date::date BETWEEN start_date AND end_date)
+        OR (start_date IS NULL AND rh.recorded_at >= (NOW() - (days_param || ' days')::interval))
+      )
+    ORDER BY rh.stay_date::date, rh.recorded_at DESC
+  ),
+  with_prev AS (
+    SELECT
+      *,
+      LAG(nightly_rate, compare_window_days) OVER (ORDER BY stay_date ASC) AS prev_nightly_rate
+    FROM daily_dedup
+  ),
+  formatted AS (
+    SELECT
+      property_id,
+      property_name,
+      market,
+      platform,
+      is_active,
+      stay_date,
+      nightly_rate,
+      trailing_avg_rate,
+      pct_above_trailing_avg,
+      ROUND(prev_nightly_rate::numeric, 2) AS prev_nightly_rate,
+      ROUND(
+        CASE
+          WHEN prev_nightly_rate IS NULL OR prev_nightly_rate = 0 OR nightly_rate IS NULL THEN NULL
+          ELSE ((nightly_rate - prev_nightly_rate) / prev_nightly_rate) * 100.0
+        END::numeric, 2
+      ) AS pct_change_vs_prev,
+      COUNT(*) OVER () AS total_matching
+    FROM with_prev
+    ORDER BY stay_date DESC
+    LIMIT LEAST(GREATEST(p_limit, 1), 30)
+  )
+  SELECT json_build_object(
+    'status', 'success',
+    'property_id', (SELECT id FROM target_prop),
+    'property_name', (SELECT name FROM target_prop),
+    'is_active', (SELECT is_active FROM target_prop),
+    'total_matching_count', COALESCE((SELECT MAX(total_matching) FROM formatted), 0),
+    'returned_count', (SELECT COUNT(*) FROM formatted),
+    'items', COALESCE(
+      json_agg(
+        json_build_object(
+          'stay_date', stay_date,
+          'nightly_rate', nightly_rate,
+          'trailing_avg_rate', trailing_avg_rate,
+          'pct_above_trailing_avg', pct_above_trailing_avg,
+          'prev_nightly_rate', prev_nightly_rate,
+          'pct_change_vs_prev', pct_change_vs_prev
+        )
+        ORDER BY stay_date ASC
+      ), '[]'::json
+    )
+  )
+  FROM formatted;
+$function$;
+
+GRANT EXECUTE ON FUNCTION public.get_property_rate_changes(text, integer, integer, date, date, integer) TO anon, authenticated, service_role;
+
+
+-- ============================================================================
+-- 5. get_market_trend
+-- ============================================================================
+-- Dropping previous signature without p_platform / p_is_active
+DROP FUNCTION IF EXISTS public.get_market_trend(text, integer);
+DROP FUNCTION IF EXISTS public.get_market_trend(text, integer, text, boolean);
+
+CREATE OR REPLACE FUNCTION public.get_market_trend(
+  p_market text,
+  p_days integer DEFAULT 14,
+  p_platform text DEFAULT NULL::text,
+  p_is_active boolean DEFAULT true
+)
+RETURNS json
+LANGUAGE plpgsql
+STABLE SECURITY DEFINER
+AS $function$
+DECLARE
+  v_midpoint timestamp with time zone;
+  v_early_avg numeric;
+  v_recent_avg numeric;
+  v_pct_change numeric;
+  v_direction text;
+  v_active_count integer;
+BEGIN
+  v_midpoint := NOW() - ((p_days / 2) || ' days')::interval;
+
+  -- Early period average
+  SELECT ROUND(AVG(rh.nightly_rate)::numeric, 2)
+  INTO v_early_avg
+  FROM public.rate_history rh
+  JOIN public.properties p ON p.id = rh.property_id
+  WHERE LOWER(p.market) = LOWER(p_market)
+    AND (p_platform IS NULL OR LOWER(p.platform) = LOWER(p_platform))
+    AND (p_is_active IS NULL OR p.is_active = p_is_active)
+    AND rh.nightly_rate IS NOT NULL
+    AND rh.stay_date < v_midpoint
+    AND rh.stay_date >= NOW() - (p_days || ' days')::interval;
+
+  -- Recent period average
+  SELECT ROUND(AVG(rh.nightly_rate)::numeric, 2)
+  INTO v_recent_avg
+  FROM public.rate_history rh
+  JOIN public.properties p ON p.id = rh.property_id
+  WHERE LOWER(p.market) = LOWER(p_market)
+    AND (p_platform IS NULL OR LOWER(p.platform) = LOWER(p_platform))
+    AND (p_is_active IS NULL OR p.is_active = p_is_active)
+    AND rh.nightly_rate IS NOT NULL
+    AND rh.stay_date >= v_midpoint;
+
+  SELECT COUNT(DISTINCT p.id)
+  INTO v_active_count
+  FROM public.properties p
+  WHERE LOWER(p.market) = LOWER(p_market)
+    AND (p_platform IS NULL OR LOWER(p.platform) = LOWER(p_platform))
+    AND (p_is_active IS NULL OR p.is_active = p_is_active);
+
+  IF v_early_avg IS NULL OR v_recent_avg IS NULL OR v_early_avg = 0 THEN
+    v_pct_change := 0.0;
+    v_direction := 'INSUFFICIENT_DATA';
+  ELSE
+    v_pct_change := ROUND(((v_recent_avg - v_early_avg) / v_early_avg * 100.0)::numeric, 2);
+    IF v_pct_change > 1.0 THEN
+      v_direction := 'UP';
+    ELSIF v_pct_change < -1.0 THEN
+      v_direction := 'DOWN';
+    ELSE
+      v_direction := 'FLAT';
+    END IF;
+  END IF;
+
+  RETURN json_build_object(
+    'status', 'success',
+    'market', p_market,
+    'platform', p_platform,
+    'properties_analyzed', v_active_count,
+    'period_days', p_days,
+    'early_period_avg', v_early_avg,
+    'recent_period_avg', v_recent_avg,
+    'pct_change', v_pct_change,
+    'trend_direction', v_direction
+  );
+END;
+$function$;
+
+GRANT EXECUTE ON FUNCTION public.get_market_trend(text, integer, text, boolean) TO anon, authenticated, service_role;
+
+
+-- ============================================================================
+-- 6. get_rate_anomaly_report
+-- ============================================================================
+DROP FUNCTION IF EXISTS public.get_rate_anomaly_report(text, integer, double precision);
+
+CREATE OR REPLACE FUNCTION public.get_rate_anomaly_report(
+  p_property_search text,
+  p_days integer DEFAULT 30,
+  p_deviation_threshold double precision DEFAULT 25.0
+)
+RETURNS json
+LANGUAGE plpgsql
+STABLE SECURITY DEFINER
+AS $function$
+DECLARE
+  v_property_id uuid;
+  v_property_name text;
+  v_market text;
+  v_platform text;
+  v_is_active boolean;
+  v_total_readings integer;
+  v_anomaly_count integer;
+  v_normal_min numeric;
+  v_normal_max numeric;
+  v_recent_anomalies json;
+  v_trailing_avg numeric;
+BEGIN
+  -- Resolve property
+  SELECT id, name, market, platform, is_active
+  INTO v_property_id, v_property_name, v_market, v_platform, v_is_active
+  FROM public.properties
+  WHERE id::text = p_property_search
+     OR LOWER(name) = LOWER(p_property_search)
+     OR LOWER(name) LIKE '%' || LOWER(p_property_search) || '%'
+  LIMIT 1;
+
+  IF v_property_id IS NULL THEN
+    RETURN json_build_object('status', 'error', 'message', 'Property not found: ' || p_property_search);
+  END IF;
+
+  -- Total observations in window
+  SELECT COUNT(*), ROUND(AVG(nightly_rate)::numeric, 2)
+  INTO v_total_readings, v_trailing_avg
+  FROM public.rate_history
+  WHERE property_id = v_property_id
+    AND created_at >= NOW() - (p_days || ' days')::interval
+    AND nightly_rate IS NOT NULL;
+
+  -- Anomalous rows (join on v.id = rh.id)
+  SELECT COUNT(*)
+  INTO v_anomaly_count
+  FROM public.rate_history rh
+  JOIN public.v_rate_volatility v ON v.id = rh.id
+  WHERE rh.property_id = v_property_id
+    AND rh.created_at >= NOW() - (p_days || ' days')::interval
+    AND rh.nightly_rate IS NOT NULL
+    AND ABS(v.pct_above_trailing_avg) >= p_deviation_threshold;
+
+  -- Normal rate baseline (explicitly qualified rh.nightly_rate)
+  SELECT
+    ROUND(MIN(rh.nightly_rate)::numeric, 2),
+    ROUND(MAX(rh.nightly_rate)::numeric, 2)
+  INTO v_normal_min, v_normal_max
+  FROM public.rate_history rh
+  JOIN public.v_rate_volatility v ON v.id = rh.id
+  WHERE rh.property_id = v_property_id
+    AND rh.created_at >= NOW() - (p_days || ' days')::interval
+    AND rh.nightly_rate IS NOT NULL
+    AND ABS(v.pct_above_trailing_avg) < p_deviation_threshold;
+
+  -- Most recent 5 anomalies
+  SELECT json_agg(r)
+  INTO v_recent_anomalies
+  FROM (
+    SELECT
+      rh.stay_date::date AS stay_date,
+      ROUND(rh.nightly_rate::numeric, 2) AS nightly_rate,
+      ROUND(v.trailing_avg_rate::numeric, 2) AS trailing_avg_rate,
+      ROUND(v.pct_above_trailing_avg::numeric, 2) AS pct_above_trailing_avg,
+      rh.created_at AS recorded_at
+    FROM public.rate_history rh
+    JOIN public.v_rate_volatility v ON v.id = rh.id
+    WHERE rh.property_id = v_property_id
+      AND rh.created_at >= NOW() - (p_days || ' days')::interval
+      AND rh.nightly_rate IS NOT NULL
+      AND ABS(v.pct_above_trailing_avg) >= p_deviation_threshold
+    ORDER BY rh.created_at DESC
+    LIMIT 5
+  ) r;
+
+  RETURN json_build_object(
+    'status', 'success',
+    'property_id', v_property_id,
+    'property_name', v_property_name,
+    'market', v_market,
+    'platform', v_platform,
+    'is_active', v_is_active,
+    'lookback_days', p_days,
+    'deviation_threshold_pct', p_deviation_threshold,
+    'baseline_avg_rate', v_trailing_avg,
+    'normal_rate_range', json_build_object('min', v_normal_min, 'max', v_normal_max),
+    'total_observations', v_total_readings,
+    'anomaly_count', v_anomaly_count,
+    'anomaly_rate_pct', ROUND((v_anomaly_count::numeric / NULLIF(v_total_readings, 0) * 100.0), 2),
+    'recent_anomalies', COALESCE(v_recent_anomalies, '[]'::json)
+  );
+END;
+$function$;
+
+GRANT EXECUTE ON FUNCTION public.get_rate_anomaly_report(text, integer, double precision) TO anon, authenticated, service_role;
+
+
+-- ============================================================================
+-- 7. compare_properties
+-- ============================================================================
+DROP FUNCTION IF EXISTS public.compare_properties(text[]);
+
+CREATE OR REPLACE FUNCTION public.compare_properties(
+  p_property_ids text[]
+)
+RETURNS json
+LANGUAGE sql
+STABLE SECURITY DEFINER
+AS $function$
+  SELECT json_build_object(
+    'status', 'success',
+    'compared_count', (SELECT COUNT(*) FROM (
+      SELECT DISTINCT ON (rvv.property_id) rvv.property_id
+      FROM public.v_rate_volatility rvv
+      WHERE rvv.property_id::text = ANY(p_property_ids)
+         OR rvv.property_name ILIKE ANY(
+             SELECT '%' || unnest || '%' FROM unnest(p_property_ids)
+           )
+      ORDER BY rvv.property_id, rvv.recorded_at DESC
+      LIMIT 5
+    ) c),
+    'compared', COALESCE(
+      json_agg(
+        json_build_object(
+          'property_id', v.property_id,
+          'property_name', v.property_name,
+          'market', v.market,
+          'platform', v.platform,
+          'bedrooms', v.bedrooms,
+          'is_active', v.is_active,
+          'current_rate', ROUND(v.nightly_rate::numeric, 2),
+          'trailing_7d_avg', ROUND(v.trailing_avg_rate::numeric, 2),
+          'pct_above_trailing_avg', ROUND(v.pct_above_trailing_avg::numeric, 2),
+          'is_available', v.is_available,
+          'avg_rating', ROUND(v.avg_rating::numeric, 2),
+          'review_count', v.review_count,
+          'last_recorded', v.recorded_at
+        )
+        ORDER BY v.property_name
+      ), '[]'::json
+    )
+  )
+  FROM (
+    SELECT DISTINCT ON (rvv.property_id) rvv.*
+    FROM public.v_rate_volatility rvv
+    WHERE rvv.property_id::text = ANY(p_property_ids)
+       OR rvv.property_name ILIKE ANY(
+           SELECT '%' || unnest || '%' FROM unnest(p_property_ids)
+         )
+    ORDER BY rvv.property_id, rvv.recorded_at DESC
+    LIMIT 5
+  ) v;
+$function$;
+
+GRANT EXECUTE ON FUNCTION public.compare_properties(text[]) TO anon, authenticated, service_role;
+
+
+-- ============================================================================
+-- 8. get_spike_alerts
+-- ============================================================================
+-- Dropping previous TABLE(...) signature and overloads
+DROP FUNCTION IF EXISTS public.get_spike_alerts(numeric, integer);
+DROP FUNCTION IF EXISTS public.get_spike_alerts(numeric, integer, text, integer, text);
+
+CREATE OR REPLACE FUNCTION public.get_spike_alerts(
+  threshold_param numeric DEFAULT 25.0,
+  days_param integer DEFAULT 7,
+  p_market text DEFAULT NULL::text,
+  p_limit integer DEFAULT 8,
+  p_rank_position text DEFAULT 'top'::text
+)
+RETURNS json
+LANGUAGE sql
+STABLE SECURITY DEFINER
+AS $function$
+  WITH all_spikes AS (
+    SELECT
+      property_id,
+      property_name,
+      market,
+      platform,
+      is_active,
+      stay_date::date AS stay_date,
+      ROUND(nightly_rate::numeric, 2) AS nightly_rate,
+      ROUND(trailing_avg_rate::numeric, 2) AS trailing_avg_rate,
+      ROUND(pct_above_trailing_avg::numeric, 2) AS pct_above_trailing_avg,
+      recorded_at
+    FROM public.v_rate_volatility
+    WHERE ABS(pct_above_trailing_avg) >= threshold_param
+      AND recorded_at >= NOW() - (days_param || ' days')::interval
+      AND (p_market IS NULL OR LOWER(market) = LOWER(p_market))
+  ),
+  ranked AS (
+    SELECT
+      *,
+      COUNT(*) OVER () AS total_matching,
+      ROW_NUMBER() OVER (ORDER BY ABS(pct_above_trailing_avg) DESC) AS rank_asc,
+      ROW_NUMBER() OVER (ORDER BY ABS(pct_above_trailing_avg) ASC) AS rank_desc
+    FROM all_spikes
+  ),
+  sliced AS (
+    SELECT
+      property_id,
+      property_name,
+      market,
+      platform,
+      is_active,
+      stay_date,
+      nightly_rate,
+      trailing_avg_rate,
+      pct_above_trailing_avg,
+      recorded_at,
+      total_matching
+    FROM ranked
+    WHERE
+      CASE
+        WHEN LOWER(p_rank_position) = 'bottom' THEN
+          rank_desc <= LEAST(GREATEST(p_limit, 1), 15)
+        WHEN LOWER(p_rank_position) = 'middle' THEN
+          rank_asc > GREATEST(0, (total_matching - LEAST(GREATEST(p_limit, 1), 15)) / 2)
+          AND rank_asc <= GREATEST(0, (total_matching - LEAST(GREATEST(p_limit, 1), 15)) / 2) + LEAST(GREATEST(p_limit, 1), 15)
+        ELSE -- 'top'
+          rank_asc <= LEAST(GREATEST(p_limit, 1), 15)
+      END
+    ORDER BY
+      CASE WHEN LOWER(p_rank_position) = 'bottom' THEN rank_desc ELSE rank_asc END ASC
+  )
+  SELECT json_build_object(
+    'status', 'success',
+    'total_matching_count', COALESCE((SELECT MAX(total_matching) FROM sliced), (SELECT COUNT(*) FROM all_spikes)),
+    'returned_count', (SELECT COUNT(*) FROM sliced),
+    'rank_position', LOWER(COALESCE(p_rank_position, 'top')),
+    'items', COALESCE(
+      json_agg(
+        json_build_object(
+          'property_id', property_id,
+          'property_name', property_name,
+          'market', market,
+          'platform', platform,
+          'is_active', is_active,
+          'stay_date', stay_date,
+          'nightly_rate', nightly_rate,
+          'trailing_avg_rate', trailing_avg_rate,
+          'pct_above_trailing_avg', pct_above_trailing_avg,
+          'recorded_at', recorded_at
+        )
+      ), '[]'::json
+    )
+  )
+  FROM sliced;
+$function$;
+
+GRANT EXECUTE ON FUNCTION public.get_spike_alerts(numeric, integer, text, integer, text) TO anon, authenticated, service_role;
+
+
+-- ============================================================================
+-- 9. get_most_volatile_properties
+-- ============================================================================
+DROP FUNCTION IF EXISTS public.get_most_volatile_properties(text, integer, integer);
+DROP FUNCTION IF EXISTS public.get_most_volatile_properties(text, integer, integer, text);
+
+CREATE OR REPLACE FUNCTION public.get_most_volatile_properties(
+  p_market text DEFAULT NULL::text,
+  p_days integer DEFAULT 14,
+  p_limit integer DEFAULT 5,
+  p_rank_position text DEFAULT 'top'::text
+)
+RETURNS json
+LANGUAGE sql
+STABLE SECURITY DEFINER
+AS $function$
+  WITH property_vol AS (
+    SELECT
+      v.property_id,
+      v.property_name,
+      v.market,
+      v.platform,
+      v.is_active,
+      ROUND(STDDEV(v.nightly_rate)::numeric, 2) AS rate_stddev,
+      COUNT(CASE WHEN ABS(v.pct_above_trailing_avg) >= 25 THEN 1 END) AS spike_count,
+      ROUND(AVG(v.nightly_rate)::numeric, 2) AS avg_rate,
+      ROUND(MIN(v.nightly_rate)::numeric, 2) AS min_rate,
+      ROUND(MAX(v.nightly_rate)::numeric, 2) AS max_rate,
+      COUNT(*) AS observation_count
+    FROM public.v_rate_volatility v
+    WHERE v.recorded_at >= NOW() - (p_days || ' days')::interval
+      AND v.nightly_rate IS NOT NULL
+      AND (p_market IS NULL OR LOWER(v.market) = LOWER(p_market))
+    GROUP BY v.property_id, v.property_name, v.market, v.platform, v.is_active
+    HAVING COUNT(*) >= 2
+  ),
+  ranked AS (
+    SELECT
+      *,
+      COUNT(*) OVER () AS total_matching,
+      ROW_NUMBER() OVER (ORDER BY COALESCE(rate_stddev, 0) DESC, spike_count DESC) AS rank_asc,
+      ROW_NUMBER() OVER (ORDER BY COALESCE(rate_stddev, 0) ASC, spike_count ASC) AS rank_desc
+    FROM property_vol
+  ),
+  sliced AS (
+    SELECT
+      property_id,
+      property_name,
+      market,
+      platform,
+      is_active,
+      rate_stddev,
+      spike_count,
+      avg_rate,
+      min_rate,
+      max_rate,
+      observation_count,
+      total_matching
+    FROM ranked
+    WHERE
+      CASE
+        WHEN LOWER(p_rank_position) = 'bottom' THEN
+          rank_desc <= LEAST(GREATEST(p_limit, 1), 15)
+        WHEN LOWER(p_rank_position) = 'middle' THEN
+          rank_asc > GREATEST(0, (total_matching - LEAST(GREATEST(p_limit, 1), 15)) / 2)
+          AND rank_asc <= GREATEST(0, (total_matching - LEAST(GREATEST(p_limit, 1), 15)) / 2) + LEAST(GREATEST(p_limit, 1), 15)
+        ELSE -- 'top'
+          rank_asc <= LEAST(GREATEST(p_limit, 1), 15)
+      END
+    ORDER BY
+      CASE WHEN LOWER(p_rank_position) = 'bottom' THEN rank_desc ELSE rank_asc END ASC
+  )
+  SELECT json_build_object(
+    'status', 'success',
+    'market_filter', p_market,
+    'period_days', p_days,
+    'total_matching_count', COALESCE((SELECT MAX(total_matching) FROM sliced), (SELECT COUNT(*) FROM property_vol)),
+    'returned_count', (SELECT COUNT(*) FROM sliced),
+    'rank_position', LOWER(COALESCE(p_rank_position, 'top')),
+    'items', COALESCE(
+      json_agg(
+        json_build_object(
+          'property_id', property_id,
+          'property_name', property_name,
+          'market', market,
+          'platform', platform,
+          'is_active', is_active,
+          'rate_stddev', rate_stddev,
+          'spike_count', spike_count,
+          'avg_rate', avg_rate,
+          'min_rate', min_rate,
+          'max_rate', max_rate,
+          'observation_count', observation_count
+        )
+      ), '[]'::json
+    )
+  )
+  FROM sliced;
+$function$;
+
+GRANT EXECUTE ON FUNCTION public.get_most_volatile_properties(text, integer, integer, text) TO anon, authenticated, service_role;
+
+
+-- ============================================================================
+-- 10. get_property_snapshot
+-- ============================================================================
+DROP FUNCTION IF EXISTS public.get_property_snapshot(text);
+
+CREATE OR REPLACE FUNCTION public.get_property_snapshot(
+  p_property_search text
+)
+RETURNS json
+LANGUAGE sql
+STABLE SECURITY DEFINER
+AS $function$
+  SELECT json_build_object(
+    'status', 'success',
+    'property_id', v.property_id,
+    'property_name', v.property_name,
+    'market', v.market,
+    'platform', v.platform,
+    'bedrooms', v.bedrooms,
+    'is_active', v.is_active,
+    'current_rate', ROUND(v.nightly_rate::numeric, 2),
+    'trailing_7d_avg', ROUND(v.trailing_avg_rate::numeric, 2),
+    'pct_above_trailing_avg', ROUND(v.pct_above_trailing_avg::numeric, 2),
+    'is_available', v.is_available,
+    'avg_rating', ROUND(v.avg_rating::numeric, 2),
+    'review_count', v.review_count,
+    'listing_url', v.url,
+    'coordinates', json_build_object('lat', v.latitude, 'lng', v.longitude),
+    'last_recorded', v.recorded_at
+  )
+  FROM (
+    SELECT DISTINCT ON (rvv.property_id) rvv.*
+    FROM public.v_rate_volatility rvv
+    WHERE rvv.property_id::text = p_property_search
+       OR LOWER(rvv.property_name) = LOWER(p_property_search)
+       OR LOWER(rvv.property_name) LIKE '%' || LOWER(p_property_search) || '%'
+    ORDER BY rvv.property_id, rvv.recorded_at DESC
+    LIMIT 1
+  ) v;
+$function$;
+
+GRANT EXECUTE ON FUNCTION public.get_property_snapshot(text) TO anon, authenticated, service_role;
+
+
+-- ============================================================================
+-- 11. get_nearby_properties
+-- ============================================================================
+DROP FUNCTION IF EXISTS public.get_nearby_properties(numeric, numeric, numeric, integer);
+
+CREATE OR REPLACE FUNCTION public.get_nearby_properties(
+  p_latitude numeric,
+  p_longitude numeric,
+  p_radius_km numeric DEFAULT 5.0,
+  p_limit integer DEFAULT 6
+)
+RETURNS json
+LANGUAGE sql
+STABLE SECURITY DEFINER
+AS $function$
+  WITH calculated AS (
+    SELECT DISTINCT ON (rvv.property_id)
+      rvv.property_id,
+      rvv.property_name,
+      rvv.market,
+      rvv.platform,
+      rvv.bedrooms,
+      rvv.is_active,
+      ROUND(rvv.nightly_rate::numeric, 2) AS nightly_rate,
+      ROUND(rvv.avg_rating::numeric, 2) AS avg_rating,
+      rvv.review_count,
+      rvv.is_available,
+      ROUND((
+        6371.0 * acos(
+          LEAST(1.0, GREATEST(-1.0,
+            cos(radians(p_latitude))
+            * cos(radians(rvv.latitude))
+            * cos(radians(rvv.longitude) - radians(p_longitude))
+            + sin(radians(p_latitude))
+            * sin(radians(rvv.latitude))
+          ))
+        )
+      )::numeric, 2) AS distance_km
+    FROM public.v_rate_volatility rvv
+    WHERE rvv.latitude IS NOT NULL
+      AND rvv.longitude IS NOT NULL
+    ORDER BY rvv.property_id, rvv.recorded_at DESC
+  ),
+  within_radius AS (
+    SELECT *, COUNT(*) OVER () AS total_matching
+    FROM calculated
+    WHERE distance_km <= p_radius_km
+    ORDER BY distance_km ASC
+    LIMIT LEAST(GREATEST(p_limit, 1), 20)
+  )
+  SELECT json_build_object(
+    'status', 'success',
+    'search_center', json_build_object('lat', p_latitude, 'lng', p_longitude),
+    'radius_km', p_radius_km,
+    'total_matching_count', COALESCE((SELECT MAX(total_matching) FROM within_radius), 0),
+    'returned_count', (SELECT COUNT(*) FROM within_radius),
+    'items', COALESCE(
+      json_agg(
+        json_build_object(
+          'property_id', property_id,
+          'property_name', property_name,
+          'market', market,
+          'platform', platform,
+          'bedrooms', bedrooms,
+          'is_active', is_active,
+          'nightly_rate', nightly_rate,
+          'is_available', is_available,
+          'avg_rating', avg_rating,
+          'review_count', review_count,
+          'distance_km', distance_km
+        )
+        ORDER BY distance_km ASC
+      ), '[]'::json
+    )
+  )
+  FROM within_radius;
+$function$;
+
+GRANT EXECUTE ON FUNCTION public.get_nearby_properties(numeric, numeric, numeric, integer) TO anon, authenticated, service_role;
+
+
+-- ============================================================================
+-- 12. get_recently_changed_tracking
+-- ============================================================================
+DROP FUNCTION IF EXISTS public.get_recently_changed_tracking(integer);
+
+CREATE OR REPLACE FUNCTION public.get_recently_changed_tracking(
+  p_days integer DEFAULT 30
+)
+RETURNS json
+LANGUAGE sql
+STABLE SECURITY DEFINER
+AS $function$
+  WITH newly_added AS (
+    SELECT
+      id AS property_id,
+      name AS property_name,
+      market,
+      platform,
+      is_active,
+      created_at AS tracking_started_at
+    FROM public.properties
+    WHERE created_at >= NOW() - (p_days || ' days')::interval
+    ORDER BY created_at DESC
+    LIMIT 10
+  ),
+  untracked_props AS (
+    SELECT
+      id AS property_id,
+      name AS property_name,
+      market,
+      platform,
+      is_active,
+      updated_at AS status_changed_at
+    FROM public.properties
+    WHERE is_active = false
+      AND updated_at >= NOW() - (p_days || ' days')::interval
+    ORDER BY updated_at DESC
+    LIMIT 10
+  )
+  SELECT json_build_object(
+    'status', 'success',
+    'period_days', p_days,
+    'newly_added_count', (SELECT COUNT(*) FROM newly_added),
+    'newly_added', COALESCE((SELECT json_agg(na) FROM newly_added na), '[]'::json),
+    'untracked_count', (SELECT COUNT(*) FROM untracked_props),
+    'untracked_or_removed', COALESCE((SELECT json_agg(up) FROM untracked_props up), '[]'::json)
+  );
+$function$;
+
+GRANT EXECUTE ON FUNCTION public.get_recently_changed_tracking(integer) TO anon, authenticated, service_role;
+
+
+-- ============================================================================
+-- 13. get_real_estate_kpis (NEW)
+-- ============================================================================
+DROP FUNCTION IF EXISTS public.get_real_estate_kpis(text, text, integer, boolean, uuid[], date, date);
+
+CREATE OR REPLACE FUNCTION public.get_real_estate_kpis(
+  p_market        TEXT     DEFAULT NULL,
+  p_platform      TEXT     DEFAULT NULL,
+  p_bedrooms      INTEGER  DEFAULT NULL,
+  p_is_active     BOOLEAN  DEFAULT true,
+  p_property_ids  UUID[]   DEFAULT NULL,
+  p_start_date    DATE     DEFAULT NULL,
+  p_end_date      DATE     DEFAULT NULL
+)
+RETURNS json
+LANGUAGE sql
+SECURITY DEFINER
+AS $function$
+  WITH filtered_props AS (
+    SELECT DISTINCT ON (property_id)
+      property_id,
+      market,
+      platform,
+      bedrooms,
+      is_active,
+      is_available,
+      stay_date
+    FROM public.v_rate_volatility
+    WHERE (p_market       IS NULL OR market      = p_market)
+      AND (p_platform     IS NULL OR platform    = p_platform)
+      AND (p_bedrooms     IS NULL OR bedrooms    = p_bedrooms)
+      AND (p_is_active    IS NULL OR is_active   = p_is_active)
+      AND (p_property_ids IS NULL OR property_id = ANY(p_property_ids))
+      AND (p_start_date   IS NULL OR stay_date  >= p_start_date)
+      AND (p_end_date     IS NULL OR stay_date  <= p_end_date)
+    ORDER BY property_id, recorded_at DESC
+  )
+  SELECT json_build_object(
+    'status', 'success',
+    'domain', 'real_estate',
+    'filters_applied', json_build_object(
+      'market', p_market,
+      'platform', p_platform,
+      'bedrooms', p_bedrooms,
+      'is_active', p_is_active,
+      'start_date', p_start_date,
+      'end_date', p_end_date
+    ),
+    'properties_tracked', (SELECT COUNT(*) FROM filtered_props),
+    'available_count', (SELECT COUNT(*) FILTER (WHERE is_available = true) FROM filtered_props),
+    'unavailable_count', (SELECT COUNT(*) FILTER (WHERE is_available = false) FROM filtered_props),
+    'availability_rate_pct', (
+      SELECT ROUND(
+        100.0 * COUNT(*) FILTER (WHERE is_available = true)
+        / NULLIF(COUNT(*), 0), 2
+      )
+      FROM filtered_props
+    ),
+    'rate_changes_7d', (
+      SELECT COUNT(*)
+      FROM public.rate_history rh
+      JOIN public.properties p ON p.id = rh.property_id
+      WHERE rh.created_at >= NOW() - INTERVAL '7 days'
+        AND rh.nightly_rate IS NOT NULL
+        AND rh.nightly_rate != (
+          SELECT nightly_rate FROM public.rate_history rh2
+          WHERE rh2.property_id = rh.property_id
+            AND rh2.created_at  < rh.created_at
+            AND rh2.nightly_rate IS NOT NULL
+          ORDER BY rh2.created_at DESC LIMIT 1
+        )
+        AND (p_market       IS NULL OR p.market    = p_market)
+        AND (p_platform     IS NULL OR p.platform  = p_platform)
+        AND (p_bedrooms     IS NULL OR p.bedrooms  = p_bedrooms)
+        AND (p_is_active    IS NULL OR p.is_active = p_is_active)
+        AND (p_property_ids IS NULL OR p.id        = ANY(p_property_ids))
+    ),
+    'spikes_7d', (
+      SELECT COUNT(*)
+      FROM public.v_rate_volatility
+      WHERE ABS(pct_above_trailing_avg) >= 25
+        AND recorded_at >= NOW() - INTERVAL '7 days'
+        AND (p_market       IS NULL OR market      = p_market)
+        AND (p_platform     IS NULL OR platform    = p_platform)
+        AND (p_bedrooms     IS NULL OR bedrooms    = p_bedrooms)
+        AND (p_is_active    IS NULL OR is_active   = p_is_active)
+        AND (p_property_ids IS NULL OR property_id = ANY(p_property_ids))
+        AND (p_start_date   IS NULL OR stay_date  >= p_start_date)
+        AND (p_end_date     IS NULL OR stay_date  <= p_end_date)
+    ),
+    'tracking_since', (
+      SELECT MIN(created_at) FROM public.properties
+      WHERE (p_market IS NULL OR market = p_market)
+    ),
+    'scrape_health', (
+      SELECT COALESCE(json_object_agg(platform, last_status), '{}'::json)
+      FROM public.v_scrape_health
+      WHERE job_type = 'REAL_ESTATE_MONITOR'
+    )
+  );
+$function$;
+
+GRANT EXECUTE ON FUNCTION public.get_real_estate_kpis(text, text, integer, boolean, uuid[], date, date) TO anon, authenticated, service_role;
+
+
+-- ============================================================================
+-- 14. get_property_detail (NEW)
+-- ============================================================================
+DROP FUNCTION IF EXISTS public.get_property_detail(text, integer);
+
+CREATE OR REPLACE FUNCTION public.get_property_detail(
+  p_property_search text,
+  p_history_days integer DEFAULT 14
+)
+RETURNS json
+LANGUAGE sql
+STABLE SECURITY DEFINER
+AS $function$
+  WITH prop AS (
+    SELECT
+      id, name, market, platform, bedrooms,
+      latitude, longitude, url, is_active, created_at
+    FROM public.properties
+    WHERE id::text = p_property_search
+       OR LOWER(name) = LOWER(p_property_search)
+       OR LOWER(name) LIKE '%' || LOWER(p_property_search) || '%'
+    LIMIT 1
+  ),
+  latest_reading AS (
+    SELECT DISTINCT ON (property_id)
+      nightly_rate,
+      trailing_avg_rate,
+      pct_above_trailing_avg,
+      is_available,
+      avg_rating,
+      review_count,
+      recorded_at
+    FROM public.v_rate_volatility
+    WHERE property_id = (SELECT id FROM prop)
+    ORDER BY property_id, recorded_at DESC
+  ),
+  daily_history AS (
+    SELECT DISTINCT ON (stay_date::date)
+      stay_date::date AS stay_date,
+      ROUND(nightly_rate::numeric, 2) AS nightly_rate,
+      ROUND(trailing_avg_rate::numeric, 2) AS trailing_avg_rate,
+      ROUND(pct_above_trailing_avg::numeric, 2) AS pct_above_trailing_avg,
+      is_available
+    FROM public.v_rate_volatility
+    WHERE property_id = (SELECT id FROM prop)
+      AND recorded_at >= NOW() - (LEAST(GREATEST(p_history_days, 1), 30) || ' days')::interval
+    ORDER BY stay_date::date, recorded_at DESC
+  )
+  SELECT json_build_object(
+    'status', 'success',
+    'property_id', p.id,
+    'property_name', p.name,
+    'market', p.market,
+    'platform', p.platform,
+    'bedrooms', p.bedrooms,
+    'is_active', p.is_active,
+    'listing_url', p.url,
+    'coordinates', json_build_object('lat', p.latitude, 'lng', p.longitude),
+    'current_rate', ROUND(lr.nightly_rate::numeric, 2),
+    'trailing_7d_avg', ROUND(lr.trailing_avg_rate::numeric, 2),
+    'pct_above_trailing_avg', ROUND(lr.pct_above_trailing_avg::numeric, 2),
+    'is_available', lr.is_available,
+    'avg_rating', ROUND(lr.avg_rating::numeric, 2),
+    'review_count', lr.review_count,
+    'last_scraped_at', lr.recorded_at,
+    'rate_history_days', (SELECT COUNT(*) FROM daily_history),
+    'rate_history', COALESCE(
+      (
+        SELECT json_agg(
+          json_build_object(
+            'stay_date', dh.stay_date,
+            'nightly_rate', dh.nightly_rate,
+            'trailing_avg', dh.trailing_avg_rate,
+            'pct_deviation', dh.pct_above_trailing_avg,
+            'is_available', dh.is_available
+          )
+          ORDER BY dh.stay_date ASC
+        )
+        FROM daily_history dh
+      ), '[]'::json
+    )
+  )
+  FROM prop p
+  LEFT JOIN latest_reading lr ON true;
+$function$;
+
+GRANT EXECUTE ON FUNCTION public.get_property_detail(text, integer) TO anon, authenticated, service_role;

services/supabase_service.py

@@ -33,7 +33,7 @@ async def execute_tool_rpc(func_name: str, args: dict) -> dict:
 
     All parameter normalization, clamping, and validation is applied here.
     Constructs clean keyword arguments matching the exact Postgres DDL signatures
-    in all_rpcs.sql to prevent PostgREST PGRST202 schema lookup errors.
+    in pulse_ai_revamped_rpcs.sql to prevent PostgREST schema lookup errors.
     """
     if func_name in _PYTHON_SIDE_TOOLS:
         return {
@@ -43,29 +43,26 @@ async def execute_tool_rpc(func_name: str, args: dict) -> dict:
 
     clean_args: dict = {}
 
-    # ── 1. get_dashboard_kpis ────────────────────────────────────────────────
-    if func_name == "get_dashboard_kpis":
-        # RPC: (p_market, p_platform, p_bedrooms, p_is_active, p_property_ids, p_start_date, p_end_date)
+    # ── 1. get_real_estate_kpis (and legacy get_dashboard_kpis) ──
+    if func_name in ("get_real_estate_kpis", "get_dashboard_kpis"):
         clean_args = {
             "p_market": args.get("p_market") or args.get("market"),
             "p_platform": args.get("p_platform") or args.get("platform"),
-            "p_bedrooms": args.get("p_bedrooms") or args.get("bedrooms"),
-            "p_is_active": args.get("p_is_active") if "p_is_active" in args else args.get("is_active"),
+            "p_bedrooms": int(args["p_bedrooms"]) if args.get("p_bedrooms") is not None else None,
+            "p_is_active": args.get("p_is_active") if "p_is_active" in args else True,
             "p_property_ids": args.get("p_property_ids") or args.get("property_ids"),
             "p_start_date": args.get("p_start_date") or args.get("start_date"),
             "p_end_date": args.get("p_end_date") or args.get("end_date"),
         }
 
-    # ── 2. get_market_averages ───────────────────────────────────────────────
+    # ── 2. get_market_averages ──
     elif func_name == "get_market_averages":
-        # RPC: (market_param text)
         market = args.get("market_param") or args.get("p_market") or args.get("market")
         if market:
             clean_args["market_param"] = str(market)
 
-    # ── 3. get_market_snapshot ───────────────────────────────────────────────
+    # ── 3. get_market_snapshot ──
     elif func_name == "get_market_snapshot":
-        # RPC: (p_market text, p_start_date date, p_end_date date)
         market = args.get("p_market") or args.get("market") or "Miami"
         start = args.get("p_start_date") or args.get("start_date")
         end = args.get("p_end_date") or args.get("end_date")
@@ -86,29 +83,37 @@ async def execute_tool_rpc(func_name: str, args: dict) -> dict:
             "p_end_date": end,
         }
 
-    # ── 4. get_market_trend ──────────────────────────────────────────────────
+    # ── 4. get_market_trend ──
     elif func_name == "get_market_trend":
-        # RPC: (p_market text, p_days integer)
         market = args.get("p_market") or args.get("market") or "Miami"
         days = _clamp(args.get("p_days") or args.get("days"), 7, 90, default=14)
+        plat = args.get("p_platform") or args.get("platform")
+        is_act = args.get("p_is_active") if "p_is_active" in args else True
         clean_args = {
             "p_market": market,
             "p_days": days,
+            "p_platform": str(plat) if plat else None,
+            "p_is_active": bool(is_act),
         }
 
-    # ── 5. get_spike_alerts ──────────────────────────────────────────────────
+    # ── 5. get_spike_alerts ──
     elif func_name == "get_spike_alerts":
-        # RPC: (threshold_param numeric, days_param integer)
         thresh = args.get("threshold_param") or args.get("p_threshold") or args.get("threshold") or 25.0
         days = _clamp(args.get("days_param") or args.get("p_days") or args.get("days"), 1, 30, default=7)
+        market = args.get("p_market") or args.get("market")
+        limit = _clamp(args.get("p_limit") or args.get("limit"), 1, 15, default=8)
+        pos = args.get("p_rank_position") or args.get("rank_position") or "top"
+        pos = str(pos).lower() if str(pos).lower() in ("top", "bottom", "middle") else "top"
         clean_args = {
             "threshold_param": max(5.0, min(float(thresh), 100.0)),
             "days_param": days,
+            "p_market": str(market) if market else None,
+            "p_limit": limit,
+            "p_rank_position": pos,
         }
 
-    # ── 6. get_rate_anomaly_report ───────────────────────────────────────────
+    # ── 6. get_rate_anomaly_report ──
     elif func_name == "get_rate_anomaly_report":
-        # RPC: (p_property_search text, p_days integer, p_deviation_threshold double precision)
         search = args.get("p_property_search") or args.get("p_search") or args.get("p_market") or args.get("property_search") or ""
         days = _clamp(args.get("p_days") or args.get("days"), 1, 90, default=30)
         dev = args.get("p_deviation_threshold") or args.get("p_threshold") or args.get("deviation_threshold") or 25.0
@@ -118,71 +123,77 @@ async def execute_tool_rpc(func_name: str, args: dict) -> dict:
             "p_deviation_threshold": max(5.0, min(float(dev), 100.0)),
         }
 
-    # ── 7. get_most_volatile_properties ──────────────────────────────────────
+    # ── 7. get_most_volatile_properties ──
     elif func_name == "get_most_volatile_properties":
-        # RPC: (p_market text, p_days integer, p_limit integer)
         market = args.get("p_market") or args.get("market")
         days = _clamp(args.get("p_days") or args.get("days"), 7, 90, default=14)
-        limit = _clamp(args.get("p_limit") or args.get("limit"), 1, 50, default=5)
+        limit = _clamp(args.get("p_limit") or args.get("limit"), 1, 15, default=5)
+        pos = args.get("p_rank_position") or args.get("rank_position") or "top"
+        pos = str(pos).lower() if str(pos).lower() in ("top", "bottom", "middle") else "top"
         clean_args = {
             "p_market": market,
             "p_days": days,
             "p_limit": limit,
+            "p_rank_position": pos,
         }
 
-    # ── 8. get_property_snapshot ─────────────────────────────────────────────
+    # ── 8. get_property_snapshot ──
     elif func_name == "get_property_snapshot":
-        # RPC: (p_property_search text)
         search = args.get("p_property_search") or args.get("p_property_id") or args.get("property_search") or args.get("property_id")
         if not search:
             return {"status": "error", "message": "get_property_snapshot requires p_property_search (UUID or property title)."}
         clean_args = {"p_property_search": str(search)}
 
-    # ── 9. get_property_rate_changes ─────────────────────────────────────────
+    # ── 9. get_property_rate_changes ──
     elif func_name == "get_property_rate_changes":
-        # RPC: (property_search text, days_param integer, compare_window_days integer, start_date date, end_date date)
         search = args.get("property_search") or args.get("p_property_search") or args.get("p_property_id") or args.get("property_id") or args.get("p_market") or ""
         start = args.get("start_date") or args.get("p_start_date")
         end = args.get("end_date") or args.get("p_end_date")
         days = _clamp(args.get("days_param") or args.get("p_days") or args.get("days"), 1, 90, default=14)
         comp = _clamp(args.get("compare_window_days"), 1, 14, default=1)
+        limit = _clamp(args.get("p_limit") or args.get("limit"), 1, 30, default=14)
         clean_args = {
             "property_search": str(search),
             "days_param": days,
             "compare_window_days": comp,
             "start_date": start,
             "end_date": end,
+            "p_limit": limit,
         }
 
-    # ── 10. compare_properties ───────────────────────────────────────────────
+    # ── 10. compare_properties ──
     elif func_name == "compare_properties":
-        # RPC: (p_property_ids text[])
         ids = args.get("p_property_ids") or args.get("property_ids") or []
         if not isinstance(ids, list) or len(ids) < 2:
-            return {"status": "error", "message": "compare_properties requires a list of 2–10 property names or UUIDs in p_property_ids."}
+            return {"status": "error", "message": "compare_properties requires a list of 2-10 property names or UUIDs in p_property_ids."}
         clean_args = {"p_property_ids": ids[:10]}
 
-    # ── 11. search_properties ────────────────────────────────────────────────
+    # ── 11. search_properties ──
     elif func_name == "search_properties":
-        # RPC: (p_search text, p_market text, p_platform text, p_bedrooms integer, p_available boolean, p_limit integer)
         search = args.get("p_search") or args.get("p_query") or args.get("query")
         market = args.get("p_market") or args.get("market")
         platform = args.get("p_platform") or args.get("platform")
         bedrooms = args.get("p_bedrooms") or args.get("bedrooms")
-        avail = args.get("p_available") if "p_available" in args else args.get("p_is_active") if "p_is_active" in args else args.get("available")
-        limit = _clamp(args.get("p_limit") or args.get("limit"), 1, 50, default=20)
+        avail = args.get("p_available") if "p_available" in args else args.get("available")
+        is_act = args.get("p_is_active") if "p_is_active" in args else True
+        pos = args.get("p_rank_position") or args.get("rank_position") or "top"
+        pos = str(pos).lower() if str(pos).lower() in ("top", "bottom", "middle") else "top"
+        sort_by = args.get("p_sort_by") or args.get("sort_by") or "rate"
+        limit = _clamp(args.get("p_limit") or args.get("limit"), 1, 20, default=6)
         clean_args = {
             "p_search": str(search) if search else None,
             "p_market": str(market) if market else None,
             "p_platform": str(platform) if platform else None,
             "p_bedrooms": int(bedrooms) if bedrooms is not None else None,
             "p_available": bool(avail) if avail is not None else None,
+            "p_is_active": bool(is_act) if is_act is not None else None,
+            "p_rank_position": pos,
+            "p_sort_by": str(sort_by),
             "p_limit": limit,
         }
 
-    # ── 12. get_availability_rate ────────────────────────────────────────────
+    # ── 12. get_availability_rate ──
     elif func_name == "get_availability_rate":
-        # RPC: (p_market text, p_platform text)
         market = args.get("p_market") or args.get("market")
         platform = args.get("p_platform") or args.get("platform")
         clean_args = {
@@ -190,9 +201,8 @@ async def execute_tool_rpc(func_name: str, args: dict) -> dict:
             "p_platform": str(platform) if platform else None,
         }
 
-    # ── 13. get_nearby_properties ────────────────────────────────────────────
+    # ── 13. get_nearby_properties ──
     elif func_name == "get_nearby_properties":
-        # RPC: (p_latitude numeric, p_longitude numeric, p_radius_km numeric, p_limit integer)
         lat = args.get("p_latitude") or args.get("latitude")
         lon = args.get("p_longitude") or args.get("longitude")
         if lat is None or lon is None:
@@ -201,7 +211,7 @@ async def execute_tool_rpc(func_name: str, args: dict) -> dict:
                 "message": "get_nearby_properties requires p_latitude and p_longitude. Call geocode_address first if you only have an address."
             }
         rad = max(0.1, min(float(args.get("p_radius_km") or args.get("radius_km") or 5.0), 20.0))
-        limit = _clamp(args.get("p_limit") or args.get("limit"), 1, 20, default=10)
+        limit = _clamp(args.get("p_limit") or args.get("limit"), 1, 20, default=6)
         clean_args = {
             "p_latitude": float(lat),
             "p_longitude": float(lon),
@@ -209,9 +219,8 @@ async def execute_tool_rpc(func_name: str, args: dict) -> dict:
             "p_limit": limit,
         }
 
-    # ── 14. get_distance_km ──────────────────────────────────────────────────
+    # ── 14. get_distance_km ──
     elif func_name == "get_distance_km":
-        # RPC: (property_a_id uuid, property_b_id uuid)
         p_a = args.get("property_a_id") or args.get("p_from_property_id") or args.get("from_property_id")
         p_b = args.get("property_b_id") or args.get("p_to_property_id") or args.get("to_property_id")
         if not is_valid_uuid(p_a) or not is_valid_uuid(p_b):
@@ -221,35 +230,62 @@ async def execute_tool_rpc(func_name: str, args: dict) -> dict:
             "property_b_id": p_b,
         }
 
-    # ── 15. get_tracked_markets ──────────────────────────────────────────────
+    # ── 15. get_tracked_markets ──
     elif func_name == "get_tracked_markets":
-        # RPC: (p_platform text)
         plat = args.get("p_platform") or args.get("platform")
         clean_args = {
             "p_platform": str(plat) if plat else None,
         }
 
-    # ── 16. get_recently_changed_tracking ────────────────────────────────────
+    # ── 16. get_recently_changed_tracking ──
     elif func_name == "get_recently_changed_tracking":
-        # RPC: (p_days integer)
         days = _clamp(args.get("p_days") or args.get("days"), 1, 90, default=30)
+        clean_args = {"p_days": days}
+
+    # ── 17. get_property_detail ──
+    elif func_name == "get_property_detail":
+        search = args.get("p_property_search") or args.get("property_search") or args.get("property_id") or args.get("name")
+        if not search:
+            return {"status": "error", "message": "get_property_detail requires p_property_search (UUID or property title)."}
+        days = _clamp(args.get("p_history_days") or args.get("history_days") or args.get("days"), 1, 30, default=14)
         clean_args = {
-            "p_days": days,
+            "p_property_search": str(search),
+            "p_history_days": days,
         }
 
-    # ── Default: Pass sanitized args ─────────────────────────────────────────
     else:
-        clean_args = dict(args)
-
-    # Strip None values so Postgres defaults take effect cleanly
-    payload = {k: v for k, v in clean_args.items() if v is not None}
+        return {
+            "status": "error",
+            "message": f"Unknown tool name: '{func_name}'"
+        }
 
-    # ── Execute RPC ───────────────────────────────────────────────────────────
     try:
-        res = supabase.rpc(func_name, payload).execute()
-        return {"status": "success", "data": res.data}
+        # Strip None values to allow Postgres DEFAULT expressions to resolve cleanly
+        query_params = {k: v for k, v in clean_args.items() if v is not None}
+        res = supabase.rpc(func_name, query_params).execute()
+        raw = res.data
+
+        if raw is None:
+            return {"status": "success", "data": []}
+
+        if isinstance(raw, dict):
+            if "status" not in raw:
+                raw["status"] = "success"
+            return raw
+
+        if isinstance(raw, list):
+            return {"status": "success", "data": raw}
+
+        return {"status": "success", "data": raw}
+
     except Exception as e:
-        return {"status": "error", "message": str(e)}
+        err_msg = str(e)
+        if "PGRST202" in err_msg:
+            return {
+                "status": "error",
+                "message": f"Tool argument schema mismatch for '{func_name}'. Ensure parameters strictly match pulse_ai_revamped_rpcs.sql."
+            }
+        return {"status": "error", "message": err_msg}
 
 
 async def search_methodology_rag(query: str, top_k: int = 3) -> list:

services/tool_compressor.py

@@ -1,11 +1,12 @@
 """
 services/tool_compressor.py
-────────────────────────────
+─────────────────────────────────────────────────────────────────────────────
 Token-efficient tool output compression and the geocode_address_handler.
 
 compress_tool_output():  Converts raw RPC dicts into compact strings for LLM
-context. Uses metadata hoisting, null-stripping, and CSV rendering.
-Estimated reduction: 70-90% vs raw JSON for time-series data.
+context. Uses metadata hoisting, null-stripping, nested list unwrapping,
+and CSV rendering.
+Estimated reduction: 70-90% vs raw JSON.
 
 geocode_address_handler(): Resolves addresses to lat/lng via Mapbox.
 """
@@ -19,17 +20,27 @@ from config import MAPBOX_ACCESS_TOKEN
 
 logger = setup_logger(__name__)
 
-_MAX_ROWS = 30         # Maximum rows per tool result (was 50)
+_MAX_ROWS = 30         # Maximum rows per tool result
 _MAX_RESULT_CHARS = 2000  # Hard char cap per compressed result (~500 tokens)
 
+_LIST_KEYS = ("items", "results", "compared", "rate_history", "ranked_properties", "newly_added", "untracked_or_removed")
+
+
+def _clean_value(val):
+    if isinstance(val, str) and len(val) >= 19 and "T" in val and (val.endswith("Z") or "+" in val):
+        # Truncate microsecond ISO timestamp to date or compact datetime: 2026-09-04 03:21
+        return val[:10]
+    return val
+
 
 def compress_tool_output(func_name: str, db_result: dict) -> str:
     """
-    Three-step compression pipeline:
-    1. Metadata hoisting: keys with identical values across all rows are
+    Multi-step compression pipeline:
+    1. Unwraps nested list envelopes ({total_matching_count, returned_count, items}).
+    2. Metadata hoisting: keys with identical values across all rows are
        extracted to a single header line, removing them from every row.
-    2. Null stripping: any key with a null/None value in a row is omitted.
-    3. CSV rendering: remaining data written as CSV (headers once, values compact).
+    3. Null stripping: any key with a null/None value in a row is omitted.
+    4. CSV rendering: remaining data written as CSV (headers once, values compact).
 
     For non-tabular (scalar/dict) results, returns a minimal string.
     """
@@ -42,20 +53,36 @@ def compress_tool_output(func_name: str, db_result: dict) -> str:
     else:
         data = {k: v for k, v in db_result.items() if k != "status"}
 
-    # ── Scalar / single-object results ──────────────────────────────────────
+    # ── Scalar / single-object results ──
     if data is None or (isinstance(data, dict) and len(data) == 0):
         return f"Tool '{func_name}': no data returned."
 
     if isinstance(data, (str, int, float, bool)):
         return f"Tool '{func_name}' result: {data}"
 
+    outer_metadata = {}
+    # Check if dict contains an inner list envelope
     if isinstance(data, dict):
-        return f"Tool '{func_name}' result:\n{json.dumps(data, default=str)}"
+        found_list_key = None
+        for lk in _LIST_KEYS:
+            if lk in data and isinstance(data[lk], list):
+                found_list_key = lk
+                break
+
+        if found_list_key:
+            # Hoist outer metadata
+            for k, v in data.items():
+                if k != found_list_key and not isinstance(v, (list, dict)):
+                    outer_metadata[k] = v
+            data = data[found_list_key]
+        else:
+            return f"Tool '{func_name}' result:\n{json.dumps(data, default=str)}"
 
     if not isinstance(data, list) or len(data) == 0:
-        return f"Tool '{func_name}': empty result."
+        meta_prefix = f"[{', '.join(f'{k}={v}' for k, v in outer_metadata.items())}]\n" if outer_metadata else ""
+        return f"Tool '{func_name}':\n{meta_prefix}0 items returned."
 
-    # ── Filter out all-null rows ─────────────────────────────────────────────
+    # ── Filter out all-null rows ──
     data = [
         row for row in data
         if isinstance(row, dict) and any(v is not None for v in row.values())
@@ -69,11 +96,15 @@ def compress_tool_output(func_name: str, db_result: dict) -> str:
         data = data[:_MAX_ROWS]
         truncated = True
 
-    # ── Step 1: Metadata hoisting ────────────────────────────────────────────
+    # ── Step 1: Metadata hoisting ──
     all_keys = list(data[0].keys())
-    hoisted = {}
+    # Omit property_id from CSV rows if property_name is available to save tokens
+    has_name = "property_name" in all_keys
+    candidate_keys = [k for k in all_keys if not (k == "property_id" and has_name)]
+
+    hoisted = dict(outer_metadata)
     row_keys = []
-    for key in all_keys:
+    for key in candidate_keys:
         unique_values = {str(row.get(key)) for row in data}
         if len(unique_values) == 1:
             val = data[0].get(key)
@@ -85,14 +116,14 @@ def compress_tool_output(func_name: str, db_result: dict) -> str:
     header_parts = [f"{k}={v}" for k, v in hoisted.items()]
     header_str = f"[{', '.join(header_parts)}]\n" if header_parts else ""
 
-    # ── Step 2 & 3: Null-strip + CSV ─────────────────────────────────────────
+    # ── Step 2 & 3: Null-strip + CSV ──
     active_keys = [k for k in row_keys if any(row.get(k) is not None for row in data)]
 
     buf = io.StringIO()
     writer = csv.writer(buf)
     writer.writerow(active_keys)
     for row in data:
-        writer.writerow([row.get(k) for k in active_keys])
+        writer.writerow([_clean_value(row.get(k)) for k in active_keys])
 
     truncation_notice = (
         f"\n[Truncated to {_MAX_ROWS} rows. Advise user to narrow date range or add filters.]"
@@ -114,7 +145,7 @@ def compress_tool_output(func_name: str, db_result: dict) -> str:
     return result_str
 
 
-# ─── GEOCODE HANDLER (Mapbox API) ─────────────────────────────────────────────
+# ── GEOCODE HANDLER (Mapbox API) ──
 
 def geocode_address_handler(address: str) -> dict:
     """
@@ -125,7 +156,7 @@ def geocode_address_handler(address: str) -> dict:
     if not MAPBOX_ACCESS_TOKEN:
         return {
             "status": "error",
-            "message": "We are unable to geocode addresses at this time — the mapping service is not configured.",
+            "message": "We are unable to geocode addresses at this time - the mapping service is not configured.",
         }
     if not address or not address.strip():
         return {"status": "error", "message": "No address was provided to geocode."}

services/tools.py

@@ -1,8 +1,8 @@
 """
-Real Estate Intelligence Layer — Tool Definitions & Dynamic Tool Discovery
+Real Estate Intelligence Layer - Tool Definitions & Dynamic Tool Discovery
 
 Implements Hierarchical Dynamic Tool Discovery / Schema Gating:
-  - Exact 1:1 parameter alignment with Supabase Postgres DDL signatures in all_rpcs.sql.
+  - Exact 1:1 parameter alignment with Supabase Postgres DDL signatures in pulse_ai_revamped_rpcs.sql.
   - Curated, semantically discriminative retrieval descriptions for all tools.
   - Pre-embedded vector representations for ~20-30ms local cosine ranking.
   - Universal tools (suggest_actions, generate_data_export, generate_contact_buttons).
@@ -10,7 +10,7 @@ Implements Hierarchical Dynamic Tool Discovery / Schema Gating:
 from typing import List, Dict, Any, Optional
 import numpy as np
 
-# ─── 1. UNIVERSAL TOOLS (Always attached to tool payloads) ───────────────────
+# ── 1. UNIVERSAL TOOLS (Always attached to tool payloads) ──
 
 SUGGEST_ACTIONS_TOOL = {
     "type": "function",
@@ -18,7 +18,7 @@ SUGGEST_ACTIONS_TOOL = {
         "name": "suggest_actions",
         "description": (
             "Suggest 0 to 4 relevant interactive action buttons or clarifying options for the user based on the conversation. "
-            "Return an empty array actions: [] if no follow-up action is genuinely useful or if the conversation has concluded naturally — do not force suggestions."
+            "Return an empty array actions: [] if no follow-up action is genuinely useful or if the conversation has concluded naturally - do not force suggestions."
         ),
         "parameters": {
             "type": "object",
@@ -38,36 +38,31 @@ GENERATE_DATA_EXPORT_TOOL = {
     "type": "function",
     "function": {
         "name": "generate_data_export",
-        "description": "Save real estate analysis, market summary, or price breakdown to a downloadable Markdown (.md) report file. Call this tool whenever a user asks to export, save, download, or generate a report file.",
+        "description": "Generate a downloadable file export (Markdown document or CSV report) containing real estate analysis or property tables requested by the user.",
         "parameters": {
             "type": "object",
             "properties": {
-                "format": {
-                    "type": "string",
-                    "enum": ["md"],
-                    "description": "Export format, strictly 'md'",
-                },
                 "content": {
                     "type": "string",
-                    "description": "Complete formatted Markdown report content to save into the file",
-                },
+                    "description": "The complete markdown or CSV text content to export into a downloadable file."
+                }
             },
-            "required": ["content"],
-        },
-    },
+            "required": ["content"]
+        }
+    }
 }
 
 GENERATE_CONTACT_BUTTONS_TOOL = {
     "type": "function",
     "function": {
         "name": "generate_contact_buttons",
-        "description": "Generates clickable Email and WhatsApp contact buttons. Use this whenever the user asks about hiring us, pricing, custom builds, or tracking their own portfolios. The tool returns the exact markdown syntax you must use to display the buttons.",
+        "description": "Generate interactive contact buttons (Email and WhatsApp) for custom engineering inquiries, bespoke scraping needs, or system requests.",
         "parameters": {
             "type": "object",
             "properties": {
                 "message": {
                     "type": "string",
-                    "description": "A personalized, plain English greeting message to pre-fill in the WhatsApp chat based on the user's inquiry (e.g., 'Hi John, I would like to discuss a custom build for my 10 properties in Miami.')."
+                    "description": "A personalized, plain English greeting message to pre-fill in the WhatsApp chat based on the user's inquiry."
                 }
             },
             "required": ["message"],
@@ -75,15 +70,15 @@ GENERATE_CONTACT_BUTTONS_TOOL = {
     }
 }
 
-# ─── 2. DOMAIN TOOLS (Exact Supabase SQL Signatures) ─────────────────────────
+# ── 2. DOMAIN TOOLS (Exact Supabase SQL Signatures) ──
 
 REAL_ESTATE_TOOLS = [
-    # ─── DASHBOARD & MARKET OVERVIEW ─────────────────────────────────────────
+    # ── DASHBOARD & MARKET OVERVIEW ──
     {
         "type": "function",
         "function": {
-            "name": "get_dashboard_kpis",
-            "description": "Fetch overall Real Estate Rate Monitor top KPI metrics (properties tracked, 7-day rate changes, 25%+ price spikes, and scrape health status), optionally filtered by market, platform, bedrooms, active status, specific property IDs, or stay date window. Matches the live dashboard top KPI cards.",
+            "name": "get_real_estate_kpis",
+            "description": "Fetch overall Real Estate Rate Monitor top KPI metrics (properties tracked, available vs booked count, availability %, 7-day rate changes, 25%+ price spikes, and scrape health), optionally filtered by market, platform, bedrooms, active status, specific property IDs, or stay date window.",
             "parameters": {
                 "type": "object",
                 "properties": {
@@ -125,7 +120,7 @@ REAL_ESTATE_TOOLS = [
         "type": "function",
         "function": {
             "name": "get_market_averages",
-            "description": "Fetch average nightly rates and 7-day trailing average price comparisons for a market across active listings. Use when the user asks for market baseline, average prices, or nightly benchmarks.",
+            "description": "Fetch average nightly rates and 7-day trailing average price comparisons for current active listings in a market. Use when the user asks for market baseline, average prices, or nightly benchmarks.",
             "parameters": {
                 "type": "object",
                 "properties": {
@@ -179,28 +174,49 @@ REAL_ESTATE_TOOLS = [
                         "type": "integer",
                         "description": "Number of historical days to analyze (default 14, max 90)",
                     },
+                    "p_platform": {
+                        "type": "string",
+                        "description": "Optional booking platform filter ('airbnb' or 'vrbo')",
+                    },
+                    "p_is_active": {
+                        "type": "boolean",
+                        "description": "Optional active status filter (default true to exclude frozen historical properties)",
+                    },
                 },
                 "required": ["p_market"],
             },
         },
     },
 
-    # ─── SPIKES, ANOMALIES & VOLATILITY ──────────────────────────────────────
+    # ── VOLATILITY & ANOMALIES ──
     {
         "type": "function",
         "function": {
             "name": "get_spike_alerts",
-            "description": "Fetch active price spike alerts where a property's nightly rate changed by more than the threshold (default 25%) relative to its 7-day trailing average. Use when user asks about sudden price jumps, surge pricing, or rate spikes.",
+            "description": "Fetch sudden sharp price changes and 25%+ price spikes, sorted by deviation intensity. Supports ranked slices (top, bottom, middle).",
             "parameters": {
                 "type": "object",
                 "properties": {
                     "threshold_param": {
                         "type": "number",
-                        "description": "Percentage change threshold (default 25.0 for 25%+ spikes)",
+                        "description": "Percentage spike deviation threshold (default 25.0)",
                     },
                     "days_param": {
                         "type": "integer",
-                        "description": "Lookback window in days (default 7, max 30)",
+                        "description": "Historical days lookback (default 7, max 30)",
+                    },
+                    "p_market": {
+                        "type": "string",
+                        "description": "Optional market filter ('Miami' or 'NYC/NJ Metro')",
+                    },
+                    "p_limit": {
+                        "type": "integer",
+                        "description": "Max spikes to return (default 8, max 15)",
+                    },
+                    "p_rank_position": {
+                        "type": "string",
+                        "enum": ["top", "bottom", "middle"],
+                        "description": "Rank slice: 'top' (most extreme spikes), 'bottom' (mildest spikes), or 'middle' (median spikes). Default 'top'.",
                     },
                 },
                 "required": [],
@@ -211,24 +227,24 @@ REAL_ESTATE_TOOLS = [
         "type": "function",
         "function": {
             "name": "get_rate_anomaly_report",
-            "description": "Fetch detailed rate anomalies (both spikes AND crashes/drops) with listing name, dates, old rate, new rate, baseline 7d avg, and percentage deviation. Use for in-depth pricing anomaly investigations.",
+            "description": "Fetch a deep-dive anomaly report for a specific property: historical normal price bounds, baseline average, anomaly frequency, and recent abnormal pricing spikes.",
             "parameters": {
                 "type": "object",
                 "properties": {
                     "p_property_search": {
                         "type": "string",
-                        "description": "Optional search term for property name, listing, or market region ('Miami' or 'NYC/NJ Metro')",
+                        "description": "Property UUID or search term matching property name",
                     },
                     "p_days": {
                         "type": "integer",
-                        "description": "Lookback window in days (default 30, max 90)",
+                        "description": "Analysis window in days (default 30, max 90)",
                     },
                     "p_deviation_threshold": {
                         "type": "number",
-                        "description": "Minimum percentage deviation threshold (default 25.0 for 25%+ deviation)",
+                        "description": "Percentage threshold defining an anomaly (default 25.0)",
                     },
                 },
-                "required": [],
+                "required": ["p_property_search"],
             },
         },
     },
@@ -236,7 +252,7 @@ REAL_ESTATE_TOOLS = [
         "type": "function",
         "function": {
             "name": "get_most_volatile_properties",
-            "description": "Fetch listings with the highest number of rate adjustments/changes over a lookback window. Use when user asks which properties change prices most frequently, most dynamic pricing, or most volatile listings.",
+            "description": "Identify property listings with the highest price volatility and most frequent rate adjustments. Supports ranked slices.",
             "parameters": {
                 "type": "object",
                 "properties": {
@@ -250,7 +266,12 @@ REAL_ESTATE_TOOLS = [
                     },
                     "p_limit": {
                         "type": "integer",
-                        "description": "Max properties to return (default 5, max 50)",
+                        "description": "Max properties to return (default 5, max 15)",
+                    },
+                    "p_rank_position": {
+                        "type": "string",
+                        "enum": ["top", "bottom", "middle"],
+                        "description": "Rank slice: 'top' (highest volatility), 'bottom' (lowest volatility), or 'middle' (median). Default 'top'.",
                     },
                 },
                 "required": [],
@@ -258,12 +279,12 @@ REAL_ESTATE_TOOLS = [
         },
     },
 
-    # ─── INDIVIDUAL PROPERTY & LISTING LEVEL ──────────────────────────────────
+    # ── INDIVIDUAL PROPERTY & LISTING LEVEL ──
     {
         "type": "function",
         "function": {
             "name": "get_property_snapshot",
-            "description": "Fetch complete current profile and latest rate data for a specific property by its UUID or listing title. Returns property name, market, bedrooms, platform, listing URL, coordinates, current nightly rate, 7-day average baseline, and availability status.",
+            "description": "Fetch complete current profile and latest rate data for a specific property by its UUID or listing title. Returns property name, market, bedrooms, platform, listing URL, coordinates, current nightly rate, 7-day average baseline, is_active, and availability status.",
             "parameters": {
                 "type": "object",
                 "properties": {
@@ -276,11 +297,32 @@ REAL_ESTATE_TOOLS = [
             },
         },
     },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_property_detail",
+            "description": "Fetch a deep single-property profile including current status, active tracking state, coordinates, listing URL, and daily-aggregated recent rate history (up to 14 days). Use when user asks to explore or dive deep into a specific property.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "p_property_search": {
+                        "type": "string",
+                        "description": "Property UUID or search term for listing name",
+                    },
+                    "p_history_days": {
+                        "type": "integer",
+                        "description": "Number of days of daily rate history to include (default 14, max 30)",
+                    },
+                },
+                "required": ["p_property_search"],
+            },
+        },
+    },
     {
         "type": "function",
         "function": {
             "name": "get_property_rate_changes",
-            "description": "Fetch chronological history of all rate revisions and price adjustments for a specific property or search term. Use to analyze price change history over time.",
+            "description": "Fetch chronological daily history of rate revisions and price adjustments for a specific property. Returns one row per calendar day.",
             "parameters": {
                 "type": "object",
                 "properties": {
@@ -304,6 +346,10 @@ REAL_ESTATE_TOOLS = [
                         "type": "string",
                         "description": "Optional stay date end window (YYYY-MM-DD)",
                     },
+                    "p_limit": {
+                        "type": "integer",
+                        "description": "Max daily entries to return (default 14, max 30)",
+                    },
                 },
                 "required": ["property_search"],
             },
@@ -313,7 +359,7 @@ REAL_ESTATE_TOOLS = [
         "type": "function",
         "function": {
             "name": "compare_properties",
-            "description": "Compare 2 to 10 specific properties side-by-side on current rate, 7-day average, bedroom count, platform, and availability status. Use when the user asks to compare specific listings.",
+            "description": "Compare 2 to 10 specific properties side-by-side on current rate, 7-day average, bedroom count, platform, is_active, and availability status. Use when the user asks to compare specific listings.",
             "parameters": {
                 "type": "object",
                 "properties": {
@@ -331,7 +377,7 @@ REAL_ESTATE_TOOLS = [
         "type": "function",
         "function": {
             "name": "search_properties",
-            "description": "Search and filter tracked properties by market ('Miami' or 'NYC/NJ Metro'), bedroom count, platform ('airbnb' or 'vrbo'), availability status, title substring, and limit. Returns listing IDs, titles, bedrooms, current rates, and availability.",
+            "description": "Search and filter tracked properties by market ('Miami' or 'NYC/NJ Metro'), bedroom count, platform ('airbnb' or 'vrbo'), availability status, title substring, and ranked slices.",
             "parameters": {
                 "type": "object",
                 "properties": {
@@ -355,9 +401,23 @@ REAL_ESTATE_TOOLS = [
                         "type": "boolean",
                         "description": "Optional availability filter: true for currently available, false for booked",
                     },
+                    "p_is_active": {
+                        "type": "boolean",
+                        "description": "Optional active status filter (default true for currently tracked)",
+                    },
+                    "p_rank_position": {
+                        "type": "string",
+                        "enum": ["top", "bottom", "middle"],
+                        "description": "Rank slice: 'top', 'bottom', or 'middle' (default 'top')",
+                    },
+                    "p_sort_by": {
+                        "type": "string",
+                        "enum": ["rate", "deviation"],
+                        "description": "Sort metric: 'rate' (by nightly price) or 'deviation' (by % deviation from 7d avg). Default 'rate'.",
+                    },
                     "p_limit": {
                         "type": "integer",
-                        "description": "Max results to return (default 20, max 50)",
+                        "description": "Max results to return (default 6, max 15). Keep small for conversational conciseness.",
                     },
                 },
                 "required": [],
@@ -386,18 +446,18 @@ REAL_ESTATE_TOOLS = [
         },
     },
 
-    # ─── GEOGRAPHIC & LOCATION TOOLS ─────────────────────────────────────────
+    # ── GEOSPATIAL & LOCATION TOOLS ──
     {
         "type": "function",
         "function": {
             "name": "geocode_address",
-            "description": "Convert a street address, landmark, or neighborhood name into latitude and longitude coordinates. Use before querying nearby properties if the user provides an address or landmark name.",
+            "description": "Convert a user-provided street address, neighborhood, landmark, or point of interest into precise latitude and longitude geographic coordinates.",
             "parameters": {
                 "type": "object",
                 "properties": {
                     "address": {
                         "type": "string",
-                        "description": "Street address, landmark, or neighborhood (e.g. 'Ocean Drive, Miami Beach' or 'Brickell, Miami')",
+                        "description": "The street address, neighborhood, landmark, or point of interest to geocode",
                     }
                 },
                 "required": ["address"],
@@ -408,17 +468,17 @@ REAL_ESTATE_TOOLS = [
         "type": "function",
         "function": {
             "name": "get_nearby_properties",
-            "description": "Fetch properties within a specified radius (in kilometers) of a target geographic coordinate. Use when the user asks for listings near a location or landmark.",
+            "description": "Find tracked property listings within a radial kilometer distance of a geographic latitude and longitude point. Always call geocode_address first if user gave a street address or neighborhood name.",
             "parameters": {
                 "type": "object",
                 "properties": {
                     "p_latitude": {
                         "type": "number",
-                        "description": "Target latitude in decimal degrees",
+                        "description": "Target center latitude coordinate",
                     },
                     "p_longitude": {
                         "type": "number",
-                        "description": "Target longitude in decimal degrees",
+                        "description": "Target center longitude coordinate",
                     },
                     "p_radius_km": {
                         "type": "number",
@@ -426,7 +486,7 @@ REAL_ESTATE_TOOLS = [
                     },
                     "p_limit": {
                         "type": "integer",
-                        "description": "Max properties to return (default 10, max 20)",
+                        "description": "Maximum properties to return (default 6, max 15)",
                     },
                 },
                 "required": ["p_latitude", "p_longitude"],
@@ -437,17 +497,17 @@ REAL_ESTATE_TOOLS = [
         "type": "function",
         "function": {
             "name": "get_distance_km",
-            "description": "Calculate distance in kilometers between two properties by UUID.",
+            "description": "Calculate exact straight-line distance in kilometers between two properties using their database UUIDs.",
             "parameters": {
                 "type": "object",
                 "properties": {
                     "property_a_id": {
                         "type": "string",
-                        "description": "UUID of origin property",
+                        "description": "UUID of the first property",
                     },
                     "property_b_id": {
                         "type": "string",
-                        "description": "UUID of destination property",
+                        "description": "UUID of the second property",
                     },
                 },
                 "required": ["property_a_id", "property_b_id"],
@@ -455,12 +515,12 @@ REAL_ESTATE_TOOLS = [
         },
     },
 
-    # ─── SYSTEM METADATA & TRACKING TOOLS ────────────────────────────────────
+    # ── REGIONAL & METADATA ──
     {
         "type": "function",
         "function": {
             "name": "get_tracked_markets",
-            "description": "Fetch list of all currently supported and active market regions, listing counts, and platform coverage in the database (NYC/NJ Metro, Miami). Use when user asks what markets or cities are available.",
+            "description": "Fetch a list of all active metropolitan real estate markets currently tracked by the system (Miami, NYC/NJ Metro) with property counts.",
             "parameters": {
                 "type": "object",
                 "properties": {
@@ -477,7 +537,7 @@ REAL_ESTATE_TOOLS = [
         "type": "function",
         "function": {
             "name": "get_recently_changed_tracking",
-            "description": "Fetch properties that recently had their monitoring status changed (newly added or paused). Use for audit or tracking health queries.",
+            "description": "Fetch listings that were recently added to or removed from active monitoring tracking status within a lookback period.",
             "parameters": {
                 "type": "object",
                 "properties": {
@@ -499,13 +559,13 @@ COMMERCIAL_TOOLS = [
 ]
 
 
-# ─── 3. TOOL REGISTRY & DISCOVERY METADATA ───────────────────────────────────
+# ── 3. TOOL REGISTRY & DISCOVERY METADATA ──
 
 TOOL_REGISTRY: List[Dict[str, Any]] = [
     {
-        "name": "get_dashboard_kpis",
+        "name": "get_real_estate_kpis",
         "category": "MARKET",
-        "retrieval_description": "High-level summary cards, aggregate portfolio metrics, active properties count, average market rate, scrape health status, overall KPI numbers.",
+        "retrieval_description": "High-level summary cards, aggregate real estate portfolio metrics, active properties count, availability count, 7-day rate changes, scrape health status, overall KPI numbers.",
         "schema": REAL_ESTATE_TOOLS[0],
     },
     {
@@ -529,7 +589,7 @@ TOOL_REGISTRY: List[Dict[str, Any]] = [
     {
         "name": "get_spike_alerts",
         "category": "ANOMALY",
-        "retrieval_description": "Sudden sharp price jumps, 25% plus rate increases, price spikes, surge pricing alerts, unseasonal rate surges in Miami or NYC.",
+        "retrieval_description": "Sudden sharp price jumps, 25% plus rate increases, price spikes, surge pricing alerts, unseasonal rate surges in Miami or NYC, ranked slices.",
         "schema": REAL_ESTATE_TOOLS[4],
     },
     {
@@ -541,7 +601,7 @@ TOOL_REGISTRY: List[Dict[str, Any]] = [
     {
         "name": "get_most_volatile_properties",
         "category": "ANOMALY",
-        "retrieval_description": "Listings with the most frequent price fluctuations, highest number of rate adjustments, unstable dynamic pricing.",
+        "retrieval_description": "Listings with the most frequent price fluctuations, highest number of rate adjustments, unstable dynamic pricing, ranked slices.",
         "schema": REAL_ESTATE_TOOLS[6],
     },
     {
@@ -551,63 +611,69 @@ TOOL_REGISTRY: List[Dict[str, Any]] = [
         "schema": REAL_ESTATE_TOOLS[7],
     },
     {
-        "name": "get_property_rate_changes",
+        "name": "get_property_detail",
         "category": "PROPERTY",
-        "retrieval_description": "Historical log of price changes, chronological rate revisions, past rate adjustments for a single property.",
+        "retrieval_description": "Deep single-property exploration, full listing profile, active tracking status, coordinates, URL, and daily-aggregated historical rate revision log.",
         "schema": REAL_ESTATE_TOOLS[8],
     },
+    {
+        "name": "get_property_rate_changes",
+        "category": "PROPERTY",
+        "retrieval_description": "Historical log of price changes, chronological rate revisions, daily past rate adjustments for a single property.",
+        "schema": REAL_ESTATE_TOOLS[9],
+    },
     {
         "name": "compare_properties",
         "category": "PROPERTY",
         "retrieval_description": "Side-by-side head-to-head comparison of multiple property listings, prices, bedrooms, and metrics.",
-        "schema": REAL_ESTATE_TOOLS[9],
+        "schema": REAL_ESTATE_TOOLS[10],
     },
     {
         "name": "search_properties",
         "category": "PROPERTY",
-        "retrieval_description": "Find, list, and filter property listings by bedroom count, price range, market (Miami, NYC), availability status, or listing name.",
-        "schema": REAL_ESTATE_TOOLS[10],
+        "retrieval_description": "Find, list, and filter property listings by bedroom count, price range, market (Miami, NYC), availability status, listing name, or ranked slices.",
+        "schema": REAL_ESTATE_TOOLS[11],
     },
     {
         "name": "get_availability_rate",
         "category": "PROPERTY",
         "retrieval_description": "Percentage of units booked versus available, occupancy rates, reservation calendar status in Miami or NYC.",
-        "schema": REAL_ESTATE_TOOLS[11],
+        "schema": REAL_ESTATE_TOOLS[12],
     },
     {
         "name": "geocode_address",
         "category": "GEO",
         "retrieval_description": "Convert street address, landmark, or neighborhood name into latitude and longitude geographic coordinates.",
-        "schema": REAL_ESTATE_TOOLS[12],
+        "schema": REAL_ESTATE_TOOLS[13],
     },
     {
         "name": "get_nearby_properties",
         "category": "GEO",
         "retrieval_description": "Find listings closest to a specific geographic coordinate, landmark, or neighborhood radius.",
-        "schema": REAL_ESTATE_TOOLS[13],
+        "schema": REAL_ESTATE_TOOLS[14],
     },
     {
         "name": "get_distance_km",
         "category": "GEO",
         "retrieval_description": "Calculate straight-line distance in kilometers between two properties or locations by UUID.",
-        "schema": REAL_ESTATE_TOOLS[14],
+        "schema": REAL_ESTATE_TOOLS[15],
     },
     {
         "name": "get_tracked_markets",
         "category": "MARKET",
         "retrieval_description": "List all cities and regions currently supported and monitored in the database (NYC/NJ Metro, Miami).",
-        "schema": REAL_ESTATE_TOOLS[15],
+        "schema": REAL_ESTATE_TOOLS[16],
     },
     {
         "name": "get_recently_changed_tracking",
         "category": "MARKET",
         "retrieval_description": "Properties recently added to or removed from active monitoring tracking status.",
-        "schema": REAL_ESTATE_TOOLS[16],
+        "schema": REAL_ESTATE_TOOLS[17],
     },
 ]
 
 
-# ─── 4. SEMANTIC EMBEDDING ENGINE (Lazy Loaded Singleton) ─────────────────────
+# ── 4. SEMANTIC EMBEDDING ENGINE (Lazy Loaded Singleton) ──
 
 _TOOL_EMBEDDINGS: Optional[np.ndarray] = None
 
@@ -688,13 +754,10 @@ def discover_tools(
         results.append(GENERATE_DATA_EXPORT_TOOL)
         seen_names.add("generate_data_export")
 
-    # SUGGEST_ACTIONS_TOOL is intentionally decoupled from data retrieval turns.
-    # It is executed exclusively in Turn 3 (Action Resolution) with tools=None during synthesis.
-
     return results
 
 
-# ─── 5. BACKWARDS COMPATIBLE SELECTOR ─────────────────────────────────────────
+# ── 5. BACKWARDS COMPATIBLE SELECTOR ──
 
 def select_tools(user_query: str) -> List[Dict[str, Any]]:
     """Backwards-compatible alias forwarding to discover_tools()."""