{"tools":[{"name":"tv_search_networks","description":"Resolves a TV network name to its network_no ID, or a set of network_no IDs back to names.\n\nPass either `name` (fuzzy substring on network_name) or `network_nos`\n(exact reverse lookup by ID). Exactly one must be given.","inputSchema":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Name","description":"Name fragment to search for (case-insensitive), e.g. \"CNN\", \"NBC\", \"ESPN\"."},"network_nos":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"default":null,"title":"Network Nos","description":"List of network_no values to resolve back to names/metadata."}},"title":"tv_search_networksArguments","type":"object"}},{"name":"tv_search_stations","description":"Finds a specific local TV station by call sign or name to get its station_no,\nor resolves a list of station_no IDs back to station metadata (reverse lookup).\n\nCovers both broadcast affiliates (positive station_no) and cable networks (negative station_no).\n\nPass either `name` (fuzzy match on call sign / station name, active stations only) or\n`station_nos` (exact reverse lookup by ID — for feed/Snowflake-share clients arriving\nwith raw IDs; includes inactive stations so historical IDs still resolve).","inputSchema":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Name","description":"Call sign or name fragment to search for (case-insensitive). Examples: \"GBTS\", \"WBZ\", \"WCVB\", \"NBC\", \"Boston CBS\", \"crmz\"."},"market_no":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Market No","description":"Optional — restrict `name` results to stations whose primary market matches this market_no. Ignored when `station_nos` is given. tv_search_markets resolves a market name to market_no."},"station_nos":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"default":null,"title":"Station Nos","description":"List of station_no values to resolve back to metadata (batched internally when large)."}},"title":"tv_search_stationsArguments","type":"object"}},{"name":"tv_search_demographics","description":"Discover and resolve TV demographic/segment IDs — including Political, Automotive,\nPlan Metrix, and other custom audience segments.\n\nCommon labels (A18-49, A25-54, M18-49, W25-54, HH, \"household\", etc.) do not need this\ntool — the high-level tools (tv_viewership_by_program, tv_viewership_by_time,\ntv_demographics) accept them directly via the `demo`/`demo_groups` parameter and resolve\nstandard demos internally (e.g. demo=\"HH\").\n\nThis tool covers everything else, via one of three modes:\n\n1. LIST CATALOGS (no arguments): returns the segment \"owner\" families available —\n   e.g. \"Comscore Political Segments\", \"Comscore Automotive - Local\",\n   \"Comscore Plan Metrix\". Start here when a user mentions Political, Automotive, or\n   Plan Metrix segments and you don't yet know what exists.\n\n2. LIST GROUPS (owner=...): returns the demo groups under an owner, each with its\n   demo_group_no, demo_group_name, and whether it is available locally/nationally.\n   E.g. owner=\"Comscore Political Segments\" returns per-state groups like\n   \"Political In-State NE v3 - 08.27.2018 to Ongoing\" (group 8541). Groups flagged\n   local can be broken out per market; national-only groups cannot.\n   demo_local=true means the group is usable via tv_demographics only — it is not\n   compatible with tv_viewership_by_program's demo parameter.\n\n3. LIST SEGMENTS (group=...): returns the individual demo_no segments inside a group.\n   Accepts the group name (exact) or its demo_group_no. E.g.\n   group=\"Political In-State NE v3 - 08.27.2018 to Ongoing\" returns the NE voter\n   segments (Democratic/Republican/Independent turnout tiers) with their demo_no.\n   demo_local=true on a segment means the same tv_demographics-only restriction\n   applies as for groups.\n\nA resolved group name is accepted directly by tv_demographics(demo_groups=[...])\nfor an audience breakout, as are individual demo_no values.\n\nA free-text `name` fragment also works for a fuzzy substring search across all demos\n(e.g. \"Hispanic A18-34\", \"WSIL\"); results include the owning group for context.\n\nWhen no owner/group matches, the requested segment is not available in TV data.\n\nA fourth mode covers reverse ID lookup:\n\n4. RESOLVE IDS (demo_nos=[...]): returns metadata for each demo_no — for feed/Snowflake-share\n   clients that arrive with raw demo_no values and need the names back.","inputSchema":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Name","description":"Optional free-text fragment for a fuzzy demo_name search."},"owner":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Owner","description":"Optional exact owner family name to list its groups (mode 2). Known owners include: Comscore Political Segments, Comscore Automotive - Local, Comscore Automotive - National, Comscore Plan Metrix."},"group":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Group","description":"Optional group name (exact) or demo_group_no to list its member segments (mode 3)."},"demo_nos":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"default":null,"title":"Demo Nos","description":"Optional list of demo_no values to resolve back to names/metadata (mode 4)."}},"title":"tv_search_demographicsArguments","type":"object"}},{"name":"tv_retrieve_next_page","description":"Retrieves the next page of results for a TV tool response that included a next_page_token.\n\nEach page's response carries its own next_page_token; a null token indicates the last page.","inputSchema":{"properties":{"next_page_token":{"title":"Next Page Token","type":"string","description":"The token from the previous response's next_page_token field."}},"required":["next_page_token"],"title":"tv_retrieve_next_pageArguments","type":"object"}},{"name":"tv_search_markets","description":"Find a Comscore TV market by name fragment to get its market_no,\nor resolve a list of market_no IDs back to market metadata.\n\nResolves a market name like \"Abilene, TX\" or \"New York\" to the market_no\nthat local TV queries take. Pass \"all\" (or leave `name` empty) to list every\nComscore market — never enumerate the footprint with letter-by-letter\nsearches, and note that the viewership tools take markets=[\"all\"] directly,\nso covering every market needs no lookup at all.\n\nPass `market_nos` instead of `name` to reverse-resolve raw market_no values\n(e.g. from a Snowflake share or a data feed) back to market metadata.\n\nIn every output — prose, headings, table columns, chart labels, and any\nWord/PPTX/PDF export — label these \"Comscore market\" (or \"CM\" after first\nuse). No other market/region term or acronym is permitted.","inputSchema":{"properties":{"name":{"default":"","title":"Name","type":"string","description":"Market name fragment (case-insensitive), e.g. \"Abilene\", \"Boston\","},"market_nos":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"default":null,"title":"Market Nos","description":"Optional list of market_no values to resolve back to metadata."}},"title":"tv_search_marketsArguments","type":"object"}},{"name":"tv_viewership_by_program","description":"Program-level viewership ranked by audience.\n\nCovers: Local Ranker, Local Program-Based, National Ranker, National Program-Based,\nNational Ad Report, Syndicated Series Reporting.\n\nScope (provide at least one, or omit all for all national networks):\n  markets:   Market names, e.g. [\"Abilene, TX\", \"Buffalo, NY\"], or [\"all\"] for\n             every Comscore market (no market lookups needed).\n             Automatically fetches all stations in those markets.\n             In output, label these \"Comscore market\" (or \"CM\" after first use) —\n             never any other market/region term.\n  stations:  Station call signs or names, e.g. [\"WABC\", \"KRBC Abilene, Texas (NBC)\"]\n             Can mix with markets.\n  networks:  Network names for national path, e.g. [\"ABC\", \"NBC\", \"A&E\"]\n             Mutually exclusive with markets/stations.","inputSchema":{"properties":{"period":{"title":"Period","type":"string","description":"\"Specific broadcast month;2023-February\" — that's the format. Other examples: \"Specific calendar month;2023-November\" \"Specific Time Range;2024-March-13-2024-March-14\" \"Specific Day;2024-July-01\""},"markets":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Markets"},"stations":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Stations"},"networks":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Networks"},"dayparts":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Dayparts","description":"Daypart names or clock hours, e.g. [\"Prime\", \"14:00\", \"3am to 3am\"]. Named: \"Early Morning\", \"Daytime\", \"Early Fringe\", \"Prime Access\", \"Prime\"/\"Broadcast Prime\", \"Late Fringe\", \"Overnight\". Clock hour: \"02:00PM\", \"14:00\", \"07:00AM\" → 1-hour window each. Multiple clock hours: pass each as a separate list item, e.g. [\"12:00AM\", \"01:00AM\"] for midnight-2am coverage (two 1-hour windows). Semicolon-separated string also works: \"12:00AM;01:00AM\". \"3am to 3am\" / \"6am to 6am\" / \"All Week\" = total day (no filter)."},"days_of_week":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Days Of Week","description":"Day filters, e.g. [\"Monday\", \"Weekdays\", \"Friday\"]. Can also be included in dayparts list."},"station_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Station Types","description":"Which stations a `markets` scope expands to. Default (omitted) = local over-the-air broadcast stations only. Options: \"broadcast\" (OTA), \"cable\" (national cable feeds as carried in those markets — the only way to get cable viewing for a market), \"independent\", \"all\"."},"dimension":{"default":"series","title":"Dimension","type":"string","description":"What to rank rows by: \"series\" (default), \"station\", \"network\", \"telecast\", \"newscasts\", \"genre\". \"series\" aggregates each program to one row across the whole period — use this for \"top N programs\" questions. \"telecast\" returns one row per individual airing (each date + start_time is a separate row, so one program can appear dozens of times) — only use this when the request is specifically about individual broadcasts/airdates, not an aggregated ranking."},"demo":{"default":"HH","title":"Demo","type":"string","description":"Demographic, e.g. \"HH\" (default), \"A18-49\", \"W25-54\", \"M18-49\". Pass the demographic the request NAMES, verbatim. \"Persons 25-54\" and \"A25-54\" are different demographics, not two spellings of one: Persons demos count people in the age range, A/M/W demos count households containing someone in it. A request for persons must be passed as \"Persons 25-54\" (likewise \"Persons 18-49\", \"Persons 18+\", \"Male Persons 25-54\", ...) — substituting the A-label silently returns another population's numbers. Multiple demos can be requested in a single call by separating them with semicolons, e.g. \"A18-34;A18-49;A25-54;A55+\". The first demo uses the bare metric name (e.g. avg_aud, rating); each additional demo gets its own column suffixed with the demo label, e.g. avg_aud_A18-49, rating_A55+, returning all demos in a single call. Custom segment IDs from tv_search_demographics (e.g. a Political, Automotive, or Plan Metrix demo_no) cannot be used here directly — pass them via demo_groups instead (see below)."},"demo_groups":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Demo Groups","description":"Cross-tab program rankings by a custom segment group discovered via tv_search_demographics — e.g. a Comscore Automotive, Political, or Plan Metrix group name/demo_group_no (owner \"Comscore Automotive - Local\" → group \"Intent to Buy - Rollup Segments\" → individual segments like \"New Pickup\"), or an individual demo_no/demo_name. Look up the exact group or segment first with tv_search_demographics — group/segment names are not guessable. Each entry adds an avg_aud/rating/share column for that segment alongside the primary demo (same one-column-per-demo pattern as semicolon-separated `demo` values) — rows stay grouped by the `dimension` (e.g. one row per program), now cross-tabbed with segment reach. Local-only groups only return data on local (markets/stations) queries; national-only groups only return data on the networks path. Segment pct/index values from the same owner family (e.g. multiple Automotive groups) can overlap and are not additive."},"metrics":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Metrics","description":"Metrics to return. Default: [\"avg_aud\", \"rating\", \"share\", \"num_hours\"]. Options: \"avg_aud\", \"rating\", \"share\", \"num_hours\", \"demo_index\" (the native \"Demo Index\" field — Demo Rating / HH Rating x100 — pass \"Index\" or \"demo_index\" directly; do not ask the user to choose a definition, this is the one canonical Demo Index), \"ad_rating\", \"ad_grps\", \"ad_avg_aud\", \"ad_gross_aud\", \"ad_to_telecast_index\", \"num_airings\", \"ad_num_airings\" (national ad report only). Syndicated series: \"daily_aa\", \"gross_aa\", \"weighted_aa\", \"available_hours\", \"series_no\" (routes to local_syndicated_views). Every row also always includes meets_demo_threshold and meets_high_quality_demo_threshold for each non-HH demo requested (true/false) — surface these to flag suppressed/low-confidence figures (below 300 HH/25 hrs, or below 75 HH for the high-quality bar). The API only computes these for a demographic, so an HH-only request (demo=\"HH\", the default) won't return them."},"stream":{"default":"live","title":"Stream","type":"string","description":"\"live\" (default), \"live+3\" / \"c3\", \"live+7\" / \"c7\". Works on both national (commercial c3/c7 ratings) and local (DVR-inclusive playback within 72h/168h) endpoints. Defaulting to \"live\" only counts live viewing — DVR/time- shifted playback within the Live+3/Live+7 windows is excluded unless requested. A response note flags when Live+3/Live+7 figures are also available for the query but weren't requested."},"series_filter":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Series Filter","description":"{\"include\": [\"Series Name\"]} or {\"exclude\": [\"Series Name\"]} to filter by specific series."},"extra_periods":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Extra Periods","description":"Additional period strings to include alongside the primary period. Use for \"Extra Period\" comparison periods. Pass the raw value from the prompt including the \"Extra Period;\" prefix if present, e.g. [\"Extra Period;2023-November-25-2023-November-26\"] or without the prefix: [\"2023-November-25-2023-November-26\"]. Results from all periods are combined into a single OR date filter."},"breakout":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Breakout","description":"Optional secondary breakout dimension that splits each program row into one row per value, instead of aggregating over the whole period. \"week\" — per-week pivot (the \"Series;Week\" column pivot): each program gets a row per broadcast week with that week's share/index, rather than a period average. \"daypart\" — one row per daypart passed in `dayparts`, in a SINGLE request. Without it, multiple dayparts aggregate into one combined number, so a per-daypart report needs one call per daypart; use it whenever a request asks for several dayparts broken out (e.g. all 7 standard dayparts). Currently supported on local program queries."},"limit":{"default":100,"title":"Limit","type":"integer","description":"Maximum rows to return in total (default 100), max 10000. Increase for full rankings, decrease for top-N queries. A scope over 300 stations is split into batched requests and merged; `limit` applies once, to that merged total, not per batch — raising it never shrinks any individual batch."}},"required":["period"],"title":"tv_viewership_by_programArguments","type":"object"}},{"name":"tv_viewership_by_time","description":"Time-slot viewership — ratings by quarter-hour, hour, day, or daypart.\n\nCovers: Local Time-Based, National Time-Based, Local Trender (Chart),\nNational Trender (Chart), Time-Based Grid widgets.\n\nScope (provide at least one, or omit for all national networks):\n  markets:  Market names, e.g. [\"Abilene, TX\"], or [\"all\"] for every Comscore\n            market (no market lookups needed).\n            In output, label these \"Comscore market\" (or \"CM\" after first use) —\n            never any other market/region term.\n  stations: Station call signs or names, e.g. [\"KRBC Abilene, Texas (NBC)\"]\n  networks: Network names for national path, e.g. [\"AMC\", \"ABC\"]","inputSchema":{"properties":{"period":{"title":"Period","type":"string","description":"Period string (same formats as tv_viewership_by_program)."},"markets":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Markets"},"stations":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Stations"},"networks":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Networks"},"dayparts":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Dayparts","description":"Daypart names or clock hours to filter to. Days of week can also be included here."},"days_of_week":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Days Of Week","description":"Day filters (can also go in dayparts)."},"station_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Station Types","description":"Which stations a `markets` scope expands to. Default (omitted) = local over-the-air broadcast stations only. Options: \"broadcast\" (OTA), \"cable\" (national cable feeds as carried in those markets — the only way to get cable viewing for a market), \"independent\", \"all\"."},"granularity":{"default":"qtr_hour","title":"Granularity","type":"string","description":"Time resolution for rows: \"qtr_hour\" (default) — one row per 15-minute slot \"hour\"               — one row per hour \"day\"                — one row per broadcast day (Trender) \"week\"               — one row per week \"daypart\"            — one row per daypart passed in `dayparts`, all from a SINGLE request. Without it, multiple dayparts collapse into one combined number, so a per-daypart report needs one call per daypart. Use it whenever a request wants several dayparts broken out (e.g. all 7 standard dayparts)."},"demo":{"default":"HH","title":"Demo","type":"string","description":"Demographic, e.g. \"HH\", \"A18-49\". Pass the demographic the request NAMES, verbatim: \"Persons 25-54\" (people in the range) and \"A25-54\" (households containing someone in it) are different demographics, so substituting one for the other silently returns another population's numbers. Multiple demos can be requested in one call by separating with semicolons, e.g. \"A18-34;A18-49;A55+\" — each gets its own column suffixed with the demo label (rating_A18-49, avg_aud_A55+, ...), returning all demos in a single call. For BOTH \"household metrics\" and \"demographic metrics\" together (e.g. household \"Live Share\" + demographic \"Share\" with a stated demographic like A18+), demo=\"HH;A18+\" combines them: the HH column covers the household metric and the demo column covers the demographic metric."},"metrics":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Metrics","description":"Default: [\"avg_aud\", \"rating\"]. Options: \"avg_aud\", \"rating\", \"share\", \"num_hours\", \"sets_in_use\" (the \"Sets In Use\" / \"SIU\" / \"QH SIU\" metric — pass \"Sets In Use\" or \"sets_in_use\"). Like share, sets_in_use emits one column per demo (HH → \"sets_in_use\", demo → \"sets_in_use_<demo>\"). Every row also always includes meets_demo_threshold and meets_high_quality_demo_threshold for each non-HH demo requested (true/false) — surface these to flag suppressed/low-confidence figures (below 300 HH/25 hrs, or below 75 HH for the high-quality bar). The API only computes these for a demographic, so an HH-only request (demo=\"HH\", the default) won't return them."},"stream":{"default":"live","title":"Stream","type":"string","description":"\"live\" (default), \"live+3\" / \"c3\", \"live+7\" / \"c7\"."},"aggregate_stations":{"default":false,"title":"Aggregate Stations","type":"boolean","description":"Collapse all stations in scope into one row per market (per time slot / daypart) by summing their audience — e.g. a single per-market \"Cable\" total with station_types=[\"cable\"]. The row carries a `stations` count. Sums avg_aud / rating / share / num_hours (all additive over a market's stations); Sets In Use is a market-level level, so its maximum is kept rather than a sum. Local (markets/stations) queries only."},"limit":{"default":100,"title":"Limit","type":"integer","description":"Maximum rows to return in total (default 100). Increase to fetch a full trender/time-grid. A scope over 300 stations is split into batched requests and merged; `limit` applies once, to that merged total, not per batch — raising it never shrinks any individual batch. Bulk-pull exception: `granularity=\"daypart\"` on a batched scope (a full-footprint pull) returns EVERY (station, daypart) row and ignores `limit` — capping there would silently drop stations, and the caller would have to shard the market list by hand to get the whole answer. For a top-N program ranker with daypart breakout, use `tv_viewership_by_program(breakout=\"daypart\", limit=N)`."}},"required":["period"],"title":"tv_viewership_by_timeArguments","type":"object"}},{"name":"tv_market_viewership","description":"Network viewership broken down by market — National Market widget.","inputSchema":{"properties":{"period":{"title":"Period","type":"string","description":"Period string, e.g. \"Specific calendar month;2023-November\"."},"markets":{"items":{"type":"string"},"title":"Markets","type":"array","description":"Market names, e.g. [\"Portland, ME\", \"Abilene, TX\"]. In output, label these \"Comscore market\" (or \"CM\" after first use) — never any other market/region term."},"networks":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Networks","description":"Network names, e.g. [\"ABC\", \"A&E\"]. None = all networks."},"metrics":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Metrics","description":"Default: [\"avg_aud\", \"rating\", \"num_hours\"]. Options: \"avg_aud\", \"rating\", \"num_hours\", \"market_index\" (market vs national rating ratio ×100), \"hh_universe\" (household universe count), \"market_rank\" (market rank number). \"Total Hours Viewed\" → \"num_hours\"; \"Market Index\" → \"market_index\"; \"Household Universe\" → \"hh_universe\"; \"Market Rnk\"/\"Market #\" → \"market_rank\"."},"group_by":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Group By","description":"Dimensions, e.g. [\"market\", \"network\"] (default), [\"network\"] (aggregate all selected markets per network), [\"market\"] (aggregate across networks per market), [\"network\", \"day_of_week\"]."},"limit":{"default":100,"title":"Limit","type":"integer"}},"required":["period","markets"],"title":"tv_market_viewershipArguments","type":"object"}},{"name":"tv_demographics","description":"Station demographic breakdown or national HH/demo universe estimates.\n\nTWO MODES:\n\n1. Station Demographic Breakdown (set universe_estimates=False, default):\n   Returns avg_aud by demographic group (income, race, education, country of origin).\n   Requires markets or stations + period.\n\n2. National HH/Demo Universe Estimates (set universe_estimates=True):\n   Returns national_demo_universe for demographic groups.\n   Use year + month instead of period.","inputSchema":{"properties":{"period":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Period","description":"Period string (mode 1). E.g. \"Specific Time Range;2024-April-03-2024-April-09\"."},"markets":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Markets","description":"Market names (mode 1). In output, label these \"Comscore market\" (or \"CM\" after first use) — never any other market/region term."},"stations":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Stations","description":"Station call signs or names (mode 1)."},"dayparts":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Dayparts","description":"Daypart filters (mode 1), e.g. [\"All Week\", \"Weekdays\"]."},"demo_groups":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Demo Groups","description":"Demographic group names to look up. Examples: Mode 1: [\"HHs W/ Race/Ethnicity\", \"Household Income\", \"Country of Origin\", \"HHs W/ Education\"] Mode 2: [\"A18+\", \"M18+\", \"W18+\", \"English more than Spanish\", \"Dog - Yes\"] Also accepts a custom SEGMENT GROUP name or demo_group_no discovered via tv_search_demographics (e.g. \"Political In-State NE v3 - 08.27.2018 to Ongoing\" or 8541) — it resolves to the group's member segments automatically. Local-flagged groups break out per market; national-only groups will not return local data."},"universe_estimates":{"default":false,"title":"Universe Estimates","type":"boolean","description":"True → national universe estimates mode."},"year":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Year","description":"Year for universe estimates mode (e.g. 2024)."},"month":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Month","description":"Month name for universe estimates mode (e.g. \"April\")."}},"title":"tv_demographicsArguments","type":"object"}},{"name":"tv_schedule","description":"Program schedule — what aired on a station/network on a given day.\n\nCovers: Station Schedule widget.\n\nScope: provide markets, stations, or networks (at least one).\n  markets:  Fetch schedule for all stations in these markets.\n  stations: Specific station call signs or names.\n  networks: Network name for national schedule lookup.","inputSchema":{"properties":{"day":{"title":"Day","type":"string","description":"Date string, e.g. \"2024-July-01\" or \"2024-07-01\"."},"markets":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Markets"},"stations":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Stations"},"networks":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Networks"},"fields":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Fields","description":"Columns to return (user-friendly OR API names). Default: all available. User-friendly → API name mappings: \"Air Date\" → \"day\" (broadcast date, formatted as 'Mon DD, YYYY') \"Air Time\" → \"airdatetime\" (broadcast start time, H:MM AM/PM local) \"Run Time\" → \"duration_minutes\" (program length in minutes, integer) \"Series Name\" → \"series_name\" \"Episode Title\" → \"episode_title\" Other API fields: \"episode_no\", \"is_new_airing\", \"series_genre\". NOTE: \"Run Time\" = duration in MINUTES (e.g. 30, 60), i.e. program length — not a time of day. \"Air Time\" is the broadcast clock time."}},"required":["day"],"title":"tv_scheduleArguments","type":"object"}},{"name":"find_media","description":"Searches for media entities (sites/apps) by name. Intended for questions like \"what sites match X\" or \"find the ID for Y\".\n\nget_metric, get_trend, get_demographics, get_audience_overlap, and get_cross_visiting resolve media internally and do not require a prior find_media call.\n\nThis is a prefix search — query=\"Nexstar\" returns all Nexstar entities in one call.","inputSchema":{"properties":{"query":{"title":"Query","type":"string","description":"Site, app, or brand as the user names it (e.g. \"HBO\", \"cnn.com\"), passed verbatim; a brand is not equivalent to its domain. The shortest parent name returns the full portfolio."},"geo":{"default":"US","title":"Geo","type":"string","description":"Geographic market, default \"US\"."},"product":{"default":"mmx","title":"Product","type":"string","description":"Product slug for context, default \"mmx\"."},"report":{"default":"keymeasures","title":"Report","type":"string","description":"Report slug for context, default \"keymeasures\"."},"time_period":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Time Period","description":"Numeric period code. Defaults to last published month."},"exact_match":{"default":false,"title":"Exact Match","type":"boolean","description":"Require exact name match, default False."}},"required":["query"],"title":"find_mediaArguments","type":"object"}},{"name":"get_metric","description":"Single-month metric for a site or publisher. Accepts a media name directly; a prior lookup is not required.","inputSchema":{"properties":{"media":{"title":"Media","type":"string","description":"Site, app, or brand as the user names it (e.g. \"HBO\", \"cnn.com\"), passed verbatim, including any qualifier in parentheses (e.g. \"ESPN (Mobile App)\", \"CNN (TV App)\"). Qualifiers are significant and a brand is not equivalent to its domain."},"metric":{"title":"Metric","type":"string","description":"\"unique visitors\", \"reach\", \"minutes\", \"pages\", \"page views (mm)\", \"visits\", \"frequency\", \"viewers\", \"video views\", \"composition index\", \"% composition\", \"composition index videos\", \"composition index minutes\", \"% composition minutes\", \"avg daily visitors\", \"desktop-only uv\", \"mobile-only uv\"  (multiplatform mmx only — exclusive audiences), (and aliases like \"people\", \"UV\", \"time spent\"). \"Composition index\" / \"% composition\" express how concentrated the audience is vs. the target's universe — they require target= to be set to be meaningful (mmx only)."},"time":{"default":"last_month","title":"Time","type":"string","description":"\"last_month\", \"YYYY-MM\", or raw period integer."},"geo":{"default":"US","title":"Geo","type":"string","description":"Geographic market, default \"US\"."},"product":{"default":"mmx","enum":["mmx","video","mobile"],"title":"Product","type":"string","description":"\"mmx\" (default, web+app), \"video\" (VMX), \"mobile\" (Mobile Metrix)."},"platform":{"default":"desktop","enum":["desktop","multiplatform","total_digital_population","mobile","ctv"],"title":"Platform","type":"string","description":"For mmx: \"desktop\" (default), \"multiplatform\" (desktop+mobile), \"total_digital_population\", \"mobile\". mmx \"multiplatform\" is the Desktop+Mobile dedup — it is NOT Total Digital Population. \"total_digital_population\" is the widest MMX view: the Desktop+Mobile dedup PLUS Social. It is a substantially larger number — use it whenever the user asks for Total Digital Population or TDP by name. Comscore publishes it for audience size, reach, composition and adult age only. For video: \"multiplatform\" (default, = Desktop+Mobile+CTV), \"desktop\", \"mobile\", \"ctv\"."},"limit":{"default":10,"title":"Limit","type":"integer","description":"Max rows, default 10."},"target":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Target","description":"Demographic segment — \"gen z\", \"women\", \"18-24\", \"men 25-34\", etc. For combined/Advanced Audience (multiple segments OR'd), prefix with \"advanced,\" e.g. \"advanced,Males: 65+,Males: 55-64,Females: 65+\". These are OR-combined (targetType=1) and returned as a single aggregate value."},"expand_all_media":{"default":false,"title":"Expand All Media","type":"boolean","description":"True to return sub-property breakdown with hierarchy (depth, parent_id)."},"beta_data":{"default":false,"title":"Beta Data","type":"boolean","description":"True to use Comscore beta/preview data instead of standard production data (the UI \"beta data\" toggle). Default False (standard). mmx only."},"percent_change":{"default":false,"title":"Percent Change","type":"boolean","description":"True to also fetch the prior month and report the change vs. that period (adds prev_value/prev_value_human/percent_change to output)."},"audience_universe":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Audience Universe","description":"Audience universe for multiplatform MMX reports. Only applies when platform=\"multiplatform\". Valid values: \"Desktop 2+ and Total Mobile 18+\" (id=4, default for most markets), \"Desktop 2+ and Total Mobile 13+\" (id=6), \"Desktop 6+ and Total Mobile 18+\" (id=4, some geos), \"Default\" or omit for no universe filter."},"include_total_internet":{"default":false,"title":"Include Total Internet","type":"boolean","description":"True to also return the Total Internet baseline for the same geo/time/target alongside the entity result, per platform where a breakdown applies. Mirrors the UI \"Include Total Internet\" toggle, and costs no extra request. With metric=\"unique visitors\" this is the population each % Reach is divided by."}},"required":["media","metric"],"title":"get_metricArguments","type":"object"}},{"name":"get_trend","description":"Multi-month time series for one or more sites and metrics — trends, \"last N months\", or any date range. Accepts media names directly; a prior lookup is not required.\n\nComparisons go in one call: pass every site and every metric the user is comparing\nas lists (e.g. media=[\"redfin.com\", \"zillow.com\"], metric=[\"unique visitors\",\n\"pages\", \"minutes\"]). They are fetched together in a single report — a call per site\nor per metric is slower and adds nothing.\n\nA request that names \"Total Digital Population\" or \"TDP\" must be sent with\nplatform=\"total_digital_population\". platform=\"multiplatform\" is Desktop+Mobile only\nand answering a TDP question with it reports the wrong audience under the user's own\nwords for a different one (CF-3510).","inputSchema":{"properties":{"media":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"}],"title":"Media","description":"Site, app, or brand as the user names it, passed verbatim, including any qualifier in parentheses (e.g. \"ESPN (Mobile App)\", \"CNN (TV App)\"). Qualifiers are significant and a brand is not equivalent to its domain. A list of up to 25 names compares them side by side."},"metric":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"}],"title":"Metric","description":"Same vocabulary as get_metric. A list of up to 6 metrics returns a series for each."},"time_range":{"default":"last_3_months","title":"Time Range","type":"string","description":"\"last_3_months\" (default), \"last_6_months\", \"last_12_months\", or \"YYYY-MM:YYYY-MM\"."},"geo":{"default":"US","title":"Geo","type":"string","description":"Geographic market, default \"US\"."},"product":{"default":"mmx","enum":["mmx","video","mobile"],"title":"Product","type":"string","description":"\"mmx\" (default), \"video\" (VMX), \"mobile\"."},"platform":{"default":"desktop","enum":["desktop","multiplatform","total_digital_population","mobile","ctv"],"title":"Platform","type":"string","description":"For mmx: \"desktop\" (default), \"multiplatform\" (desktop+mobile), \"total_digital_population\", \"mobile\". mmx \"multiplatform\" is the Desktop+Mobile dedup, not Total Digital Population. \"total_digital_population\" is the widest MMX view: the Desktop+Mobile dedup PLUS Social. It is a substantially larger number — use it whenever the user asks for Total Digital Population or TDP by name. Comscore publishes it for audience size, reach, composition and adult age only. For video: \"multiplatform\" (default, = Desktop+Mobile+CTV), \"desktop\", \"mobile\", \"ctv\"."},"limit":{"default":0,"title":"Limit","type":"integer","description":"Max rows, default 0 (all months)."},"target":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Target","description":"Single demographic segment — same vocabulary as get_metric."},"audience_universe":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Audience Universe","description":"Audience universe for multiplatform MMX — same values as get_metric."},"include_total_internet":{"default":false,"title":"Include Total Internet","type":"boolean","description":"True to also return a Total Internet baseline series (`total_internet_series`), at no extra request."},"expand_all_media":{"default":false,"title":"Expand All Media","type":"boolean","description":"True to return sub-property trend breakdown (e.g. CNN sections over time). One entity and one metric only."}},"required":["media","metric"],"title":"get_trendArguments","type":"object"}},{"name":"search_category","description":"Find available category names for get_top_entities.","inputSchema":{"properties":{"query":{"title":"Query","type":"string","description":"Partial name to search (case-insensitive), e.g. \"auto\", \"health\"."}},"required":["query"],"title":"search_categoryArguments","type":"object"}},{"name":"get_top_entities","description":"Ranked list of top entities within a category.\n\nCovers Media Ranker, Media Industry Ranker, and any widget that shows a ranked\nlist of sites/publishers within an industry or category. When an entity\n(e.g. \"CNN.COM\") is the context for a ranker, that entity's industry category is\npassed as `category` and the ranked list is returned (a single-entity value is\nthe domain of get_metric).\n\nCommon entity → category mappings (search_category resolves an unknown category):\n  CNN.COM, BBC → \"News\" or \"General News\"\n  Spotify, Apple Music → \"Entertainment - Music\" or \"Entertainment\"\n  ESPN, BBC Sport → \"Sports\"\n  YouTube, Netflix → \"Streaming Video\"\n  SHOPIFY.COM → \"Retail\"\n  Adobe Sites → \"Technology\"\n  PSG.FR, sports teams → \"Sports\"\n  NPR.ORG → \"News\"\n  OUTKICK.COM → \"Sports\" or \"News\"\n  Lifestyles / BDG Lifestyles / lifestyle brands → \"Lifestyles\"\n  Automotive brands → \"Automotive\"\n  Health/medical → \"Health\"\n  Travel brands → \"Travel\"\nFor Mobile Metrix ranker (product=\"mobile\"), pass the same category name — it maps to the\ncorrect mobile-specific mediaSet automatically.\n\nproduct='video' (VMX) IS supported — use it for video publisher / streaming queries.\nproduct='mobile' (Mobile Metrix) IS supported — use it for mobile audience queries.\nproduct='mmx' is the default for general web audience queries.\n\nProduct routing:\n  - \"top video publishers\", \"streaming\", \"video views\", \"viewers\" → product='video', metric='video views'\n  - \"top mobile apps/sites\", \"mobile audience\" → product='mobile'\n  - everything else → product='mmx'\n\nSupported metrics by product (use these alias names):\n  mmx (multiplatform): 'unique visitors', 'reach', 'minutes', 'pages', 'visits',\n                       'video views', 'frequency', 'median age', 'mean age'\n  mmx (desktop only):  all above + 'composition index'\n  video (VMX):         'video views', 'viewers' (=unique viewers/reach 000),\n                       'minutes', 'reach', 'frequency', 'videos per viewer'\n  mobile:              'unique visitors', 'reach', 'minutes', 'pages', 'visits',\n                       'frequency', 'median age', 'mean age', 'median income'","inputSchema":{"properties":{"category":{"title":"Category","type":"string","description":"\"top 100\" for general queries; verticals: \"news\", \"sports\", \"automotive\", \"health\", \"travel\", \"finance\", \"technology\", \"retail\", \"social media\", \"streaming video\", etc. search_category resolves an unknown category. For Media Industry Ranker: this is the entity's industry category, not the entity itself. Also accepts the exact name of the user's own private MMX Saved Group (product=\"mmx\" only) — a custom list of entities they built and saved in the Comscore web UI. Tried automatically as a fallback when the name doesn't match a known category; ranks that group's own member entities instead of an industry vertical."},"metric":{"default":"unique visitors","title":"Metric","type":"string","description":"Metric to rank by, default \"unique visitors\". For multiplatform metrics specify the platform suffix, e.g. \"unique visitors, Desktop and Mobile\" or \"% Reach, Desktop\"."},"time":{"default":"last_month","title":"Time","type":"string","description":"\"last_month\" (default), \"YYYY-MM\", or raw period integer."},"geo":{"default":"US","title":"Geo","type":"string","description":"Geographic market, default \"US\"."},"product":{"default":"mmx","enum":["mmx","video","mobile"],"title":"Product","type":"string","description":"\"mmx\" (default), \"video\" (VMX), or \"mobile\" (Mobile Metrix)."},"platform":{"default":"multiplatform","enum":["desktop","multiplatform","mobile","ctv"],"title":"Platform","type":"string","description":"\"multiplatform\" (default), \"desktop\", \"mobile\". For video: also \"ctv\"."},"limit":{"default":100,"title":"Limit","type":"integer","description":"Top N to return (default 100, max 100)."}},"required":["category"],"title":"get_top_entitiesArguments","type":"object"}},{"name":"get_audience_overlap","description":"Audience overlap (duplication) across 2–10 sites/apps — the shared audience and what\nfraction of each entity's audience also visits the others.\n\nFor MMX, platform=\"multiplatform\" (the default) returns the combined Desktop-and-Mobile\nfigure plus the Desktop AND Mobile breakdowns together under each entity's \"by_platform\"\nkey — a single call covers all three; separate desktop and mobile calls return data already\npresent in the multiplatform response. The combined figure is the Desktop+Mobile dedup; it\nis not Total Digital Population, which also includes Social and is not reported here.\n\nReports a per-entity value for every requested metric plus the duplicated audience\n(\"2 or More Sites\" and \"All Sites\") and the combined unduplicated total. Supports an\naudience filter (age/gender/HH-size etc.) and US local markets (CS Markets).","inputSchema":{"properties":{"media":{"items":{"type":"string"},"title":"Media","type":"array","description":"2–10 entities as the user names them (e.g. [\"HBO\", \"ESPN\", \"cnn.com\"]),"},"metrics":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Metrics","description":"Metrics to report, e.g. [\"unique visitors\", \"reach\", \"minutes\","},"audience":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Audience","description":"Optional audience filter. Pass a single string (\"women 25-54\", \"adults 18+\","},"time":{"default":"last_month","title":"Time","type":"string","description":"\"last_month\" (default), \"YYYY-MM\", or raw period integer."},"geo":{"default":"US","title":"Geo","type":"string","description":"\"US\" (default), a country, or a US local market / CS Market (e.g. \"Boston, MA\")."},"product":{"default":"mmx","enum":["mmx","video","mobile"],"title":"Product","type":"string","description":"\"mmx\" (default), \"video\" (VMX), \"mobile\"."},"platform":{"default":"multiplatform","enum":["desktop","multiplatform","mobile","ctv"],"title":"Platform","type":"string","description":"\"multiplatform\" (default) — use this for all MMX requests. Returns combined"}},"required":["media"],"title":"get_audience_overlapArguments","type":"object"}},{"name":"get_demographics","description":"Full demographic breakdown for a site — Demographic Profile, Demographic Breakouts,\nand any widget asking for age/gender/region/income breakdown of an entity's audience.\nReturns all segments in a single call.\n\nA request that names \"Total Digital Population\" or \"TDP\" must be sent with\nplatform=\"total_digital_population\". platform=\"multiplatform\" is Desktop+Mobile only\nand answering a TDP question with it reports the wrong audience under the user's own\nwords for a different one (CF-3510).","inputSchema":{"properties":{"media":{"title":"Media","type":"string","description":"Site, app, or brand as the user names it, passed verbatim; a brand is not equivalent to its domain. For multiple entities pass comma-separated names, e.g. \"Yahoo,Yahoo Sports\"."},"time":{"default":"last_month","title":"Time","type":"string","description":"\"last_month\" (default), \"YYYY-MM\", or raw period integer."},"geo":{"default":"US","title":"Geo","type":"string","description":"Geographic market, default \"US\"."},"product":{"default":"mmx","enum":["mmx","video","mobile"],"title":"Product","type":"string","description":"\"mmx\" (default), \"video\" (VMX), \"mobile\"."},"platform":{"default":"multiplatform","enum":["desktop","multiplatform","total_digital_population","mobile","ctv"],"title":"Platform","type":"string","description":"\"multiplatform\" (default), \"desktop\", \"total_digital_population\", \"mobile\". Ignored for video/mobile. \"multiplatform\" is the Desktop+Mobile dedup, reported under the \"Desktop and Mobile\" by_platform key — not Total Digital Population. \"total_digital_population\" is the Desktop+Mobile dedup plus Social, a substantially larger number; use it whenever the user asks for Total Digital Population or TDP by name. Report each figure under the platform name the response gives it (CF-3510)."},"audience":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Audience","description":"Comma-separated demographic dimensions to break down by (e.g. \"Children,HH Size\", \"Region,Language\", \"Persons\"). Default: age/gender breakdown. Valid segments: standard age/gender targets, plus \"Children\", \"HH Size\", \"HHI\" (household income), \"Race\", \"Region\", \"Language\". Prefix with \"advanced,\" for a filtered single segment (e.g. \"advanced,Children: Yes\")."},"metrics":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Metrics","description":"List of metrics to return alongside UV (e.g. [\"% Reach\", \"% Composition\", \"Total Visits\", \"Total Views\"]). Default: unique visitors only. For multiplatform, % Reach breakdown by Desktop/Mobile is always included."},"audience_universe":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Audience Universe","description":"Audience universe for multiplatform MMX, same values as get_metric (e.g. \"Desktop 2+ and Total Mobile 18+\", \"Desktop 2+ and Total Mobile 13+\"). Defaults to \"Desktop 2+ and Total Mobile 18+\" (universeTypeId 4), which the demographicprofile report requires to return data for multiplatform/mobile."}},"required":["media"],"title":"get_demographicsArguments","type":"object"}},{"name":"get_cross_visiting","description":"Other sites that a site's audience also visits (affinity / cross-visiting). Returns,\nper co-visited site/category, the shared audience and the requested cross-visiting metrics.","inputSchema":{"properties":{"media":{"title":"Media","type":"string","description":"Base site/app/brand as the user names it, passed verbatim. For multiple base"},"time":{"default":"last_month","title":"Time","type":"string","description":"\"last_month\" (default), \"YYYY-MM\", or raw period integer."},"geo":{"default":"US","title":"Geo","type":"string","description":"Geographic market, default \"US\" (e.g. \"Brazil\" for non-US)."},"product":{"default":"mmx","enum":["mmx","video","mobile"],"title":"Product","type":"string","description":"\"mmx\" (default), \"video\" (VMX), \"mobile\"."},"platform":{"default":"multiplatform","enum":["desktop","multiplatform","mobile","ctv"],"title":"Platform","type":"string","description":"\"multiplatform\" (default), \"desktop\", \"mobile\". Ignored for video/mobile."},"limit":{"default":100,"title":"Limit","type":"integer","description":"Co-visited sites to return, default 100."},"target_category":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Target Category","description":"Target entity category whose members become the rows — an industry"},"target_entities":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Target Entities","description":"Specific target entities to use as rows (Digital Entities mode), e.g."},"metrics":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Metrics","description":"Cross-visiting metrics, e.g. [\"Shared Audience (000)\", \"% Vertical\","},"audience":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Audience","description":"Audience filter. Single string (\"Total Audience\", \"Males 21+\") for a standard"},"domains_only":{"default":false,"title":"Domains Only","type":"boolean","description":"When True, expand categories to individual domains (leaf entities) rather"}},"required":["media"],"title":"get_cross_visitingArguments","type":"object"}},{"name":"get_plan_metrix","description":"Plan Metrix metrics (views, visitors, reach, etc.) for a custom audience segment.\n\nUse this tool whenever the audience is anything other than a plain age/gender demo — including:\nhousehold size, income, education, purchase intent, lifestyle, psychographics, or ANY combination\nof multiple segments (e.g. Female AND household size 2 or 3). get_metric only accepts a single\nage/gender target; all other audience definitions require this tool.\n\nsearch_plan_metrix_audience returns the numeric segment IDs this tool requires. When that\nsearch returns several segments that each fit the requested audience, ask the user which\nto use (or whether to OR them) before calling this tool.\n\nFor demographic breakdown queries (e.g. \"show results by Hispanic sub-segment\"),\nmedia=\"total internet\" is appropriate — the audience segments are the rows, not a media filter.\n\nAudience expressions combine all required segments: use ^ (AND) / | (OR) to compose a single\nexpression (e.g. \"A^B|A^C\"). One expression describes ONE audience, so combine the segments\nthat together define it into one expression. To compare or characterise several separate\naudiences, pass them as a list — see BATCHING.\n\nBATCHING: media, metric and audience all accept lists, and one call covers every\ncombination of them — pass all the entities, metrics and audiences you need rather than\nlooping. A list returns a `rows` table instead of a single flat value: one row per\nentity, or one row per entity x audience when several audiences are given (each row then\ncarries `audience` and `audience_expr`). Characterising an audience across 5-6 segments is\none call with audience=[\"6339\", \"65076\", ...], not one call per segment.\n`time` is the exception: Plan Metrix allows only one period per report, so a multi-month\ntrend genuinely needs one call per month. Batch the other two axes into each of those\ncalls (e.g. 6 entities x 2 metrics x 11 months = 11 calls, not 132).\n\nCROSSTAB MODE: When the user asks for a matrix of row segments × column segments (e.g.\n\"show Hispanic sub-segments as rows and music purchase categories as columns\"), pass:\n  - audience_rows: the row segment expression (e.g. \"6607|4827|5965\")\n  - audience: the column segment expression (e.g. \"859216|859640|859641\")\n  - metric: \"target audience (000)\" and/or \"% vertical\" — both are returned natively in one call.\nThis uses a single API call instead of N×M separate calls.","inputSchema":{"properties":{"media":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"}],"title":"Media","description":"\"total internet\" for universe figures, a PMX category name (e.g. \"Entertainment\", \"Automotive\", \"News\"), or a specific domain/brand name (e.g. \"netflix.com\"). This is a name, not a numeric ID. Accepts a list to report many entities in one call (e.g. [\"netflix.com\", \"hulu.com\", \"espn.com\"])."},"audience":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"}],"title":"Audience","description":"Boolean expression of numeric segment IDs (column segments in crosstab mode). Operators: ^ (AND), | (OR), ! (NOT). NO parentheses — API rejects them. Use distributive law: (A|B)^C → A^C|B^C E.g. \"583658\", \"583658^5425\", \"583658|583655\", \"583658^!12417\" Accepts a list of expressions to report several audiences in one call (up to 20), e.g. [\"6339\", \"65076\", \"6339^65076\"]. Each expression is one audience; they are reported side by side, never combined. Crosstab mode takes a single expression."},"metric":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"}],"default":"unique visitors","title":"Metric","description":"\"unique visitors\" (default), \"reach\", \"total minutes\", \"total views\", \"total pages\", \"total visits\", \"avg minutes\", \"avg visits\", \"composition index\", \"composition %\", \"% vertical\" (crosstab only). Accepts a list — every metric is returned by the same report, so asking for several costs no more than asking for one. Note: \"total views\" and \"total pages\" both map to the same Plan Metrix measure — the Core UI labels it \"Total Views MM\". \"avg visits\" is published per platform only — request it with platform=\"desktop\" or platform=\"mobile\"."},"time":{"default":"last_month","title":"Time","type":"string","description":"\"last_month\" (default), \"YYYY-MM\", or raw period integer. One period per call — the API does not accept a range or a list here."},"geo":{"default":"US","title":"Geo","type":"string","description":"Geographic market, default \"US\"."},"platform":{"default":"desktop+mobile","title":"Platform","type":"string","description":"\"desktop+mobile\" (default), \"desktop\", \"mobile\". \"desktop+mobile\" reads Plan Metrix's cross-platform data source, which is what the Plan Metrix UI reports as \"Desktop and Mobile\" — one report, deduplicated upstream. Do not add a desktop and a mobile call together to approximate it: unique visitors would double-count people who used both platforms and rates (reach, composition index) do not add at all. Category media sets are only published cross-platform, so a category always returns desktop+mobile figures whatever this is set to."},"audience_rows":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Audience Rows","description":"Row segment expression for crosstab mode. When set, `audience` becomes the column expression and a single consumertargetprofilev2 call returns the full matrix with Target Audience (000) and % Vertical for every row × column cell. Use the same boolean expression syntax as `audience`."},"expand_all_media":{"default":false,"title":"Expand All Media","type":"boolean","description":"True to report every individual site underneath the requested entity instead of the entity itself — the site list a publisher network needs. Use it whenever the ask is a site list, a per-site breakdown, \"the sites within <publisher/network>\", or which of a network's sites over-index with an audience (pair it with min_composition_index). Report the sites as returned rather than summarising them into groupings — the unfolded list is the deliverable. The Plan Metrix catalog indexes a network at the parent and category-grouping level only, so the site list is taken from the MMX media tree (at the same platform scope as `platform`) and each site is then reported from Plan Metrix in one batched set of calls. Returns `rows` (one row per site, with `parent`), never a single value."},"expand_limit":{"default":0,"title":"Expand Limit","type":"integer","description":"Max sites per requested entity when expand_all_media=True. Defaults to 0 = the whole network (ceiling 2000), which is what site-list building needs. Set it only when a sample is genuinely wanted: it keeps the largest sites by MMX unique visitors, which biases against the small niche sites that over-index hardest. A network runs one report per 100 sites (~1,700 sites ≈ 100s)."},"min_composition_index":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Min Composition Index","description":"Drop sites whose composition index is below this, e.g. 100 for \"the sites that over-index with this audience\". Composition index is added to the reported metrics when it is set. Filtering here rather than after the fact is what makes a 1,700-site network a usable site list."}},"required":["media","audience"],"title":"get_plan_metrixArguments","type":"object"}},{"name":"search_plan_metrix_audience","description":"Search the audience segment catalog (~5700 segments) across every data layer get_plan_metrix can target. Returns the numeric segment IDs that get_plan_metrix accepts as input.\n\nThe catalog spans several data layers, and each match says which layer it came from:\n  - \"Plan Metrix\" — the survey itself (claimed purchases, ownership, activities, attitudes).\n  - \"IAB Digital Interests 2.0\" — behavioural interest signals from measured browsing,\n    organised on the IAB content taxonomy (e.g. Business and Finance > Venture Capital,\n    Movies > Horror Movies).\n  - \"Demos\" / \"Demos - Hispanic\" — age, gender, income, household size, race breakouts.\n\nSegments from different layers combine freely in one get_plan_metrix `audience`\nexpression, so a definition can mix a survey answer with an IAB interest signal.\nWhich layer a segment belongs to changes what it measures — an IAB interest is\nbrowsing behaviour, a Plan Metrix segment is a survey response — so state the layer\nalongside any number derived from it.\n\nChoosing segments — ask before pulling data:\n  - If exactly one match fits the audience the user described, use it directly.\n  - If two or more matches each fit it (e.g. \"VP/C-suite\" matches both Work Demos >\n    Title > Executive (C-Level) and Management (VP, Director, Manager)), do NOT call\n    get_plan_metrix yet. List those matches (id, layer, name) and ask the user which to\n    use, offering their OR combination as an option, then pull the data.\n  `answer_groups` lists matches that are answers to the same catalog question, with the\n  OR expression ready to offer.","inputSchema":{"properties":{"query":{"title":"Query","type":"string","description":"Natural language audience description, e.g. \"podcast listener\", \"venture capital\", \"angel investment\", \"horror movies\", \"TikTok user\"."},"layer":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Layer","description":"Optional data-layer filter. Accepts \"iab\" (IAB Digital Interests 2.0), \"plan metrix\" (the survey), or \"demos\". Omit to search every layer, which is usually right — the best segment for a query is often in a layer the caller did not think to ask for."},"limit":{"default":10,"title":"Limit","type":"integer","description":"Max matches to return, default 10."}},"required":["query"],"title":"search_plan_metrix_audienceArguments","type":"object"}},{"name":"list_metrics","description":"List all metrics available for a given product and platform by querying the API live.\n\nReturns the authoritative metric list for questions like \"what metrics are available\",\n\"what can I measure\", or \"what views/reach/minutes metrics exist\" for a given data source.","inputSchema":{"properties":{"product":{"default":"mmx","title":"Product","type":"string","description":"\"mmx\" (default, desktop+mobile web), \"video\" (VMX), \"mobile\" (Mobile Metrix)."},"platform":{"default":"multiplatform","title":"Platform","type":"string","description":"\"multiplatform\" (default), \"desktop\", \"mobile\". For mmx: \"multiplatform\" = dataSource=25, \"desktop\" = dataSource=1."},"geo":{"default":"US","title":"Geo","type":"string","description":"Geographic market, default \"US\"."}},"title":"list_metricsArguments","type":"object"}},{"name":"get_entity_status","description":"Entity Status widget — shows measurement coverage for a site/publisher across\nplatforms (Desktop, Smartphone iOS/Android, CTV) and content types (Display, Video).\nUse for the Entity Status widget or when the user asks about measurement/tagging status.","inputSchema":{"properties":{"media":{"title":"Media","type":"string","description":"Site, category, or brand (e.g. \"CNN.COM\", \"Social\", \"ESPN.com Sites\")."},"time":{"default":"last_month","title":"Time","type":"string","description":"\"last_month\" (default), \"YYYY-MM\", or raw period integer."},"geo":{"default":"US","title":"Geo","type":"string","description":"Geographic market, default \"US\"."},"entity_type":{"default":"Digital Entities","title":"Entity Type","type":"string","description":"\"Digital Entities\" (default) for a specific site/brand, or \"Digital Categories\" for a category (e.g. \"Social\", \"News\") — a category returns the measurement status of every property within it."}},"required":["media"],"title":"get_entity_statusArguments","type":"object"}}]}