# Search States

`Search_States` is the GovTribe MCP dataset tool for U.S.

## When To Use

Typical questions this tool answers well:

* Which GovTribe state record matches a given USPS code or a known state name?
* What is the canonical GovTribe state ID needed for downstream filters in state and local tools?
* Which states should be included or excluded before running opportunity or award analysis?
* How can I quickly list state records to seed jurisdiction or procurement market segmentation workflows?
* Which state entities should be used as stable references when creating saved-search or pipeline workflows that depend on state filters?

## Required Reading

1. [Search\_Mode\_And\_Query\_Guide](/user-guide/mcp/guides/search_mode_and_query_guide.md): Required before setting free-text query strings.
2. [Location\_Filtering\_Guide](/user-guide/mcp/guides/location_filtering_guide.md): Required before setting location filters.

## 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.
* Row keys:
  * `govtribe_id`
  * `govtribe_type`
  * `govtribe_url`
  * `name`
  * `usps_code`
  * `updated_at`
* Relationship retrieval map:
  * `none`: This resource has no relationship fields.

## Usage Patterns

Pattern A: Resolve one state by USPS code before applying downstream `state_ids` filters. Tool: `Search_States`

```json
{
  "fields_to_return": [
    "govtribe_id"
  ],
  "page": 1,
  "per_page": 1,
  "state_ids": [
    "VA"
  ],
  "state_ids_operator": "in"
}
```

Pattern B: Keyword lookup for multiple named states and return a small working set. Tool: `Search_States`

```json
{
  "query": "\"Texas\" | \"Virginia\" | \"Florida\"",
  "fields_to_return": [
    "govtribe_id"
  ],
  "page": 1,
  "per_page": 10
}
```

Pattern C: Exclude known states while exploring the remaining state universe. Tool: `Search_States`

```json
{
  "fields_to_return": [
    "govtribe_id"
  ],
  "page": 1,
  "per_page": 25,
  "state_ids": [
    "CA",
    "NY",
    "TX"
  ],
  "state_ids_operator": "not_in"
}
```

Pattern D: Metadata-only response when a workflow only needs counts and result-set identifiers. Tool: `Search_States`

```json
{
  "page": 1,
  "per_page": 0
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.govtribe.com/user-guide/mcp/tools/search-states.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.