Daily Command

Summarize the active brand's morning brief and point the user at the Daily Command desk. Renders from the canonical desk generator (the same sections the on-screen desk uses), returning a short summary plus a deep link rather than a long inline brief body. Use this for: "morning brief", "morning briefing", "daily brief", "what needs attention", "what happened today". Requires advertiser_id/brand_id from list_accounts. IDs are for tool plumbing only — never display raw IDs to the user; refer to the brand/advertiser by name. Returns status='complete' with 'result' immediately on a warm brand context; on a cold one, returns status='running' with a 'task_id' -- poll it with get_mcp_task_result until status is 'complete' or 'failed'.

Fetch the result of a ``start_analytics_query``/``run_nlp_to_sql`` task by ``task_id``. Returns ``{"status":"running"}`` while in progress, the full analytics payload once complete, or an error envelope if it failed or the id is unknown (including one belonging to another user). Prefer the generic ``get_mcp_task_result`` for new integrations; this is kept for existing callers.

Get Audience Quality Score (AQS) summary: average, min, max scores, total HCPs scored, score distribution (high/medium/low percentages). Use for AQS methodology, how AQS is calculated, what defines high/medium/low AQS, score thresholds, AQS distribution, average/min/max scores, how many HCPs have high AQS, what is a good AQS score, AQS for brand prescribers. Requires advertiser_id/brand_id from list_accounts. IDs are for tool plumbing only — never display raw IDs to the user; refer to the brand/advertiser by name.

Get audience engagement breakdown by platform type (Endemic vs POC). Requires advertiser_id/brand_id from list_accounts. IDs are for tool plumbing only — never display raw IDs to the user; refer to the brand/advertiser by name. Returns status='complete' with 'result' immediately on a warm brand context; on a cold one, returns status='running' with a 'task_id' -- poll it with get_mcp_task_result until status is 'complete' or 'failed'.

List saved targets of one type for an advertiser/brand. ``advertiser_id``/``brand_id`` MUST come from ``list_accounts``. ``target_type`` is one of ``audience`` (HCP, default), ``account`` (ABM), ``patient`` (DTC/DOOH), or ``pharmacist`` (POD). Read-only. Unlike the chat tool, this is session-less: it reads the brand's saved targets directly, with no campaign-flow guardrail.

One curated brand attribute (dosage form, route, manufacturer, biomarkers, …).

Get strategic marketing challenges for the brand. Uses real market data (market share, competitors, prescribers) and web research to identify specific, actionable challenges. Results are cached -- same challenges every time. Call this when the user asks about challenges, problems, issues, barriers, or difficulties the brand faces. Also use for what makes this drug unique, competitive differentiation, brand positioning challenges. Requires advertiser_id/brand_id from list_accounts. IDs are for tool plumbing only — never display raw IDs to the user; refer to the brand/advertiser by name.

Get brand's month-over-month growth: scripts, previous month, growth %. Use when user asks: is the brand growing, declining, month over month, MoM trend, rising, falling, trajectory, growth rate, monthly growth. Returns monthly script counts with MoM growth percentage. Requires advertiser_id/brand_id from list_accounts. IDs are for tool plumbing only — never display raw IDs to the user; refer to the brand/advertiser by name. Returns status='complete' with 'result' immediately on a warm brand context; on a cold one, returns status='running' with a 'task_id' -- poll it with get_mcp_task_result until status is 'complete' or 'failed'.

Get all NDC codes for the brand drug: code, formulation, package size. Use for NDC codes, formulations, package sizes, NDC-11/NDC-10 formats, how many NDCs, what strengths are available, dosage forms. For volume/prescriber breakdown per NDC, use get_ndc_analysis instead. Requires advertiser_id/brand_id from list_accounts. IDs are for tool plumbing only — never display raw IDs to the user; refer to the brand/advertiser by name. Returns status='complete' with 'result' immediately on a warm brand context; on a cold one, returns status='running' with a 'task_id' -- poll it with get_mcp_task_result until status is 'complete' or 'failed'.

Brand identity snapshot: name, generic name, therapeutic area, drug class, indication, lifecycle stage — for one advertiser/brand from ``list_accounts``. Returns status='complete' immediately on a warm brand context; on a cold one, returns status='running' — poll with get_mcp_task_result.

