Access Versium's B2B2C identity graph directly through your AI agent. Generate targeted lead lists, enrich records with contact and firmographic data, validate emails, and size audiences — all through natural language. No manual exports or API coding required. Requires an active Versium REACH subscription with API access.
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Average 4.2/5 across 19 of 19 tools scored. Lowest: 3.4/5.
Each tool targets a distinct resource and action: list generation (B2B vs B2C), enrichment (contact, demographic, firmographic, C2B, IP-to-domain), project/list management, job lifecycle, and validation. No two tools appear to do the same thing, so an agent can reliably select the correct one.
All tool names follow the verb_noun pattern consistently, using verbs like list, show, create, preview, search, validate, append, and estimate. Even the segmented append tools (c2b_append, contact_append, demographic_append, firmographic_append, ip_to_domain_append) follow the same pattern with clear noun modifiers. No mixed conventions or vague verbs.
With 19 tools, this is on the higher side but still well-scoped for a data enrichment and list-building platform. The count covers distinct functional areas (audience estimation, enrichment, job/project management, list inspection, documentation) without unnecessary bloat. It feels slightly heavy but each tool earns its place.
The tool surface covers the core workflows: estimating audiences, creating and monitoring jobs, managing projects and lists, and enriching records with various data types. Minor gaps exist, such as no explicit delete/update operations for projects or lists, and no direct file download for list contents (though preview_list and show_list provide partial coverage). These are non-blocking gaps that agents can work around.
b2b2c_appendB2 B2 C Append Mcp ToolAEnrich a business contact with their full business-to-consumer profile: with a LinkedIn URL or a name + city/state, retrieve business email plus consumer mobile phone, consumer email, and consumer address data in a single match.
Use this tool when users ask for 'B2B2C', 'b2b2c', or 'Business to Business to Consumer' data.
**Tips for Best Results:**
- Provide a LinkedIn URL (format: linkedin.com/in/username) for the best match quality
- Alternatively provide first name, last name, city, and state together
- Choose one or more outputs; use `required_outputs` to return only records that matched those outputs| Name | Required | Description | Default |
|---|---|---|---|
| zip | No | 5 digit ZIP code | |
| city | No | City name | |
| last | No | A person's last name | |
| No | A known email address for the contact | ||
| first | No | A person's first name | |
| state | No | Two-character state code (US) | |
| li_url | No | A LinkedIn URL (accepts https://www.linkedin.com/in/username, www.linkedin.com/in/username, or linkedin.com/in/username) | |
| address | No | Street address | |
| country | No | Two-character country code (currently only US data is supported) | |
| outputs | Yes | Contact data to return: business_email, consumer_mobile, consumer_email, consumer_address | |
| required_outputs | No | Subset of outputs a record must have to be returned | |
| cfg_max_emails_b2c | No | Maximum consumer email addresses to return per record | |
| cfg_max_phones_b2c | No | Maximum consumer phone numbers to return per record |
| Name | Required | Description |
|---|---|---|
| results | No | Records returned by the Operations API. Record fields pass through unchanged. |
| query_id | No | |
| warnings | No | |
| input_query | No | |
| num_matches | No | Number of matching queries. |
| num_results | No | Number of records returned. |
| match_counts | No | Sparse match counts. An absent key means zero. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this a read-only, idempotent, non-destructive operation, lowering the behavioral disclosure burden. The description adds useful context beyond that: it performs a single match, supports multiple input strategies, and explains that required_outputs filters results to matched records. This gives the agent a meaningful model of behavior beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core purpose, and rounds out with a focused set of actionable tips. Every line adds information, there is no filler, and the scannable bullet list makes invocation guidance easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 13-parameter schema, rich annotations, and an output schema, the description covers the essential invocation choices without needing to repeat field details. It mentions match quality, alternative input schemes, and output filtering behavior. It stops short of stating data limitations such as country restrictions beyond the schema, so it is strong but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema documents each parameter's meaning already. The description adds genuinely useful parameter semantics by explaining the two valid input strategies (LinkedIn URL alone, or first/last/city/state together) and by clarifying the purpose of outputs vs. required_outputs. That is meaningful value beyond the per-parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's job with a specific verb and resource: enrich a business contact with their full B2C profile, and names the exact data types returned. The opening sentence distinguishes this from sibling enrichment tools by tying it specifically to 'B2B2C' / 'Business to Business to Consumer' requests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool ('Use this tool when users ask for B2B2C...'), which gives the agent routing guidance. It does not explicitly name alternative tools or provide when-not conditions, but it does give clear invocation scenarios and best-match input strategies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
b2b_listgen_estimateB2B Listgen Estimate Mcp ToolAEstimate business contact audience sizes with firmographic and role-based targeting using Versium's B2B Persona Audience Builder (B2B Listgen) API.
**Tips for Best Results:**
- Start with a single output type and add filters incrementally
- Combine geography with company size or industry filters for precise targeting
- Use title_seniority for leadership focus, or department for functional targeting
- Provide SIC codes when you need strict industry alignment
- To check values for fields with large, high-cardinality option sets, call the B2B Persona Listgen Options tool
- Toggle `cfg_b2cloc` to switch between business-location and home-location targeting| Name | Required | Description | Default |
|---|---|---|---|
| d_sic | No | Legacy 4-digit SIC codes | |
| d_zip | No | U.S. ZIP codes (5-digit codes) | |
| output | No | Campaign type specification. Must include exactly one: "email" or "oa". Email should almost always be used; OA can ONLY be used for audience targeting in ad platforms and will return hashed data | |
| d_naics | No | Raw 2- to 6-digit NAICS codes. Use the options tool to retrieve valid values | |
| d_state | No | U.S. states (2-letter codes) | |
| rd_role | No | Job roles. Use the options tool to retrieve valid values | |
| d_county | No | U.S. counties (full county names) | |
| cfg_b2cloc | No | Whether location filters apply to business location (0) or employee home location (1) | |
| max_records | No | Cap the number of records returned by the eventual list build | |
| d_city_state | No | U.S. City and state combinations, e.g. "Austin, TX" | |
| d_salesvolume | No | Company revenue range, in the format "min-max" (e.g. "100000-1000000" for $100K to $1M) | |
| rd_department | No | Job departments. Use the options tool to retrieve valid values | |
| d_numemployees | No | Company size range, in the format "min-max" (e.g. "100-50000") | |
| rd_title_seniority | No | Title seniority levels |
| Name | Required | Description |
|---|---|---|
| results | No | |
| query_id | No | |
| warnings | No | |
| input_query | No | |
| num_matches | No | |
| num_results | No | |
| match_counts | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds valuable context by framing the operation as an estimate of audience sizes rather than a list build. It also discloses the cfg_b2cloc behavior for switching between business-location and home-location targeting, which is useful beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear purpose sentence and then organized into concise, scannable bullet tips. Each tip earns its place by providing actionable guidance for a complex 14-parameter tool, with no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description is complete: it states the core purpose, offers filter selection strategies, points to the options tool for valid values, and clarifies location targeting behavior. The output schema and annotations cover return values and safety, so the description does not need to repeat those.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, but the description adds meaningful parameter guidance: it explains when to use title_seniority vs department, when to provide SIC codes, and how to interpret cfg_b2cloc. These tips go beyond the schema definitions by linking parameters to targeting strategies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Estimate business contact audience sizes with firmographic and role-based targeting using Versium's B2B Persona Audience Builder (B2B Listgen) API.' This clearly distinguishes the tool from siblings like b2c_listgen_estimate (B2C) and b2b_listgen_options (options lookup).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Tips for Best Results' section provides concrete guidance on when to use specific filters, such as using title_seniority for leadership focus, department for functional targeting, and SIC codes for strict industry alignment. It also explicitly directs users to call the B2B Persona Listgen Options tool for high-cardinality field values, though it does not explicitly contrast with the B2C sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
b2b_listgen_optionsB2B Listgen Options Mcp ToolAReturn allowed option values for B2B Persona Listgen filter fields such as NAICS, department and role.
Use this tool when you need the valid values for large, high-cardinality fields too big to embed directly in tool schemas.
| Name | Required | Description | Default |
|---|---|---|---|
| field | No | The field for which options are requested | |
| limit | No | Maximum number of returned values. Optional; default 50 | |
| query | No | Case-insensitive substring to filter option values. Optional | |
| offset | No | Pagination offset. Optional; default 0 |
| Name | Required | Description |
|---|---|---|
| field | No | |
| query | No | |
| offset | No | |
| values | No | |
| returned | No | |
| next_offset | No | |
| total_matches | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about high-cardinality fields but doesn't disclose pagination behavior or response format beyond what the schema implies. With annotations covering the safety aspects, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the purpose, and every word earns its place. The first sentence states what it does, the second explains when to use it. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return values are documented. The description covers purpose and usage context. With 100% schema coverage and good annotations, the description is complete enough for an agent to select and invoke the tool correctly. The only minor gap is not listing example field values, but that's not necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters are documented in the schema. The description adds the context that fields like NAICS are high-cardinality, which helps understand why the tool exists, but doesn't add parameter-specific meaning beyond the schema. Baseline 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns allowed option values for B2B Persona Listgen filter fields, naming specific examples (NAICS, department, role). It distinguishes itself from the sibling b2c_listgen_options by specifying B2B, and the verb 'Return' is specific to the resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this tool when you need the valid values for large, high-cardinality fields too big to embed directly in tool schemas,' which provides clear context for when to use it. It doesn't explicitly mention alternatives or when not to use it, but the context is sufficient given the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
b2c_listgen_estimateB2C Listgen Estimate Mcp ToolAEstimate consumer audience sizes using Versium's Consumer Audience Builder (B2C Listgen) API. Supports the full 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| Name | Required | Description | Default |
|---|---|---|---|
| d_age | No | Age range in years (single value or min-max, e.g., "35-45") | |
| d_lor | No | Length of residence in years (single value or range) | |
| d_zip | No | Array of 5-digit ZIP codes to filter by | |
| d_golf | No | ||
| d_news | No | ||
| d_pets | No | ||
| d_soho | No | ||
| d_state | No | Array of 2-letter state codes to filter by | |
| d_county | No | Array of county,state combinations (e.g., "King, WA") | |
| d_gender | No | Gender filter (M=Male, F=Female) | |
| d_travel | No | ||
| d_fishing | No | ||
| d_hunting | No | ||
| d_ownrent | No | Home ownership status codes (H=Owner, R=Renter, 9=Probable Owner) | |
| d_exercise | No | ||
| d_language | No | Language codes. See values in options tool | |
| d_networth | No | Estimated net worth range using codes. See values in options tool | |
| d_religion | No | Religion codes. See values in options tool | |
| d_shooting | No | ||
| d_auto_year | No | Automobile year range (single year or min-max) | |
| d_education | No | Education level codes: A=High School, B=College, C=Graduate, D=Technical/Vocational | |
| d_gardening | No | ||
| d_hhld_size | No | Household size range (1-9, e.g., "2-4"); 9 means 9 or more | |
| d_home_year | No | Year home was built (single year or range) | |
| d_magazines | No | ||
| d_refi_date | No | Refinance date or date range using YYYYMMDD format | |
| max_records | No | Cap the number of records returned by the eventual list build | |
| d_city_state | No | Array of city,state combinations (e.g., "Seattle, WA") | |
| d_home_value | No | Home value range. See values in options tool | |
| d_occupation | No | Occupation codes. See values in options tool | |
| d_weightloss | No | ||
| max_coverage | No | Request append processing for selected channels (must overlap required/optional fields) | |
| cfg_zipradius | No | Radius expansion (pseudo-miles) applied around supplied ZIP or city/state centers | |
| d_creditlines | No | Number of credit lines range (e.g. "0-5") | |
| d_electronics | No | ||
| d_ethnicgroup | No | Ethnic group codes. See values in options tool | |
| d_hhldveteran | No | ||
| d_loantovalue | No | Loan-to-value percentage as single value or range (0-100) | |
| d_motorcycles | No | ||
| d_refi_amount | No | Refinance amount in thousands (single value or range) | |
| d_senior_hhld | No | ||
| d_apparel_mens | No | ||
| d_creditrating | No | Credit rating range. See values in options tool | |
| d_donation_env | No | ||
| d_dwellingtype | No | Dwelling type codes (M=Multi Family, S=Single Family, U=Unknown) | |
| d_num_children | No | Number of children range (0-8, e.g., "2-3") | |
| d_singleparent | No | ||
| d_workingwoman | No | ||
| d_esthhldincome | No | Estimated household income range using codes. See values in options tool | |
| d_maritalstatus | No | Marital status codes (M=Married, S=Single, A=Married (Inferred), B=Single (Inferred)) | |
| d_mortgage_rate | No | Mortgage interest rate percentage (e.g., "6.75%", "10%") | |
| optional_fields | No | Optional contact fields to include when available | |
| required_fields | No | Required 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_name | No | Set to true to require full names in the output | |
| d_apparel_womens | No | ||
| d_auto_makemodel | No | Auto make and model combo(s) (e.g. "Ford:Escape") | |
| d_mailorderbuyer | No | ||
| d_mortgage2_date | No | Second mortgage date in YYYYMMDD format | |
| d_mortgage2_rate | No | Second mortgage interest rate percentage | |
| d_refi_loan_type | No | Refinance loan type codes. See values in options tool | |
| d_refi_rate_type | No | Refinance rate type codes. A=Adjustable, B=Balloon, F=Fixed, U=Unknown | |
| cfg_require_email | No | Set to true to require email addresses in the output | |
| cfg_require_phone | No | Set to true to require phone numbers in the output | |
| contacts_per_addr | No | Maximum contacts per street address (0=unlimited, 1=one contact per address) | |
| d_cardholder_bank | No | ||
| d_donation_health | No | ||
| d_lifestyle_music | No | ||
| d_mortgage_amount | No | Mortgage amount in thousands (use values like "50" or "400") | |
| d_onlinepurchaser | No | ||
| d_political_party | No | Political party affiliation values | |
| d_youngadult_hhld | No | ||
| rcfg_phone_format | No | Set to 1 to prefix returned phone numbers with the country code | |
| d_donation_animals | No | ||
| d_home_improvement | No | ||
| d_investing_active | No | ||
| d_lifestyle_sports | No | ||
| d_military_history | No | ||
| d_mortgage2_amount | No | Second mortgage amount in thousands | |
| cfg_require_address | No | Set to true to require mailing addresses in the output | |
| cfg_zipradius_focus | No | Limits radius expansion to ZIP, city/state, or none | |
| d_donation_children | No | ||
| d_donation_intl_aid | No | ||
| d_donation_religion | No | ||
| d_donation_veterans | No | ||
| d_home_market_value | No | Home market value range. See values in options tool | |
| d_lifestyle_cooking | No | ||
| d_lifestyle_outdoor | No | ||
| d_lifestyle_reading | No | ||
| d_cardholder_upscale | No | ||
| d_donation_community | No | ||
| d_donation_political | No | ||
| d_home_purchase_date | No | Home purchase date in YYYYMMDD format | |
| d_lifestyle_antiques | No | ||
| d_mortgage_rate_type | No | Mortgage rate type codes. A=Adjustable, B=Balloon, F=Fixed, U=Unknown | |
| include_filter_attrs | No | Include selected filter attributes as columns in the final audience | |
| d_home_purchase_price | No | Home purchase price in thousands | |
| d_mortgage2_loan_type | No | Second mortgage loan type codes. See values in options tool | |
| d_mortgage2_rate_type | No | Second mortgage rate type codes. A=Adjustable, B=Balloon, F=Fixed, U=Unknown | |
| d_donation_unspecified | No | ||
| d_lifestyle_decorating | No | ||
| d_presence_of_children | No | ||
| d_donation_arts_culture | No | ||
| d_donation_env_wildlife | No | ||
| include_demo_categories | No | Demographic 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_general | No | ||
| d_mortgage_purchase_date | No | Mortgage purchase date in YYYYMMDD format | |
| d_lifestyle_health_beauty | No | ||
| d_donation_political_liberal | No | ||
| d_donation_political_conservative | No | ||
| d_mortgage_purchase_loan_type_code | No | Mortgage purchase loan type codes. See values in options tool |
| Name | Required | Description |
|---|---|---|
| results | No | |
| query_id | No | |
| warnings | No | |
| input_query | No | |
| num_matches | No | |
| num_results | No | |
| match_counts | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral detail beyond annotations, such as the uniform 'Y' flag convention and a concrete example showing how to combine filters. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but earns its length given the tool's 110 parameters. It front-loads the core purpose, then adds compactly organized behavioral guidance and tips in a scannable bullet list. Minor redundancy exists in 'Supports the full configuration and demographic filter set,' but overall it is well structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a high-complexity tool with 110 parameters, rich annotations, and an output schema. The description provides the essential operational context: where to look up option values, how to interpret Y flags, and how to approach filter construction. It does not explain everything, but the combination of schema, annotations, and description is adequate for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 53% schema description coverage, the description helps fill gaps: it explains the semantics of the many undocumented 'Y' enum parameters, points to the options tool for high-cardinality fields, and provides a working filter example. While not every parameter is individually described, the cross-cutting guidance substantially compensates for the schema's omissions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair: 'Estimate consumer audience sizes using Versium's Consumer Audience Builder (B2C Listgen) API.' This clearly distinguishes it from sibling tools like b2c_listgen_options and the B2B-focused b2b_listgen_estimate, and the consumer/B2C framing reinforces when it applies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit routing guidance for related tools: use the Consumer Audience Options tool for high-cardinality values and call b2c_listgen_options for attribute flag meanings. It does not explicitly contrast with every sibling, like b2b_listgen_estimate or list-building tools, but the purpose and alternatives are largely clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
b2c_listgen_optionsB2C Listgen Options Mcp ToolAReturn allowed option values for Consumer Audience Builder (B2C Listgen) fields
Use this tool when you need the valid values for large, high-cardinality fields too big to embed directly in tool schemas
| Name | Required | Description | Default |
|---|---|---|---|
| field | No | The field for which options are requested | |
| limit | No | Maximum number of returned values. Optional; default 50 | |
| query | No | Case-insensitive substring to filter option values. Optional | |
| offset | No | Pagination offset. Optional; default 0 |
| Name | Required | Description |
|---|---|---|
| field | No | |
| query | No | |
| offset | No | |
| values | No | |
| returned | No | |
| next_offset | No | |
| total_matches | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context about high-cardinality fields and why the options cannot be embedded in schemas. No contradictions exist between the description and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core purpose, and contains no filler or redundant material. Every sentence contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple read-only options lookup with full schema coverage, rich annotation coverage, and an output schema. The description explains both the core function and appropriate use, making it complete for an agent to understand and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 4 parameters already have complete descriptions in the input schema, so the description does not need to repeat parameter details. However, it also adds little beyond the schema; for example, it does not clarify which fields are valid or that `field` is semantically required despite the schema listing no required parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Return allowed option values for Consumer Audience Builder (B2C Listgen) fields.' It clearly identifies the consumer/B2C scope, distinguishing it from the sibling b2b_listgen_options tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'Use this tool when you need the valid values for large, high-cardinality fields too big to embed directly in tool schemas.' It provides a clear context but does not explicitly mention alternatives or when not to use it, such as pointing to the B2B sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
c2b_appendC2B Append Mcp ToolAGet business demographic details for consumers. Identify the consumer with a LinkedIn URL, or with first name, last name, and one of: email, phone, or city and state. Retrieve job title, seniority, department, business email, LinkedIn profile, and complete business information.
Use this tool when users ask for 'C2B', 'c2b', or 'Consumer to Business Person' data
**Tips for Best Results:**
- Provide full name and consumer email for best match quality
- LinkedIn URLs must be in format: linkedin.com/in/username
- Use `rcfg_require_email` to return only records with business email
- Use `rcfg_require_value` to filter by job title, department, or other attributes| Name | Required | Description | Default |
|---|---|---|---|
| city | No | A person's city | |
| last | No | A person's last name | |
| No | A valid consumer email address | ||
| first | No | A person's first name | |
| phone | No | A person's phone number | |
| state | No | A person's two-letter state code | |
| domain | No | A business domain | |
| li_url | No | A LinkedIn URL (accepts https://www.linkedin.com/in/username, www.linkedin.com/in/username, or linkedin.com/in/username) | |
| rcfg_max_time | No | Maximum allowed API run time (in seconds) | |
| rcfg_require_email | No | Returns only records with email (set to 1 to enable) | |
| rcfg_require_value | No | Field/value requirements in "Field=Value" format. Example: ["Title=Manager"] |
| Name | Required | Description |
|---|---|---|
| results | No | Records returned by the Operations API. Record fields pass through unchanged. |
| query_id | No | |
| warnings | No | |
| input_query | No | |
| num_matches | No | Number of matching queries. |
| num_results | No | Number of records returned. |
| match_counts | No | Sparse match counts. An absent key means zero. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=false, idempotentHint=true, destructiveHint=false, covering the core behavioral traits. The description adds context about the matching logic (anyOf combinations) and configuration parameters (rcfg_*), but doesn't introduce conflicting or additional behavioral traits. It's consistent and slightly enriches understanding without redundancy.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet comprehensive. It opens with a clear purpose, includes a usage trigger, and breaks out tips in a bulleted list. Every sentence adds value; no fluff or repetition of schema details. Front-loaded with the core function, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (11 params, anyOf constraints) and that an output schema exists, the description adequately covers the essential context: required input combinations, configuration options, and best practices. It does not need to explain return values (output schema handles that), and it provides enough guidance for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with each parameter described, but the description adds extra meaning by explaining the anyOf grouping (which parameter sets are valid), the intended use of rcfg_require_email and rcfg_require_value, and the LinkedIn URL formats. This goes beyond the schema to clarify business logic and configuration semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get business demographic details for consumers' and specifies the identification criteria (LinkedIn URL or name+email/phone/city-state). It also lists the output fields (job title, seniority, department, business email, LinkedIn profile, complete business information), making it specific and distinguishable from sibling tools via the explicit 'Use this tool when users ask for C2B' guidance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage cues: 'Use this tool when users ask for C2B, c2b, or Consumer to Business Person data'. It also gives best-practice tips (provide full name and email, LinkedIn URL format, use rcfg_require_email and rcfg_require_value for filtering), guiding when and how to use the tool effectively without ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
contact_appendContact Append Mcp ToolAEnrich consumer records with contact information including emails, phone numbers, and mailing addresses
**Tips for Best Results:**
- Provide as many input fields as possible to improve match quality
- Use `indiv` match type when targeting a specific person
- Request one output type per call when optimizing for match quality (especially for phone outputs)
- Set `cfg_maxrecs` when more than one record is acceptable| Name | Required | Description | Default |
|---|---|---|---|
| zip | No | 5 digit ZIP code | |
| city | No | City name | |
| last | No | Person's last name | |
| No | Email address to enrich | ||
| first | No | Person's first name | |
| phone | No | 10 digit phone number without formatting | |
| state | No | Two-character state code (US) | |
| address | No | Street address (line 1) | |
| outputs | Yes | Types of contact data to return. Choose at least one output type | |
| address_2 | No | Apartment or unit number | |
| match_type | No | Match at household (hhld) or individual (indiv) level | hhld |
| cfg_maxrecs | No | Maximum number of records to return | |
| rcfg_max_emails | No | Maximum number of emails per record (use with email_multiple) | |
| rcfg_exclude_domains | No | Domains to exclude from alternate email results |
| Name | Required | Description |
|---|---|---|
| results | No | Records returned by the Operations API. Record fields pass through unchanged. |
| query_id | No | |
| warnings | No | |
| input_query | No | |
| num_matches | No | Number of matching queries. |
| num_results | No | Number of records returned. |
| match_counts | No | Sparse match counts. An absent key means zero. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description need not repeat those. The description adds context about match quality and output types, but does not disclose additional behavioral aspects (e.g., rate limits, error handling). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise opening sentence followed by four actionable bullet points. Every sentence provides genuine guidance; there is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 14 parameters, full schema coverage, and an output schema present, the description covers the essential usage considerations and best practices. It does not explain every parameter but the schema does; the description adds critical guidance on match types and output optimization.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are documented. The description adds value with tips linking specific parameters to outcomes (e.g., 'use indiv match type when targeting a specific person', 'Request one output type per call when optimizing for match quality'), enhancing understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Enrich consumer records with contact information including emails, phone numbers, and mailing addresses', which is a specific verb+resource+scope. It distinguishes from sibling tools like firmographic_append (company data) and demographic_append (demographics) by explicitly targeting consumer records and contact information types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides practical tips (e.g., 'Provide as many input fields as possible', 'Use indiv match type when targeting a specific person') that guide usage. It implies when to use this tool (consumer enrichment) but does not explicitly mention alternative tools or when not to use it, falling short of complete exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_jobCreate Job Mcp ToolAInspectCreate a B2B or B2C listgen job for the authenticated user.
Use `project_id` when possible. For charge-on-finish jobs, tell the user about usage and only submit `usage_consent_confirmed = true` after they consent. Read the `consent_required_job_types` meta field to know which job types require consent.| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Output list name | |
| config | Yes | Nested job config using the exact input shape documented by `b2b_listgen_estimate` or `b2c_listgen_estimate` for the selected job_type, without nesting or renaming fields. b2b_listgen requires `output`. b2c_listgen requires `required_fields`. max_records defaults to 10000 and may not exceed 50000. | |
| job_type | Yes | Selects the internal operation branch for the nested config payload | |
| project_id | No | Preferred project target when the user already has a project | |
| project_name | No | Fallback project name when the user wants MCP to create/find the project | |
| usage_consent_confirmed | No | Set to true to confirm the user has consented to usage charges. Required for job types that bill upon completion. |
| Name | Required | Description |
|---|---|---|
| job_id | No | |
| job_guid | No | |
| job_state | No | |
| list_name | No | |
| project_id | No | |
| job_operation | No | |
| output_list_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations are minimal (all false), so the description carries the burden of disclosing behavioral traits. It discloses that the job is created for the authenticated user, that charge-on-finish jobs require consent and usage_consent_confirmed, and that the consent_required_job_types meta field determines which types need consent. This adds meaningful operational context beyond the annotations, though it doesn't detail side effects or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, front-loaded with the primary purpose, followed by actionable usage notes. No wasted words; every sentence adds operational value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 parameters, a nested config, and a complex consent workflow. The description addresses key contextual elements: project_id preference, consent handling for charge-on-finish jobs, the meta field for consent requirements, and directing users to estimate tools for config shape. It does not explain the output format, but an output schema exists, which shifts that responsibility. Given the complexity and available structured information, the description is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by giving operational guidance: prioritizing project_id over project_name, the exact workflow for consent (tell user, then confirm), and the need to consult the consent_required_job_types meta field. It also reinforces that config must match the shape from estimate tools. This enriches parameter usage beyond mere descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create a B2B or B2C listgen job for the authenticated user.' It identifies the specific verb (create), the resource (listgen job), and the B2B/B2C scope. It also distinguishes this from sibling estimate/options tools by referencing 'listgen job' and focusing on creation rather than estimation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: 'Use project_id when possible,' and for charge-on-finish jobs, instructs to inform the user about usage and only set usage_consent_confirmed after explicit consent. It also directs the reader to read the consent_required_job_types meta field. While it doesn't explicitly say when not to use this tool versus sibling tools, the context of it being the creation step and the guidance for consent makes the usage context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_projectCreate Project Mcp ToolAInspectCreate a new REACH project for the authenticated user.
Use this tool when a user asks to create a project container before working with lists.
| Name | Required | Description | Default |
|---|---|---|---|
| project_name | Yes | Project name |
| Name | Required | Description |
|---|---|---|
| created_at | No | ISO-8601 creation timestamp |
| project_id | No | |
| project_name | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only and non-destructive behavior, lowering the burden. The description adds the auth context ('for the authenticated user') but does not disclose other behaviors like name uniqueness or error handling. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and every word serves a purpose. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with an output schema present, the description covers purpose, usage trigger, and authentication context. There is no need to describe return values because the output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage of the single parameter ('Project name'). The description does not add significant additional meaning beyond calling it a 'project container,' so it stays at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Create a new REACH project') and resource ('project'), and the addition of 'for the authenticated user' clarifies scope. It distinguishes itself from siblings like list_projects and show_project by being the create operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit usage trigger: 'Use this tool when a user asks to create a project container before working with lists.' This provides clear context, though it does not explicitly mention alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
demographic_appendDemographic Append Mcp ToolAAppend consumer records with household and lifestyle insights across demographic, financial, lifestyle, political, or full demographic categories
**Tips for Best Results:**
- Request only the insight categories you need to keep responses focused
- Combine name, location, and digital identifiers (email or phone) for higher match confidence
- Use `cfg_required` or `rcfg_require_value` to enforce must-have attributes in the response| Name | Required | Description | Default |
|---|---|---|---|
| zip | No | 5 digit ZIP code | |
| city | No | City name | |
| last | No | Person's last name | |
| No | Email address to enrich | ||
| first | No | Person's first name | |
| phone | No | 10 digit phone number without formatting | |
| state | No | Two-character state code (US) | |
| address | No | Street address (line 1) | |
| outputs | Yes | Insight categories to return. Choose at least one category | |
| address_2 | No | Apartment or unit number | |
| match_type | No | Match at household (hhld) or individual (indiv) level | hhld |
| cfg_maxrecs | No | Maximum number of records to return | |
| cfg_required | No | Comma or semi-colon separated response fields that must be populated for a record to be returned | |
| rcfg_require_value | No | Field/value requirements in "Field=Value" format. Example: ["Language=Spanish"] |
| Name | Required | Description |
|---|---|---|
| results | No | Records returned by the Operations API. Record fields pass through unchanged. |
| query_id | No | |
| warnings | No | |
| input_query | No | |
| num_matches | No | Number of matching queries. |
| num_results | No | Number of records returned. |
| match_counts | No | Sparse match counts. An absent key means zero. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already communicate readOnlyHint, idempotentHint, and non-destructive behavior, so the description does not need to restate safety traits. It adds context about matching confidence and response focus, but it does not disclose details like fallback behavior when no match is found or how output is structured.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, action-first, and structured into a main purpose statement followed by a short tips section. Every sentence earns its place, and the formatting makes the guidance easy to skim.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has 14 parameters and an output schema, the description provides sufficient practical context for selection and invocation. It does not explicitly compare to sibling tools, but it covers input strategy, required fields, output category selection, and parameter controls, which is strong coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter already has a description. The tool description adds meaningful parameter-level context by advising identifier combinations and by explaining when to use cfg_required and rcfg_require_value, which goes beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: append consumer records with household and lifestyle insights across defined categories (demographic, financial, lifestyle, political, full demographic). This clearly identifies the tool's purpose and distinguishes it from sibling tools like firmographic_append or contact_append.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides actionable usage guidance: request only needed categories, combine identifiers for higher match confidence, and use cfg_required or rcfg_require_value to enforce must-have attributes. It does not explicitly discuss alternatives among siblings, but it gives clear context for effective use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
docs_searchDocs Search Mcp ToolASearch Versium's official documentation for information about the web application or APIs.
Use this tool when a user has questions about how to use the Versium REACH platform.
**Usage Tips:**
- Use `docs_target: app` for questions about the Versium REACH web application
- Use `docs_target: api` for questions about Versium's data enrichment APIs
- Use `docs_target: both` (default) to search all documentation| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results to return per documentation source | |
| query | Yes | The search query to find relevant documentation | |
| docs_target | No | Which documentation to search: "app" for web application docs, "api" for API docs, or "both" | both |
| Name | Required | Description |
|---|---|---|
| results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description need not restate safety traits. The description adds useful contextual scope about searching official docs and defaulting to both doc sources. However, it does not add deeper behavioral detail such as response shape, pagination, or source behavior beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear purpose sentence, a usage context sentence, and three bullet usage tips. Every line adds practical value without irrelevant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema, fully detailed annotations, and only one required parameter, the description does enough by stating the search domain and when to use the tool. It could be slightly more complete with explicit mention that search is read-only, but the annotations already provide that context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter coverage with descriptions and defaults. The description adds extra semantic value by explaining the meaning of 'app' vs 'api' docs_target choices in practical terms. This goes beyond the schema's basic enum documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's function: searching Versium's official documentation for web application or API information. This is specific and aligned with the tool name, and it is clearly distinct from all sibling tools, which handle data append, job, project, and list operations rather than documentation search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'Use this tool when a user has questions about how to use the Versium REACH platform.' It also provides concrete guidance for choosing docs_target values. It does not explicitly discuss alternatives or when not to use the tool, but the sibling context makes alternative use cases obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
email_validationEmail Validation Mcp ToolAValidate email addresses and optionally get alternate valid emails using Versium's Email Validation API. Returns validation status, sub-status, and whether the email is valid for mailing.
**Tips for Best Results:**
- Provide a valid email address or MD5/SHA256 hashed email (HEM)
- Use `include_alternate` to get an alternate valid email if the input is invalid
- Provide additional contact info (name, address) to improve alternate email matching
- Use `rcfg_exclude_domains` to filter out unwanted email domains from alternates| Name | Required | Description | Default |
|---|---|---|---|
| zip | No | 5 digit US ZIP code | |
| city | No | City name | |
| last | No | Person's last name (helps find alternate email) | |
| Yes | Email address to validate. Can also be an MD5 or SHA256 hashed email (HEM). | ||
| first | No | Person's first name (helps find alternate email) | |
| phone | No | 10 digit phone number | |
| state | No | US state two-letter abbreviation | |
| address | No | Street address (helps find alternate email) | |
| address_2 | No | Apartment or unit number | |
| rcfg_snake_case | No | Return response field names in snake_case instead of "Title Case With Spaces". | |
| include_alternate | No | Whether to include an alternate valid email in the response if the input email is invalid. | |
| rcfg_exclude_domains | No | Domains to exclude from alternate email results (e.g., aol.com, yahoo.com). Only applies when include_alternate is true. |
| Name | Required | Description |
|---|---|---|
| results | No | Records returned by the Operations API. Record fields pass through unchanged. |
| query_id | No | |
| warnings | No | |
| input_query | No | |
| num_matches | No | Number of matching queries. |
| num_results | No | Number of records returned. |
| match_counts | No | Sparse match counts. An absent key means zero. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It reveals that the tool returns validation status and whether the email is valid for mailing, and explains the optional alternate-email behavior. However, it doesn't disclose error handling, rate limits, or any side effects, but for a read-only validation tool this is acceptable. It adds moderate value beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear main line and a bulleted list of tips. It is front-loaded with the primary purpose guide. Each tip is relevant and adds value. Slightly long but well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 12 parameters and an output schema, the description covers enough context: it explains the core behavior, optional alternate email feature, and tips for better results. It doesn't delve into output format, but the output schema likely covers that. For a tool with this complexity, the description is adequate and complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the parameters well (100% have descriptions), so the baseline is 3. The description adds value by clarifying the purpose of additional contact info ('improve alternate email matching') and explains how rcfg_exclude_domains works. This goes beyond schema descriptions, justifying a slightly higher score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Validate email addresses and optionally get alternate valid emails using Versium's Email Validation API.' It specifies the verb (validate), the resource (email addresses), and the API used aids in distinguishing it from sibling tools like data append tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes 'Tips for Best Results' which provides practical usage guidance, such as using hashed emails, including additional contact info for better alternates, and filtering domains. While it doesn't explicitly state when not to use the tool or compare to alternatives, the context is clear enough for tool selection among the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
firmographic_appendFirmographic Append Mcp ToolAGet business information including company details, location, industry classifications, employee counts, and revenue data.
**Tips for Best Results:**
- Provide domain for fastest, most accurate results
- For business name searches, include complete address information or phone number
- Use `rcfg_require_value` to filter for specific industries or business characteristics| Name | Required | Description | Default |
|---|---|---|---|
| zip | No | A 5 digit zip code | |
| city | No | A city name | |
| No | A valid business email address | ||
| phone | No | A valid 10 digit business phone number | |
| state | No | A US state two letter abbreviation | |
| domain | No | A business domain | |
| address | No | An address (street address line 1) | |
| business | No | A business name | |
| rcfg_max_time | No | Maximum allowed API run time (in seconds) | |
| rcfg_require_value | No | Field/value requirements in "Field=Value" format. Example: ["Industry=Technology"]. |
| Name | Required | Description |
|---|---|---|
| results | No | Records returned by the Operations API. Record fields pass through unchanged. |
| query_id | No | |
| warnings | No | |
| input_query | No | |
| num_matches | No | Number of matching queries. |
| num_results | No | Number of records returned. |
| match_counts | No | Sparse match counts. An absent key means zero. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds minimal behavioral detail beyond that, such as performance hints, but does not discuss edge cases, errors, or side effects. It is consistent with the annotations, so no contradiction, but transparency is adequate rather than enhanced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and well-organized: a one-sentence summary followed by three clear, actionable tips. No redundant or vague language is present, making it easy to parse and apply.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives a clear purpose and practical usage tips, and with an output schema present, it need not elaborate on return values. It could mention what happens when no data is found or how to handle multiple inputs, but for a straightforward append operation, the provided context is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes each parameter, so coverage is 100%. The description adds extra semantic value by explaining parameter interplay and best practices, such as how 'domain' improves speed and how 'business' searches benefit from address or phone. It does not explain all parameters, but the tips meaningfully enhance the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get business information including company details, location, industry classifications, employee counts, and revenue data.' This is specific to firmographic data and distinguishes it from sibling tools like contact_append or demographic_append.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tips provide concrete guidance on how to optimize usage (e.g., 'Provide domain for fastest, most accurate results') and when to include additional parameters (e.g., 'include complete address information or phone number' for business name searches). While it doesn't explicitly contrast with alternative tools, the focus on firmographic data and the naming make the appropriate use case clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ip_to_domain_appendIp To Domain Append Mcp ToolADiscover business domains and firmographic information from IP addresses using Versium's IP-to-Domain API. Accepts an IPv4 address and returns up to 3 associated business domains with details like company name, address, industry, employee count, and revenue.
**Tips for Best Results:**
- Provide a valid IPv4 address for best results
- Useful for identifying businesses from web traffic or server information
- Returns comprehensive firmographic data similar to domain-based lookups| Name | Required | Description | Default |
|---|---|---|---|
| ip | Yes | IPv4 address to query for associated business domains. | |
| rcfg_max_time | No | Maximum allowed API run time in seconds (optional). |
| Name | Required | Description |
|---|---|---|
| results | No | Records returned by the Operations API. Record fields pass through unchanged. |
| query_id | No | |
| warnings | No | |
| input_query | No | |
| num_matches | No | Number of matching queries. |
| num_results | No | Number of records returned. |
| match_counts | No | Sparse match counts. An absent key means zero. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior. The description adds the output cardinality limit ('up to 3 associated business domains') and the range of returned firmographic attributes, which is useful beyond the annotations. It does not discuss edge cases like invalid IPs, but the schema pattern covers input format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear one-sentence summary followed by a short tips section. The last bullet and IP-validity tip are somewhat redundant with earlier content, but the overall length is reasonable and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter lookup with a single required field, an output schema, and strong annotations, the description covers purpose, expected output, and practical use. It could be more complete by naming sibling alternatives or clearly scoping when not to use it, but nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters (ip and rcfg_max_time) already have meaningful descriptions. The tool description adds no parameter-level detail beyond the schema, matching the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Discover') and resource ('business domains and firmographic information from IP addresses'), clearly distinguishing this from sibling append/list tools by the IP-to-domain lookup mechanism. It states the core action and result (up to 3 domains with firmographic details).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Tips for Best Results' section gives clear use context: use for identifying businesses from web traffic or server information. It does not explicitly name alternatives or when-not-to-use scenarios, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
job_statusJob Status Mcp ToolACheck the status of an existing job after `create_job`.
Use this tool to poll progress, ETA, and output list readiness while a job is running or after it finishes.| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Positive integer job ID (must be ≥ 1) |
| Name | Required | Description |
|---|---|---|
| job_id | No | |
| job_guid | No | |
| list_url | No | |
| job_state | No | |
| created_at | No | ISO-8601 creation timestamp |
| finished_at | No | ISO-8601 completion timestamp |
| job_operation | No | |
| output_list_id | No | |
| est_sec_remaining | No | |
| output_file_ready | No | |
| progress_percentage | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds value by explaining what status information is available (progress, ETA, output readiness) and when it is meaningful, which goes beyond the schema and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with the key action front-loaded. Every sentence earns its place; no filler or repetition of structured data.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter polling tool with an output schema and strong annotations, the description fully covers the tool's purpose, timing, and what status aspects are relevant. No major contextual gap remains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single `job_id` parameter is clearly documented as a positive integer. The description only implies the parameter via 'existing job' and does not add semantic detail beyond the schema, so the baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb ('Check') and resource ('status of an existing job'), clearly tying it to `create_job`. It also distinguishes this tool from sibling creation/estimation/list tools by focusing on status polling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description gives clear usage context: use after `create_job`, to poll progress, ETA, and output list readiness while the job runs or after it finishes. It does not explicitly list when-not-to-use scenarios or alternatives, but the context is sufficiently directive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_listsList Lists Mcp ToolBList REACH lists for the authenticated user.
Optionally filter by project or name prefix.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of returned lists | |
| search | No | Optional prefix search on list name | |
| project_id | No | Optional project ID to restrict results to a specific project |
| Name | Required | Description |
|---|---|---|
| lists | Yes | List summaries. created_at is an ISO-8601 timestamp. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey read-only and idempotent behavior, and the description adds useful context about user scoping ('for the authenticated user'). However, it doesn't disclose pagination, rate limits, or other behavioral details that could be relevant.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the primary action, and contains no fluff. Every sentence carries meaning, and it stays within two sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward list operation with a complete schema, output schema, and safe annotations, the description adequately covers purpose and filters. No critical gaps are present, though 'REACH' could be unclear to agents unfamiliar with the domain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description's note about filtering by project or name prefix adds minimal value beyond what's already in the schema, and it omits the 'limit' parameter entirely.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and clarifies the resource type ('REACH lists') and scope ('for the authenticated user'). It distinguishes this from listing projects or showing a single list, though it doesn't explicitly name sibling alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like preview_list or show_list. The mention of optional filters is about parameters, not usage context, and no exclusions or alternative tools are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_projectsList Projects Mcp ToolAList REACH projects for the authenticated user.
Use this tool to find the right project before calling `show_project`.| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of returned projects | |
| search | No | Optional prefix search on project name |
| Name | Required | Description |
|---|---|---|
| projects | Yes | Project summaries. created_at is an ISO-8601 timestamp. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds limited behavioral context beyond the annotations, such as the 'REACH' qualifier and the fact that it's for the authenticated user, but it doesn't elaborate on pagination, rate limits, or other behaviors. It's not contradictory and adequately supports the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is remarkably concise, consisting of just two sentences. The first states the core action, and the second offers actionable guidance. No unnecessary words, perfectly front-loaded information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with two well-documented optional parameters, an output schema, and rich annotations, the description is complete. It explains the tool's purpose and provides a usage hint, covering all necessary aspects for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides complete descriptions for both parameters ('Maximum number of returned projects' and 'Optional prefix search on project name'), giving 100% schema coverage. The description adds no additional parameter-level detail, which is acceptable as the schema already does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List'), the resource ('REACH projects'), and the scope ('for the authenticated user'). It also differentiates from siblings by indicating its role in preparation for `show_project`, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case: 'Use this tool to find the right project before calling show_project.' This gives contextual guidance for when to use it, though it does not explicitly exclude alternatives or mention contrast with other list-type tools (e.g., list_lists), keeping it from a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
preview_listPreview List Mcp ToolAPreview a sample of rows from a REACH list.
Use this tool to inspect the actual data rows in a list. Returns a row sample
from the list file. The optional `count` parameter is a hint for how many rows
to return; the actual number may differ depending on list type and backend
preview behavior. When omitted, the service default applies.| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Hint for number of rows to return (1–25). Actual rows may vary by list type. When omitted the service default is used. | |
| list_id | Yes | Positive integer list ID (must be ≥ 1) |
| Name | Required | Description |
|---|---|---|
| rows | No | |
| list_id | No | |
| list_url | No | |
| returned_rows | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral nuance beyond the annotations, including that the count parameter is only a hint, the actual row count may differ by list type and backend behavior, and a service default applies when omitted. This is helpful and consistent with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the primary purpose. It covers sample behavior, count variability, and default behavior in four short sentences. There is slight redundancy between 'Preview a sample of rows' and 'Returns a row sample', but no substantial waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read-only preview tool with full schema coverage and an output schema, the description context is appropriately complete. It explains the extent of the sample, the count limitations, and backend variability. It does not address all possible sibling distinctions, but that is not essential for using this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already has 100% coverage for both list_id and count, including the hint-like nature of count. The description mostly paraphrases what the schema already states, reinforcing that count is a hint and varies, but it does not add additional meaning beyond the structured schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Preview a sample of rows from a REACH list' and further clarifies that it inspects the actual data rows. This specific verb-resource combination differentiates it from siblings like show_list, which likely shows list metadata or structure rather than row samples.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a concise use case: 'Use this tool to inspect the actual data rows in a list.' This provides clear context for when the tool is appropriate. It does not explicitly mention when not to use it or name alternatives, but the usage context is sufficient for a read-only preview tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
show_listShow List Mcp ToolAShow one REACH list and a summary of its latest job.
Use this tool when you already know the list ID and need full metadata plus job status.
| Name | Required | Description | Default |
|---|---|---|---|
| list_id | Yes | Positive integer list ID (must be ≥ 1) |
| Name | Required | Description |
|---|---|---|
| list | No | |
| job_summary | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior, lowering the burden on the description. The description adds useful behavioral context by clarifying that the tool returns both full list metadata and a summary of the latest job, which goes beyond the static annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no wasted words. The first sentence states the action and scope, and the second provides the primary usage condition, making it easy to scan and understand.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple tool with only one required parameter, robust annotations, and an output schema present. The description adequately covers purpose, scope, and when to use it without needing further elaboration on return values, which are presumably documented in the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes list_id as a positive integer with a minimum of 1, so schema coverage is 100%. The description mentions needing to already know the list ID, but adds no additional parameter-level semantics beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool shows one REACH list plus a summary of its latest job, and reinforces that it returns full metadata and job status. This distinguishes it from siblings like list_lists and job_status by specifying the single-list scope and combined metadata/status purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use this tool when the list ID is already known and full metadata plus job status is needed. It provides clear context for use, though it does not explicitly name alternatives or when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
show_projectShow Project Mcp ToolAShow one REACH project and a small summary of its lists.
Use this tool when you already know the project ID and need counts plus a recent-list preview.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Positive integer project ID (must be ≥ 1) |
| Name | Required | Description |
|---|---|---|
| project | No | |
| list_summary | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already confirm read-only, non-destructive, and idempotent behavior. The description adds detail about the output nature ('small summary', 'counts', 'recent-list preview'), giving further clarity without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using two short sentences with no redundant information. It is well-structured and directly addresses the tool's purpose and usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While an output schema exists (so return values need not be detailed), the description gives sufficient context about what the summary contains ('counts', 'recent-list preview'). It is complete enough for an agent to understand the tool's functional scope, though edge cases like error handling are not mentioned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter project_id is fully described in the schema with type and constraints. The description does not add extra semantic meaning beyond 'Positive integer project ID', so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: showing one REACH project and a summary of its lists. It distinguishes from sibling tools like list_projects by specifying a single project and the inclusion of list summaries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage condition is given: 'Use this tool when you already know the project ID and need counts plus a recent-list preview.' This clearly indicates when to choose this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user or an account that owns the GitHub organization, then choose Claim with GitHub.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
