Skip to main content
Glama
cliwant

mcp-sam-gov

by cliwant
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

census_business_patterns

Read-only

Get US business statistics—establishments, employment, and annual payroll—by NAICS industry and geography (US, state, or county) from Census County Business Patterns to size markets.

Instructions

Market sizing by NAICS × geography — establishments, employment, and annual payroll from the US Census County Business Patterns (CBP) API (api.census.gov/data/{year}/cbp). ★REQUIRES a free CENSUS_API_KEY: the Census Data API has NO keyless tier, so without the key this tool THROWS an honest config error (get one at https://api.census.gov/data/key_signup.html; call api_key_status to check). Input: optional naics (2–6 digit NAICS-2017, e.g. '5415'; omit to aggregate all sectors), geography (us|state|county, default us; county REQUIRES state), state (2-digit FIPS, e.g. '06'), year (default '2023'), optional limit (client-side top-N). Returns { rows:[{ name, geoId, naicsCode, naicsLabel, establishments, employees, annualPayrollUsd, state }] } + honest _meta. HONESTY: establishments/employees are integer counts and annualPayrollUsd is annual US dollars (×1000 from source's $1,000-unit PAYANN); large-negative suppression sentinels map to null — NEVER a negative number and NEVER 0 (genuine 0 stays 0; CBP primarily uses noise-infusion + suppression flags, surfaced as reported); geoId/naicsCode/state are STRINGS (leading zeros survive). CBP returns the COMPLETE geography set (no pagination) → totalAvailable = row count, complete:true. Missing/invalid key → invalid_input (302 to Missing-Key page); header-only body → honest empty; 5xx → THROWS; 200 non-JSON → schema_drift. Key rides ONLY in the &key= query param.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
yearNoThe CBP data year (default '2023', the latest published vintage — CBP is released with a ~2-year lag). Validated ^\d{4}$ (it rides in the request path).
limitNoOPTIONAL client-side top-N cap on the returned rows. CBP has NO server-side pagination, so this slices AFTER the full set is fetched and DISCLOSES the omission (totalAvailable stays the full count). Omit to return every matching row.
naicsNoA NAICS-2017 code (2–6 digits), e.g. '5415' (Computer Systems Design & Related Services) or '54' (Professional/Scientific/Technical). Omit to aggregate across all sectors. Validated ^\d{2,6}$.
stateNoA 2-digit state FIPS code, e.g. '06' (California), '48' (Texas). Optional filter for geography='state'; REQUIRED for geography='county' (the CBP `in=state:` predicate). Validated ^\d{2}$.
geographyNoThe geography level (default 'us'). 'state' returns one row per state (or a single state when `state` is given); 'county' returns every county in a state and REQUIRES `state`.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.12.0

TDQS

A4.5/5.0
Behavior5/5

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

Annotations provide readOnlyHint=true and openWorldHint=true, but the description goes far beyond by dislosing: the tool throws config errors without key, honest handling of missing/invalid keys (invalid_input with 302), mapping of suppression sentinels to null (never negative or 0), that results are complete (no pagination), and potential schema_drift on non-JSON responses. It also clarifies that the key rides only in query param. This is exemplary behavioral disclosure, far exceeding what annotations convey.

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

Conciseness3/5

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

The description is information-dense but somewhat lengthy, with multiple clauses and parenthetical explanations. While it front-loads key requirements (API key) and facts, it could be tightened without losing clarity. It is not excessively wordy given the complexity, but it is not as crisp as it could be.

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?

Given the tool's complexity (5 params, no output schema, external API quirks), the description covers all critical operational details: key requirement, error handling, data format nuances, pagination absence, and parameter dependencies. An agent can confidently and correctly invoke the tool with this description alone. Nothing critical is missing.

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

Parameters3/5

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

Schema description coverage is 100% and each parameter's description is thorough, including validation and required relationships. The tool description adds value by giving examples (e.g., '5415') and clarifying optionality, but the schema already carries the essential meaning. Since coverage is high, baseline 3 is appropriate; the description slightly enhances but does not need to compensate.

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?

The description states a specific verb ('market sizing'), a clear resource (Census CBP data by NAICS and geography), and lists the output fields. It distinguishes itself from sibling tools like census_geocode_address and census_geographies_by_coordinates by focusing on business patterns data. It fully communicates what the tool does.

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

Usage Guidelines5/5

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

The description explicitly explains when to use the tool (market sizing) and provides critical usage context: mandatory API key, no keyless tier, where to get the key, how to check key status, and details for each parameter (e.g., county requires state, NAICS optional). It effectively guides the agent on when to invoke this tool versus others.

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