# BLS Occupational Wage Data

`BLS_Occupational_Wage_Data` queries GSA CALC+ BLS occupational wage data for pricing workflows.

## Purpose

Use this tool when an agent needs wage-rate benchmarks, live filter discovery, or area/industry narrowing data that can be turned into pricing-model inputs.

## When To Use

Typical questions this tool answers well:

* Which BLS occupational wage rows match a labor category, geography, industry, or level?
* Which occupation, state, industry, or area filter values are legal next steps for narrowing a query?
* What current median or wage-stat summary data exists for a given slice of the CALC+ dataset?

## Required Reading

## Output Contract

* Always returns:
  * `summary`
* `search` mode additionally returns:
  * `items`
  * `empty`
  * `aggregations` when explicitly requested through `fields_to_return`
* `filters` mode additionally returns:
  * `occupation_names`
  * `occupation_codes`
  * `occupation_levels`
  * `states`
  * `industries`
  * `areas`
  * `modeling_presets`

## Usage Notes

* Start broad, inspect the returned filters, then narrow using the exact values the API returns.
* Use `keyword` as the occupation anchor. This is the most reliable way to search by BLS title or SOC code in the current CALC+ API.
* Treat wage rows as unburdened labor-rate inputs, not fully burdened bill rates or awarded prices.
* Use `fields_to_return` to drop bulky top-level sections like raw `aggregations` or `modeling_presets` when they are not needed.
* In `search` mode, the default response already omits raw `aggregations`. Add `aggregations` to `fields_to_return` only when you need the raw CALC+ bucket payload for debugging or advanced post-processing.
* Use `item_fields_to_return` in `search` mode to keep only the row attributes needed for the current pricing step.
* `filters` mode is the preferred way to discover legal `occupation_name`, `industry_code`, `area_name`, and `normalized_area_name` values before issuing a narrow `search` request.
* Location plus industry constraints matter. The CALC+ user guide states that BLS data for specific industry NAICS codes is not available for specific locations such as MSA and state; use `000000` / `All Industries` when narrowing to a specific state or area unless you have evidence otherwise.
* Areas are query-scoped. Cross-state metros only appear when the backend returns them for the current query, so do not assume every metro that touches a state will appear in every state-scoped result set.

## Search Semantics

* CALC+ search is BLS-taxonomy driven, not a synonym engine for business titles.
* Exact BLS titles such as `Project Management Specialists` work well as `keyword` values.
* Broader fragments such as `project` or `operations` are useful for discovery.
* User phrasing like `Senior Program Manager` may legitimately return zero rows even when a close BLS proxy title exists.

## Field Meanings

* `rate`: The CALC+ price field shown in the results table. This is the field used for median and average pricing summaries.
* `h_mean`: Local hourly mean wage for the returned geography and occupation.
* `h_median`: Local hourly median wage for the returned geography and occupation.
* `national_h_mean`: National hourly mean wage for the same occupation.
* `national_h_median`: National hourly median wage for the same occupation.
* `areatype_code`: CALC+ geography-type code. Treat this as backend geography metadata rather than a user-facing filter.
* `summary.median_price`: Median of the returned `rate` values.
* `summary.wage_stats`: Raw CALC+ stats aggregation over the returned `rate` values.

## Examples

Discover likely BLS proxy titles for a user-friendly role label:

```json
{
  "mode": "filters",
  "keyword": "program manager",
  "state_name": ["Virginia"]
}
```

Narrow a discovered BLS title to Virginia senior rows:

```json
{
  "mode": "search",
  "keyword": "Project Management Specialists",
  "occupation_level": ["Senior"],
  "state_name": ["Virginia"],
  "fields_to_return": ["items", "summary"],
  "item_fields_to_return": ["_id", "occupation_name", "occupation_level", "state_name", "rate", "h_median"],
  "ordering": "rate",
  "sort": "asc"
}
```

Use GovTribe NAICS entity ids as an industry filter bridge:

```json
{
  "mode": "search",
  "keyword": "Project Management Specialists",
  "state_name": ["Virginia"],
  "naics_category_ids": ["<govtribe_naics_category_id>"],
  "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/bls-occupational-wage-data.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.