Cortex Analyst routing: verified-query-anchored, not description-anchored
Cortex Analyst tool routing is verified-query-anchored, not description-anchored
Discovered: 2026-05-08, RUNWAL_BOT routing fix during Sales+CRM alignment.
Pattern: Snowflake Intelligence agents (SNOWFLAKE_INTELLIGENCE.AGENTS.*) with multiple cortex_analyst_text_to_sql tools have an undocumented routing preference: verified-query coverage on the bound semantic view ranks above tool-description text. Even imperative orchestration text (e.g. “ALWAYS use TOOL_X for net sales questions”) is OUTRANKED by the verified-query advantage of a different tool.
Concrete case: RUNWAL_BOT had two analyst tools — RUNWAL_SALES_ANALYST (22 verified queries on RNWL_SALES_REPORTING, FACT_BOOKING-anchored) and a new RUNWAL_SALES_DASHBOARDS_ANALYST (0 verified queries on RNWL_SALES_DASHBOARDS, Tableau-canonical). Every “FY 25-26 net sales” test routed to the OLD tool because of its 22-query advantage, returning ₹1,905 Cr (FACT_BOOKING definition) instead of the canonical ~₹2,242 Cr (Tableau definition).
What worked (Phase 1B routing fix):
- Prepend
❌❌❌ DO NOT USE THIS TOOL FOR ...HARD-NO disqualification to the OLD tool’s description listing every banned question pattern (Net Sales, Gross Sales, bookings, FY, vertical, marketing spend, ANY aggregate) - Prepend
✅ PRIMARY TOOL — USE THIS FOR EVERY QUESTION ABOUT: ...boost to the NEW tool’s description listing every keyword - Description grew ~21K → ~23K chars; routing flipped immediately
Better long-term fix: add ≥3 verified queries to the new semantic view via DDL verified_queries (\"name\" AS (QUESTION '...' VERIFIED_AT <unix-ts> VERIFIED_BY '...' SQL '...')). Verified queries anchor routing without polluting tool descriptions.
Pattern for future Snowflake Intelligence agent design:
- ✅ Match verified-query coverage across all tools at agent creation time
- ✅ If migrating from old → new tool, add verified queries to the new tool BEFORE attempting routing-instruction-based migration
- ❌ NEVER rely on orchestration text alone to flip routing on a tool that has fewer verified queries
Codified at: session-learnings.md 2026-05-08 (aj-workspace).
Reach: any future Cortex Analyst agent design, any division.