Tools Reference
SponserdIQ exposes 28 MCP tools for querying and interacting with sponsorship data. All tools return JSON responses. The same tool surface powers both the external /mcp endpoint (Claude Desktop, Claude Code, Cursor) and the in-app chat widget — one implementation, two delivery channels.
Tool categories:
-
Search & discovery —
search_sponsorships,search_brands,list_brands,list_properties,get_filter_options,resolve_entity,get_example_questions -
Entity drilldown —
get_brand_sponsorships,get_brand_details,get_property_sponsorships,get_property_sources -
Compound one-shot views —
property_snapshot,brand_snapshot(bundle 4–5 reads into a single call) -
Disambiguation —
resolve_entity,parse_date_range,get_canonical_vocabulary -
Self-service —
get_my_usage,get_my_conversations,get_subscription_status -
Platform state —
get_stats,get_pipeline_status,get_usage_stats -
Ad-hoc query —
query_sponsorships(structured filter + group-by + anti-join over the dataset) -
Meta —
run_skill,log_feedback
Source URLs
Every tool that returns sponsorship rows (search_sponsorships, get_property_sponsorships, get_brand_sponsorships) includes a sources field per row — a list of up to 5 {url, title} maps linking back to the specific press releases, partner pages, or news articles that evidenced that sponsorship. Sources are aggregated across every scrape that found the brand at the property and deduped by URL. An empty list means we haven't captured a machine-readable citation yet (the data may still be valid — the next scrape fills the gap). For a property-wide view of curated partner pages and the web-search citations that fed recent discovery, use get_property_sources.
search_sponsorships
Filter and paginate sponsorship relationships between brands and properties.
| Parameter | Type | Required | Description |
|---|---|---|---|
brand_name |
string | no | Filter by brand name (exact match or comma-separated list) |
property_name |
string | no | Filter by property name (exact match or comma-separated list) |
tier |
string | no | Filter by tier (e.g., title, presenting, official) |
industry |
string | no | Filter by brand industry |
segment |
string | no | Filter by property segment (e.g., College, Professional) |
league |
string | no | Filter by league (e.g., NFL, NBA, NHL) |
region |
string | no | Filter by region (e.g., Northeast, Pacific) |
activation |
string | no | Filter by activation (e.g., Official Healthcare Partner, Naming Rights Partner) |
sponsorship_type |
string | no | Filter by sponsorship type (naming_rights, presenting, title, official, signage, digital, community) |
renewal_status |
string | no |
Filter by renewal health: active, at_risk, stale, inconclusive. Accepts a single value or comma-separated list. inconclusive narrows to rows that look at-risk/stale but live on a property whose scrape hasn't succeeded recently |
page |
integer | no | Page number (default: 1) |
page_size |
integer | no | Results per page (default: 25, max: 100) |
Each result also includes a computed renewal_status field, property_last_successful_scrape_at, and a sources list (primary-source URLs for that sponsorship — see Source URLs).
Soft-removed sponsorships (those the Data Audit Agent verified as lapsed or pointing the wrong way) and sponsorships under quarantined brands or properties are excluded from results — they're inspectable separately via the removed_sponsorships skill.
Example: "Search for all NFL title sponsorships in the financial services industry" Example: "Search for at-risk sponsorships at the Dallas Cowboys" Example: "Find MLS sponsorships in the banking industry and show me the source for each"
search_brands
Search and filter brands with optional fuzzy name matching and pagination. More targeted than list_brands -- use this when you need specific brands.
| Parameter | Type | Required | Description |
|---|---|---|---|
query |
string | no | Fuzzy search by brand name (case-insensitive partial match) |
industry |
string | no | Filter by industry (exact match) |
company_size |
string | no | Filter by company size (startup, mid_market, enterprise, public) |
revenue_range |
string | no | Filter by revenue range (e.g., $1M-$10M, $100M-$1B) |
has_sponsorships |
boolean | no | Only return brands with active sponsorships (default: true) |
page |
integer | no | Page number (default: 1) |
page_size |
integer | no | Results per page (default: 25, max: 100) |
Example: "Search for enterprise healthcare brands"
list_brands
List all active brands in the sponsorship database. Returns brand name, industry, website, company size, revenue range, founding year, and description.
No parameters required.
list_properties
List sports properties (teams, leagues, events) with optional segment filter.
| Parameter | Type | Required | Description |
|---|---|---|---|
segment |
string | no | Filter by segment (e.g., College, Professional) |
get_brand_sponsorships
Get all sponsorships for a specific brand by name. Includes full brand details, each associated sponsorship record, and a sources list per sponsorship linking to the URLs that evidenced that specific deal.
| Parameter | Type | Required | Description |
|---|---|---|---|
brand_name |
string | yes | The brand name to look up |
Example: "Get all sponsorships for Nike" Example: "Show me every Nike sponsorship and cite the source for each"
get_brand_details
Get comprehensive details for a brand including full enrichment data, known aliases, source contexts from scraping, and a sponsorship summary. This is the deep-dive tool -- it exposes the AI-generated brand intelligence and the raw evidence from where each sponsorship was discovered.
| Parameter | Type | Required | Description |
|---|---|---|---|
brand_name |
string | yes | The brand name to look up |
Returns: Full brand fields (industry, company size, revenue range, founded year, description, enrichment timestamp), all known aliases, source contexts (which page the sponsor was found on, the surrounding text, extraction method, confidence score), and a sponsorship summary with tier distribution and league/segment coverage.
Example: "Get full details and source evidence for Best Nutrition"
get_property_sponsorships
Get all sponsorships for a specific property by name. Includes property details, scrape/enrichment health timestamps, and all sponsor records with brand enrichment data.
| Parameter | Type | Required | Description |
|---|---|---|---|
property_name |
string | yes | The property name to look up |
Returns: Under property, the response includes:
-
last_successful_scrape_at— ISO timestamp (ornull) of the most recent scrape that produced at least one non-review raw sponsor. Use this to tell whether the property's scrape signal is healthy. -
last_enriched_at— ISO timestamp (ornull), the most recent time any sponsorship under this property was enriched with AI-generated fields.
Each entry in sponsorships includes a renewal_status computed with property-health context (active / at_risk / stale / inconclusive) and a sources list of up to 5 URLs evidencing that specific sponsorship.
Example: "Get all sponsors of the Dallas Cowboys"
get_property_sources
Get the admin-curated partner pages and recent web-search citations for a property. Unlike get_property_sponsorships (which returns sponsors with their per-deal sources), this tool gives the property-wide source picture — useful for provenance debugging, data-quality reviews, or understanding which pages a property's discovery pipeline relies on.
| Parameter | Type | Required | Description |
|---|---|---|---|
property_name |
string | yes | The property name to look up |
Returns: admin_sources (partner pages curated by staff, each with url, label, active flag) and search_citations (URLs Claude's web search cited during recent discovery runs, newest first, capped at 25, deduped by URL).
Example: "What partner pages do we use for Angel City FC and what web sources has our search pulled from?"
get_filter_options
Get all available filter dropdown values. Returns valid options for tiers, industries, segments, leagues, regions, brand names, property names, category labels, and activation types.
No parameters required. Useful for discovering what filter values exist before running search_sponsorships.
get_stats
Get database statistics including row counts for all core tables, enrichment coverage percentages, and data freshness metrics.
No parameters required.
Returns: Table counts for brands, properties, sponsorships, raw_sponsors, scrape_runs, and brand_aliases. Also includes enrichment coverage (percentage of brands and sponsorships enriched by AI) and data freshness (when the last scrape completed and how many days ago).
get_renewal_health
Get sponsorship renewal-status counts (active / at_risk / stale / inconclusive) using the same definitions the dashboard's renewal stat cards use. Driven by last_seen_at recency, with at_risk/stale rows reclassified to inconclusive when the property's own scrape is unhealthy.
Use when the user asks about renewal health, churn risk, or at-risk deals — "how many at-risk renewals do we have?", "which segment has the worst churn signal?", "what's the renewal status breakdown for baseball properties?". For a single property's snapshot, prefer property_snapshot (returns the same renewal_counts block alongside more context).
Sponsorships soft-removed by the Data Audit Agent (AI-verified "deal is dead" — see removed_sponsorships skill) and sponsorships under quarantined brands or properties are excluded from these counts — the totals match what the dashboard shows. For AI-verified churn signal, use the removed_sponsorships or sponsorship_movement skills.
| Parameter | Type | Required | Description |
|---|---|---|---|
property_name |
string | no | Restrict to a single property (case-insensitive exact match) |
brand_name |
string | no | Restrict to a single brand (comma-separated list also accepted) |
industry |
string | no | Restrict to brands in this industry (canonical or raw) |
segment |
string | no |
Restrict to properties in this segment (e.g. mens_baseball, nwsl) |
league |
string | no | Restrict to properties in this league |
region |
string | no | Restrict to properties in this region |
tier |
string | no | Restrict to sponsorships of this tier |
Returns: Counts for each renewal bucket (active, at_risk, stale, inconclusive) plus the total, scoped to the filter set.
get_pipeline_status
Get scraping pipeline health metrics including run success rates, recent failures, and enrichment coverage.
| Parameter | Type | Required | Description |
|---|---|---|---|
property_name |
string | no | Filter to a specific property |
days |
integer | no | Lookback window in days (default: 7) |
Returns: Scrape run summary (total, completed, failed, success rate), recent failures with error details, and enrichment coverage rates for brands, sponsorships, and raw sponsor classification.
get_usage_stats
Get AI token usage and MCP tool call statistics for consumption monitoring and cost tracking.
| Parameter | Type | Required | Description |
|---|---|---|---|
days |
integer | no | Lookback window in days (default: 30) |
group_by |
string | no | Group AI usage by: day, model, or call_type (default: model) |
Returns: AI usage (total calls, tokens, estimated cost in USD grouped by model/type/day) and MCP tool usage (call counts, average duration, error counts per tool).
run_skill
Execute an enhanced analytics skill by name. Skills provide advanced queries beyond basic CRUD operations.
| Parameter | Type | Required | Description |
|---|---|---|---|
skill_name |
string | yes |
Name of the skill to execute (e.g., find_competitors, trending_sponsors, sponsorship_movement, brand_portfolio_history) |
params |
map | no | Skill-specific parameters (varies by skill) |
See the Skills Reference for the full list of available skills and their parameters.
Example: "Run the find_competitors skill for Coca-Cola"
Example: "Show me brands with the biggest 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"})
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})
log_feedback
Submit feedback about a previous tool or skill result. Used to report result quality and suggest improvements.
| Parameter | Type | Required | Description |
|---|---|---|---|
tool_name |
string | yes | Name of the tool or skill this feedback is about |
useful |
boolean | no | Whether the result was useful |
notes |
string | no | Free-text feedback about result quality |
missing_data |
string | no | Description of any expected but missing data |
resolve_entity
Disambiguate a free-form string to a specific entity type — brand, property, segment, league, industry, region, or unknown. Two-stage resolution:
- Exact match against brand aliases, property names, and canonical filter buckets (industries, leagues, regions, tiers, …). Returns immediately if it lands a high-confidence hit.
-
Semantic match when no exact hit clears the threshold. The query is embedded with OpenAI's
text-embedding-3-large, then ranked by cosine similarity against precomputed embeddings of every brand / property / canonical bucket. Lets descriptive phrases ("big beverage companies", "fast-food sponsors in the South") land on the right entity even though they don't string-match anything.
| Parameter | Type | Required | Description |
|---|---|---|---|
query |
string | yes | Free-form entity name or descriptive phrase (e.g. "Coke", "Lakers", "NFL", "healthcare", "big beverage companies") |
hint |
string | no |
Optional type hint to bias resolution: brand, property, segment, league, industry, or region |
Returns: type, canonical_name, confidence (0–1), matches (all candidates, each with via: "exact" or via: "semantic" so callers can see how the hit was made), and suggested_tool — the recommended next tool/skill given the resolved type.
Examples:
-
"Pepsi" → resolves to brand
Pepsi, suggestsbrand_snapshot -
"big beverage company" → resolves to brand
Coca-Colavia semantic, confidence ~0.7 -
"drinks" → resolves to industry canonical
Beveragesvia semantic
parse_date_range
Convert a natural-language date expression into a UTC ISO-8601 range. Use whenever the user mentions a relative time window and a downstream tool needs explicit from/to timestamps.
| Parameter | Type | Required | Description |
|---|---|---|---|
expression |
string | yes |
Natural-language expression: today, yesterday, this/last week, this/last month, this/last quarter, this/last year, Q1 2026–Q4 2026, 2024 (4-digit year), past N days, last N days, next N days |
reference_date |
string | no | Optional ISO-8601 date or datetime anchoring the parse (defaults to now, UTC) |
Returns: from, to (ISO-8601, half-open interval), label, granularity (day/week/month/quarter/year/range), and the resolved reference_date.
Example: "Show me NFL sponsorships from last quarter" → parse last quarter first, then filter.
property_snapshot
Single-call property brief — metadata + top-N sponsorships + renewal bucket counts + source coverage + scrape/enrichment freshness. Replaces get_property_sponsorships + get_property_sources + manual renewal-counting in one tool round.
| Parameter | Type | Required | Description |
|---|---|---|---|
property_name |
string | yes | The property name to snapshot (case-insensitive exact match) |
top_n |
integer | no |
Max sponsorships to include, ordered by most-recent last_seen_at (default 10, max 50) |
Returns: property (metadata plus scrape_unhealthy flag, last_successful_scrape_at, last_enriched_at), renewal_counts (active/at_risk/stale/inconclusive), sources (admin + search-citation counts), top_sponsorships (with renewal status per row), and total_sponsorships.
Example: "Give me a snapshot of the Los Angeles Lakers."
brand_snapshot
Single-call brand brief — details + aliases + sponsorships with distributions + top-N competitors + renewal counts. Replaces get_brand_details + get_brand_sponsorships + run_skill find_competitors in one tool round.
| Parameter | Type | Required | Description |
|---|---|---|---|
brand_name |
string | yes | The brand to snapshot (resolved via alias, case-insensitive) |
top_competitors |
integer | no | Max competitors to include (default 5, max 20) |
Returns: brand (full enrichment), aliases, total_sponsorships, renewal_counts, tier_distribution, league_breakdown, segment_breakdown, region_breakdown, and top_competitors (with overlap counts).
Example: "Tell me about Pepsi's sponsorship portfolio."
get_canonical_vocabulary
Return the canonical vocabulary for a field — the bucketed values AI classification collapses raw variants into. Disambiguates "what industries do you track?" in one call.
| Parameter | Type | Required | Description |
|---|---|---|---|
field_type |
string | yes |
One of: tier, industry, activation, sponsorship_type, region |
include_raw_examples |
boolean | no | If true, each canonical includes up to 10 raw-value examples that map to it |
include_unmapped |
boolean | no | If true, returns top raw values that haven't been classified yet (QA view) |
limit |
integer | no | Max canonicals to return (default 50, max 200) |
Returns: field_type, canonical_count, canonicals (with optional raw_values), and optional unmapped list.
Example: "What industries do you track?" / "Show me the tier vocabulary with examples."
get_my_usage
User-scoped usage snapshot — current-period chat-token quota, most-recent tool calls, and top tools by call count. Distinct from get_usage_stats which is org-wide.
| Parameter | Type | Required | Description |
|---|---|---|---|
recent_limit |
integer | no | Max recent tool calls to return (default 10, max 50) |
top_limit |
integer | no | Max top-tools entries (default 5, max 20) |
Returns: period (start/end), chat (tokens used/limit/remaining, staff_bypass), recent_tool_calls, top_tools with call counts.
Example: "How much have I been using the chat this month?"
get_my_conversations
User's recent chat-conversation index — titles, message counts, last activity. Answers "what did I ask yesterday?" without guessing.
| Parameter | Type | Required | Description |
|---|---|---|---|
limit |
integer | no | Max conversations, ordered by most-recent activity (default 10, max 50) |
Returns: conversations (id, title, message_count, last_message_at, inserted_at) and total.
Example: "Show me my recent chat conversations."
get_subscription_status
Subscription, trial, and billing-portal pointer for the authenticated user. Does not call Stripe inline — returns a manage_url pointing at /users/settings where the actual portal redirect lives.
No parameters required.
Returns: status, has_active_access, is_staff, trial (is_trialing, trial_ends_at, trial_days_remaining), stripe (id presence flags + subscription_activated_at), and manage_url.
Example: "What plan am I on?" / "When does my trial end?"
get_example_questions
Curated catalog of example questions SponserdIQ can answer, grouped by theme. Each question includes a suggested tool-call sequence so the assistant can demonstrate capability concretely.
| Parameter | Type | Required | Description |
|---|---|---|---|
theme |
string | no |
Narrow to one theme: brands, properties, competitive, renewal, market, trends, account, or cross_set. Omit for all themes. |
Returns: themes (list of {name, questions: [{text, tools}]}).
Example: "What can I ask?" / "Show me some examples for competitive analysis."
query_sponsorships
Structured ad-hoc query over the sponsorships dataset — the escape hatch when no pre-built skill covers the shape of the question. Supports filter + group-by + anti-join, all in one call.
Use for cross-set analysis ("in A but not B"), top-N aggregation ("top 10 industries by count"), and threshold questions ("brands with ≥3 NFL sponsorships").
| Parameter | Type | Required | Description |
|---|---|---|---|
filters |
object | conditional |
Inclusion filters. Keys: brand_name, property_name, tier, industry, segment, league, region, sponsorship_type, activation, renewal_status. Canonicalized fields (tier/industry/region/activation/sponsorship_type) resolve via canonical+fuzzy — "Charlotte" matches "Charlotte, NC" raw values. |
exclude_filters |
object | conditional |
Same keys as filters, applied as NOT. With group_by set, removes any group-key value whose sponsorships ALSO match these filters — the anti-join primitive. |
group_by |
string[] | conditional |
One field: brand_name, property_name, industry, segment, league, region, tier, or sponsorship_type. Returns {group_key, count} rows. Omit for flat sponsorship rows. |
having_min_count |
integer | no |
Drop groups with fewer than N matching sponsorships. Only meaningful with group_by. |
order |
string | no |
Ordering for grouped results: count_desc (default), count_asc, name_asc, name_desc. |
limit |
integer | no | Max rows returned (default 25, hard cap 500). |
At least one of filters / exclude_filters / group_by must be provided.
Returns:
-
rows— list of sponsorship rows (flat mode) or{group_key, count}entries (grouped mode). -
total_rows,applied_filters,applied_exclude_filters,group_by,truncated(bool),warnings(string list).
Safety rails:
-
Max 500 rows, max 50 distinct groups per call. Over-cap queries return partial results with a
warningsentry. -
Soft-removed sponsorships and sponsorships under quarantined brands/properties are excluded from both flat-row and grouped results, mirroring the visibility model of every other read tool. For agent-removed deals, use the
removed_sponsorshipsskill.
Examples:
-
"Brands sponsoring in Charlotte but not Greenville" —
filters: {region: "Charlotte"},exclude_filters: {region: "Greenville"},group_by: ["brand_name"]. -
"Top 10 industries in the Southeast by sponsorship count" —
filters: {region: "Southeast"},group_by: ["industry"],order: "count_desc",limit: 10. -
"Brands with ≥3 NFL sponsorships" —
filters: {league: "NFL"},group_by: ["brand_name"],having_min_count: 3.
relationship_graph
The connected relationship graph (nodes + edges) around an anchor — a brand, a property, or a category (segment / industry / league / region). Use this to see the network around something, not just a flat list: who sponsors a property and what those sponsors also sponsor (depth: 2), the brands and properties inside a segment, and dual-role bridges (an entity that is both a sponsor and sponsored). For a flat list prefer get_brand_sponsorships / get_property_sponsorships; for a single-brand brief use brand_snapshot.
| Parameter | Type | Required | Description |
|---|---|---|---|
anchor |
string | yes | The brand, property, segment, industry, league, or region to map. |
anchor_type |
string | no |
brand | property | segment | industry | league | region. Default auto (tries brand, then property, then category). |
depth |
integer | no |
Hops for a brand/property anchor: 1 = direct connections, 2 = neighbors-of-neighbors. Default 1, max 2. |
limit |
integer | no | Max relationships (edges) returned. Default 100, max 500. |
Returns: summary (anchor + node/edge/brand/property/dual_role counts), nodes ({id, label, type, group, degree}), edges ({source, target, type, tier, value}), total_count, and a graph_url that opens the same view in the SponserdIQ graph UI.
Example: "Map Liverpool FC's sponsors and who those sponsors also sponsor."
get_market_map
The canonical market map: a weighted cross-tab between any two of SponserdIQ's canonical dimensions — industry, segment, league, region, tier, activation, sponsorship_type. Each node is a canonical bucket (e.g. "Financial Services", "Men's Soccer"); each edge is weighted by the number of sponsorships connecting the two buckets. This is the same "Aggregate" view as the /graph axis dropdown. Use it for market-structure questions ("which industries sponsor men's soccer?", "what tiers dominate which leagues?") instead of paging through individual deals. Bounded by the number of buckets (dozens), so it stays cheap no matter how many sponsorships exist.
| Parameter | Type | Required | Description |
|---|---|---|---|
dimension_a |
string | no |
First axis — one of industry, segment, league, region, tier, activation, sponsorship_type. Default industry. |
dimension_b |
string | no |
Second axis (same options). Default segment. |
Returns: dimension_a, dimension_b, nodes ({id, label, type, group, count, degree}), edges ({source, target, count}), total_count, graph_url.
Example: "How do industries map to leagues?" — dimension_a: "industry", dimension_b: "league".
get_discovered_clusters
The discovered market map: emergent groupings of brands and properties found by k-means clustering over their semantic embeddings — NOT the human/AI taxonomy. Returns a bipartite map of brand-clusters ↔ property-clusters, each cluster labeled by its most representative member ("brands like Ticketmaster"). This is the "Discovered clusters" view in the /graph UI. Use it to surface affinities the taxonomy doesn't encode; compare it against get_market_map to spot where a discovered cluster cuts across your canonical labels — a hidden affinity worth a closer look. For the entities most similar to ONE brand/property, use the similar_entities skill.
| Parameter | Type | Required | Description |
|---|---|---|---|
cluster_type |
string | no |
brand or property. With cluster_index, drills into one cluster's member entities + their deals. With against, picks the anchor pile (default brand). |
cluster_index |
integer | conditional |
The cluster's numeric index — the number in a node id like bclus:3 → 3. Required when drilling into one cluster. |
against |
string | no |
Cross the discovered piles against the other pile or a canonical dimension (industry, segment, …). E.g. against: "industry" shows whether a discovered brand group lines up with your industry labels or cuts across them. |
Returns: mode (overview or a drill), nodes ({id, label, type, group, count, degree}), edges ({source, target, count}), total_count, graph_url.
Example: "What natural brand groups exist, and do they line up with industries?" — overview, then against: "industry".