Skip to main content
Glama
cliwant

mcp-sam-gov

by cliwant
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

bls_qcew

Read-only

Retrieve BLS QCEW quarterly employment, wages, and location quotients by county or NAICS industry for market analysis.

Instructions

BLS QCEW (Quarterly Census of Employment & Wages) — county×NAICS market-size / wages / location-quotient (keyless; data.bls.gov/cew Open Data Access CSV, un-rate-limited). Inputs: mode (REQUIRED {area,industry}); area (area_fips ^[0-9A-Za-z]{1,6}$ — REQUIRED for mode=area); industry (NAICS ^[0-9]{1,6}$ DIGIT-ONLY — REQUIRED for mode=industry; hyphenated 31-33 404s, use digit aggregate); year (REQUIRED), quarter (REQUIRED 1|2|3|4); client-side ownership/aggregationLevel/sizeCode; limit/offset. Returns { found, mode, rows:[{ area_fips, own_code, industry_code, agglvl_code, size_code, base:{disclosed, disclosureCode, qtrly_estabs, month1/2/3_emplvl, total_qtrly_wages, taxable_qtrly_wages, qtrly_contributions, avg_wkly_wage}, locationQuotient:{disclosed, disclosureCode, lq_…}, overTheYear:{disclosed, disclosureCode, oty_…} }] }. ★DISCLOSURE HONESTY: each row has three disclosure codes (base/lq/oty). QCEW encodes SUPPRESSED values as literal 0 — under 'N': confidential emplvl/wage/avg-wkly → null (WITHHELD), estab count + oty-estab change stay DISCLOSED; under '-': WHOLE block → null; under blank: genuine reported/NEGATIVE 0 SURVIVES. NEVER blanket 0→null; null carries disclosed:false + raw disclosureCode; suppression note fires on any suppressed row. HONESTY: totalAvailable is EXACT filtered row count (fetch-once; QCEW does not paginate); per-tuple HTTP 404 → honest empty; 5xx/timeout THROW; 200 non-CSV/renamed header/wrong field-count → schema_drift THROW. Do-NOT-sum-across-agglvl/ownership note rides every response.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
areaNoThe area_fips (^[0-9A-Za-z]{1,6}$): county 01005, statewide 01000, national US000, MSA C1018, CSA CS122. REQUIRED when mode=area (the path segment). When mode=industry it is an OPTIONAL client-side narrow (keep only rows for this area_fips).
modeYesREQUIRED — the slice shape: 'area' (all industries × ownership × aggregation levels for ONE area_fips) or 'industry' (all areas for ONE NAICS). A fixed enum interpolated as a LITERAL path segment.
yearYesREQUIRED — the 4-digit year (1990..2027). QCEW Open Data coverage begins ~1990; a pre-coverage or future year is an honest per-tuple HTTP 404 (found:false), NOT zero establishments.
limitNoRows per page (CLIENT-SIDE window over the fetched-once slice), 1..1000, default 50.
offsetNo0-based row offset for CLIENT-SIDE pagination over the filtered set (QCEW has no server-side pagination), default 0.
quarterYesREQUIRED — the quarter '1'|'2'|'3'|'4' (all four live-servable). The annual 'a' is not enabled this build.
industryNoThe NAICS code (DIGIT-ONLY ^[0-9]{1,6}$): 5415, or the aggregate 10. REQUIRED when mode=industry (the path segment). When mode=area it is an OPTIONAL client-side narrow (keep only rows for this NAICS). A hyphenated NAICS supersector (31-33, 44-45) 404s on QCEW — pass its digit aggregate code, never the hyphenated form.
sizeCodeNoOptional CLIENT-SIDE filter on size_code.
ownershipNoOptional CLIENT-SIDE filter on own_code (e.g. 0=Total, 1=Federal, 2=State, 3=Local, 5=Private). Never on the URL (no SSRF surface).
aggregationLevelNoOptional CLIENT-SIDE filter on agglvl_code (e.g. 70=total-all-industries, 78=6-digit-NAICS-by-ownership). Filter to ONE agglvl_code for a coherent, non-double-counted total.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.12.0

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Exceptional disclosure beyond the readOnlyHint/openWorldHint annotations. It explains the QCEW suppression semantics (literal-0 encoding, 'N' vs '-' vs blank handling, never blanket 0→null), exact error behavior (404→honest empty, 5xx/timeout→throw, schema_drift→throw), and the fetch-once pagination model. This goes far beyond the annotations' low burden.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long and dense, but nearly every sentence earns its place given the tool's complexity — the 0→null disclosure trap, pagination honesty, and NAICS edge case are genuinely load-bearing for correct invocation. It is front-loaded with the identifying purpose. The formatting is a wall of text rather than structured sections, which keeps it from a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter tool with no output schema, this is exceptionally complete: it describes the return shape, the three disclosure codes per row, pagination semantics, error behaviors, and required/optional routing. Nothing an agent needs to call it correctly is missing; the complexity is fully matched.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Though schema coverage is 100% (baseline 3), the description adds high-value semantics: cross-conditional requirements (area REQUIRED for mode=area, industry REQUIRED for mode=industry), the hyphenated-NAICS trap, ownership code mappings (0/1/2/3/5), and the anti-double-counting guidance for aggregationLevel. It materially improves parameter understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a precise statement of function — 'county×NAICS market-size / wages / location-quotient' — naming the resource (BLS QCEW), the data product, and the data source. The two slice shapes (area/industry) are spelled out, making it instantly distinguishable from sibling bls_timeseries and bls_oews_wages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides extensive when-to-use guidance nested in the parameter rules: when mode=area vs mode=industry, year coverage window, the explicit NAICS hyphenation pitfall ('31-33 404s'), and the aggregationLevel advice to filter to one agglvl_code. It lacks explicit exclusions naming alternatives, but the mode/parameter routing is thorough enough to qualify as clear context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools