Refine AI hints for better readability

Simplified AI hints across deals and leads models by:
- Removing verbose explanations and reducing to essential guidance
- Replacing special characters (arrows, em dashes, backticks) with plain text
- Using "from X to Y" instead of arrow symbols
- Using "like" instead of "e.g." with parentheses
- Removing backticks around field names for cleaner appearance

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

Author: torimwhaley

models/demo/deals.yml

@@ -5,12 +5,7 @@ models:
     primary_key: deal_id
     order_fields_by: 'index'
     ai_hint: |
-          CloseRate Kevin: This is your primary deals model for analyzing pipeline progression and win/loss performance.
-          Use this to measure stage-to-stage conversion (New → Qualified → PoC → Negotiation → Won/Lost), calculate win rates, and identify stalled deals.
-          Key dimensions: `stage` (with stages: New, Qualified, PoC, Negotiation, Won, Lost), `created_date` (for cohort analysis).
-          Core metrics: `win_rate` (won deals / total deals), stage-specific counts (`new_deals`, `qualified_deals`, `poc_deals`, `negotiation_deals`, `won_deals`, `lost_deals`), `total_amount`, `total_won_amount`.
-          Critical for AE performance analysis. Focus on demo-to-close rates (PoC → Negotiation → Won conversion) and identifying aging deals at each stage.
-          Default to line charts for trend analysis, with period-over-period comparisons using `created_date` dimensions.
+          CloseRate Kevin: Primary deals model for analyzing pipeline progression and win/loss performance. Use for stage-to-stage conversion analysis and calculating win rates.
 
     parameters:
         deal_value_toggle:
@@ -46,7 +41,7 @@ models:
                 - kpi
                 - sales
             ai_hint: |
-              CloseRate Kevin: Use `unique_deals` as the denominator for win rate and stage conversion calculations.
+              CloseRate Kevin: Use unique_deals as the denominator for win rate and stage conversion calculations.
               This represents total deal volume. Break down by time period to track pipeline growth or contraction.
           new_deals:
             type: count_distinct
@@ -72,8 +67,8 @@ models:
             filters:
               - stage: 'PoC'
             ai_hint: |
-              CloseRate Kevin: Use `poc_deals` to track the "demo" or proof-of-concept stage—critical for demo-to-close analysis.
-              Calculate PoC → Won conversion by dividing `won_deals` by `poc_deals`. Monitor aging PoC deals to identify stalled demos.
+              CloseRate Kevin: Use poc_deals to track the demo or proof-of-concept stage which is critical for demo-to-close analysis.
+              Calculate PoC to Won conversion by dividing won_deals by poc_deals. Monitor aging PoC deals to identify stalled demos.
           negotiation_deals:
             type: count_distinct
             groups: ['Deal Counts']
@@ -92,8 +87,8 @@ models:
                 - kpi
                 - sales
             ai_hint: |
-              CloseRate Kevin: Use `won_deals` as the numerator for win rate calculations and stage conversion analysis.
-              Track over time to measure sales momentum. Compare against `poc_deals` for demo-to-close performance.
+              CloseRate Kevin: Use won_deals as the numerator for win rate calculations and stage conversion analysis.
+              Track over time to measure sales momentum. Compare against poc_deals for demo-to-close performance.
           lost_deals:
             type: count_distinct
             groups: ['Deal Counts']
@@ -114,9 +109,9 @@ models:
               categories:
                 - kpi
             ai_hint: |
-              CloseRate Kevin: Use `win_rate` to measure overall deal closure effectiveness (won deals ÷ total deals).
-              This is a core KPI for AE performance. Break down by time period (week, month, quarter) to identify trends.
-              Compare period-over-period to spot declining win rates early. Pair with `loss_rate` to understand win/loss balance.
+              CloseRate Kevin: Use win_rate to measure overall deal closure effectiveness. This is won deals divided by total deals.
+              Core KPI for AE performance. Break down by time period like week, month, or quarter to identify trends.
+              Compare period-over-period to spot declining win rates early. Pair with loss_rate to understand win/loss balance.
             groups: ['Rates & Ratios']
           loss_rate:
             type: number
@@ -153,9 +148,9 @@ models:
         dimension:
           type: string
         ai_hint: |
-          CloseRate Kevin: Use `stage` to track deals through the sales funnel: New → Qualified → PoC → Negotiation → Won/Lost.
+          CloseRate Kevin: Use stage to track deals through the sales funnel from New to Qualified to PoC to Negotiation to Won or Lost.
           Critical for calculating stage-to-stage conversion rates and identifying where deals stall or drop off.
-          Filter by specific stages to analyze aging deals (e.g., deals stuck in Negotiation). Use `stage_order` for proper funnel sequencing.
+          Filter by specific stages to analyze aging deals like deals stuck in Negotiation. Use stage_order for proper funnel sequencing.
         additional_dimensions:
           stage_order:
             type: number
@@ -209,8 +204,8 @@ models:
                 - kpi
                 - sales
             ai_hint: |
-              CloseRate Kevin: Use `total_amount` to measure total pipeline value across all deal stages.
-              Track over time to monitor pipeline health and growth. Break down by `stage` to see value distribution across funnel stages.
+              CloseRate Kevin: Use total_amount to measure total pipeline value across all deal stages.
+              Track over time to monitor pipeline health and growth. Break down by stage to see value distribution across funnel stages.
           total_won_amount:
             groups: ['Deal Amounts']
             type: sum
@@ -219,8 +214,8 @@ models:
             filters:
               - stage: 'Won'
             ai_hint: |
-              CloseRate Kevin: Use `total_won_amount` to measure actual closed revenue—your core revenue KPI.
-              Track by time period (week, month, quarter) to monitor revenue trends. Compare period-over-period for growth analysis.
+              CloseRate Kevin: Use total_won_amount to measure actual closed revenue which is your core revenue KPI.
+              Track by time period like week, month, or quarter to monitor revenue trends. Compare period-over-period for growth analysis.
             spotlight:
               visibility: show
               categories:

models/demo/leads.yml

@@ -5,12 +5,7 @@ models:
         is_admin_saas_demo: 'true'
       primary_key: lead_id
       ai_hint: |
-          CloseRate Kevin: This is your primary leads model for analyzing top-of-funnel performance and SDR effectiveness.
-          Use this to measure lead-to-opportunity conversion, identify stalled leads, and diagnose drop-off patterns by stage.
-          Key dimensions: `sdr` (for individual rep performance), `sdr_team` (for country-level team analysis), `lead_status` (stages: new → contacted → qualified → converted).
-          Core metrics: `conversion_rate`, `avg_days_to_convert` (funnel velocity), `unique_lead_count`, and stage-specific counts (`open_leads`, `contacted_leads`, `qualified_leads`, `converted_leads`).
-          Join to `deals` via `deal_id` to analyze full funnel from lead creation through deal closure.
-          Focus on period-over-period trends using `created_at` or `converted_at` time dimensions. Default to line charts for trend analysis.
+          CloseRate Kevin: Primary leads model for analyzing top-of-funnel performance and SDR effectiveness. Use for lead-to-opportunity conversion analysis and identifying stalled leads.
 
       joins:
         - join: users
@@ -45,10 +40,10 @@ models:
             categories:
               - leads
           ai_hint: |
-            CloseRate Kevin: Use `conversion_rate` to measure SDR and team effectiveness at converting leads to opportunities.
-            Break down by `sdr` for individual performance or `sdr_team` for country-level comparisons.
-            Trend over time using `created_at` (by week or month) to identify declining conversion patterns.
-            Compare period-over-period (e.g., this month vs. last month) to spot performance changes early.
+            CloseRate Kevin: Use conversion_rate to measure SDR and team effectiveness at converting leads to opportunities.
+            Break down by sdr for individual performance or sdr_team for country-level comparisons.
+            Trend over time using created_at by week or month to identify declining conversion patterns.
+            Compare period-over-period to spot performance changes early.
         avg_days_to_convert:
           type: average
           description: "Average number of days it takes for a lead to convert"
