Skills Reference
Skills are advanced analytics queries executed via the run_skill tool. Each skill is invoked by name with skill-specific parameters passed in the params map.
run_skill(skill_name: "find_competitors", params: {"brand_name": "Nike"})Live Research Pattern
Most entity-centric skills attach a live-research block to their response. SponserdIQ provides the proprietary structured context (portfolio, citations, renewals); the calling Claude executes the recommended live web searches to add what our DB can't know (current contract values, recent exec hires, RFPs, market news). Combined synthesis is something neither stock Claude nor SponserdIQ alone can produce.
Two shapes share id / query field names so callers see consistent structure:
research_protocol — the deep shape, used by the three flagship live-research skills (pitch_brief_for_brand, compare_with_live, challenge_protocol):
"research_protocol": {
"purpose": "",
"queries": [
{
"id": "recent_deal_announcements",
"query": "Nike sponsorship announcement 2026",
"extract": { "new_deals": "list of {property_name, url, date}" },
"compare_against": "portfolio[].property_name"
}
],
"output_schema": { /* how Claude should structure the synthesis */ }
}
live_research_hints — the lightweight shape, attached to a curated subset of entity-centric skills. 1–3 deterministic queries with a one-line purpose, no extraction schemas:
"live_research_hints": [
{
"id": "recent_brand_news",
"purpose": "verify the last 90 days of news for Nike",
"query": "Nike sponsorship news 2026"
}
]Skills returning either shape: every skill listed below as "live-research" returns a block. Pure-aggregate skills (segment counts, market overviews) intentionally don't — forced hints would be noise rather than signal.
Relational Skills
Skills that analyze relationships between brands and properties.
find_competitors
Finds brands that sponsor the same properties as a given brand, ranked by overlap count.
| Parameter | Type | Required | Description |
|---|---|---|---|
brand_name |
string | yes | The brand to find competitors for |
limit |
integer | no | Max competitors to return (default: 20) |
Returns: each competitor entry includes healthy_overlap_count alongside overlap_count — narrows the overlap to properties whose scrape is currently fresh, distinguishing live competitive presence from historical rivalry.
similar_entities
Finds the brands or properties most semantically SIMILAR to a given one, by embedding cosine similarity (k-nearest-neighbors). Unlike find_competitors (shared-property overlap), this ranks by what the entity is — so it surfaces lookalikes even when they share no sponsorships yet. Ideal for prospecting ("brands like Gatorade").
| Parameter | Type | Required | Description |
|---|---|---|---|
entity_name |
string | yes | The brand or property to find lookalikes for |
entity_type |
string | no |
brand or property (default: auto — brand first, then property) |
limit |
integer | no | Max lookalikes (default: 10, max: 50) |
Returns: a ranked similar list of {id, name, similarity} (cosine similarity in [-1, 1], higher = closer) plus live_research_hints. Returns similar: [] with a note when the entity has no embedding cached yet.
coverage_gaps
Identifies properties where a brand's competitors are active but the brand is not. Useful for finding expansion opportunities.
Returns: each gap entry includes healthy_competitor_count alongside competitor_count — narrows to competitors whose specific sponsorship at that property is fresh, so you target gaps where rivals are still actively present, not just historically present.
| Parameter | Type | Required | Description |
|---|---|---|---|
brand_name |
string | yes | The brand to check coverage for |
segment |
string | no | Filter to a specific property segment |
limit |
integer | no | Max results (default: 25) |
sponsor_prospects
Finds prospective sponsors for a property -- brands active in similar properties (same segment, league, or region) that do not yet sponsor the target property.
| Parameter | Type | Required | Description |
|---|---|---|---|
property_name |
string | yes | The property to find prospects for |
limit |
integer | no | Max results (default: 25) |
Returns: for each prospect, a healthy_similar_property_count alongside similar_property_count. The healthy count narrows the similarity score to properties whose scrape is currently fresh — useful for filtering rankings inflated by stale dormant sponsorships.
co_sponsorship_patterns
Identifies brands that frequently appear alongside a given brand at the same properties. Unlike competitors (same industry), co-sponsors are often complementary brands targeting similar audiences.
| Parameter | Type | Required | Description |
|---|---|---|---|
brand_name |
string | yes | The brand to analyze |
limit |
integer | no | Max results (default: 20) |
Returns: each co-sponsor entry includes healthy_co_occurrence_count alongside co_occurrence_count — narrows the affinity signal to properties whose scrape is currently fresh, so you see current market affinity rather than historical noise.
property_comparison
Compares two properties side by side -- sponsor overlap, tier distribution, industry mix, and category gaps.
| Parameter | Type | Required | Description |
|---|---|---|---|
property_a |
string | yes | First property name |
property_b |
string | yes | Second property name |
Returns: each property summary includes last_successful_scrape_at and a renewal_breakdown (active/at_risk/stale/inconclusive counts) — surfaces underlying scrape health so you don't compare a well-scraped property against a stale one without context.
industry_crossover
Analyzes which industries tend to co-sponsor at the same properties. Given an anchor industry, finds which other industries frequently appear alongside it.
| Parameter | Type | Required | Description |
|---|---|---|---|
industry |
string | yes | The anchor industry to analyze |
segment |
string | no | Filter to a specific property segment |
limit |
integer | no | Max co-occurring industries to return (default: 15) |
brand_overlap_matrix
Builds a pairwise property overlap matrix for multiple brands. Unlike find_competitors (single brand), this shows the full competitive landscape across the top N brands in an industry.
| Parameter | Type | Required | Description |
|---|---|---|---|
industry |
string | no | Filter brands by industry |
brand_names |
string | no | Comma-separated list of specific brands |
limit |
integer | no | Max brands in matrix (default: 10) |
Temporal Skills
Skills that leverage longitudinal scraping data to track changes over time.
trending_sponsors
Identifies brands with the most new sponsorships discovered within a recent period.
| Parameter | Type | Required | Description |
|---|---|---|---|
days |
integer | no | Look-back period in days (default: 90) |
limit |
integer | no | Max results (default: 20) |
Returns: each brand entry includes healthy_sponsorship_count alongside new_sponsorship_count — the same count narrowed to sponsorships on properties with a fresh successful scrape. Compare the two to separate genuine momentum from scrape-resume bursts.
sponsorship_movement
Population-wide top-movers leaderboard by net sponsorship change (new wins minus AI-verified removals) over a time window, at the user's chosen granularity. Complements brand_portfolio_history (single-brand timeline) with cross-population comparison: "which brands grew the most last quarter?", "which leagues lost the most sponsors?", "what industries are growing fastest in NWSL?".
| Parameter | Type | Required | Description |
|---|---|---|---|
scope |
string | yes |
Dimension to aggregate by — one of brand, property, industry, segment, league |
| direction | string | no | growing (positive net, sorted desc), shrinking (negative net, sorted asc), or both (default — non-zero movers sorted by |net|) |
| from | string | no | Window start (ISO-8601 datetime) — pair with to |
| to | string | no | Window end (ISO-8601 datetime) — pair with from |
| days | integer | no | Window size in days from now (alternative to from/to). Default 90 |
| limit | integer | no | Max movers (default 10, max 50) |
Returns: scope, direction, period (resolved window), total_movers, truncated, and movers — each row carries name, new_count (sponsorships first-seen in window, not removed), removed_count (sponsorships soft-removed in window via DataAuditAgent), net_change, and current_active_count for growth-rate context. Brand and property scopes also include id.
removed_count is the AI-verified churn signal (distinct from the timestamp-derived churned_sponsors skill). Visibility model matches the dashboard: quarantined brands, quarantined properties, and deleted/merged brands are excluded from all counts.
Example: "Top 5 brands by net portfolio gain in Q1 2026" → run_skill(sponsorship_movement, {scope: "brand", direction: "growing", from: "2026-01-01T00:00:00Z", to: "2026-03-31T23:59:59Z", limit: 5})
Example: "Which leagues lost the most sponsors in the last 90 days?" → run_skill(sponsorship_movement, {scope: "league", direction: "shrinking"})
churned_sponsors
Identifies sponsors whose last_seen_at has not been refreshed beyond a threshold, indicating likely dropped sponsorships.
| Parameter | Type | Required | Description |
|---|---|---|---|
days |
integer | no | Stale threshold in days (default: 90) |
property_name |
string | no | Filter to a specific property |
segment |
string | no | Filter by segment |
limit |
integer | no | Max results (default: 50) |
This is the timestamp-derived churn signal — "we haven't seen this sponsorship on a scrape recently". For the AI-verified churn audit trail (deals the autonomous Data Audit Agent searched the web and concluded were genuinely lapsed, with citations), use removed_sponsorships instead. They're complementary: churned_sponsors is fast and probabilistic; removed_sponsorships is slow and definitive.
removed_sponsorships
Audit trail of sponsorships soft-removed by the Data Audit Agent — AI-verified "deal is dead" decisions with the agent's stated reason and full original metadata. Has two modes: flat (default — one row per removed sponsorship) and trend (pass granularity — a removal time-series grouped by property or brand).
| Parameter | Type | Required | Description |
|---|---|---|---|
granularity |
string | no |
"week" or "month". When set, switches to trend mode (removal counts bucketed over time). Omit for the flat row list. |
group_by |
string | no |
Trend mode only. "property" (default — which properties are losing sponsors) or "brand" (which brands are being removed). |
brand_name |
string | no | Filter to one brand |
property_name |
string | no | Filter to one property |
reason_contains |
string | no |
Case-insensitive substring match on removal_reason (e.g. "direction", "still_active") |
from |
string | no |
ISO-8601 datetime — filters removed_at >= from. In trend mode, the window lower bound (defaults to ~12 buckets back) |
to |
string | no |
ISO-8601 datetime — filters removed_at <= to. In trend mode, the window upper bound (defaults to now) |
limit |
integer | no | Flat mode: max rows (default 50, max 200). Trend mode: max groups (default 20, max 200) |
Returns (flat mode): mode: "flat", filters (echoed), total_results, truncated, and removed_sponsorships — each row carries sponsorship_id, brand {id, name}, property {id, name}, tier, source_url, source_type, first_seen_at, last_seen_at, removed_at, removal_reason. Newest-first.
Returns (trend mode): mode: "trend", granularity, group_by, filters (echoed), period {from, to, buckets} (the resolved bucket window), total_groups, truncated, and groups — each carries id, name (the brand or property), total_removed, and a dense, zero-filled series of {bucket_start, removed_count}. Ranked by total_removed desc. The property side is the analog to brand_portfolio_history's weekly removed series (computed live from removed_at); a property's removed_count = distinct sponsors lost in that bucket.
Example: "Show me everything the agent removed for Pisa Pain in the last 30 days." → run_skill(removed_sponsorships, {brand_name: "Pisa Pain", from: "2026-04-18T00:00:00Z"})
Example: "List sponsorships removed under reason 'direction reversed'." → run_skill(removed_sponsorships, {reason_contains: "direction reversed"})
Example: "Plot weekly sponsorship removals per property this quarter." → run_skill(removed_sponsorships, {granularity: "week"})
Example: "Which brands get removed the most, month over month?" → run_skill(removed_sponsorships, {granularity: "month", group_by: "brand"})
new_entrants
Identifies brands new to sports sponsorship -- those where all sponsorships were first seen within a recent window.
| Parameter | Type | Required | Description |
|---|---|---|---|
days |
integer | no | Look-back period in days (default: 90) |
industry |
string | no | Filter by industry |
limit |
integer | no | Max results (default: 25) |
Returns: each brand entry includes a healthy_sponsorship_count alongside sponsorship_count so you can filter scrape-resume artifacts (a brand looking "new" only because its property just resumed scraping after a gap) from genuine net-new entrants.
For brands new to a SPECIFIC segment, league, or region (rather than sports overall), use segment_newcomers.
segment_newcomers
Identifies brands new to a specific scope — a segment, league, or region — within a recent window. Distinct from new_entrants (which is about being new to sports overall): a brand can be a long-time NFL sponsor and a brand-new NWSL sponsor at the same time. This skill surfaces that signal.
Two modes driven by whether brand_name is provided:
-
Discovery (no
brand_name) — returns a ranked list of brands newcomers to the scope. -
Check (
brand_nameprovided) — returnsis_newcomer: true | falsefor that single brand with supporting context.
At least one of segment, league, or region is required.
| Parameter | Type | Required | Description |
|---|---|---|---|
segment |
string | one of three |
Property segment to scope (e.g. "nwsl") |
league |
string | " |
Property league to scope (e.g. "NWSL") |
region |
string | " |
Property region to scope (e.g. "Southeast") |
brand_name |
string | no | If set, single-brand check mode |
days |
integer | no | Window in days (default: 90) |
industry |
string | no | Filter newcomers by industry (discovery only) |
limit |
integer | no | Max results (default: 25, discovery only) |
Returns: in both modes, a prior_sponsorships_outside_scope count tells you whether the brand has prior sponsorship history elsewhere — non-zero means "expanding into a new vertical", zero means "net-new to sports". Discovery mode also returns a per-brand healthy_sponsorship_count for the same scrape-resume filtering as new_entrants.
Example: "Which brands appeared in NWSL for the first time in the last 90 days?"
Example: "Is Modelo new to women's soccer?" → run_skill(segment_newcomers, {segment: "nwsl", brand_name: "Modelo"})
brand_momentum
Analyzes a brand's sponsorship acquisition rate over time. Classifies momentum as accelerating, decelerating, steady, new_entrant, or inactive.
| Parameter | Type | Required | Description |
|---|---|---|---|
brand_name |
string | yes | The brand to analyze |
months |
integer | no | Analysis window in months (default: 6) |
Returns: each monthly_activity entry includes new_on_healthy_properties alongside new_sponsorships — the same monthly count narrowed to sponsorships on properties with a fresh successful scrape. Sanity-check the momentum classification against this subcount when the brand's properties are mostly unhealthy.
renewal_tracker
Categorizes sponsorships by freshness relative to the scrape cycle. Catches at-risk deals before they fully churn.
- active -- last seen within the last scrape cycle (healthy)
- at_risk -- last seen 1-3 cycles ago (warning)
- stale -- last seen 3+ cycles ago (likely dropped)
| Parameter | Type | Required | Description |
|---|---|---|---|
league |
string | no | Filter by league |
segment |
string | no | Filter by segment |
property_name |
string | no | Filter to a specific property |
deal_tenure_analysis
Analyzes how long sponsorships have been active using first/last seen dates. Provides average tenure grouped by tier, league, or industry.
| Parameter | Type | Required | Description |
|---|---|---|---|
group_by |
string | no | Group results by: tier, league, or industry (default: tier) |
league |
string | no | Filter by league |
segment |
string | no | Filter by segment |
Returns: each entry in longest_deals and shortest_deals includes a renewal_status field for freshness context — tenure numbers can look "frozen" on properties whose scrape is unhealthy, and the renewal status flags those rows.
Analytics Skills
Skills that provide portfolio-level and market-level analysis.
geographic_analysis
Analyzes regional sponsorship patterns. Can show a brand's geographic spread, a region's sponsor makeup, or overall market distribution by region.
| Parameter | Type | Required | Description |
|---|---|---|---|
brand_name |
string | no | Analyze one brand's geographic spread |
region |
string | no | Analyze one region's sponsor makeup |
industry |
string | no | Filter by industry |
Provide brand_name for a brand's regional coverage and gaps, region for a region deep-dive, or neither for a market-wide geographic overview.
Returns: all three modes include healthy_sponsorship_count per region (or per brand in region-mode) alongside sponsorship_count — narrows to sponsorships on properties whose scrape is currently fresh, distinguishing genuine current geographic presence from stale historical data.
white_space_finder
Surfaces market WHITE SPACE — untapped (zero-deal) and under-served combinations between two canonical dimensions. Builds the canonical cross-tab (same data as the get_market_map tool), then reports the gaps every other tool hides. Market-structural, not entity-anchored — complements the brand-specific coverage_gaps / property_gap_finder.
| Parameter | Type | Required | Description |
|---|---|---|---|
dimension_a |
string | no | First canonical axis: industry, segment, league, region, tier, activation, sponsorship_type (default: industry) |
dimension_b |
string | no | Second canonical axis, same options (default: segment) |
limit |
integer | no | Max rows in each list (default: 20, max: 100) |
Returns: white_space (bucket pairs with zero deals between them, ranked by combined volume — the biggest "nobody bridges these two yet" gaps), thin_pairings (existing pairings with the fewest deals), and a summary of bucket/pairing counts.
property_gap_finder
Finds properties that are underselling compared to their peers -- properties with fewer sponsors than the segment/league average. Flags opportunities for sales outreach.
| Parameter | Type | Required | Description |
|---|---|---|---|
segment |
string | no | Scope to a segment |
league |
string | no | Scope to a league |
min_gap_pct |
integer | no | Minimum gap below peer average to flag (default: 25) |
limit |
integer | no | Max results (default: 20) |
portfolio_health
Analyzes a property's sponsor portfolio health -- tier distribution, industry diversity, staleness, and a computed health score.
| Parameter | Type | Required | Description |
|---|---|---|---|
property_name |
string | yes | The property to analyze |
stale_days |
integer | no | Staleness threshold in days (default: 90) |
Returns: tier distribution, industry distribution, segment-average comparison, a composite health score, and:
-
renewal_breakdown--{active, at_risk, stale, inconclusive}bucket counts. When the property's own scrape is unhealthy, at-risk and stale counts collapse intoinconclusive. -
property.last_successful_scrape_at-- most recent scrape that produced usable sponsors -
property.last_enriched_at-- most recent AI enrichment across the property's sponsorships -
Each entry in
stale_sponsorscarries arenewal_statusfield
brand_portfolio_summary
Generates a comprehensive portfolio summary for a brand -- tier breakdown, segment distribution, league spread, regional coverage, and industry peer comparison.
| Parameter | Type | Required | Description |
|---|---|---|---|
brand_name |
string | yes | The brand to summarize |
Returns: the breakdowns above plus renewal_breakdown (deals grouped by renewal status across the brand's portfolio). newest_sponsorship and oldest_sponsorship each include a renewal_status field.
brand_spend_estimate
Rolls a brand's bucketed estimated_value deals into a single annual-spend figure. Sums the bucket low / midpoint / high boundaries across all of the brand's sponsorships, with a validator-coverage breakdown so callers can gauge how much of the estimate is Sonnet-confirmed vs Haiku-only.
| Parameter | Type | Required | Description |
|---|---|---|---|
brand_name |
string | yes | The brand to estimate annual sponsorship spend for |
include_unvalidated |
boolean | no |
Include deals where only Haiku ran (no Sonnet validator rationale). Default false — totals reflect validator-confirmed buckets only. |
Returns: brand, sponsorship_count, priced_sponsorship_count, total_estimated_annual_spend: {low, midpoint, high}, bucket_distribution, validator_coverage: {validated, low_confidence, proposer_only, avg_confidence}, and per_sponsorship[] — each row contains property_name, tier, bucket, confidence, midpoint_estimate, validator_ran, rationale (Sonnet's free-text grounding for the bucket), and model (which model + outcome produced it).
Bucket midpoints are coarse by design — <$50K → $25K, $50K-$100K → $75K, $100K-$500K → $300K, $500K-$1M → $750K, $1M-$5M → $3M, $5M+ → $7.5M. This is a portfolio-level "whale or fish" answer, not a quote-grade number.
industry_benchmark
Benchmarks a brand's sponsorship portfolio against its industry peers -- sponsorship count, tier distribution, and segment coverage vs the industry average.
| Parameter | Type | Required | Description |
|---|---|---|---|
brand_name |
string | yes | The brand to benchmark |
market_overview
Provides a high-level overview of the entire sponsorship market -- totals, tier distribution, most active industries, top properties, top brands, and month-over-month growth.
| Parameter | Type | Required | Description |
|---|---|---|---|
top_n |
integer | no | Number of top items to return per category (default: 10) |
property_attractiveness
Ranks properties by attractiveness using sponsor count, title-tier ratio, and industry diversity. Computes a composite attractiveness score.
| Parameter | Type | Required | Description |
|---|---|---|---|
segment |
string | no | Filter by segment |
league |
string | no | Filter by league |
limit |
integer | no | Max results (default: 25) |
Enrichment Skills
Skills that leverage AI-enriched data for deeper analysis.
activation_exclusivity
Analyzes whether a brand holds exclusive sponsorship activations at its properties. Classifies each property position as exclusive (sole brand in activation), shared (1-2 others), or crowded (3+ others).
| Parameter | Type | Required | Description |
|---|---|---|---|
brand_name |
string | yes | The brand to analyze |
Returns: each property entry includes healthy_competitor_count and healthy_status alongside competitor_count and status — healthy_* versions only count activation competitors whose own sponsorship is currently fresh. A position listed as crowded with healthy_status: "exclusive" has 3+ historical activation competitors but none currently active. The summary block also includes healthy_exclusive, healthy_shared, healthy_crowded, and healthy_exclusivity_rate.
high_value_prospects
Identifies large companies (enterprise/public with high revenue) that have few or no sponsorships -- brands with budget capacity that are under-indexed in sports sponsorship.
| Parameter | Type | Required | Description |
|---|---|---|---|
min_revenue |
string | no | Minimum revenue tier (e.g., $100M-$1B, $1B+) |
industry |
string | no | Filter by industry |
limit |
integer | no | Max results (default: 25) |
Returns: each prospect entry includes healthy_sponsorship_count alongside sponsorship_count. A prospect with sponsorship_count: 5 but healthy_sponsorship_count: 0 is just as untapped as one with zero sponsorships — the historical deals are on properties we can no longer scrape.
sponsorship_type_breakdown
Analyzes the distribution of sponsorship types across the market (naming rights, presenting, signage, digital, community, etc.) grouped overall, by league, or by segment.
| Parameter | Type | Required | Description |
|---|---|---|---|
group_by |
string | no | Group by: overall, league, or segment (default: overall) |
segment |
string | no | Filter by segment |
league |
string | no | Filter by league |
activation_market_map
Maps sponsorship activations across the market. Shows which activations are most contested vs have openings at specific properties or leagues.
| Parameter | Type | Required | Description |
|---|---|---|---|
league |
string | no | Filter by league |
segment |
string | no | Filter by segment |
limit |
integer | no | Max activations to return (default: 20) |
deal_intelligence
Sales pitch preparation tool. Given a brand and/or property, finds comparable deals, suggests tier positioning, identifies competitors already present, and surfaces opportunity signals like category exclusivity and open tier slots.
| Parameter | Type | Required | Description |
|---|---|---|---|
brand_name |
string | no | The brand being pitched |
property_name |
string | no | The target property |
industry |
string | no | Industry for comparable deals (defaults to brand's industry) |
segment |
string | no | Property segment for comparable deals |
At least one of brand_name or property_name is required.
Returns: comparable deals, suggested tier positioning, competitors at the target property, and opportunity signals. Renewal-aware fields:
-
property_sponsors_by_renewal-- bucket counts across the target property's current roster -
Each entry in
competitors_at_propertycarries arenewal_statusso you can see which same-industry incumbents are vulnerable - An opportunity signal fires when the target property has at-risk or stale same-industry sponsors: "N Industry competitor(s) at risk or stale (Foo, Bar) — category may be opening"
-
Each entry in
comparable_dealsincludes asourceslist -- up to 5 primary-source URLs (press releases, news articles, partner pages) that evidenced each deal, so pitch decks can cite directly
Example: "Prepare a pitch for Best Nutrition to sponsor the North Carolina Courage" Example: "Show me comparable healthcare sponsorships and cite the press for each"
source_intelligence
Analyzes data source quality and distribution -- which source URLs produce the most sponsors, which extraction methods are most effective, and which properties have the lowest confidence scores. Also surfaces per-sponsor citation coverage (the rate at which Claude's web search attributes specific URLs to specific sponsors) and the most-cited URLs and domains across the corpus, so you can see which outlets (press releases, Sportico, Forbes, etc.) supply the most evidence.
| Parameter | Type | Required | Description |
|---|---|---|---|
property_name |
string | no | Scope to a specific property |
league |
string | no | Scope to a specific league |
limit |
integer | no | Max results per section (default: 20) |
Returns:
-
top_sources-- source URLs ranked by sponsor count, with average confidence -
extraction_method_distribution-- counts and avg confidence per method (ai_page/web_search) -
confidence_by_property-- properties with the lowest average confidence, low-confidence counts -
citation_coverage-- per-method{total, with_citations, coverage_percent}showing how often each extraction path attaches URLs to individual sponsors. Surfaces the web-search compliance gap (often 50-70%) vs. HTML back-fill (100%). -
top_cited_urls-- individual URLs cited across the most raw sponsors (deduped per-sponsor) -
top_cited_domains-- host-level rollup (forbes.com,sportico.com, etc.) so you can see outlet-level patterns rather than per-article detail
Example: "Which external outlets are driving our Angel City FC citations?" Example: "What's our citation coverage by extraction method across the NWSL?"
Live-Research Skills
The three skills below exist primarily to drive the live-research pattern (see "Live Research Pattern" near the top of this doc). Each returns the deep research_protocol block — a purpose, a list of pre-computed search queries with extraction schemas, and an output schema describing how Claude should structure the synthesis.
pitch_brief_for_brand
Sales-ready pitch brief for a brand. Returns the brand's known sponsorship portfolio with sources, plus a research_protocol Claude is meant to execute via live web search to add what our DB can't know — recent deal announcements, marketing-budget signals, exec changes, and RFP/open-inventory signals at a top property.
| Parameter | Type | Required | Description |
|---|---|---|---|
brand_name |
string | yes | The brand to build a pitch brief for |
Returns:
-
brand— id, name, industry, hq_location, company_size, revenue_range, description -
portfolio— each known sponsorship with property metadata, tier, dates, renewal_status, andsources(primary-source URLs) -
portfolio_summary— counts by segment, tier, renewal status; covered segments -
competing_categories— same-industry brands sharing properties (category-exclusivity angles) -
research_protocol— 3–4 pre-computed live-research queries withextractschemas plus anoutput_schemadescribing the synthesis Claude should produce
Example: "Give me a pitch brief for Nike" Example: "What's the live-research checklist for selling Coca-Cola on a new NWSL deal?"
compare_with_live
Returns SponserdIQ's last-known sponsor list for a property as a baseline and a research_protocol instructing the calling Claude to live-search the property's CURRENT sponsors and emit a structured diff (added / removed / unchanged / uncertain). Inverts the usual flow — our DB is treated as ground truth and the world gets checked against it.
| Parameter | Type | Required | Description |
|---|---|---|---|
property_name |
string | yes | The property to diff against live web results |
Returns:
-
property— id, name, segment, league, region,last_successful_scrape_at,last_web_search_at -
baseline—snapshot_taken_at(latest of HTML scrape and web search) and a list of known sponsors with brand_name, industry, tier, dates, sources -
research_protocol— 3 queries (current sponsors directory, recent partner announcements, departed-sponsor signals) plus adiff_schemadefiningadded/removed/unchanged/uncertain
Example: "Compare Angel City FC's current sponsors against what we have" Example: "What's changed at Atlanta United FC since our last scrape?"
challenge_protocol
Takes a structured claim about a sponsorship (existence, tier, or active) and returns SponserdIQ's supporting evidence plus a challenge_protocol of falsifying live web-search queries. The calling Claude runs the queries, weighs contradictions vs corroborations, and emits a calibrated verdict — lets users get confidence-rated answers instead of accepting the DB at face value.
| Parameter | Type | Required | Description |
|---|---|---|---|
brand_name |
string | yes | The brand named in the claim |
property_name |
string | yes | The property named in the claim |
claim_type |
enum | yes |
sponsorship_exists | tier | active |
claim_detail |
string | conditional |
Required when claim_type is tier (e.g. "title") |
Returns:
-
claim— echoed back -
our_evidence—matching_sponsorships(tier, dates, sources per match) andconfidence_signals(citation_count, most_recent_evidence_at, extraction_methods) -
challenge_protocol— theresearch_protocolshape, with queries deterministic perclaim_type:-
All claim types:
sponsorship_ended,official_directory_check(skipped if property has nowebsite_url) -
Tier claims add:
contradictory_holder,tier_downgrade,competitor_signed
-
All claim types:
-
falsification_schema— describes the verdict shape Claude should emit (verdict/contradictions/corroborations/confidence)
Example: "Verify that Nike is the title sponsor of Angel City FC" Example: "Is Coca-Cola's sponsorship of the Lakers still active?"
Deal-Level Skills
Skills that surface deal-specific fields (notes, estimated value, tenure) and feedback/QA context.
search_deals
Searches sponsorships by the rich fields the main search_sponsorships tool doesn't expose — deal notes, estimated-value substring, and deal tenure (days between first_seen_at and last_seen_at). At least one filter is required.
| Parameter | Type | Required | Description |
|---|---|---|---|
notes_contains |
string | no |
Case-insensitive substring match on deal_notes |
value_contains |
string | no |
Case-insensitive substring match on estimated_value (free-form string like "$5M/year") |
min_tenure_days |
integer | no |
Minimum days between first_seen_at and last_seen_at |
max_tenure_days |
integer | no |
Maximum days between first_seen_at and last_seen_at |
limit |
integer | no | Max rows (default 25, max 100) |
Returns: results (with brand_name, property_name, tier, deal_notes, estimated_value, tenure_days, renewal_status, timestamps), total_count, and the applied limit.
Example: "Find deals worth over $5M" / "Show me deals that mention naming rights."
get_feedback_activity
Read-side companion to the log_feedback tool — surfaces open-feedback counts and recent entries for a brand or property. At least one of brand_name / property_name must be provided.
| Parameter | Type | Required | Description |
|---|---|---|---|
brand_name |
string | conditional | Brand alias (case-insensitive) |
property_name |
string | conditional | Property name (case-insensitive) |
limit |
integer | no | Max recent entries (default 10, max 50) |
Returns: brand / property scope info, open_count, and entries (category, status, truncated message, timestamp).
Example: "Is anyone flagging data issues on Pepsi?"
low_confidence_extractions
Raw-sponsor extractions below a confidence threshold (and/or flagged needs_review). Review queue for data-quality triage.
| Parameter | Type | Required | Description |
|---|---|---|---|
property_name |
string | no | Scope to a specific property |
min_confidence |
number | no | Minimum confidence (default 0.0) |
max_confidence |
number | no | Maximum confidence (default 0.7) |
only_needs_review |
boolean | no |
If true, only rows with needs_review: true |
limit |
integer | no | Max rows (default 25, max 100) |
Returns: property scope, filters (echoed), total_count, limit, and extractions with brand_raw, confidence, needs_review, review_reason, extraction_method, source_url, truncated context_text, and classified flag.
Example: "Show me the review queue for Angel City FC."
Cross-Set / Ad-Hoc Query Recipes
Named shortcuts layered on top of the query_sponsorships tool. Each skill below is a thin recipe with pre-baked filters / exclude_filters / group_by / having shapes — use them when an English-named shortcut beats assembling raw query params.
market_presence_gap
Brands active in one scope (A) but absent from another (B). The classic anti-join question ("brands sponsoring in Charlotte but not Greenville?").
| Parameter | Type | Required | Description |
|---|---|---|---|
scope_type |
string | yes |
region / league / segment / industry / property_name |
scope_a |
string | yes | Included scope (brands must be present) |
scope_b |
string | yes | Excluded scope (brands must be absent) |
min_sponsorships |
integer | no | Minimum sponsorships in A (default 1) |
limit |
integer | no | Max brands (default 25) |
Returns: brands: [{brand_name, count_in_scope_a}], plus echoed scope params and warnings.
top_by_scope
Top-N values of a dimension within an optional scope, ranked by sponsorship count.
| Parameter | Type | Required | Description |
|---|---|---|---|
group_by |
string | yes |
brand_name / industry / property_name / tier / sponsorship_type |
scope_type |
string | no |
region / league / segment / industry / property_name; omit for global |
scope_value |
string | conditional |
Required iff scope_type is set |
limit |
integer | no | Default 10, max 100 |
Returns: rows: [{value, count}], plus scope description ("global" or "region=Southeast").
brands_above_threshold
Brands with ≥ N sponsorships, optionally scoped.
| Parameter | Type | Required | Description |
|---|---|---|---|
min_count |
integer | yes | Threshold (≥1) |
scope_type |
string | no |
region / league / segment / industry / property_name |
scope_value |
string | conditional |
Required iff scope_type is set |
limit |
integer | no | Default 25, max 200 |
Returns: brands: [{brand_name, sponsorship_count}], sorted desc by count.
Discovery Skills
suggest_next_queries
Deterministic follow-up suggester — maps an intent keyword in the context string to a curated list of next-question suggestions, each with a tool/skill chain. No AI call; cheap and predictable.
| Parameter | Type | Required | Description |
|---|---|---|---|
context |
string | yes | Free-form topic, summary, or recent-result description |
max_suggestions |
integer | no | Max suggestions (default 5, max 20) |
Returns: context (echoed) and suggestions (each with suggestion text and a tools array). Falls back to a stable 3-entry list (brand_snapshot, property_snapshot, resolve_entity, get_example_questions) when nothing matches.
Example: "What should I look at next after finding Nike's competitors?"
Segment / Market Skills
Scope-focused siblings to market_overview and new_entrants.
segment_snapshot
Segment-scoped market overview — total sponsorships, top brands, top properties, industry diversity, new-this-period count, and renewal bucket counts within a specific segment.
| Parameter | Type | Required | Description |
|---|---|---|---|
segment |
string | yes |
Property segment (e.g., womens_soccer, mens_football) |
region |
string | no |
Optional region filter — city, state, or macro-region (canonical+fuzzy). E.g. "Charlotte", "North Carolina", "Southeast". |
top_n |
integer | no | Top-N per category (default 10, max 50) |
months |
integer | no | Window for new-this-period count (default 3) |
Returns: segment, total_sponsorships, top_brands, top_properties, industries, new_this_period, renewal_counts.
Example: "Give me a market snapshot of NWSL."
first_mover_advantage
For a segment, league, or region, rank brands by the earliest first_seen_at on any sponsorship in that scope — identifies who pioneered the category.
| Parameter | Type | Required | Description |
|---|---|---|---|
segment |
string | conditional | Property segment |
league |
string | conditional | Property league |
region |
string | conditional | Property region (city, state, or macro-region; canonical+fuzzy) |
limit |
integer | no | Max brands (default 20, max 100) |
At least one of segment / league / region is required.
Returns: filters (echoed), total, first_movers (brand_name, industry, earliest_first_seen_at, tenure_days, sponsorship_count in scope).
Example: "Who were the first Apparel brands to enter NWSL?"
industry_concentration
Property-level market-concentration diagnostic — Herfindahl–Hirschman Index (HHI) over the brand-industry distribution. Bands follow DOJ/FTC guidelines: <1500 diverse, 1500–2500 moderately_concentrated, >2500 highly_concentrated. Works in property mode (full breakdown) or scope mode (per-property summary).
| Parameter | Type | Required | Description |
|---|---|---|---|
property_name |
string | conditional | Single-property mode |
segment |
string | conditional | Scope mode — per-property summaries |
league |
string | conditional | Scope mode — per-property summaries |
region |
string | conditional | Scope mode — filter to a region (city, state, or macro-region; canonical+fuzzy) |
limit |
integer | no | Max properties in scope mode (default 25, max 100) |
At least one of property_name, segment, league, or region is required.
Returns (property mode): property, total_sponsorships, industry_count, industry_distribution, hhi, concentration_band.
Returns (scope mode): filters, total, properties (each with hhi and concentration_band), ordered desc by HHI.
Example: "How diverse is the Lakers' sponsor base?" / "Which NWSL properties are most industry-concentrated?"
Timeline / Peer Skills
brand_timeline
Chronological view of a brand's sponsorship history — every sponsorship ordered by first_seen_at, annotated with tenure-to-date and current renewal status. Great for pitch prep and storytelling.
| Parameter | Type | Required | Description |
|---|---|---|---|
brand_name |
string | yes | The brand to timeline |
region |
string | no | Optional region filter — city, state, or macro-region (canonical+fuzzy) |
limit |
integer | no | Max events (default 50, max 200) |
Returns: brand (basic info), total_events, timeline (each event with property, league, segment, tier, first_seen_at, last_seen_at, tenure_days, current_renewal_status).
Example: "Show me Pepsi's sponsorship timeline."
brand_portfolio_history
Weekly historical portfolio metrics for ONE brand, sourced from the brand_sponsorship_history weekly snapshot table. Returns up to two years of week-by-week counts so you can plot trends and answer "how has the portfolio shape changed?". Complements brand_timeline (per-sponsorship event log) with portfolio-level aggregate trajectories.
| Parameter | Type | Required | Description |
|---|---|---|---|
brand_name |
string | yes | The brand to chart |
weeks |
integer | no |
Number of recent weeks to return (default 12, max 104). Ignored when from/to are provided. |
from |
string | no |
Optional ISO-8601 start date (YYYY-MM-DD). Filters week_start >= from. |
to |
string | no |
Optional ISO-8601 end date (YYYY-MM-DD). Filters week_start <= to. |
Returns: brand (basic info), total_weeks, snapshots — each row carries week_start, total, active, at_risk, stale, new, churned, removed, industry_at_capture. Ordered newest-first.
Metric semantics:
-
total / active / at_risk / stale— stock metrics describing the living portfolio at snapshot time. Excludes soft-removed sponsorships. -
new— flow: sponsorships first seen in the 7-day window before snapshot time. -
churned— flow: sponsorships whoselast_seen_atcrossed into stale within the last 30 days (timestamp-derived staleness proxy). -
removed— flow: sponsorships soft-removed by the Data Audit Agent in the last 7 days (AI-verified deaths with citations). Net portfolio change per week =new - removed.
Example: "How has Coca-Cola's at-risk count trended over the last 6 months?" → run_skill(brand_portfolio_history, {brand_name: "Coca-Cola", weeks: 26})
Example: "How many sponsorships did Nike lose to AI-verified churn last quarter?" → run_skill(brand_portfolio_history, {brand_name: "Nike", from: "2026-01-01", to: "2026-03-31"})
peer_comparison
Given a brand, auto-identifies peers in the same industry + similar company_size/revenue_range and compares portfolio size and segment spread side-by-side. Answers "how are we doing relative to peers?" without the user naming them.
| Parameter | Type | Required | Description |
|---|---|---|---|
brand_name |
string | yes | The anchor brand |
top_peers |
integer | no | Max peers (default 5, max 20) |
Returns: anchor (brand + portfolio stats) and peers (each with industry, portfolio stats, segment/league lists).
Example: "How does Nike's portfolio compare to its peers?"
compare_brands
Side-by-side comparator for 2–3 brands — portfolio sizes, segment/league spread, and pairwise shared-property counts. Complements challenge_protocol (tactics) with a vanilla diff view.
| Parameter | Type | Required | Description |
|---|---|---|---|
brand_names |
array or string | yes | List of 2–3 brand names (array or comma-separated string) |
Returns: brands (each with industry, company_size, revenue_range, total_sponsorships, leagues, segments) and pairwise_overlap (every pair with shared_property_count).
Example: "Compare Nike, Adidas, and Puma side by side."
Renewal / Health Skills
renewal_calendar
Upcoming renewal-risk schedule — currently-active sponsorships bucketed by weeks until they'd cross the at-risk cutoff if no refresh lands. Sales forecasting gold: turns raw last_seen_at dates into "call these N accounts in the next M weeks".
| Parameter | Type | Required | Description |
|---|---|---|---|
segment |
string | no | Scope to a segment |
league |
string | no | Scope to a league |
region |
string | no | Scope to a region (city, state, or macro-region; canonical+fuzzy) |
brand_name |
string | no | Scope to a brand |
weeks_ahead |
integer | no | Window in weeks (default 8, max 26) |
Returns: filters (echoed), total_projected, buckets (each with weeks_out, deal_count, deals array including projected_at_risk_at).
Example: "Which NFL deals are coming up for renewal in the next 8 weeks?"
data_freshness_report
Per-property scrape + enrichment health diagnostic — last_successful_scrape_at, last_enriched_at, scrape-unhealthy flag, inconclusive-renewal count, and a recommended action (healthy / rescrape / rescrape_and_reenrich / no_sponsorships). Useful for triaging data-quality concerns.
| Parameter | Type | Required | Description |
|---|---|---|---|
segment |
string | no | Scope to a segment |
league |
string | no | Scope to a league |
region |
string | no | Scope to a region (city, state, or macro-region; canonical+fuzzy) |
limit |
integer | no | Max properties (default 25, max 100) |
Returns: filters, total, properties (each with health timestamps, sponsorship_count, inconclusive_count, scrape_unhealthy flag, recommendation), and scrape_health_cutoff.
Example: "Which properties have stale scrape data?"
Cluster / Embedding Skills
These act on the discovered (k-means) embedding clusters behind the get_discovered_clusters tool — the emergent behavioral grouping, not the canonical taxonomy. They need a clustering run to have populated embedding_clusters; until then they degrade to a note.
cluster_discovery_for_entity
Shows which discovered cluster a brand or property belongs to (index, label, size) plus the top co-members ranked by cosine closeness. Cluster navigation from any single entity. Distinct from similar_entities (continuous k-NN): this is the entity's HARD k-means assignment.
| Parameter | Type | Required | Description |
|---|---|---|---|
entity_name |
string | yes | The brand or property |
entity_type |
string | no | brand, property, or auto (default) |
limit |
integer | no | Max co-members (default 10, max 50) |
Returns: entity, cluster {index, label, size}, and ranked members ({id, name, similarity}). cluster: nil + a note when unassigned.
cluster_gap_analysis
For ONE brand, find its cluster, then the properties (and a roll-up by any canonical dimension) that its cluster PEERS sponsor but it does NOT — ranked by peer support. The embedding-cluster analogue of coverage_gaps/find_competitors, which rank by shared properties instead.
| Parameter | Type | Required | Description |
|---|---|---|---|
brand_name |
string | yes | The brand to analyze |
gap_by |
string | no | Roll-up dimension (default: segment) |
limit |
integer | no | Max gap properties (default 20, max 100) |
peer_limit |
integer | no | Max cluster peers (default 200, max 500) |
min_peer_support |
integer | no | Min peers backing a gap (default 2) |
Returns: cluster, peer_count, gaps (per-property peer support + example peers + top tier), gap_by_dimension.
cluster_peer_benchmarking
Benchmark a brand's portfolio against the other brands in its cluster — "typical or outlier?". Compares portfolio size and per-dimension breadth/mix (tier distribution, segment spread, geographic reach) to the cluster norm across any of the 7 dimensions.
| Parameter | Type | Required | Description |
|---|---|---|---|
brand_name |
string | yes | The brand to benchmark |
dimensions |
array | no | Subset of dimensions (default: all 7) |
peer_limit |
integer | no | Max cluster peers (default 200, max 500) |
Returns: brand_profile, cluster_norms, and deviations (per metric: brand value, cluster mean, ratio, verdict typical/outlier_high/outlier_low).
cross_cluster_bridge_finder
Find entities bridging two behavioral groups. CLUSTER mode (two discovered-cluster refs): property clusters → bridging brands, brand clusters → bridging properties. CATEGORY mode (two canonical sides): brands active on both (e.g. industry=Automotive × segment=Esports). Ranked by min(side_a_deals, side_b_deals).
| Parameter | Type | Required | Description |
|---|---|---|---|
cluster_a / cluster_b |
string | cluster mode |
Cluster refs (pclus:3/bclus:3 or index) |
cluster_type |
string | no | Pile for plain indices (default: property) |
dimension_a + value_a |
string | category mode | First canonical side |
dimension_b + value_b |
string | category mode | Second canonical side |
limit |
integer | no | Max bridges (default 25, max 100) |
Returns: mode, bridge_entity, side_a/side_b echoes, bridge_count, ranked bridges (id, name, side deal counts, balance_score).
property_cluster_prospects
Seller-side mirror of cluster_gap_analysis. For a property, finds the BRANDS sponsoring its cluster-peer properties that it lacks — a ready-made prospect list, ranked by peer-property support. The embedding-cluster analogue of sponsor_prospects (taxonomy-based); distinct from property_gap_finder (segment-average scan).
| Parameter | Type | Required | Description |
|---|---|---|---|
property_name |
string | yes | The property (seller) to prospect for |
gap_by |
string | no | Roll-up dimension (default: industry) |
limit |
integer | no | Max prospect brands (default 20, max 100) |
peer_limit |
integer | no | Max cluster-peer properties (default 200, max 500) |
min_peer_support |
integer | no | Min peer properties a prospect is on (default 2) |
Returns: cluster, peer_count, ranked prospects (per brand: peer_support + example_properties + top_tier they buy at), prospects_by_dimension.
property_cluster_benchmarking
Seller-side mirror of cluster_peer_benchmarking. Benchmarks a property's sponsor base against its embedding-cluster peer properties — "am I typical, or under-monetized vs the properties most like me?" Compares sponsor count + per-dimension sponsor-base breadth/mix to the cluster norm across all 7 dims.
| Parameter | Type | Required | Description |
|---|---|---|---|
property_name |
string | yes | The property to benchmark |
dimensions |
array | no | Subset of dimensions (default: all 7) |
peer_limit |
integer | no | Max cluster-peer properties (default 200, max 500) |
Returns: property_profile (sponsor_count + per-dim distinct + top), cluster_norms, and deviations (per metric: property value, cluster mean, ratio, verdict).
Segment Landscape & Routing Skills
segment_competitive_landscape
Competitive landscape for a canonical dimension value broken down by another dimension: leading breakdown values, concentration (HHI), and over/under-indexing vs the overall market. Both dimensions accept any of the 7 canonical dimensions; pass scope_values to pool segments.
| Parameter | Type | Required | Description |
|---|---|---|---|
scope_value / scope_values |
string / array | yes (one) | The dimension value(s) to analyze |
scope_dimension |
string | no | Dimension the scope belongs to (default: segment) |
breakdown_dimension |
string | no | Dimension to break down by (default: industry) |
limit |
integer | no |
Max top rows (default 25, max 100) |
Returns: top (count + scope_share + market_share + index per value), over_indexed/under_indexed, hhi + concentration_band, scope/market totals.
recommend_analysis
Meta router. Given a scope (a brand, property, or canonical dimension value), computes cheap data-shape signals (volume, concentration, tier diversity, spread, cluster/embedding presence, staleness) and recommends which skills to run, in priority order, with reasons and suggested params.
| Parameter | Type | Required | Description |
|---|---|---|---|
entity_name |
string | one scope | A brand or property to profile |
entity_type |
string | no | brand, property, or auto |
dimension + value |
string | one scope | A canonical dimension value scope |
Returns: scope, signals, and ordered recommendations ({skill, reason, suggested_params}).
Seller-Side Parity Mirrors
Property-anchored mirrors of buyer-anchored skills, so a rights-holder gets the same intelligence pointed the other way. Each takes property_name.
find_property_competitors
Mirror of find_competitors. The OTHER properties sharing the most SPONSORS with yours (rivals for the same sponsor dollars), ranked by overlap. Unlike property_comparison (compare two named properties), this discovers them.
Returns: property, ranked competitors (overlap_count, healthy_overlap_count, shared_sponsors), total_sponsors.
property_timeline
Mirror of brand_timeline. A property's sponsors ordered by first_seen_at with sponsor brand + industry, tenure, and renewal status. Optional industry filter. Pitch-prep storytelling.
Returns: property, total_events, timeline.
property_revenue_estimate
Mirror of brand_spend_estimate. Rolls a property's bucketed sponsorship estimated_values into total annual revenue (low/midpoint/high) + validator coverage. "What's my book worth?" Optional include_unvalidated.
Returns: property, sponsorship counts, total_estimated_annual_revenue, validator_coverage, bucket_distribution, per_sponsorship.
property_momentum
Mirror of brand_momentum. A property's sponsor-acquisition rate recently vs historical → accelerating | decelerating | steady | new_entrant | inactive. Optional months (default 6).
Returns: property, momentum, recent_avg_per_month, historical_avg_per_month, total_new_sponsors, monthly_activity.