# Labor Ceiling Rate Benchmarks

`Labor_Ceiling_Rate_Benchmarks` queries labor ceiling-rate benchmark data for pricing and benchmark workflows.

## Purpose

Use this tool when an agent needs MAS labor ceiling-rate benchmarks, live filter discovery, or vendor / contract / labor-category comparisons that should stay separate from wage-based BLS analysis.

## When To Use

Typical questions this tool answers well:

* Which labor ceiling-rate benchmark rows match a labor category, vendor, contract number, or benchmark slice?
* Which worksite, business-size, education, SIN, category, or subcategory values are legal next steps for narrowing a ceiling-rate query?
* What current median, average, and percentile statistics exist for the current ceiling-rate result set?

## Output Contract

* Always returns:
  * `summary`
* `search` mode additionally returns:
  * `items`
  * `empty`
  * `aggregations` when explicitly requested through `fields_to_return` on direct single-request searches
* `filters` mode additionally returns:
  * `labor_categories`
  * `education_levels`
  * `worksites`
  * `business_sizes`
  * `security_clearances`
  * `sins`
  * `categories`
  * `subcategories`
  * `contract_years`

## Usage Notes

* Treat these rows as MAS not-to-exceed labor ceiling-rate benchmarks, not wages and not promised payable order rates.
* Start specific. Generic labor-category phrases can produce noisy comparisons that mix unlike services and contract contexts.
* If `search_by` is known, prefer it over broad keyword search:
  * `labor_category` for labor titles
  * `vendor_name` for vendor benchmark lookups
  * `contract_number` for exact contract references
* If fewer than 3 rows come back, broaden the labor-category phrase, widen `experience_range` or `price_range`, or remove a restrictive filter before drawing conclusions.
* If worksite is unknown and the user needs a conservative lower benchmark, start with `worksite: ["customer"]`.
* Use `fields_to_return` to drop bulky top-level sections like raw `aggregations` when they are not needed.
* In `search` mode, the default response already omits raw `aggregations`. Add `aggregations` to `fields_to_return` only for debugging or advanced post-processing.
* `filters` mode is the preferred way to discover legal `labor_category`, `worksite`, `business_size`, `security_clearance`, `sin`, `category`, and `subcategory` values before issuing a narrow `search` request.
* `security_clearance` remains discovery-driven. The live source values are inconsistent, so do not hardcode assumptions about its exact vocabulary.

## Field Meanings

* `benchmark_price`: The tool-selected ceiling-rate benchmark for the chosen `contract_year`.
* `benchmark_price_source`: Which raw field supplied `benchmark_price`: `current_price`, `next_year_price`, or `second_year_price`.
* `current_price`: Current contract-year ceiling rate returned by CALC+.
* `next_year_price`: Next contract-year ceiling rate when available.
* `second_year_price`: Following contract-year ceiling rate when available.
* `summary.result_count`: Count of matching rows from the CALC+ stats aggregation.
* `summary.average_price`: Mean ceiling rate for the current query.
* `summary.median_price`: Median ceiling rate for the current query.
* `summary.percentiles`: Percentile values returned by CALC+.

## Examples

Broad labor-category discovery:

```json
{
  "mode": "filters",
  "keyword": "program manager"
}
```

Specific labor-category benchmark with canonical filters:

```json
{
  "mode": "search",
  "keyword": "Program Manager",
  "search_by": "labor_category",
  "contract_year": "next",
  "worksite": ["contractor"],
  "business_size": ["small_business"],
  "fields_to_return": ["items", "summary"],
  "item_fields_to_return": [
    "_id",
    "labor_category",
    "benchmark_price",
    "benchmark_price_source",
    "vendor_name",
    "idv_piid",
    "schedule"
  ],
  "ordering": "current_price",
  "sort": "asc"
}
```

Broad benchmark scan with raw aggregations explicitly requested:

```json
{
  "mode": "search",
  "price_range": {
    "min": 15,
    "max": 500
  },
  "fields_to_return": ["items", "aggregations", "summary", "empty"]
}
```

Search by GovTribe vendor entity rather than a hand-typed vendor keyword:

```json
{
  "mode": "search",
  "vendor_ueis": ["<vendor_uei>"],
  "worksite": ["contractor"],
  "fields_to_return": ["items", "summary", "empty"],
  "item_fields_to_return": ["_id", "labor_category", "benchmark_price", "vendor_name", "idv_piid"]
}
```

Search by GovTribe MAS IDV entity ids for exact contract benchmarks:

```json
{
  "mode": "search",
  "federal_contract_idv_ids": ["<govtribe_federal_contract_idv_id>"],
  "contract_year": "next",
  "fields_to_return": ["items", "summary"]
}
```


---

# 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/tools/labor-ceiling-rate-benchmarks.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.