Manage search context

Use aggregations and focused returned fields to keep GovTribe MCP search work scoped before requesting richer records.

Manage what enters the model context before requesting broad records. GovTribe Search_* MCP tools can summarize a result set with aggregations, return compact records with fields_to_return, and then expand only the shortlisted records that need deeper review.

Progressive discovery works in three steps:

Explore the cohort. Use aggregations and per_page: 0 when rows are not needed.

Narrow the search. Use the aggregate buckets or filters that matter.

Request focused records. Use fields_to_return, then expand fields only for selected records.

This keeps token usage lower and helps agents answer the next decision before carrying unnecessary record detail forward.

Rerank a bounded shortlist

Use Rerank Search Results when the first retrieval step found a reasonable shortlist, but the next question needs a different ordering goal. MCP clients and GovTribe AI can use this tool after retrieval as a second-stage ordering pass over at most 50 GovTribe records; it is not a replacement for searching, filtering, sorting, or aggregating.

Prefer search_results_id after a typed Search_* tool returns a replayable result set. Use candidates[] after Search_GovTribe, after merging records from multiple searches, or after hand-curating a short list of GovTribe IDs.

Reranking front-loads available strategic priority signals before the record's semantic search text. For award-style records, GovTribe can include obligated value, ceiling value, buyer, awardee, award or contract type, program, vehicle, competition context, UAS or drone indicators, and routine small-BPA cues so ranking goals can weigh more than exact phrase matches. Explicit candidates[] snippets are added as candidate context after the record is rehydrated, so agents can preserve useful clues from a previous broad search or hand-curated shortlist.

Keep max_results to the number of records the answer needs. When rerank_status is failed_open, the response returned source order because runtime reranking failed.

Explore without records using aggregations

Use aggregations when the agent needs to understand a search cohort before reading individual records. Aggregations can answer counts, distributions, top-N leaders, value rollups, and other summary questions without returning result rows.

Set per_page: 0 when the user only needs the rollup. Add filters, date ranges, location filters, categories, or search text first so the aggregation summarizes the intended cohort.

Aggregation-first award rollup:

Tool: Search_Federal_Contract_Awards

{
  "query": "\"cloud modernization\"",
  "search_mode": "keyword",
  "aggregations": ["top_awardees_by_dollars_obligated"],
  "per_page": 0
}

Use the returned buckets to decide what to do next. For example, an agent might choose a top awardee, agency, location, NAICS code, PSC code, or date window from the rollup before requesting matching records.

Shape returned records with fields_to_return

Use fields_to_return when the agent needs records back. It chooses which fields a dataset-specific Search_* tool includes in each returned record; it does not change matching, filtering, sorting, aggregation, paging, or search mode.

Rule	What it means
`fields_to_return` is optional.	Omit it when the record ID alone is enough.
Allowed values come from the tool reference.	Use the exact field names listed in the selected tool's `Available Fields` table.
Omitted or empty requests return `govtribe_id`.	Start there when the next step only needs IDs for follow-up calls.
Unselected fields are removed from records.	Request relationship, summary, description, file, contact, category, and financial fields only when the current step needs them.
High-volume relationships use previews.	Fields ending in `_preview` return `items`, `returned_count`, `limit`, `truncated`, and `sort`; use the listed IDs with the related `Search_*` tool when `truncated` is true or when the preview is not enough.
Search scores are explicit.	Typed `Search_*` record rows include `score` as a number when the result is relevance-ranked and `null` when the result set is not score-ranked or a score is unavailable.

Compact opportunity scan:

Tool: Search_Federal_Contract_Opportunities

{
  "query": "\"zero trust architecture\"",
  "search_mode": "keyword",
  "fields_to_return": [
    "govtribe_id",
    "name",
    "govtribe_url",
    "posted_date",
    "due_date",
    "opportunity_state"
  ],
  "per_page": 10
}

Award follow-up for a selected result:

Tool: Search_Federal_Contract_Awards

{
  "federal_contract_award_ids": ["<FEDERAL_CONTRACT_AWARD_ID>"],
  "fields_to_return": [
    "govtribe_id",
    "name",
    "govtribe_url",
    "award_date",
    "dollars_obligated",
    "awardee",
    "contracting_federal_agency",
    "place_of_performance"
  ],
  "per_page": 1
}

Avoid requesting every available field during the first pass. Use preview fields only after the agent has narrowed the result set, then switch to the related search tool when the answer needs the complete related set.

Choose a search mode and write queries: Choose keyword or semantic search and write query values that fit the selected tool.
Aggregations and leaderboards: Use rollups when counts, distributions, or leaderboards answer the question better than rows.
MCP tools: Review tool-specific arguments, available fields, filters, sorts, and aggregation keys.

Rerank a bounded shortlist

Explore without records using aggregations

Shape returned records with fields_to_return

Related articles

On this page