Skip to main content
Glama

Versium REACH

by com.versium.app
OverviewDiscussionsAdmin

B2C Listgen Estimate Mcp Tool

b2c_listgen_estimate
Read-onlyIdempotent
Estimate consumer audience sizes using Versium's Consumer Audience Builder (B2C Listgen) API. Supports the configuration and demographic filter set

For fields with large, high-cardinality option sets (e.g. esthhldincome), use the Consumer Audience Options tool to retrieve available values
Any property restricted to `enum: ["Y"]` is enabled by sending `"Y"`. For example, pet owners who golf in Washington use `{"state":["WA"],"d_pets":"Y","d_golf":"Y"}`.
Call `b2c_listgen_options` with `field: "attribute_flags"` when you need the human-readable meanings of those flag names.

**Tips for Best Results:**
- Start with a single output type and add filters incrementally
- Combine geography with age, income, or lifestyle filters for precise targeting
- Leverage lifestyle and interest filters to reach specific consumer segments

Input Schema

NameRequiredDescriptionDefault
d_ageNoAge range in years (single value or min-max, e.g., "35-45")
d_lorNoLength of residence in years (single value or range)
d_zipNoArray of 5-digit ZIP codes to filter by
d_golfNo
d_newsNo
d_petsNo
d_sohoNo
d_stateNoArray of 2-letter state codes to filter by
d_countyNoArray of county,state combinations (e.g., "King, WA")
d_genderNoGender filter (M=Male, F=Female)
d_travelNo
d_fishingNo
d_huntingNo
d_ownrentNoHome ownership status codes (H=Owner, R=Renter, 9=Probable Owner)
d_exerciseNo
d_languageNoLanguage codes. See values in options tool
d_networthNoEstimated net worth range using codes. See values in options tool
d_shootingNo
d_auto_yearNoAutomobile year range (single year or min-max)
d_educationNoEducation level codes: A=High School, B=College, C=Graduate, D=Technical/Vocational
d_gardeningNo
d_hhld_sizeNoHousehold size range (1-9, e.g., "2-4"); 9 means 9 or more
d_home_yearNoYear home was built (single year or range)
d_magazinesNo
d_refi_dateNoRefinance date or date range using YYYYMMDD format
max_recordsNoCap the number of records returned by the eventual list build
d_city_stateNoArray of city,state combinations (e.g., "Seattle, WA")
d_home_valueNoHome value range. See values in options tool
d_occupationNoOccupation codes. See values in options tool
max_coverageNoRequest append processing for selected channels (must overlap required/optional fields)
cfg_zipradiusNoRadius expansion (pseudo-miles) applied around supplied ZIP or city/state centers
d_creditlinesNoNumber of credit lines range (e.g. "0-5")
d_electronicsNo
d_loantovalueNoLoan-to-value percentage as single value or range (0-100)
d_motorcyclesNo
d_refi_amountNoRefinance amount in thousands (single value or range)
d_senior_hhldNo
d_apparel_mensNo
d_donation_envNo
d_dwellingtypeNoDwelling type codes (M=Multi Family, S=Single Family, U=Unknown)
d_num_childrenNoNumber of children range (0-8, e.g., "2-3")
d_singleparentNo
d_workingwomanNo
d_esthhldincomeNoEstimated household income range using codes. See values in options tool
d_maritalstatusNoMarital status codes (M=Married, S=Single, A=Married (Inferred), B=Single (Inferred))
d_mortgage_rateNoMortgage interest rate percentage (e.g., "6.75%", "10%")
optional_fieldsNoOptional contact fields to include when available
required_fieldsNoRequired output contact fields. Must include at least one. Recommended to include address for estimate calls for geo info. IMPORTANT: Unlike the B2B Persona API, this field along with optional_fields are used to define output instead of the "output" parameter
cfg_require_nameNoSet to true to require full names in the output
d_apparel_womensNo
d_auto_makemodelNoAuto make and model combo(s) (e.g. "Ford:Escape")
d_mailorderbuyerNo
d_mortgage2_dateNoSecond mortgage date in YYYYMMDD format
d_mortgage2_rateNoSecond mortgage interest rate percentage
d_refi_loan_typeNoRefinance loan type codes. See values in options tool
d_refi_rate_typeNoRefinance rate type codes. A=Adjustable, B=Balloon, F=Fixed, U=Unknown
cfg_require_emailNoSet to true to require email addresses in the output
cfg_require_phoneNoSet to true to require phone numbers in the output
contacts_per_addrNoMaximum contacts per street address (0=unlimited, 1=one contact per address)
d_cardholder_bankNo
d_lifestyle_musicNo
d_mortgage_amountNoMortgage amount in thousands (use values like "50" or "400")
d_onlinepurchaserNo
d_youngadult_hhldNo
rcfg_phone_formatNoSet to 1 to prefix returned phone numbers with the country code
d_donation_animalsNo
d_home_improvementNo
d_investing_activeNo
d_lifestyle_sportsNo
d_mortgage2_amountNoSecond mortgage amount in thousands
cfg_require_addressNoSet to true to require mailing addresses in the output
cfg_zipradius_focusNoLimits radius expansion to ZIP, city/state, or none
d_donation_childrenNo
d_donation_intl_aidNo
d_home_market_valueNoHome market value range. See values in options tool
d_lifestyle_cookingNo
d_lifestyle_outdoorNo
d_lifestyle_readingNo
d_cardholder_upscaleNo
d_donation_communityNo
d_home_purchase_dateNoHome purchase date in YYYYMMDD format
d_lifestyle_antiquesNo
d_mortgage_rate_typeNoMortgage rate type codes. A=Adjustable, B=Balloon, F=Fixed, U=Unknown
include_filter_attrsNoInclude selected filter attributes as columns in the final audience
d_home_purchase_priceNoHome purchase price in thousands
d_mortgage2_loan_typeNoSecond mortgage loan type codes. See values in options tool
d_mortgage2_rate_typeNoSecond mortgage rate type codes. A=Adjustable, B=Balloon, F=Fixed, U=Unknown
d_lifestyle_decoratingNo
d_presence_of_childrenNo
d_donation_arts_cultureNo
d_donation_env_wildlifeNo
include_demo_categoriesNoDemographic category summaries to include in the response. Recommended to include at least one with estimate calls for audience insights in the preview response
d_lifestyle_arts_generalNo
d_mortgage_purchase_dateNoMortgage purchase date in YYYYMMDD format
d_mortgage_purchase_loan_type_codeNoMortgage purchase loan type codes. See values in options tool

