# Aggregation\_and\_Leaderboard\_Guide

## Purpose

Use this guide to produce counts, percentages, top-N lists, and distribution views from supported search tools. Use it when:

* users ask for percentages, totals, rankings, or breakdowns by agency/vendor/category.
* users ask for dashboard-like rollups from filtered result sets.
* users need numerator/denominator logic for ratio calculations.

## Construction Rules

* Aggregation-driven analysis should use the default keyword behavior. Do not send `search_mode` unless you need a non-default mode.
* Keep aggregation requests focused:
  * one question per call when possible.
  * include only filters needed to define the cohort.
* Apply filters before aggregation:
  * agency, vendor, NAICS/PSC, location, set-aside, and date ranges.
* For percentages, run two consistent cohorts:
  * denominator: full scoped population.
  * numerator: same scope plus the qualifying condition.
* Keep aggregation names explicit and stable for downstream reporting.

## Examples

Top awardees by dollars obligated for a scoped window: Tool: `Search_Federal_Contract_Awards`

```json
{
  "query": "",
  "award_date_range": {
    "from": "now-2y/d",
    "to": "now/d"
  },
  "naics_category_ids": ["541512"],
  "aggregations": ["top_awardees_by_dollars_obligated"]
}
```

Count-style breakdown by agency in one category: Tool: `Search_Federal_Contract_Opportunities`

```json
{
  "query": "",
  "posted_date": {
    "from": "now-12M/d",
    "to": "now/d"
  },
  "naics_category_ids": ["541611"],
  "aggregations": ["top_federal_agencies_by_doc_count"]
}
```

Numerator cohort for percentage calculation: Tool: `Search_Federal_Contract_Awards`

```json
{
  "query": "",
  "award_date_range": {
    "from": "now-12M/d",
    "to": "now/d"
  },
  "set_aside_types": ["Total Small Business"],
  "aggregations": ["top_awardees_by_dollars_obligated"]
}
```