Who writes the brand's prescriptions — bounded snapshot for the chat agent. Returns how prescribers split across segments in the loaded universe (counts only) plus how many NPI rows exist in the prescriber registry metadata. Does **not** enumerate every prescriber record (that payload can be millions of characters). Use when the user asks who prescribes the brand, who writes for the brand, brand prescriber mix, or prescriber composition. For ranked HCPs use get_top_prescribers or catalog tools; for one NPI use search_hcp_by_npi; for overlap totals use get_prescriber_stats. For audience export use audience_builder. Requires advertiser_id/brand_id from list_accounts. IDs are for tool plumbing only — never display raw IDs to the user; refer to the brand/advertiser by name. Returns status='complete' with 'result' immediately on a warm brand context; on a cold one, returns status='running' with a 'task_id' -- poll it with get_mcp_task_result until status is 'complete' or 'failed'.

Get the brand's rank within its therapeutic area by script volume. Use when user asks: rank, position, ranking, where does brand stand, therapeutic area rank, drug class rank, what number, leader or follower. Returns ranked list with script counts. Requires advertiser_id/brand_id from list_accounts. IDs are for tool plumbing only — never display raw IDs to the user; refer to the brand/advertiser by name. Returns status='complete' with 'result' immediately on a warm brand context; on a cold one, returns status='running' with a 'task_id' -- poll it with get_mcp_task_result until status is 'complete' or 'failed'.

Get the brand's total prescription script count by month. Use when user asks: how many prescriptions, scripts this month, brand prescription count, monthly script volume, total scripts, Rx volume. Returns monthly script counts for the active brand. Requires advertiser_id/brand_id from list_accounts. IDs are for tool plumbing only — never display raw IDs to the user; refer to the brand/advertiser by name. Returns status='complete' with 'result' immediately on a warm brand context; on a cold one, returns status='running' with a 'task_id' -- poll it with get_mcp_task_result until status is 'complete' or 'failed'.

Brand vs Tier-1: ``volume``, ``monthly_trend``, or ``overlap_counts``.

Fetch one saved AI business rule by id (read-only). ``advertiser_id``/``brand_id`` MUST come from ``list_accounts``.

Supplementary per-subcampaign breakdown card with spend, impressions, clicks, CTR, CPM, and HCPs reached. Do NOT call this as the primary tool for performance analysis — use run_nlp_to_sql instead for live delivery + Rx stitched narratives with per-campaign GROUP BY. Only call this for a quick subcampaign lookup table after run_nlp_to_sql has already provided the main analysis. Requires advertiser_id/brand_id from list_accounts. IDs are for tool plumbing only — never display raw IDs to the user; refer to the brand/advertiser by name. Returns status='complete' with 'result' immediately on a warm brand context; on a cold one, returns status='running' with a 'task_id' -- poll it with get_mcp_task_result until status is 'complete' or 'failed'.

Campaign lifecycle view: delivery + Rx + pacing by subcampaign for one brand. Use when the user asks for a campaign "journey", flight-to-date story, how many doctors saw ads, prescription totals by tactic, or post-mortem for completed flights. Delegates to the same NLP-to-SQL pipeline as ``run_nlp_to_sql`` with a fixed multi-part analytical brief. ``advertiser_id``/``brand_id`` MUST come from ``list_accounts``. ``campaign_focus`` optionally narrows to one campaign name. May return status='running' — poll with get_mcp_task_result.

Supplementary UI performance card with KPI tiles, pillar summaries, and an 8-week trend chart. Do NOT call this as the primary tool for performance questions — use run_nlp_to_sql instead for live delivery + Rx stitched narratives. Only call this AFTER run_nlp_to_sql when the user specifically wants the UI performance card format. ``advertiser_id``/``brand_id`` MUST come from ``list_accounts``. May return status='running' — poll with get_mcp_task_result.

Combination-drug data for the active brand (``actual`` or ``predicted_vs_actual``).

Get competitor scripts grouped by drug class. Use when user asks: competitor by class, drug class breakdown, class-level competitors, classes competing, group by class. Returns competitor scripts per drug class. Requires advertiser_id/brand_id from list_accounts. IDs are for tool plumbing only — never display raw IDs to the user; refer to the brand/advertiser by name. Returns status='complete' with 'result' immediately on a warm brand context; on a cold one, returns status='running' with a 'task_id' -- poll it with get_mcp_task_result until status is 'complete' or 'failed'.

Get competitor information: tiered breakdown (direct, therapeutic alternatives, treatment pathway) with names, drug classes, prescriber counts, AND per-competitor Rx share and TRx from market share data. Use for competitor names, generic names, manufacturers, drug classes, mechanisms, tiers (tier 1/2/3), therapeutic alternatives, treatment pathway drugs, drugs in the same class on the market, how many competitors, who are the direct competitors, competitor NDC codes. Also use when asked about a specific competitor by name. Requires advertiser_id/brand_id from list_accounts. IDs are for tool plumbing only — never display raw IDs to the user; refer to the brand/advertiser by name. Returns status='complete' with 'result' immediately on a warm brand context; on a cold one, returns status='running' with a 'task_id' -- poll it with get_mcp_task_result until status is 'complete' or 'failed'.

