# Search Vendors

`Search_Vendors` returns GovTribe vendor records with identifiers, registration timing, certification tags, and core relationship context used across award and opportunity research.

## When To Use

Typical questions this tool answers well:

* Which GovTribe vendor record matches a specific company name, UEI, or known vendor ID?
* Which vendors in a topic area match specific small-business designations or SBA certifications?
* Which vendors are registered in a location, primary NAICS, or PSC footprint?
* Which vendors have recent federal contract or grant award activity?
* What are the top NAICS, PSC, or locations represented by the current vendor result set?

## Required Reading

1. [Search\_Query\_Guide](https://docs.govtribe.com/user-guide/mcp/guides/search_query_guide): Required before setting free-text query strings when search\_mode is used.
2. [Search\_Mode\_Guide](https://docs.govtribe.com/user-guide/mcp/guides/search_mode_guide): Required before choosing keyword vs semantic retrieval.
3. [Date\_Filtering\_Guide](https://docs.govtribe.com/user-guide/mcp/guides/date_filtering_guide): Required before setting date window filters.
4. [Location\_Filtering\_Guide](https://docs.govtribe.com/user-guide/mcp/guides/location_filtering_guide): Required before setting location filters.

## Input Contract

* `query`: Free-text query string. See Required Reading: [Search\_Query\_Guide](https://docs.govtribe.com/user-guide/mcp/guides/search_query_guide).
  * `type`: `string`
  * `required`: `no`
  * `default`: `n/a`
* `page`: 1-based page index.
  * `type`: `null|number`
  * `required`: `no`
  * `default`: `1`
* `per_page`: Rows per page.
  * `type`: `null|number`
  * `required`: `no`
  * `default`: `10`
* `search_mode`: Query interpretation mode. See Required Reading: [Search\_Mode\_Guide](https://docs.govtribe.com/user-guide/mcp/guides/search_mode_guide).
  * `type`: `string`
  * `required`: `no`
  * `default`: `keyword`
  * `options`: `keyword`, `semantic`
* `most_recent_federal_contract_award_date_range`: Filter by the date of the vendor's most recent federal contract award. See Required Reading: [Date\_Filtering\_Guide](https://docs.govtribe.com/user-guide/mcp/guides/date_filtering_guide).
  * `type`: `object`
  * `required`: `no`
  * `default`: `n/a`
  * `shape`: `{ from?: null|string, to?: null|string }`
* `most_recent_federal_grant_award_date_range`: Filter by the date of the vendor's most recent federal grant award. See Required Reading: [Date\_Filtering\_Guide](https://docs.govtribe.com/user-guide/mcp/guides/date_filtering_guide).
  * `type`: `object`
  * `required`: `no`
  * `default`: `n/a`
  * `shape`: `{ from?: null|string, to?: null|string }`
* `registration_date_range`: Filter by the date the vendor registered to do business with the federal government. See Required Reading: [Date\_Filtering\_Guide](https://docs.govtribe.com/user-guide/mcp/guides/date_filtering_guide).
  * `type`: `object`
  * `required`: `no`
  * `default`: `n/a`
  * `shape`: `{ from?: null|string, to?: null|string }`
* `registration_expiration_date_range`: Filter by the date the vendor registration expires or expired. See Required Reading: [Date\_Filtering\_Guide](https://docs.govtribe.com/user-guide/mcp/guides/date_filtering_guide).
  * `type`: `object`
  * `required`: `no`
  * `default`: `n/a`
  * `shape`: `{ from?: null|string, to?: null|string }`
* `vendor_location_ids`: Filter by vendor locations. Use GovTribe location IDs or location text for countries, cities/localities, ZIP or postal codes, states/territories, or counties; matching is US-biased for ambiguous names. See Required Reading: [Location\_Filtering\_Guide](https://docs.govtribe.com/user-guide/mcp/guides/location_filtering_guide).
  * `type`: `array<string>`
  * `required`: `no`
  * `default`: `n/a`
* `vendor_location_ids_operator`: Choose whether to include or exclude values for Vendor Location IDs or Locations.
  * `type`: `null|string`
  * `required`: `no`
  * `default`: `in`
  * `options`: `in`, `not_in`
* `vendor_primary_registered_naics_category_ids`: Filter by the vendor's primary registered NAICS categories. Uses NAICS codes and applies the legacy -N suffix transform.
  * `type`: `array<string>`
  * `required`: `no`
  * `default`: `n/a`
* `vendor_primary_registered_naics_category_ids_operator`: Choose whether to include or exclude values for Vendor Primary Registered NAICS Category Codes.
  * `type`: `null|string`
  * `required`: `no`
  * `default`: `in`
  * `options`: `in`, `not_in`
* `vendor_registered_psc_category_ids`: Filter by the vendor's registered PSC categories. Uses PSC codes and applies the legacy -P suffix transform.
  * `type`: `array<string>`
  * `required`: `no`
  * `default`: `n/a`
* `vendor_registered_psc_category_ids_operator`: Choose whether to include or exclude values for Vendor Registered PSC Category Codes.
  * `type`: `null|string`
  * `required`: `no`
  * `default`: `in`
  * `options`: `in`, `not_in`
* `sba_certifications`: Filter by Small Business Administration (SBA) certifications.
  * `type`: `array<string>`
  * `required`: `no`
  * `default`: `n/a`
  * `options`: `SBA Certified Small Disadvantaged Business`, `SBA Certified 8A Program Participant`, `SBA Certified 8A Joint Venture`, `SBA Certified HUBZone Firm`, `SBA Certified Women-Owned Small Business`, `SBA Certified Economically Disadvantaged Women-Owned Small Business`
* `sba_certifications_operator`: Choose whether to include or exclude values for SBA Certifications.
  * `type`: `null|string`
  * `required`: `no`
  * `default`: `in`
  * `options`: `in`, `not_in`
* `business_types`: Filter by business type certifications and designations.
  * `type`: `array<string>`
  * `required`: `no`
  * `default`: `n/a`
  * `options`: `AbilityOne Non Profit Agency`, `Alaskan Native Corporation Owned Firm`, `American Indian Owned`, `Asian-Pacific American Owned`, `Black American Owned`, `DOT Certified DBE`, `Economically Disadvantaged Women Small Owned Business`, `For Profit Organization`, `Hispanic American Owned`, `Indian Economic Enterprise`, `Indian Small Business Economic Enterprise`, `Indian Tribe (Federally Recognized)`, `Joint Venture Economically Disadvantaged Women Small Owned Business`, `Joint Venture Women Owned Small Business`, `Minority Owned Business`, `Native American Owned`, `Native Hawaiian Organization Owned Firm`, `Non-Profit Organization`, `Self Certified Small Disadvantaged Business`, `Service Disabled Veteran Owned Business`, `Subcontinent Asian (Asian-Indian) American Owned`, `Tribally Owned Firm`, `Veteran Owned Business`, `Woman Owned Business`, `Woman Owned Small Business`
* `business_types_operator`: Choose whether to include or exclude values for Business Types.
  * `type`: `null|string`
  * `required`: `no`
  * `default`: `in`
  * `options`: `in`, `not_in`
* `similar_filter`: Find similar to the provided govtribe\_type + govtribe\_id.
  * `type`: `null|object`
  * `required`: `no`
  * `default`: `n/a`
  * `shape`: `{ govtribe_type: string, govtribe_id: string }`
* `vendor_ids`: Include or exclude results by vendors. Use GovTribe IDs or vendor UEIs.
  * `type`: `array<string>`
  * `required`: `no`
  * `default`: `n/a`
* `vendor_ids_operator`: Choose whether to include or exclude values for Vendor IDs (GovTribe or UEI).
  * `type`: `null|string`
  * `required`: `no`
  * `default`: `in`
  * `options`: `in`, `not_in`
* `aggregations`: Aggregation keys to compute.
  * `type`: `array<string>`
  * `required`: `no`
  * `default`: `n/a`
  * `options`: `top_sba_certifications_by_doc_count`, `top_naics_codes_by_doc_count`, `top_psc_codes_by_doc_count`, `top_locations_by_doc_count`
* `sort`: Sort configuration.
  * `type`: `object`
  * `required`: `no`
  * `default`: `n/a`
  * `shape`: `{ key?: null|string, direction?: null|string }`
  * `options`: `key`: `registrationDate`, `expirationDate`, `most_recent_federal_contract_award_model_date`, `most_recent_federal_grant_award_model_date`, `sbaCert8aExpirationDate`, `_score`; `direction`: `asc`, `desc`
* `fields_to_return`: Optional field list for row payloads. If omitted and `per_page > 0`, rows default to `govtribe_id`. For `per_page: 0` aggregation/meta calls, this field may be omitted. Specify `fields_to_return` whenever the user asks for fields beyond `govtribe_id`, and prefer omitting it in pure aggregation workflows.
  * `type`: `array<string>`
  * `required`: `no`
  * `default`: `n/a`
  * `options`: `govtribe_id`, `govtribe_ai_summary`, `govtribe_type`, `govtribe_url`, `uei`, `name`, `division`, `dba`, `address`, `registration_date`, `registration_expiration_date`, `structure`, `sba_certifications`, `sba_cert_8a_expiration_date`, `sba_cert_8a_joint_venture_expiration_date`, `sba_cert_hubzone_expiration_date`, `sba_cert_small_disadvantaged_business_expiration_date`, `business_types`, `parent_or_child`, `awarded_federal_contract_award`, `awarded_federal_contract_idv`, `awarded_federal_contract_vehicle`, `awarded_federal_grant_award`, `has_federal_contract_prime_awardees`, `has_federal_grant_prime_awardees`, `updated_at`, `parent`, `naics_category`, `federal_contract_awards`, `federal_contract_idvs`, `federal_contract_sub_awards`, `federal_grant_awards`, `federal_grant_sub_awards`

## Output Contract

* Top-level keys:
  * `current_page`: Current page number when `per_page > 0`.
  * `data`: Array of result rows when `per_page > 0`.
  * `from`: First row position in the current page.
  * `last_page`: Last page number for current filters.
  * `path`: GovTribe search URL for this result set.
  * `per_page`: Applied page size.
  * `to`: Last row position in the current page.
  * `total`: Total matched row count for current query filters.
  * `contains`: Dataset label for the returned result set.
  * `search_results_id_can_generate_saved_search`: Saved-search eligibility flag.
  * `search_results_id`: Server-side search result identifier.
  * `view_search_results_url`: URL to open this exact result set.
  * `aggregations`: Aggregation payload keyed by requested aggregation names when requested.
  * `per_page: 0` behavior: response omits `data` and pagination keys, returning metadata keys above plus `aggregations` when requested.
* Row keys:
  * `govtribe_id`
  * `govtribe_ai_summary`
  * `govtribe_type`
  * `govtribe_url`
  * `uei`
  * `name`
  * `division`
  * `dba`
  * `address`
  * `registration_date`
  * `registration_expiration_date`
  * `structure`
  * `sba_certifications`
  * `sba_cert_8a_expiration_date`
  * `sba_cert_8a_joint_venture_expiration_date`
  * `sba_cert_hubzone_expiration_date`
  * `sba_cert_small_disadvantaged_business_expiration_date`
  * `business_types`
  * `parent_or_child`
  * `awarded_federal_contract_award`
  * `awarded_federal_contract_idv`
  * `awarded_federal_contract_vehicle`
  * `awarded_federal_grant_award`
  * `has_federal_contract_prime_awardees`
  * `has_federal_grant_prime_awardees`
  * `updated_at`
  * `parent`
  * `naics_category`
  * `federal_contract_awards`
  * `federal_contract_idvs`
  * `federal_contract_sub_awards`
  * `federal_grant_awards`
  * `federal_grant_sub_awards`
* SBA certification expiration row fields return ISO 8601 Zulu timestamp strings when present.
* Relationship retrieval map:
  * `federal_contract_awards`
    * `resource_type`: `federal_contract_award`
    * `tool`: `Search_Federal_Contract_Awards`
    * `filter`: `federal_contract_award_ids`
    * `nested_keys`: `govtribe_id`, `govtribe_type`, `govtribe_url`, `name`
  * `federal_contract_idvs`
    * `resource_type`: `federal_contract_idv`
    * `tool`: `Search_Federal_Contract_IDVs`
    * `filter`: `federal_contract_i_d_v_ids`
    * `nested_keys`: `govtribe_id`, `govtribe_type`, `govtribe_url`, `name`
  * `federal_contract_sub_awards`
    * `resource_type`: `federal_contract_sub_award`
    * `tool`: `Search_Federal_Contract_Sub_Awards`
    * `filter`: `federal_contract_sub_award_ids`
    * `nested_keys`: `govtribe_id`, `govtribe_type`, `govtribe_url`, `name`
  * `federal_grant_awards`
    * `resource_type`: `federal_grant_award`
    * `tool`: `Search_Federal_Grant_Awards`
    * `filter`: `federal_grant_award_ids`
    * `nested_keys`: `govtribe_id`, `govtribe_type`, `govtribe_url`, `name`
  * `federal_grant_sub_awards`
    * `resource_type`: `federal_grant_sub_award`
    * `tool`: `Search_Federal_Grant_Sub_Awards`
    * `filter`: `federal_grant_sub_award_ids`
    * `nested_keys`: `govtribe_id`, `govtribe_type`, `govtribe_url`, `name`
  * `naics_category`
    * `resource_type`: `naics_category`
    * `tool`: `Search_Naics_Categories`
    * `filter`: `naics_category_ids`
    * `nested_keys`: `govtribe_id`, `govtribe_type`, `govtribe_url`, `name`
  * `parent`
    * `resource_type`: `vendor`
    * `tool`: `Search_Vendors`
    * `filter`: `vendor_ids`
    * `nested_keys`: `govtribe_id`, `govtribe_type`, `name`, `uei`, `govtribe_url`

## Usage Patterns

Pattern A: Resolve a specific vendor by exact name/phrase before downstream award lookups. Tool: `Search_Vendors`

```json
{
  "query": "\"BLN LLC\"",
  "search_mode": "keyword",
  "fields_to_return": [
    "govtribe_id"
  ],
  "page": 1,
  "per_page": 5,
  "sort": {
    "key": "registrationDate",
    "direction": "desc"
  }
}
```

Pattern B: Find small-business vendors in a topic area using certification filters. Tool: `Search_Vendors`

```json
{
  "query": "cybersecurity services for federal agencies",
  "search_mode": "semantic",
  "fields_to_return": [
    "govtribe_id"
  ],
  "business_types": [
    "Woman Owned Small Business",
    "Service Disabled Veteran Owned Business"
  ],
  "business_types_operator": "in",
  "most_recent_federal_contract_award_date_range": {
    "from": "now-3y/d",
    "to": null
  },
  "page": 1,
  "per_page": 25,
  "sba_certifications": [
    "SBA Certified HUBZone Firm"
  ],
  "sba_certifications_operator": "in",
  "sort": {
    "key": "most_recent_federal_contract_award_model_date",
    "direction": "desc"
  }
}
```

Pattern C: Aggregation-only market profile for NAICS/PSC/location distributions. Tool: `Search_Vendors`

```json
{
  "query": "",
  "search_mode": "keyword",
  "aggregations": [
    "top_naics_codes_by_doc_count",
    "top_psc_codes_by_doc_count",
    "top_locations_by_doc_count"
  ],
  "most_recent_federal_contract_award_date_range": {
    "from": "now-2y/d",
    "to": null
  },
  "page": 1,
  "per_page": 0
}
```

Pattern D: Similar-vendor discovery from a known vendor record. Tool: `Search_Vendors`

```json
{
  "query": "",
  "search_mode": "semantic",
  "fields_to_return": [
    "govtribe_id"
  ],
  "page": 1,
  "per_page": 20,
  "similar_filter": {
    "govtribe_type": "vendor",
    "govtribe_id": "<VENDOR_ID>"
  }
}
```

Pattern E: Vendors with registrations expiring soon, ordered by expiration. Tool: `Search_Vendors`

```json
{
  "query": "",
  "search_mode": "keyword",
  "fields_to_return": [
    "govtribe_id"
  ],
  "page": 1,
  "per_page": 25,
  "registration_expiration_date_range": {
    "from": "now/d",
    "to": "now+90d/d"
  },
  "sort": {
    "key": "expirationDate",
    "direction": "asc"
  }
}
```