Aggregations and leaderboards

Use aggregations when the user needs a summary of a scoped search cohort instead of a list of individual records.

When to use aggregations

Aggregations are the right path for:

• counts and totals
• percentages or ratios
• top lists, rankings, and leaderboards
• distributions by agency, vendor, category, location, or time period
• monthly lifecycle trends, such as posted opportunities by month or active solicitations by due month
• dashboard-style KPI rollups

Aggregation-first analysis should usually keep the default keyword behavior. Do not send search_mode unless the selected search tool supports it and the question genuinely needs semantic matching.

Construction rules

Build the cohort first, then ask for the aggregation.

Scope the cohort before aggregating

The query value defines which records enter the aggregation. If the query is too broad, long-tail matches can skew every returned bucket, including top vendors, agencies, categories, locations, and dollar rollups.

Use search_mode: "keyword" with quoted phrase anchors when the user names a specific market, service, program, description, or identifier. If the selected tool does not expose search_mode, omit it and still use keyword-style quoted phrases in query.

Use + when two anchors must both match. For example, prefer "home oxygen" + "medical equipment" over home oxygen delivery and medical equipment support for veterans when the aggregation should summarize records that mention both core concepts.

Use broader unquoted text, semantic search, prefix matching, or fuzzy matching only when the user asks for exploratory sizing or related-language discovery. When broadening a query, pair it with structured filters when possible and review a small row sample before treating the rollup as authoritative.

Choose aggregation keys

The tool page is the source of truth for available keys. Common patterns are:

If the user asks "which vendors/agencies/categories dominate this space?", choose a top-list aggregation. If they ask "how much?" or "how many?", choose a stats aggregation or compare the returned total count.

Use date histograms for monthly trends

Date histogram aggregations return monthly buckets for the scoped result set. Use them when the user needs timing, workload, or trend context before reviewing individual records.

Common date histogram bucket fields are:

Scope the cohort before interpreting monthly buckets. For opportunity work, apply filters such as agency, NAICS, PSC, set-aside, vehicle, opportunity type, opportunity status, posted date, or due date before using posted_date_histogram or due_date_histogram.

Use per_page: 0 for aggregation-only requests. When charting a trend, treat returned buckets as the matched months in the scoped cohort; add zero-value months only after you have chosen the full comparison window.

Summarize workspace portfolio work

Workspace portfolio rollups use the same aggregation pattern as public-record searches: build the cohort first, then request the summary. Search_Pursuits is the main portfolio rollup tool because pursuits carry pipeline, stage, owner, creator, tag, value, due-date, estimated-award-date, and updated-date fields.

Common pursuit portfolio questions include:

For pipeline-level stage distribution, call Search_Pursuits with pipeline_ids and top_stages_by_doc_count. Search_Pipelines summarizes pipeline records by owner, creator, and tag, but pipeline records do not expose a per-stage pursuit distribution aggregation.

Portfolio value and timing:

Tool: Search_Pursuits

{
  "aggregations": [
    "estimated_value_stats",
    "probable_value_stats",
    "due_date_histogram",
    "estimated_award_date_histogram"
  ],
  "per_page": 0
}

Pipeline stage distribution:

Tool: Search_Pursuits

{
  "pipeline_ids": ["<pipeline_govtribe_id>"],
  "aggregations": [
    "top_stages_by_doc_count"
  ],
  "per_page": 0
}

Pipeline owner and tag distribution:

Tool: Search_Pipelines

{
  "aggregations": [
    "top_owners_by_doc_count",
    "top_creators_by_doc_count",
    "top_tags_by_doc_count"
  ],
  "per_page": 0
}

Interpret stale pursuit buckets

updated_at_staleness groups the scoped pursuit cohort into four recency buckets:

Use owner, creator, pipeline, stage, tag, or pursuit ID filters before requesting stale buckets when the user asks about a specific team member, pipeline, capture lane, or shortlist. Use the returned buckets to decide whether to follow up with row-level searches for specific owners, stages, or pipelines.

Percentages and matched cohorts

For percentage questions, run matched numerator and denominator requests. The denominator request should represent the full scoped population. The numerator request should use the same scope plus the qualifying condition.