Identify Tier 1 competitors actually stealing prescribers from the brand. Use when user asks: stealing prescribers, switchers, lost prescribers, prescribers we lost, switched away, churn analysis, defection. Switching is detected period-over-period using the IQVIA / Symphony "loss of share" methodology with 1-month windows: - W1 (months -3..-2): baseline brand-writing month - GAP (months -2..-1): buffer for behaviour to stabilise - W2 (months -1..now): recent month An NPI counts as switched when ALL four conditions hold: - brand_trx in W1 >= 2 (was a regular brand writer, not one-shot) - brand_trx in W2 < 50% of W1 (brand declined materially) - competitor_trx in W2 > W1 on the same NPI (competitor grew) - the growing competitor is a Tier 1 direct competitor Returns one row per Tier 1 competitor with: - ``competitor`` - drug name - ``npis_who_switched`` - count of NPIs meeting all conditions - ``avg_competitor_trx_growth`` - mean added TRx for the competitor - ``avg_brand_trx_decline`` - mean lost TRx on the brand Adoption (writing both with no decline) does NOT count as switching. Requires advertiser_id/brand_id from list_accounts. IDs are for tool plumbing only — never display raw IDs to the user; refer to the brand/advertiser by name. Returns status='complete' with 'result' immediately on a warm brand context; on a cold one, returns status='running' with a 'task_id' -- poll it with get_mcp_task_result until status is 'complete' or 'failed'.

Competitor tiers: ``list`` (by tier) or ``market_share`` (by tier).

Get data quality assessment: quality score, tier (gold/silver/bronze), field availability, evidence summary. Use for data reliability, data freshness, how current the data is, data methodology, data sources, field completeness, data quality score, is the data reliable, how was the data collected, data confidence level. Requires advertiser_id/brand_id from list_accounts. IDs are for tool plumbing only — never display raw IDs to the user; refer to the brand/advertiser by name. Returns status='complete' with 'result' immediately on a warm brand context; on a cold one, returns status='running' with a 'task_id' -- poll it with get_mcp_task_result until status is 'complete' or 'failed'.

Clinical and financial context for any drug name via live web search.

Count of writers of ``drug_a`` who do not write ``drug_b`` (set difference).

Get comprehensive profile of dual writers -- HCPs who prescribe BOTH brand AND competitor drugs. Includes volume comparison vs brand-only prescribers, loyalty ratio, per-competitor loyalty breakdown (how many lean towards each competitor), top states, top specialties. Use for how many prescribers write both brand and competitors, dual writer analysis, are dual writers higher volume, loyalty ratio of shared prescribers, which states have the most dual writers, dual writer characteristics, brand loyalty among shared prescribers, which competitor do they lean towards. Requires advertiser_id/brand_id from list_accounts. IDs are for tool plumbing only — never display raw IDs to the user; refer to the brand/advertiser by name. Returns status='complete' with 'result' immediately on a warm brand context; on a cold one, returns status='running' with a 'task_id' -- poll it with get_mcp_task_result until status is 'complete' or 'failed'.

Get the active brand's campaign/subcampaign hierarchy with exact Snowflake IDs and human-readable names. Returns ONLY the currently active brand — not other brands under the advertiser. Call this when you need BRAND_ID, CAMPAIGN_ID, or SUBCAMPAIGN_ID for SQL queries or campaign analysis. Requires advertiser_id/brand_id from list_accounts. IDs are for tool plumbing only — never display raw IDs to the user; refer to the brand/advertiser by name. Returns status='complete' with 'result' immediately on a warm brand context; on a cold one, returns status='running' with a 'task_id' -- poll it with get_mcp_task_result until status is 'complete' or 'failed'.

Cached KPI headline for one advertiser/brand: total campaigns, spend, impressions, HCPs reached, effective CPM. Quick cached check only — for live delivery + Rx data use ``run_nlp_to_sql`` instead, same as the chat agent's guidance. Returns status='complete' immediately on a warm brand context; on a cold one, returns status='running' — poll with get_mcp_task_result.