@@ -60,9 +55,9 @@ models:
             categories:
               - leads
           ai_hint: |
-            CloseRate Kevin: Use `avg_days_to_convert` to measure funnel velocity—how quickly SDRs move leads through qualification.
-            Lower values indicate faster pipeline movement. Compare by `sdr` to identify top performers and slower reps.
-            Group by `sdr_team` to compare country-level velocity. Rising values may signal pipeline bottlenecks or stalled leads.
+            CloseRate Kevin: Use avg_days_to_convert to measure funnel velocity and how quickly SDRs move leads through qualification.
+            Lower values indicate faster pipeline movement. Compare by sdr to identify top performers and slower reps.
+            Group by sdr_team to compare country-level velocity. Rising values may signal pipeline bottlenecks or stalled leads.
         cost_per_conversion:
           type: number
           description: "Average cost per converted lead"
@@ -91,9 +86,9 @@ models:
                   - leads
                   - marketing
               ai_hint: |
-                CloseRate Kevin: Use `unique_lead_count` as your base metric for total lead volume.
-                Break down by `sdr` to measure individual workload or by `sdr_team` to compare country teams.
-                Combine with stage-specific metrics (`contacted_leads`, `qualified_leads`, `converted_leads`) to calculate stage-to-stage conversion rates.
+                CloseRate Kevin: Use unique_lead_count as your base metric for total lead volume.
+                Break down by sdr to measure individual workload or by sdr_team to compare country teams.
+                Combine with stage-specific metrics like contacted_leads, qualified_leads, converted_leads to calculate stage-to-stage conversion rates.
             open_leads:
               type: count_distinct
               groups: ['Lead Counts']
@@ -162,9 +157,9 @@ models:
             type: string
             label: "SDR"
           ai_hint: |
-            CloseRate Kevin: Use `sdr` to analyze individual SDR performance. Critical for identifying top performers vs. underperformers.
-            Combine with `conversion_rate`, `avg_days_to_convert`, or stage counts to measure rep effectiveness.
-            Compare individual SDRs within the same `sdr_team` for fair benchmarking.
+            CloseRate Kevin: Use sdr to analyze individual SDR performance. Critical for identifying top performers vs. underperformers.
+            Combine with conversion_rate, avg_days_to_convert, or stage counts to measure rep effectiveness.
+            Compare individual SDRs within the same sdr_team for fair benchmarking.
       - name: industry
         description: "The industry associated with the lead's company"
         meta:
@@ -232,7 +227,7 @@ models:
               format: '$#,##0'
               groups: ['Lead Costs']
               ai_hint: |
-                Sum of attributed lead acquisition costs. Useful for calculating CAC and evaluating marketing ROI when joined to `deals.total_amount`.
+                Sum of attributed lead acquisition costs. Useful for calculating CAC and evaluating marketing ROI when joined to deals.total_amount.
               spotlight:
                 visibility: show
                 categories:
@@ -254,7 +249,7 @@ models:
           dimension:
             type: string
           ai_hint: |
-            CloseRate Kevin: Use `lead_status` to track progression through the funnel (new → contacted → qualified → converted).
+            CloseRate Kevin: Use lead_status to track progression through the funnel from new to contacted to qualified to converted.
             Filter by status to identify stalled leads or analyze drop-off rates at each stage.
             Combine with time dimensions to spot aging leads that need attention.
       - name: created_at
@@ -288,6 +283,6 @@ models:
             type: string
             label: "SDR Team"
           ai_hint: |
-            CloseRate Kevin: Use `sdr_team` to compare performance across country-based SDR teams.
+            CloseRate Kevin: Use sdr_team to compare performance across country-based SDR teams.
             Essential for team-level analysis and understanding regional performance differences.
-            Group by `sdr_team` when measuring aggregate conversion rates, velocity, or lead volume by geography.
+            Group by sdr_team when measuring aggregate conversion rates, velocity, or lead volume by geography.