# Search State And Local Contract Awards `Search_State_And_Local_Contract_Awards` is the GovTribe MCP tool for retrieving state and local award records with monetary fields, issuing entities, attached supporting materials, and direct parent links when they are available. ## When To Use * Find state and local awards for a topic, agency-like issuing entity, or geography. * Build award spend rollups for states, NIGP categories, UNSPSC categories, or issuing entities. * Pull award rows that include nested state, parent IDV/opportunity links, line items, government files, and points of contact. * Investigate likely incumbents or prior contracts using date windows and contact filters. * Retrieve exact awards when GovTribe IDs are already known. ## 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 and choosing keyword vs semantic retrieval. 2. [Date\_Filtering\_Guide](/user-guide/mcp/guides/date_filtering_guide.md): Required before setting date window filters. 3. [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. * `aggregations`: Aggregation payload keyed by requested aggregation names when requested. * Aggregation value shapes: * `dollars_obligated_stats`: `{ count, min, max, avg, sum }`. * Terms aggregations (`top_*_by_dollars_obligated`): `{ doc_count_error_upper_bound, sum_other_doc_count, buckets }`. * `buckets[*]`: `{ key, doc_count, sum_value: { value } }`. * `key` is a hydrated object for state/NIGP/UNSPSC aggregations and a string for `top_contract_entities_by_dollars_obligated`. * Row keys: * `govtribe_id` * `govtribe_ai_summary` * `govtribe_type` * `govtribe_url` * `name` * `description` * `awardee_name` * `contracting_organization` * `award_date` * `completion_date` * `estimated_annual_value` * `contract_amount` * `cumulative_value` * `contract_number` * `contract_type` * `updated_at` * `state` * `state_local_contract_idv` * `state_local_contract_opportunity` * `line_items` * `unspsc_categories` * `nigp_categories` * `government_files` * `points_of_contact` * Relationship retrieval map: * `government_files` * `resource_type`: `government_file` * `tool`: `Search_Government_Files` * `filter`: `government_file_ids` * `nested_keys`: `govtribe_id`, `govtribe_type`, `govtribe_url`, `name` * `line_items` * `resource_type`: `line_item` * `tool`: `Search_Line_Items` * `filter`: `line_item_ids` * `nested_keys`: `govtribe_id`, `govtribe_type`, `name` * `nigp_categories` * `resource_type`: `nigp_category` * `tool`: `Search_Nigp_Categories` * `filter`: `nigp_category_ids` * `nested_keys`: `govtribe_id`, `govtribe_type`, `govtribe_url`, `name` * `points_of_contact` * `resource_type`: `contact` * `tool`: `Search_Contacts` * `filter`: `contact_ids` * `nested_keys`: `govtribe_id`, `govtribe_type`, `name`, `email`, `govtribe_url` * `state` * `resource_type`: `state` * `tool`: `Search_States` * `filter`: `state_ids` * `nested_keys`: `govtribe_id`, `govtribe_type`, `govtribe_url`, `name` * `state_local_contract_idv` * `resource_type`: `state_local_contract_idv` * `tool`: `Search_State_And_Local_Contract_IDVs` * `filter`: `state_local_contract_idv_ids` * `nested_keys`: `govtribe_id`, `govtribe_type`, `govtribe_url`, `name` * `state_local_contract_opportunity` * `resource_type`: `state_local_contract_opportunity` * `tool`: `Search_State_And_Local_Contract_Opportunities` * `filter`: `state_local_contract_opportunity_ids` * `nested_keys`: `govtribe_id`, `govtribe_type`, `govtribe_url`, `name` * `unspsc_categories` * `resource_type`: `unspsc_category` * `tool`: `Search_Unspsc_Categories` * `filter`: `unspsc_category_ids` * `nested_keys`: `govtribe_id`, `govtribe_type`, `govtribe_url`, `name` ## Usage Patterns Pattern A: State-level spend leaderboard (aggregations only) Tool: `Search_State_And_Local_Contract_Awards` ```json { "search_mode": "keyword", "award_date_range": { "from": "now-12M/d", "to": "now/d" }, "state_ids": [ "CA" ], "aggregations": [ "dollars_obligated_stats", "top_contract_entities_by_dollars_obligated", "top_nigp_codes_by_dollars_obligated", "top_unspsc_codes_by_dollars_obligated", "top_states_by_dollars_obligated" ], "per_page": 0 } ``` Pattern B: Recent awards for a known contact in a specific state Tool: `Search_State_And_Local_Contract_Awards` ```json { "search_mode": "keyword", "fields_to_return": [ "govtribe_id" ], "award_date_range": { "from": "now-18M/d", "to": "now/d" }, "state_ids": [ "MD" ], "contact_ids": [ "" ], "sort": { "key": "awardDate", "direction": "desc" }, "page": 1, "per_page": 25 } ``` Pattern C: Exact award lookup by GovTribe IDs Tool: `Search_State_And_Local_Contract_Awards` ```json { "search_mode": "keyword", "fields_to_return": [ "govtribe_id" ], "per_page": 10, "state_and_local_contract_award_ids": [ "", "" ] } ``` Pattern D: Semantic topic exploration across state/local awards Tool: `Search_State_And_Local_Contract_Awards` ```json { "query": "statewide cybersecurity incident response retainer contracts", "search_mode": "semantic", "fields_to_return": [ "govtribe_id" ], "award_date_range": { "from": "now-24M/d", "to": "now/d" }, "state_ids": [ "VA", "NC" ], "per_page": 20 } ``` Pattern E: Find awards similar to a known state/local award Tool: `Search_State_And_Local_Contract_Awards` ```json { "search_mode": "semantic", "fields_to_return": [ "govtribe_id" ], "similar_filter": { "govtribe_type": "state_local_contract_award", "govtribe_id": "" }, "per_page": 10 } ``` --- # 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-state-and-local-contract-awards.md?ask= ``` 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.