Identify the fastest-growing competitor by linear regression slope. Use when user asks: fastest growing competitor, accelerating competitor, gaining share, which competitor is rising, momentum competitor. Returns competitors ranked by growth slope. Requires advertiser_id/brand_id from list_accounts. IDs are for tool plumbing only — never display raw IDs to the user; refer to the brand/advertiser by name. Returns status='complete' with 'result' immediately on a warm brand context; on a cold one, returns status='running' with a 'task_id' -- poll it with get_mcp_task_result until status is 'complete' or 'failed'.

State-level HCP deep dive (segments, volumes, cities, specialties) for one US state.

Get geographic distribution (top states) of brand-related doctors/HCPs: state, HCP count, percentage. Quick state-level counts. Use for which state has the most prescribers/doctors/physicians, state-level summary, geographic breakdown, top states, regional distribution, where are the prescribers located. For DETAILED state drill-down with TRx/segments/cities, use get_geographic_deep_dive instead. Requires advertiser_id/brand_id from list_accounts. IDs are for tool plumbing only — never display raw IDs to the user; refer to the brand/advertiser by name. Returns status='complete' with 'result' immediately on a warm brand context; on a cold one, returns status='running' with a 'task_id' -- poll it with get_mcp_task_result until status is 'complete' or 'failed'.

Get all HCPCS/CPT procedure codes associated with the brand: code, frequency, patient count, prescriber count. Also includes validated codes with categories and relevance levels. Use for HCPCS/CPT code lookups, what a specific HCPCS code means/represents, code descriptions, ranking by frequency/patients/prescribers, validated codes, code categories (drug administration, monitoring, diagnostic, treatment, supportive care), how many HCPCS codes, which codes are most common, show only validated codes, reimbursement-related procedure codes. Requires advertiser_id/brand_id from list_accounts. IDs are for tool plumbing only — never display raw IDs to the user; refer to the brand/advertiser by name. Returns status='complete' with 'result' immediately on a warm brand context; on a cold one, returns status='running' with a 'task_id' -- poll it with get_mcp_task_result until status is 'complete' or 'failed'.

Get all ICD diagnosis codes associated with the brand: code, frequency, patient count, prescriber count. Also includes validated ICD codes with categories and relevance levels. Use for ICD code lookups, what a specific ICD code means/represents, code descriptions, ranking by frequency/patients/prescribers, validated vs unvalidated codes, relevance levels (high/medium/low), how many ICD codes, which codes are most common, ICD codes for the brand's indication, show only validated codes, show only high-relevance codes. Requires advertiser_id/brand_id from list_accounts. IDs are for tool plumbing only — never display raw IDs to the user; refer to the brand/advertiser by name. Returns status='complete' with 'result' immediately on a warm brand context; on a cold one, returns status='running' with a 'task_id' -- poll it with get_mcp_task_result until status is 'complete' or 'failed'.

Brand vs. competitor market share for one advertiser/brand. ``view``: ``brand_vs_competitors`` (default), ``by_tier``, or ``vs_tier1_direct``. Returns status='complete' immediately on a warm brand context; on a cold one, returns status='running' — poll with get_mcp_task_result.

Get market share breakdown for brand vs all competitors over last 12 months. Use when user asks: market share, share percentage, share vs competitors, brand share, percentage breakdown, who has what share, share split. Returns scripts and share % per drug. Requires advertiser_id/brand_id from list_accounts. IDs are for tool plumbing only — never display raw IDs to the user; refer to the brand/advertiser by name. Returns status='complete' with 'result' immediately on a warm brand context; on a cold one, returns status='running' with a 'task_id' -- poll it with get_mcp_task_result until status is 'complete' or 'failed'.

Poll any long-running MCP tool call by its ``task_id``. Every tool that can return status='running' (run_nlp_to_sql, get_campaign_journey_timeline, get_campaign_performance_brief, get_brand_challenges, query_audience, web_search, and any brand-scoped tool on a cold context) is polled the same way here. Call this again with the same task_id until status is 'complete' or 'failed' — never report the connector as unavailable solely because the operation is still running.

Compare mechanism of action (MOA) of the brand vs competitors. Use when user asks: mechanism of action, MOA, how does it work, pharmacology comparison, action mechanism vs competitors, MOA difference. Returns brand and competitor MOA comparison. Requires advertiser_id/brand_id from list_accounts. IDs are for tool plumbing only — never display raw IDs to the user; refer to the brand/advertiser by name. Returns status='complete' with 'result' immediately on a warm brand context; on a cold one, returns status='running' with a 'task_id' -- poll it with get_mcp_task_result until status is 'complete' or 'failed'.

Count of prescribers writing ALL listed drugs (intersection).

Messaging/narrative framework for a marketing challenge. Empty ``challenge`` returns the catalog of available challenge keys.