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
• 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.

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
}

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.