Denominator:

Tool: Search_Federal_Contract_Awards

{
  "award_date_range": {
    "from": "now-12M/d",
    "to": "now/d"
  },
  "aggregations": ["dollars_obligated_stats"],
  "per_page": 0
}

Numerator:

Tool: Search_Federal_Contract_Awards

{
  "award_date_range": {
    "from": "now-12M/d",
    "to": "now/d"
  },
  "set_aside_types": ["Total Small Business"],
  "aggregations": ["dollars_obligated_stats"],
  "per_page": 0
}

Displaying rollups

Use Show stats display for KPI cards, totals, averages, percentages, and small metric groups.

Use Show chart for standard inline trend, comparison, or leaderboard charts when the aggregation output can be converted into clean rows and series.

Use a text answer when the result is small, exploratory, or primarily a decision about which follow-up search to run.

Examples

Award value and top awardees:

Tool: Search_Federal_Contract_Awards

{
  "query": "\"cloud migration\"",
  "search_mode": "keyword",
  "award_date_range": {
    "from": "now-2y/d",
    "to": "now/d"
  },
  "naics_category_ids": ["541512"],
  "aggregations": [
    "dollars_obligated_stats",
    "top_awardees_by_dollars_obligated"
  ],
  "per_page": 0
}

Opportunity count leaders by agency and NAICS:

Tool: Search_Federal_Contract_Opportunities

{
  "query": "\"cybersecurity support\"",
  "search_mode": "keyword",
  "due_date_range": {
    "from": "now/d",
    "to": "now+90d/d"
  },
  "set_aside_types": ["Total Small Business"],
  "aggregations": [
    "top_federal_agencies_by_doc_count",
    "top_naics_codes_by_doc_count"
  ],
  "per_page": 0
}

Opportunity due-month trend and lifecycle mix:

Tool: Search_Federal_Contract_Opportunities

{
  "opportunity_types": ["Solicitation"],
  "due_date_range": {
    "from": "now/d",
    "to": "now+12M/d"
  },
  "aggregations": [
    "due_date_histogram",
    "top_opportunity_states_by_doc_count"
  ],
  "per_page": 0
}

IDV ceiling leaders and ordering-window trend:

Tool: Search_Federal_Contract_IDVs

{
  "query": "\"cybersecurity operations\"",
  "search_mode": "keyword",
  "aggregations": [
    "ceiling_value_stats",
    "top_awardees_by_ceiling_value",
    "last_date_to_order_histogram"
  ],
  "per_page": 0
}

Chart a leaderboard after converting aggregation buckets to rows:

Tool: Show_Chart

{
  "id": "top-awardees-by-obligation",
  "kind": "leaderboard",
  "title": "Top awardees by obligated dollars",
  "rows": [
    {
      "awardee": "Example Systems LLC",
      "dollars_obligated": 128500000
    },
    {
      "awardee": "Example Mission Services Inc.",
      "dollars_obligated": 74200000
    }
  ],
  "labelKey": "awardee",
  "series": [
    {
      "key": "dollars_obligated",
      "label": "Dollars obligated"
    }
  ],
  "valueFormat": {
    "kind": "currency",
    "currency": "USD",
    "compact": true
  },
  "maxItems": 10
}

Display KPI cards after extracting stats:

Tool: Show_Stats_Display

{
  "id": "award-rollup",
  "title": "Award cohort summary",
  "stats": [
    {
      "key": "award_count",
      "label": "Awards",
      "value": 384,
      "format": {
        "kind": "number",
        "compact": true
      }
    },
    {
      "key": "total_obligated",
      "label": "Total obligated",
      "value": 2145000000,
      "format": {
        "kind": "currency",
        "currency": "USD",
        "compact": true
      }
    }
  ]
}

Related articles

• MCP tools: Review tool-specific aggregation keys and filter fields.
• Date filtering: Build date-bounded cohorts before rollups.
• Location filtering: Build location-scoped cohorts before rollups.
• Show stats display: Render KPI-style rollups from structured stat values.
• Show chart: Render standard trend, comparison, or leaderboard charts.