# 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
{
  "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
{
  "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
{
  "award_date_range": {
    "from": "now-12M/d",
    "to": "now/d"
  },
  "set_aside_types": ["Total Small Business"],
  "aggregations": ["top_awardees_by_dollars_obligated"]
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.govtribe.com/user-guide/mcp/guides/aggregation_and_leaderboard_guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.