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.

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.

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. Broad relationship fields can be useful, but they are usually better after the agent has already narrowed the result 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.

Explore without records using aggregations

Shape returned records with fields_to_return

Related articles

On this page