Output Schema

NameRequiredDescriptionDefault
resultsNo
query_idNo
warningsNo
input_queryNo
num_matchesNo
num_resultsNo
match_countsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed16 schema fields changed
    • removedInput schema / properties / d_creditrating
      Removed value: -{
-  "description": "Credit rating range. See values in options tool",
-  "pattern": "^[A-H](-[A-H])?$",
-  "type": "string"
-}
    • removedInput schema / properties / d_donation_health
      Removed value: -{
-  "enum": [
-    "Y"
-  ],
-  "type": "string"
-}
    • removedInput schema / properties / d_donation_political
      Removed value: -{
-  "enum": [
-    "Y"
-  ],
-  "type": "string"
-}
    • removedInput schema / properties / d_donation_political_conservative
      Removed value: -{
-  "enum": [
-    "Y"
-  ],
-  "type": "string"
-}
    • removedInput schema / properties / d_donation_political_liberal
      Removed value: -{
-  "enum": [
-    "Y"
-  ],
-  "type": "string"
-}
    • removedInput schema / properties / d_donation_religion
      Removed value: -{
-  "enum": [
-    "Y"
-  ],
-  "type": "string"
-}
    • removedInput schema / properties / d_donation_unspecified
      Removed value: -{
-  "enum": [
-    "Y"
-  ],
-  "type": "string"
-}
    • removedInput schema / properties / d_donation_veterans
      Removed value: -{
-  "enum": [
-    "Y"
-  ],
-  "type": "string"
-}
    • removedInput schema / properties / d_ethnicgroup
      Removed value: -{
-  "description": "Ethnic group codes. See values in options tool",
-  "items": {
-    "pattern": "^[A-Z]$",
-    "type": "string"
-  },
-  "type": "array"
-}
    • removedInput schema / properties / d_hhldveteran
      Removed value: -{
-  "enum": [
-    "Y"
-  ],
-  "type": "string"
-}
    • removedInput schema / properties / d_lifestyle_health_beauty
      Removed value: -{
-  "enum": [
-    "Y"
-  ],
-  "type": "string"
-}
    • removedInput schema / properties / d_military_history
      Removed value: -{
-  "enum": [
-    "Y"
-  ],
-  "type": "string"
-}
    • removedInput schema / properties / d_political_party
      Removed value: -{
-  "description": "Political party affiliation values",
-  "items": {
-    "enum": [
-      "REPUBLICAN",
-      "DEMOCRAT",
-      "LIBERTARIAN",
-      "GREEN",
-      "INDEPENDENT",
-      "REFORM",
-      "NO AFFILIATION"
-    ],
-    "type": "string"
-  },
-  "type": "array"
-}
    • removedInput schema / properties / d_religion
      Removed value: -{
-  "description": "Religion codes. See values in options tool",
-  "items": {
-    "pattern": "^[A-Z]$",
-    "type": "string"
-  },
-  "type": "array"
-}
    • removedInput schema / properties / d_weightloss
      Removed value: -{
-  "enum": [
-    "Y"
-  ],
-  "type": "string"
-}
    • changedInput schema / properties / include_demo_categories / items / enum
      Previous value: -[
-  "b2cDemographic",
-  "b2cHouseFinAuto",
-  "b2cLifestyleInterest",
-  "b2cPoliticalDonor",
-  "firmographic"
-]New value: +[
+  "b2cDemographic",
+  "b2cHouseFinAuto",
+  "b2cLifestyleInterest",
+  "firmographic"
+]
  2. Changed1 schema field changed
    • addedInput schema / properties / d_hhld_size
      Added value: +{
+  "description": "Household size range (1-9, e.g., \"2-4\"); 9 means 9 or more",
+  "pattern": "^[1-9]-[1-9]$",
+  "type": "string"
+}
  3. Changed54 schema fields changed
    • removedInput schema / properties / d_apparel_mens / description
      Removed value: -"Set to \"Y\" to include households associated with men's apparel interest."
    • removedInput schema / properties / d_apparel_womens / description
      Removed value: -"Set to \"Y\" to include households associated with women's apparel interest."
    • removedInput schema / properties / d_cardholder_bank / description
      Removed value: -"Set to \"Y\" to include households associated with bank card ownership."
    • removedInput schema / properties / d_cardholder_upscale / description
      Removed value: -"Set to \"Y\" to include households associated with upscale card ownership."
    • removedInput schema / properties / d_donation_animals / description
      Removed value: -"Set to \"Y\" to include households associated with animal welfare donors."
    • removedInput schema / properties / d_donation_arts_culture / description
      Removed value: -"Set to \"Y\" to include households associated with arts and culture donors."
    • removedInput schema / properties / d_donation_children / description
      Removed value: -"Set to \"Y\" to include households associated with children's causes donors."
    • removedInput schema / properties / d_donation_community / description
      Removed value: -"Set to \"Y\" to include households associated with community organization donors."
    • removedInput schema / properties / d_donation_env / description
      Removed value: -"Set to \"Y\" to include households associated with environmental donors."
    • removedInput schema / properties / d_donation_env_wildlife / description
      Removed value: -"Set to \"Y\" to include households associated with environmental or wildlife donors."
    • removedInput schema / properties / d_donation_health / description
      Removed value: -"Set to \"Y\" to include households associated with health-related donors."
    • removedInput schema / properties / d_donation_intl_aid / description
      Removed value: -"Set to \"Y\" to include households associated with international aid donors."
    • removedInput schema / properties / d_donation_political / description
      Removed value: -"Set to \"Y\" to include households associated with general political donors."
    • removedInput schema / properties / d_donation_political_conservative / description
      Removed value: -"Set to \"Y\" to include households associated with conservative political donors."
    • removedInput schema / properties / d_donation_political_liberal / description
      Removed value: -"Set to \"Y\" to include households associated with liberal political donors."
    • removedInput schema / properties / d_donation_religion / description
      Removed value: -"Set to \"Y\" to include households associated with religious donors."
    • removedInput schema / properties / d_donation_unspecified / description
      Removed value: -"Set to \"Y\" to include households associated with unspecified cause donors."
    • removedInput schema / properties / d_donation_veterans / description
      Removed value: -"Set to \"Y\" to include households associated with veteran support donors."
    • removedInput schema / properties / d_electronics / description
      Removed value: -"Set to \"Y\" to include households associated with consumer electronics interest."
    • removedInput schema / properties / d_exercise / description
      Removed value: -"Set to \"Y\" to include households associated with fitness and exercise interest."
    • removedInput schema / properties / d_fishing / description
      Removed value: -"Set to \"Y\" to include households associated with fishing interest."
    • removedInput schema / properties / d_gardening / description
      Removed value: -"Set to \"Y\" to include households associated with gardening interest."
    • removedInput schema / properties / d_golf / description
      Removed value: -"Set to \"Y\" to include households associated with golf interest."
    • removedInput schema / properties / d_hhldveteran / description
      Removed value: -"Set to \"Y\" to include households associated with veteran households."
    • removedInput schema / properties / d_home_improvement / description
      Removed value: -"Set to \"Y\" to include households associated with home improvement interest."
    • removedInput schema / properties / d_hunting / description
      Removed value: -"Set to \"Y\" to include households associated with hunting interest."
    • removedInput schema / properties / d_investing_active / description
      Removed value: -"Set to \"Y\" to include households associated with active investing interest."
    • removedInput schema / properties / d_lifestyle_antiques / description
      Removed value: -"Set to \"Y\" to include households associated with antiques interest."
    • removedInput schema / properties / d_lifestyle_arts_general / description
      Removed value: -"Set to \"Y\" to include households associated with arts interest."
    • removedInput schema / properties / d_lifestyle_cooking / description
      Removed value: -"Set to \"Y\" to include households associated with cooking interest."
    • removedInput schema / properties / d_lifestyle_decorating / description
      Removed value: -"Set to \"Y\" to include households associated with decorating interest."
    • removedInput schema / properties / d_lifestyle_health_beauty / description
      Removed value: -"Set to \"Y\" to include households associated with health and beauty interest."
    • removedInput schema / properties / d_lifestyle_music / description
      Removed value: -"Set to \"Y\" to include households associated with music interest."
    • removedInput schema / properties / d_lifestyle_outdoor / description
      Removed value: -"Set to \"Y\" to include households associated with outdoor recreation interest."
    • removedInput schema / properties / d_lifestyle_reading / description
      Removed value: -"Set to \"Y\" to include households associated with reading interest."
    • removedInput schema / properties / d_lifestyle_sports / description
      Removed value: -"Set to \"Y\" to include households associated with general sports interest."
    • removedInput schema / properties / d_magazines / description
      Removed value: -"Set to \"Y\" to include households associated with magazine subscriptions."
    • removedInput schema / properties / d_mailorderbuyer / description
      Removed value: -"Set to \"Y\" to include households associated with mail order purchasing activity."
    • removedInput schema / properties / d_military_history / description
      Removed value: -"Set to \"Y\" to include households associated with military history households."
    • removedInput schema / properties / d_motorcycles / description
      Removed value: -"Set to \"Y\" to include households associated with motorcycle interest."
    • removedInput schema / properties / d_news / description
      Removed value: -"Set to \"Y\" to include households associated with current affairs engagement."
    • removedInput schema / properties / d_onlinepurchaser / description
      Removed value: -"Set to \"Y\" to include households associated with online purchasing activity."
    • removedInput schema / properties / d_pets / description
      Removed value: -"Set to \"Y\" to include households associated with pet ownership."
    • removedInput schema / properties / d_presence_of_children / description
      Removed value: -"Set to \"Y\" to include households with children present"
    • removedInput schema / properties / d_senior_hhld / description
      Removed value: -"Set to \"Y\" to include households associated with senior households."
    • removedInput schema / properties / d_shooting / description
      Removed value: -"Set to \"Y\" to include households associated with shooting sports interest."
    • removedInput schema / properties / d_singleparent / description
      Removed value: -"Set to \"Y\" to include households associated with single parent households."
    • removedInput schema / properties / d_soho / description
      Removed value: -"Set to \"Y\" to include households associated with small office/home office households."
    • removedInput schema / properties / d_travel / description
      Removed value: -"Set to \"Y\" to include households associated with travel interest."
    • removedInput schema / properties / d_weightloss / description
      Removed value: -"Set to \"Y\" to include households associated with dieting and weight loss interest."
    • removedInput schema / properties / d_workingwoman / description
      Removed value: -"Set to \"Y\" to include households associated with working women households."
    • removedInput schema / properties / d_youngadult_hhld / description
      Removed value: -"Set to \"Y\" to include households associated with young adult households."
    • removedInput schema / properties / rcfg_max_time
      Removed value: -{
-  "description": "Maximum allowed API run time in seconds",
-  "minimum": 0.1,
-  "type": "number"
-}
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "properties": {
+    "input_query": {
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "match_counts": {
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "num_matches": {
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
+    "num_results": {
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
+    "query_id": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "results": {
+      "properties": {
+        "estimated_credits": {
+          "type": [
+            "string",
+            "integer",
+            "number",
+            "boolean",
+            "object",
+            "array",
+            "null"
+          ]
+        },
+        "estimated_match_credits": {
+          "type": [
+            "string",
+            "integer",
+            "number",
+            "boolean",
+            "object",
+            "array",
+            "null"
+          ]
+        },
+        "estimated_record_count": {
+          "type": [
+            "string",
+            "integer",
+            "number",
+            "boolean",
+            "object",
+            "array",
+            "null"
+          ]
+        },
+        "estimated_records_available": {
+          "type": [
+            "string",
+            "integer",
+            "number",
+            "boolean",
+            "object",
+            "array",
+            "null"
+          ]
+        },
+        "estimated_time": {
+          "type": [
+            "string",
+            "integer",
+            "number",
+            "boolean",
+            "object",
+            "array",
+            "null"
+          ]
+        },
+        "estimated_time_in_seconds": {
+          "type": [
+            "string",
+            "integer",
+            "number",
+            "boolean",
+            "object",
+            "array",
+            "null"
+          ]
+        },
+        "preview": {
+          "items": {
+            "items": {
+              "type": [
+                "string",
+                "integer",
+                "number",
+                "boolean",
+                "object",
+                "array",
+                "null"
+              ]
+            },
+            "type": "array"
+          },
+          "type": [
+            "array",
+            "null"
+          ]
+        }
+      },
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "warnings": {
+      "items": {
+        "type": [
+          "string",
+          "integer",
+          "number",
+          "boolean",
+          "object",
+          "array",
+          "null"
+        ]
+      },
+      "type": [
+        "array",
+        "null"
+      ]
+    }
+  },
+  "type": "object"
+}
  4. First observed

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, which matches an 'estimate' operation, and the description adds non-obvious model semantics: the enum ["Y"] flag convention with a concrete Washington/golf/pets example. It does not disclose cost/credit consumption, whether estimates create a persistent job, or rate limits — meaningful context for a 95-parameter sizing call that the annotations do not cover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded in sentence one, followed by scoped operational notes and a short tips block, with no filler. Minor inefficiency: the options tool is referred to both as 'Consumer Audience Options tool' and `b2c_listgen_options`, and the 'Tips' bullets are somewhat generic.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return-value explanation is correctly omitted, and the description handles enum-flag semantics well. But for a 95-parameter, zero-required tool it never states what a minimal valid call looks like or which of required_fields/optional_fields/max_coverage must be coordinated — the coordination rule lives only in the schema's required_fields text, not in the description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 95 parameters including 54 enums and only 57% schema description coverage, the description carries real weight by explaining the shared `enum: ["Y"]` activation convention and routing ambiguous code sets (income, net worth, home value, occupation, attribute_flags) to the options tool. That single convention covers a large share of the otherwise undescribed boolean-style flags, though no guidance is given on safe defaults or minimal viable filter sets.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence gives a specific verb (estimate) and resource (consumer audience sizes) and names the backing API (Versium Consumer Audience Builder / B2C Listgen), so the agent knows this is a sizing/estimate call over demographic filters. It implicitly separates from b2b_listgen_estimate via 'consumer,' but never names that sibling or explains the consumer-vs-business split explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives real procedural guidance — look up high-cardinality values (e.g., esthhldincome) via the options tool, call b2c_listgen_options with field: "attribute_flags" for flag meanings, and a 'Tips' list recommending incremental filter building. However, these are all intra-tool/parameter hints; there is no guidance on when to use this estimate versus sibling tools like preview_list, setup_list, or b2b_listgen_estimate, and no stated exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Versium REACH toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources