BLS OEWS

Look up a federal entity by its Unique Entity ID (UEI). Returns the full entity record from SAM.gov Entity Management v3. The UEI is a 12-character alphanumeric identifier assigned by SAM.gov. include_sections controls response size: - entityRegistration: UEI, CAGE, name, status, activation/expiration dates (ALWAYS include) - coreData: addresses, POCs at high level, business types, hierarchy - assertions: NAICS and PSC codes (in goodsAndServices subsection) - pointsOfContact: detailed POC records (name, title, address; email/phone FOUO only) - repsAndCerts: FAR/DFARS certification responses (must be explicitly requested) - integrityInformation: FAPIIS proceedings data (must be explicitly requested) - All: entityRegistration + coreData + assertions + pointsOfContact (but NOT repsAndCerts/integrityInformation) Default: entityRegistration + coreData. Always include entityRegistration alongside any other section or the response loses entity identification. sam_registered='Yes' (default) returns only fully registered entities. Use 'No' to find entities with a UEI assigned but incomplete registration.

Look up a federal entity by its CAGE code. CAGE (Commercial and Government Entity) codes are 5-character alphanumeric identifiers assigned by DLA. Useful when you have a CAGE but no UEI.

Search SAM.gov entities with flexible filters. All filters are AND-ed together. Returns paginated results; note that Entity Management has a HARD CAP of 10 records per page (size <= 10). For more results, increment 'page' and make multiple calls. Key filter notes: - legal_business_name does partial matching with no relevance ranking. Cannot contain & or parentheses (API strips them, returns 0 results). For exact lookup use UEI or CAGE. - primary_naics matches the entity's designated primary NAICS only. - any_naics matches any NAICS the entity has on file. - business_type_code uses codes like QF (SDVOSB), A2 (Women-Owned), 8W (WOSB), 23 (Minority-Owned). SDVOSB is NOT XS (that's S-Corp). - state_code is 2-letter USPS. - purpose_of_registration: Z1=Federal Assistance only, Z2=All Awards, Z5=Supplemental grants only. - free_text (q parameter) ANDs multiple words together. "cybersecurity cloud" returns entities matching BOTH words, not either. Default registration_status is 'A' (Active); use 'E' for expired registrations.

Fetch FAR/DFARS representations and certifications for an entity by UEI. repsAndCerts is NOT included in the default response or even in includeSections=All. It must be explicitly requested. Returns the entity's responses to standard FAR 52.212-3, FAR 52.204-17, FAR 52.209-2, FAR 52.219-1, FAR 52.222-18, FAR 52.225-2, DFARS 252.204-7016, and other certification clauses. Combined with entityRegistration for identification context. Parameters: - summary_only (default True): returns a condensed view (clause ID, title, and answer summary per clause) instead of the full certification text. The full repsAndCerts payload for a large entity can exceed 70KB, which blows the MCP response budget. Set False to get the raw response. - clause_filter: list of FAR/DFARS clause identifiers to include (e.g. ['FAR 52.204-17', 'FAR 52.219-1']). Case-insensitive substring match. Combines with summary_only.

Fetch FAPIIS proceedings integrity information for an entity by UEI. integrityInformation is NOT included in the default response or even includeSections=All. Requires explicit request plus proceedingsData=Yes query parameter. Returns proceedings disclosures per FAR 52.209-7/9.

Check if an entity has any exclusion/debarment records by UEI. Returns exclusion records from the consolidated Excluded Parties List. totalRecords=0 means the entity is not currently excluded. totalRecords>0 means one or more exclusion records exist; check recordStatus='Active' on each entry to determine if the exclusion is currently in effect. This is the single most important check for FAR 9.104-1 responsibility determinations and FAR 9.405 debarment prohibitions.

Search SAM.gov exclusion records with flexible filters. All filters are AND-ed. Unlike Entity Management, Exclusions uses 'size' (not 'limit') for pagination. Size can go up to 100 per page. Key filter notes: - entity_name: firm name for classification=Firm; for individuals use the full name. Cannot contain &, |, {, }, ^, backslash. - cage_code: 5-character CAGE of the excluded entity. - classification: Firm, Individual, Vessel, or Special Entity Designation. - exclusion_program: Reciprocal (cross-agency), NonProcurement, or Procurement. - excluding_agency_code: agency code that imposed the exclusion (e.g., DOD, HHS). - country: MUST be 3-character ISO alpha-3 (USA, CAN, GBR). 2-char codes (US, CA, GB) return 0 results. - activation_date_range: use bracket format [MM/DD/YYYY,MM/DD/YYYY]. - free_text (q parameter): supports wildcards (*), AND, OR operators. Example: "acme*" matches any company starting with acme.

Search contract opportunities on SAM.gov. posted_from and posted_to are MANDATORY. Format is MM/DD/YYYY (not ISO 8601). The date range cannot exceed 364 days. For older notices or longer ranges, chain multiple calls with sequential date windows. Notice type codes: - p = Presolicitation - o = Solicitation - k = Combined Synopsis/Solicitation - r = Sources Sought - s = Special Notice - i = Intent to Bundle - a = Award Notice - u = Justification (J&A) - g = Sale of Surplus Property WORKING filters: title, solicitation_number, notice_id, notice_type, naics_code, psc_code, set_aside, state, zip_code, response_deadline_from, response_deadline_to. BROKEN filters (do not use): deptname, subtier. The SAM.gov API silently ignores these. To filter by agency, use agency_keyword — this tool will post-filter the results by checking fullParentPathName for a substring match. PSC code filter (psc_code) requires exact 4-character match. Prefix matching (e.g. 'R4') returns 0 results; use 'R425'. Set-aside codes: SBA, SBP, 8A, 8AN, HZC, HZS, SDVOSBC, SDVOSBS, WOSB, WOSBSS, EDWOSB, EDWOSBSS, VSA, VSS. The 'description' field in each result is a URL, not inline text. Use get_opportunity_description() to fetch the actual description HTML.

Fetch the full description text for a contract opportunity by notice ID. The 'description' field in search_opportunities results is a URL, not inline text. This tool handles the second fetch to retrieve the actual HTML description. Pass the noticeId from the search results.

Look up a Product/Service Code (PSC) by its code value. Returns the PSC name, full name, level 1 and level 2 category information, and includes/excludes guidance. Useful for validating PSC codes before using them as filters in other searches.

Free-text search for Product/Service Codes (PSC). Searches across PSC names, descriptions, and category hierarchy. Returns matching PSC codes with full context. Useful for discovering PSCs from plain-language descriptions like 'engineering' or 'application development'.

Search contract award records on SAM.gov (FPDS replacement). This is the replacement for FPDS.gov (decommissioned Feb 2026). Same data, new endpoint. Uses limit/offset pagination (NOT page/size). CRITICAL date format: MM/dd/yyyy for single dates, [MM/dd/yyyy,MM/dd/yyyy] for ranges (brackets included). ISO 8601 dates are rejected. Boolean operators: use ~ for OR (e.g. naics_code="541512~541511"), use ! for NOT (e.g. extent_competed_code="!A"). Key parameters: - awardee_name: awardeeLegalBusinessName (partial match). NOT "vendorName". - awardee_uei: awardeeUniqueEntityId (exact match) - awardee_cage_code: awardeeCageCode (exact match) - piid: Procurement Instrument Identifier. Returns all mods for that PIID. - naics_code: 6-digit NAICS. Supports ~ for OR, ! for NOT. - psc_code: Product/Service Code (4-char). Supports ~ for OR. - contracting_department_code: top-level department (e.g. "9700" for DoD) - contracting_subtier_code: subtier agency (e.g. "1700" for Navy) - contracting_office_code: contracting office (e.g. "N00039") - date_signed: date of award action. MM/dd/yyyy or [MM/dd/yyyy,MM/dd/yyyy] - last_modified_date: when record was last modified. Same format. - fiscal_year: filter by FY (e.g. "2026") - award_or_idv: "AWARD" for contracts/orders, "IDV" for indefinite-delivery vehicles - type_of_contract_pricing_code: J=FFP, U=CPFF, etc. - type_of_set_aside_code: SBA, 8A, HZC, SDVOSBC, etc. - extent_competed_code: A=Full, B=Not Available, CDO=Competed Under SAP, etc. - dollars_obligated: bracket range [min,max] as string - modification_number: "0" for base award, specific mod number, or range - free_text: q parameter for full-text search across all fields - include_sections: comma-separated: contractId, coreData, awardDetails (default: all) - limit: max records per page (1-100, default 10) - offset: 0-based record skip count for pagination Returns normalized response with awardSummary list and totalRecords count. Each record has up to 3 sections: contractId, coreData, awardDetails.

Look up all contract award modifications for a single PIID. Returns all modification records for the given Procurement Instrument Identifier, sorted by modification number. This is the primary way to get the full history of a contract action. PIIDs are alphanumeric identifiers assigned by the contracting office. Format varies by agency (e.g. "GS-35F-0119Y", "W912BV22P0112", "N0003925F7516"). The search is exact match. include_sections: comma-separated list of contractId, coreData, awardDetails. Defaults to all sections if not specified. Returns normalized response with awardSummary list containing all modifications. Check totalRecords for the number of mods found.

Search contract award records that have been deleted from FPDS/SAM.gov. Uses the same Contract Awards endpoint with deletedStatus=Y. Deleted records are removed from normal search results but remain accessible through this parameter. Useful for audit trails and historical research. Supports the same date format as search_contract_awards: MM/dd/yyyy or [MM/dd/yyyy,MM/dd/yyyy] for ranges. limit: 1-100 (default 10). offset: 0-based pagination.

Composite pre-award vendor responsibility check per FAR 9.104-1. Performs TWO API calls in sequence: 1. Entity Management lookup (registration status, business types, CAGE, activation/expiration dates, exclusion flag on the entity record) 2. Exclusions lookup (active debarment/suspension records) Returns a structured summary with: - registration: full registration details or None if not registered - exclusion: exclusion record count and active exclusion details - flags: list of responsibility concern flags Flag meanings: - NOT_REGISTERED: entity has no SAM registration (cannot receive award per FAR 4.1102) - REGISTRATION_NOT_ACTIVE: registration expired or inactive - EXCLUSION_FLAG_ON_ENTITY: entity record indicates exclusion exists - ACTIVE_EXCLUSION_FOUND: confirmed active exclusion (FAR 9.405 prohibits award) No flags = clear for responsibility determination.

Search the SAM.gov Federal Hierarchy. Returns federal organizations (departments, agencies, sub-agencies, offices) with their FH IDs, codes, hierarchical relationships, and status. Useful for normalizing agency names to canonical FH IDs before passing them to Contract Awards, Opportunities, or Subaward searches. Filter notes: - fh_org_id: exact lookup by Federal Hierarchy organization ID (numeric). - fh_org_name: partial substring match on the organization name. - fh_org_type: case-insensitive substring filter. Live values from the API look like 'Department/Ind. Agency', but the API also accepts shorthand like 'DEPARTMENT' or 'AGENCY' and matches loosely. Pass whatever the response showed, or one of: department, agency, sub-agency, office, major command, field activity. - status: ACTIVE (default if filter omitted), INACTIVE (retired), or MERGED. Live audit (April 2026): the API defaults to ACTIVE-only when no filter is sent, so passing status='ACTIVE' is a no-op vs. the unfiltered call. Pass 'INACTIVE' to expand the search to retired orgs. - agency_code: legacy agency code if known. - cgac: Common Government-wide Accounting Classification (Treasury) code. Pagination uses limit (1-100) / offset (0-based). The Federal Hierarchy API uses lowercase 'totalrecords' and 'orglist' in responses (unlike the camelCase used elsewhere in SAM.gov); the normalizer preserves both keys.

Get the immediate child organizations of a federal organization. Pass an FH org ID (use search_federal_organizations to find one) and receive the list of its direct subordinates. To traverse the full tree, call recursively on each child. Pagination uses limit (1-100) / offset.

Search FFATA subcontract reports (acquisition subawards). These are subcontracts reported by prime contractors under the Federal Funding Accountability and Transparency Act. Use this to map prime contractors to their subs, see subcontract values, and identify the full distribution of a federal procurement dollar. CRITICAL: dates use ISO yyyy-MM-dd format (NOT MM/dd/yyyy like the rest of SAM.gov). Pagination uses pageNumber/pageSize (NOT limit/offset). Key filters: - prime_contract_key: business key for subawards under a prime - piid: Procurement Instrument ID of the prime contract (returns all subs) - referenced_idv_piid: prime contract family identifier (parent IDV) - referenced_idv_agency_id: agency on the parent IDV - agency_id: numeric agency identifier on the prime - prime_award_type: type of the parent prime award - from_date / to_date: yyyy-MM-dd window (filters on subaward report date) - status: 'Published' (default) or 'Deleted' for audit trails - page_number: 0-based page index - page_size: 1-1000, default 100 Response: {totalPages, totalRecords, pageNumber, nextPageLink, previousPageLink, data: [...]}.

Get rate distribution and statistics for a specific SIN. Returns rate statistics, education breakdown, business size breakdown, and sample records for a GSA MAS Special Item Number. Common SINs for professional services: - 54151S: IT Professional Services - 541611: Management and Financial Consulting - 541715: Engineering R&D - 541330ENG: Engineering Services - 541512: Computer Systems Design - 611430: Training

Search FFATA grant subaward reports (financial assistance subawards). These are subawards reported by prime grant recipients on cooperative agreements and grants. Use this to trace federal grant funds from prime recipient down to subrecipients. CRITICAL: dates use ISO yyyy-MM-dd format (NOT MM/dd/yyyy). Pagination uses pageNumber/pageSize. Key filters: - prime_award_key: business key identifying subawards under a prime grant - fain: Federal Award Identification Number for grants - agency_code: numeric agency identifier on the prime - from_date / to_date: yyyy-MM-dd window - status: 'Published' (default) or 'Deleted' - page_number: 0-based page index - page_size: 1-1000, default 100

Look up federal per diem rates for a city and state. Returns lodging rates (monthly breakdown for seasonal locations) and M&IE (meals and incidental expenses) for the specified fiscal year. state: 2-letter USPS code (e.g., 'DC', 'VA', 'MD', 'CA'). fiscal_year: defaults to current FY. FY runs Oct 1 - Sep 30, so FY2026 = 2025-10-01 through 2026-09-30. The API uses prefix matching on city names, which can return multiple entries. This tool auto-selects the best match: 1. Exact city name match 2. Composite NSA name containing the city (e.g., 'Boston' matches 'Boston / Cambridge') 3. First non-standard rate entry 4. Standard rate as fallback Apostrophes and hyphens in city names are auto-replaced with spaces (GSA API quirk). Keep periods for 'St.' prefix cities (St. Louis). For DC: query city='Washington', state='DC'.

Look up federal per diem rates by ZIP code. May return multiple entries (NSA + standard rate). This tool auto-selects the NSA rate over the standard rate. Useful when the exact city name is uncertain but the ZIP is known. Accepts 5-digit ZIPs or ZIP+4 (e.g., '02101' or '02101-1234').

Get all Non-Standard Area (NSA) per diem rates for a state. Returns every city/county with rates above the standard rate in that state. Useful for comparing rates across cities within a state or for building a travel IGCE with multiple destinations.

Get the M&IE (meals and incidental expenses) tier breakdown table. Returns all M&IE tiers with breakfast, lunch, dinner, incidental, and first/last day (75%) amounts. Use this to show the meal component breakdown when presenting per diem estimates. M&IE does NOT vary seasonally (unlike lodging). The tier is set per location and applies year-round.

Estimate total per diem cost for a trip. Calculates lodging + M&IE for the specified number of nights. First and last travel days use 75% M&IE per 41 CFR 301-11.101. travel_month: 3-letter abbreviation (Jan, Feb, ..., Dec). If omitted, uses the max monthly lodging rate (conservative estimate for IGCE). Does NOT include airfare or ground transportation. Add those separately. Formula: - Lodging = nightly_rate * num_nights - M&IE = full_day_rate * (travel_days - 2) + first/last_day_rate * 2 - Travel days = num_nights + 1 num_nights bounded 1-365. A single trip longer than a year is unlikely to be covered by per diem.

Compare per diem rates across multiple locations. locations: list of {"city": "...", "state": "XX"} dicts, max 25 entries (DEMO_KEY limits you to ~10 req/hr so this is generous). Returns rates sorted by max daily total (highest first). Useful for travel IGCE development when comparing destination costs.

Search Regulations.gov documents (proposed rules, final rules, notices). Filter values are CASE-SENSITIVE. Use exact casing: - document_type: 'Proposed Rule', 'Rule', 'Notice', 'Supporting & Related Material', 'Other' - Lowercase values silently return 0 results (no error) Key parameters: - agency_id: FAR, DARS, GSA, SBA, OFPP, DOD, NASA, VA, etc. Empty string is REJECTED (previously returned all 1.95M records). - docket_id: e.g., 'FAR-2023-0008' for a specific FAR case - within_comment_period: True to find documents currently accepting comments - posted_date_ge/le: YYYY-MM-DD format (calendar-checked) - comment_end_date_ge/le: YYYY-MM-DD format Response includes meta.aggregations with counts by document type, agency, and comment period status. Page size: 5-250. page_number: 1-20 (API caps total results at ~5,000). For larger sets, use date ranges to partition. sort: '-postedDate' (newest first, default), 'postedDate', '-commentEndDate', 'lastModifiedDate', 'title', 'documentId'.

Get full details for a single Regulations.gov document. Returns fileFormats (download URLs), cfrPart, displayProperties, and other detail fields not available in search results. Set include_attachments=True to get attachment objects with download URLs. document_id format: FAR-2023-0008-0023

Search public comments on Regulations.gov. To find comments on a specific document, use comment_on_id with the hex objectId from document search results (NOT the human-readable documentId). docket_id can also filter comments to all documents in a docket. Page size: 5-250. Comments sorted by '-postedDate' by default.

Get full details for a single comment. Returns the full comment text, organization, submitter info (if public), tracking number, and duplicate comment count. Some fields (firstName, lastName, organization) are agency-configurable and may be hidden.

Search Regulations.gov dockets. Dockets are containers for related regulatory documents (proposed rules, comments, supporting materials). FAR cases, DFARS cases, and agency rulemaking actions each have a docket. docket_type is CASE-SENSITIVE: 'Rulemaking' or 'Nonrulemaking'. lastModifiedDate format: 'YYYY-MM-DD HH:MM:SS' (space-separated, NOT ISO). This is a Regulations.gov quirk; ISO 8601 is rejected. Limited filters: only searchTerm, agencyId, docketType, lastModifiedDate.

Get full details for a single docket. Returns title, abstract, RIN (links to Unified Agenda), agency, keywords, and modification date. docket_id format: FAR-2023-0008, DARS-2025-0071, SBA-2024-0002

Find documents with currently open comment periods. Searches for documents where withinCommentPeriod=true, sorted by soonest closing deadline. Returns document IDs, titles, agencies, comment end dates, and docket IDs. Default searches FAR, DARS, GSA, SBA, OFPP, DOD, NASA, VA. Pass agency_ids to narrow or expand the scope. An empty list is rejected; pass None to use the defaults.

Get the full lifecycle of a FAR/DFARS rulemaking case. Fetches the docket metadata (title, abstract, RIN) plus all documents filed under the docket, sorted by most recent first. docket_id examples: FAR-2023-0008, DARS-2025-0071 Returns the docket abstract, RIN (links to Unified Agenda), and all documents with their types, dates, and URLs.

Get full details for a single Federal Register document by number. Returns all available fields including full text URLs, docket info, RIN details, page views, topics, corrections, and CFR references. Document numbers look like '2026-03065' or 'C1-2026-01234' (corrections).

Fetch multiple documents in one call (up to ~20). Pass a list of document numbers. More efficient than individual calls.

Get document counts grouped by type, agency, or topic. Accepts the same filter conditions as search_documents. Returns aggregated counts without individual document results. Useful for understanding the volume of rulemaking by agency or type within a date range before drilling into specific documents. At least one filter (agencies, doc_types, term, or pub_date_gte/lte) is required. An unfiltered facet query returns the entire all-time aggregate.

Get current public inspection documents (pre-publication). Public inspection documents are FR documents filed for publication but not yet published. Updated business days only. The PI endpoint does NOT support server-side filtering. This tool fetches all current PI documents and filters client-side by agency slug and/or keyword in the title. Useful for getting early notice of upcoming regulatory actions. Parameters: - agency_filter: substring match against each document's agency slugs - keyword_filter: substring match against document titles - limit: max documents returned after filtering (default 50, max 500). Unfiltered dumps can exceed 170KB; narrow with filters or raise the cap.

List agencies with their IDs, names, slugs, and parent agencies. Use the 'slug' values with search_documents() and other tools. Common procurement slugs: - federal-procurement-policy-office (OFPP) - defense-department (DoD) - general-services-administration (GSA) - defense-acquisition-regulations-system (DARS/DFARS) - small-business-administration (SBA) - national-aeronautics-and-space-administration (NASA) - veterans-affairs-department (VA) Parameters: - query: optional case-insensitive substring match against name, short_name, and slug. Recommended: narrow results before pulling full detail. - include_detail: if False (default), returns only id/name/short_name/slug/parent_id. If True, returns all fields (description, urls, etc.). The full dump is ~700KB.

Search GSA CALC+ ceiling rates by keyword. Performs wildcard matching across labor_category, vendor_name, and idv_piid fields. This is the primary search tool for finding rates. Returns matching rate records plus aggregation statistics (wage_stats, percentiles, education breakdown, business size) covering the FULL result set even when individual hits are capped at 10,000. Important notes: - These are NTE (not-to-exceed) ceiling rates, not prices paid - Rates are fully burdened hourly rates from GSA MAS contracts - Data refreshes nightly from vendor price proposal tables - Use P50 from percentiles for median (more accurate than median_price) Filter parameters: - education_level: AA, BA, HS, MA, PHD, TEC (pipe-delimited for OR: 'BA|MA') - experience_min/max: years of experience range - price_min/max: hourly rate range in USD - business_size: 'S' (small) or 'O' (other/large) - security_clearance: 'yes' or 'no' - sin: Special Item Number (e.g., '54151S' for IT Professional Services) - worksite: 'Customer', 'Contractor', or 'Both' ordering: current_price, labor_category, vendor_name, education_level, min_years_experience. sort: 'asc' or 'desc'. exclude: pipe-delimited hit _id values to exclude from results and stats.

Exact match search on a specific field. Use suggest_contains() first to discover the exact field value, then pass it here. The API requires exact string matching -- partial matches return 0 results. Fields: labor_category, vendor_name, idv_piid (GSA MAS contract number).

Discover exact field values via autocomplete/contains matching. Returns aggregation buckets showing matching values and their record counts. Use this BEFORE exact_search() to find the right value string. Minimum 2 characters required for the search term. Example workflow: 1. suggest_contains('vendor_name', 'booz') -> finds 'Booz Allen Hamilton Inc.' 2. exact_search('vendor_name', 'Booz Allen Hamilton Inc.') -> all their rates

Browse rates with filters only (no search keyword). Useful for market segment statistics: "what do all BA-level rates with 5-15 years experience look like across all of GSA MAS?" Returns rate records plus full aggregation statistics.

Get ceiling rate benchmarks for IGCE development. Returns statistical summary for a labor category: count, min, max, avg, median, standard deviation, percentile distribution (P10-P90), education breakdown, and outlier bounds. This is the primary tool for building Independent Government Cost Estimates. The returned statistics represent the market distribution of GSA MAS ceiling rates for comparable labor categories. Reminder: these are ceiling rates (max a contractor can charge), not prices paid. Actual task order rates should be lower per FAR 8.405-2(d).

Evaluate a proposed hourly rate against GSA ceiling rate distribution. Returns the benchmark statistics plus a positioning analysis: z-score, comparison to median, IQR position, and delta from average. Use this for FAR 15.404-1 price analysis: is the proposed rate within the expected range for comparable labor categories on GSA MAS? A rate above P75 may be high; above P90 warrants scrutiny. A rate below P25 may indicate an unrealistically low offer (potential performance risk).

Get all ceiling rates for a specific vendor. Auto-discovers the exact vendor name via suggest-contains, then pulls all their rate records. Returns labor categories, rates, education levels, experience requirements, SINs, and contract numbers. Pass a partial name (e.g., 'booz' for Booz Allen Hamilton). The tool finds the exact registered name automatically. If the discovery term matches multiple vendors, this tool picks the one with the most rate records and returns a _candidates list so the caller can re-query with a more specific term if needed.

Search federal awards (contracts, IDVs, grants, loans, etc.) on USASpending.gov. This is the primary workhorse for finding awards. Returns matching awards with standard fields (Award ID, Recipient, Description, Amount, Agencies, NAICS, PSC, dates). Use get_award_detail() with the generated_internal_id from results to get full award details. Important rules: - award_type groups cannot be mixed; pick one category per call - time_period_start/end use YYYY-MM-DD format - award_amount_min/max are in USD - place_of_performance_state is a 2-letter USPS code (e.g. 'MD', 'VA') - For loans, use award_type='loans' and sort='Loan Value' Filtering to specific contracting commands (NAVSEA, AFRL, etc.): USASpending's subtier level is at the service branch (Department of the Navy, Army, Air Force), not the contracting command. To filter to a specific command, use keywords with the PIID office prefix instead: - NAVSEA contracts: keywords=['N00024'] - Army Contracting: keywords=['W91CRB'] - AFRL: keywords=['FA8650'] - NAVAIR: keywords=['N00019'] This performs a substring match on the PIID field and is more reliable than the award_ids filter for partial matches. Common filter value references: - set_aside_type_codes: SBA, SBP, 8A, 8AN, HZC, HZS, SDVOSBS, SDVOSBC, WOSB, WOSBSS, EDWOSB, EDWOSBSS, VSA - extent_competed_type_codes: A (Full & Open), B, C, D, E, F, G, CDO, NDO - contract_pricing_type_codes: J (FFP), Y (T&M), Z (LH), U (CPFF), V (CPIF), R (CPAF), L (FP Incentive), M (FP Award Fee) IMPORTANT: awarding_agency/funding_agency must be the FULL NAME, not a slug. Use 'Department of the Navy', NOT 'department-of-the-navy'. Slugs silently return zero results. Use list_toptier_agencies() to find exact names.

Count awards matching filters, broken down by award category. Returns counts grouped by: contracts, idvs, grants, loans, direct_payments, other. Use this for dimensional analysis: how many FFP vs T&M awards, how many competed vs sole-source, how many small business set-asides, etc. Unlike search_awards, this returns total counts across ALL award categories in a single call (not just the one specified in award_type). The award_type parameter is ignored here; filters apply to the count query directly. At least one filter is required (the API rejects empty filter sets with HTTP 400). Typical usage: pass time_period_start + time_period_end, or a keywords/agency filter.

Aggregate spending amounts over time, grouped by fiscal year, quarter, or month. Use this to visualize spending trends, identify fiscal-year-end spikes, or compare spending patterns across years. Note: The API returns fiscal_year as a STRING. Cast to int for numeric comparisons. At least one filter is required (the API rejects empty filter sets with HTTP 400). Typical usage: pass time_period_start + time_period_end.

Aggregate spending by a dimension (top vendors, top agencies, top NAICS, etc.). The 'category' parameter controls the grouping dimension. Common uses: - category='recipient': top vendors for a filter set (vendor landscape analysis) - category='awarding_subagency': which contracting offices within an agency - category='naics': which work categories got the most spending - category='psc': which product/service codes got the most spending - category='state_territory': geographic distribution - category='cfda': grant assistance listings Note: recipient category returns vendor names in ALL CAPS and may contain duplicates (subsidiaries, rebrands, re-registrations). For precise market share, apply name normalization to the returned 'name' field.

Fetch full details for a single award by its generated_internal_id. Use the generated_internal_id value returned by search_awards to fetch the complete award record. Returns: PIID, full description, total obligation, recipient details, parent award info, latest transaction contract data (competition, set-aside, pricing type), period of performance, place of performance, NAICS hierarchy, PSC hierarchy, base and all options value, and sub-award totals. Example generated_award_id format: CONT_AWD_N0002424C0085_9700_N0002421D0001_9700

Fetch the full transaction (modification) history for an award. Every modification, option exercise, and de-obligation is a transaction. Modification number '0' is the original base award. Use to understand the full lifecycle of a contract including its descriptive text at each point in time. Returns per transaction: id, type, action_date, action_type, modification_number, description, federal_action_obligation.

Fetch File C funding data for an award: federal account, object class, program activity. Shows which Treasury accounts, object classes, and program activities funded an award. Useful for appropriations analysis and understanding what colors of money paid for what. Sort fields: reporting_fiscal_date, account_title, transaction_obligated_amount, object_class.

Fetch child awards (task/delivery orders) under an IDV. For a Multiple Award IDV, child_awards returns the task orders or delivery orders placed against it. For a parent IDV, child_idvs returns the downstream IDV structure. grandchild_awards walks the hierarchy. Field name differences from search_awards: children use 'piid' (not 'Award ID'), 'obligated_amount' (not 'Award Amount'), and 'generated_unique_award_id' (not 'generated_internal_id').

Get full profile for a recipient by their USASpending hash. Returns recipient details: name, UEI, DUNS, business categories, location, parent (if any), and lifetime award totals. The hash is the 'id' field returned by search_recipients() or autocomplete_recipient(). year: optional 'all' or a fiscal year like '2026'. Default is 'latest'.

Look up awards by PIID or PIID prefix with automatic award-type detection. Convenience tool: tries contracts first, then IDVs if no match. Uses keyword search under the hood, which behaves as a substring match on the PIID field, so you can pass a full PIID or a contracting-office prefix (e.g. 'N00024' for NAVSEA, 'W91CRB' for Army Contracting Command, 'FA8650' for AFRL). Returns the matching awards with basic fields. Use get_award_detail() with the returned generated_internal_id for the full record. Handy for enriching PRISM, Contract Court, or FPDS exports where you have a PIID but don't know whether it's a contract or IDV.

Autocomplete lookup for Product/Service Codes (PSC). Works best with code prefixes ('R499', 'D3', 'AJ') or keywords ('professional', 'application'). Returns matching PSC entries with code and description. Minimum 2 characters required. Single-character queries return first-N alphabetical results from the upstream API (useless for matching) and empty strings return HTTP 400.

Autocomplete lookup for NAICS codes. Accepts partial codes ('541') or keywords ('software'). Returns matching NAICS entries with code and description. Minimum 2 characters required. Short queries silently match substrings inside parenthetical notes (e.g. 'x' matches 'except') and produce nonsense results, so we require 2+ chars. exclude_retired defaults to True. The upstream NAICS taxonomy still returns codes retired in 2012/2017/2022; these are almost never what callers want. Set exclude_retired=False to include them.

List all top-tier federal agencies tracked by USASpending. Returns agency codes, names, abbreviations, and current-year budgetary resources. Use the returned 'toptier_code' values with get_agency_overview().

Get summary information for a specific agency in a given fiscal year. toptier_code is the 3- or 4-digit agency code (e.g. '097' for DoD, '075' for HHS, '080' for NASA). Shorter inputs like '97' are left-padded to '097' automatically. Get valid codes via list_toptier_agencies().

Get award summary totals for an agency in a given fiscal year. Returns obligation totals by award category. toptier_code is auto-padded to 3 digits if a shorter numeric value is supplied.

Get details for a NAICS code (2-6 digits). Returns the NAICS description, parent categories, and child subcategories if applicable.

Get the PSC hierarchy tree. Pass an empty path for the top-level. Drill down with paths like 'Service/R/' to get the service professional services tree, or 'Product/5' for product codes starting with 5.

Get spending profile for a US state by its 2-digit FIPS code. Examples: '06' = California, '48' = Texas, '24' = Maryland, '51' = Virginia. Returns award totals, top agencies, top recipients, and district data.

Search FFATA subaward reports on USASpending. Returns the FFATA subaward records (subcontracts under prime contracts and subawards under prime grants). Complementary to the SAM.gov FFATA endpoints but expressed at the USASpending data model. award_id: optional generated_internal_id (CONT_AWD_..., ASST_NON_..., etc.) to scope subawards to a single prime award. If omitted, returns subawards across all primes for the page. Pagination uses page (1-indexed) and limit (1-100).

Search subawards using the standard filters object (grouped result set). Unlike search_subawards which is scoped to a single prime, this returns subawards grouped under their primes given a filter set similar to search_awards. Useful for FFATA-wide analysis ("show me all DoD subcontracts on cyber awards in FY2026").

Search USASpending recipients (vendors and grantees) by keyword. Returns paginated recipients with their UEI, DUNS, name, and a recipient 'id' that downstream tools use as the hash for get_recipient_profile and get_recipient_children. keyword can match recipient name, UEI, or DUNS. If omitted, returns the top recipients ranked by `sort`.

Get an individual federal account's metadata + budgetary resources.

Get the child recipients (subsidiaries) of a parent recipient hash. Pass a recipient hash with -P (parent) suffix to retrieve subsidiary recipients. The endpoint returns a list of -C suffixed hashes representing children. For -R (regular, no parent) recipients this returns an empty list or 4xx. Useful for mapping corporate structures (e.g. Lockheed Martin -P -> all its subsidiaries -C).

Find recipient hashes by partial name or UEI/DUNS. Returns matching recipients with their hash IDs and metadata. Use the hash from results in get_recipient_profile() or get_recipient_children().

List all states with their FIPS codes and award totals. Returns the full list of US states/territories with FIPS codes you can pass to get_state_profile(). The /recipient/state/ endpoint returns a JSON array (not an object). We wrap it in {"results": [...]} to keep the tool return type consistent with every other endpoint in this MCP.

Get an agency's budgetary resources by fiscal year. Returns total budgetary resources, obligations, outlays, and discretionary vs mandatory breakdown for each fiscal year on file.

List the subordinate (subtier) organizations of a toptier agency. Returns each sub-agency with its obligations, outlays, transaction count, and new-award count for the given fiscal year. Useful for finding the canonical subtier name to pass into search_awards() awarding_subagency.

List the Treasury Account Symbols (federal accounts) used by an agency. Returns each federal account with its obligated amount and gross outlay for the given fiscal year. Useful for understanding how an agency's money flows through Treasury.

List the object class breakdown (what an agency spends money on). Object classes are OMB categories: Personnel Compensation, Travel, Contractual Services, Equipment, Grants, etc. Useful for understanding what types of expenditures an agency makes.

List the program activities (specific programs) within an agency. Program activities are the specific named programs that obligate funds (e.g., 'Cybersecurity and Infrastructure Security Agency'). Useful for pinpointing which program funds a specific activity.

Get an agency's obligation breakdown by award category. Returns total obligated dollars split by category: contracts, IDVs, grants, loans, direct payments, other. Quick way to see what mix of award types an agency uses (heavy contractor agency vs grant-issuing agency vs mixed).

Get a rollup of an award's funding totals. Returns total transaction obligated amount, awarding agency count, funding agency count, and federal account count for a single award. Useful for a one-line summary of an award's funding picture.

Count of subawards (FFATA subcontracts/subawards) reported on an award.

Count of distinct federal accounts (TAS) funding an award.

Count of transactions (modifications) on an award.

Get the timestamp of the last USASpending award data refresh. Use this to determine data freshness when comparing to other sources (SAM.gov Contract Awards API for example).

Get the object class breakdown of obligations for a federal account. Note: this endpoint requires POST (not GET like the other federal account sub-endpoints). Live audit caught this; the body is empty.

Get the program activities funded under a federal account.

Search at the transaction (modification) level. Unlike search_awards which returns one row per award, this returns one row per transaction (initial action plus every modification). Useful for tracking obligation events over time, ceiling adjustments, deobligations, and admin mods. Returns standard transaction fields: Action Date, Mod, Award ID, Action Type, Awarding Agency, Recipient Name.

Geographic breakdown of spending. scope: 'recipient_location' (where the recipient is) or 'place_of_performance' (where the work happens). geo_layer: 'state', 'county', or 'district'.

Pipeline trend of new awards to a recipient over time. REQUIRES recipient_id (the recipient hash with -P suffix for parent-level rollup, or -R for a single recipient). Returns counts of new awards grouped by month, quarter, or fiscal year. The endpoint will reject calls without recipient_id with HTTP 422.

Top-line amounts for an Indefinite Delivery Vehicle (IDV). Returns child IDV count, child award count, child award total obligation, and base/option values rolled up across all task/delivery orders under the IDV. Pass a CONT_IDV_* generated_internal_id.

List the funding records (File C) for an IDV's child orders.

Funding rollup totals for an IDV (single dict, not paginated).

List child task/delivery orders awarded under an IDV.

Find awarding agency names by partial match. USASpending search filters require the EXACT awarding agency name (slugs return zero). Use this to resolve a partial name to the canonical one before passing to search_awards() awarding_agency parameter.

Find funding agency names by partial match (companion to awarding agency).

Find CFDA (Catalog of Federal Domestic Assistance) program numbers by partial title or program number. CFDA codes are used in grants.

Find glossary terms (acquisition + spending vocabulary) by partial match.

Return the full mapping of award type codes to descriptions. Returns the canonical reference: contracts (A=BPA Call, B=Purchase Order, C=Delivery Order, D=Definitive Contract), IDVs, grants, loans, etc. Authoritative source if you're unsure what a code letter means.

Return all Disaster Emergency Fund (DEFC) codes with public laws. DEFCs are used to filter awards funded by specific supplemental appropriations (COVID-19, IIJA, IRA, etc.).

Get the full USASpending glossary of acquisition + spending terms.

Return the list of agency submission periods (when each agency last submitted data for each fiscal period). Useful for understanding which quarters of which fiscal years have full data coverage.

List Treasury federal accounts (TAS) with budgetary resources. keyword filters by account name or AID. fiscal_year defaults to current FY. sort is a dict like {'field':'budgetary_resources','direction':'desc'}.

Get a single-fiscal-year snapshot of a federal account's resources. Important: this endpoint takes the numeric `account_id` (e.g. 4595), NOT the alphanumeric `account_number` (e.g. "027-5183") used by the other federal-account endpoints. The list_federal_accounts response includes both fields per record. Pass the integer account_id here.

Get the most recent available date for a CFR title. CRITICAL: eCFR lags 1-2 business days behind the Federal Register. Using today's date on versioner endpoints causes 404 errors. Call this first to get the safe date, then pass it to other tools. Default title 48 = Federal Acquisition Regulations System (FAR, DFARS, and all agency supplements). Other common titles: 2 (Grants/Agreements), 5 (Administrative Personnel), 29 (Labor), 41 (Public Contracts). Raises ValueError for titles 1-50 that are reserved (no content).

Get the full text of a CFR section, subpart, or part. This is the primary workhorse for reading regulatory text. Returns parsed clean text by default (heading, paragraphs, citations). Set raw_xml=True to get the original XML instead. Specify the narrowest scope possible to keep responses manageable: - section='15.305' for a single FAR section - subpart='15.3' for a subpart - part='15' for an entire part (can be large) - chapter='1' for an entire chapter (often >1 MB, avoid) Date auto-resolves to the latest available if not provided. Do NOT use today's date directly -- eCFR lags 1-2 business days and today often 404s. Title 48 = FAR/DFARS. Chapter 1 = FAR (Parts 1-99), Chapter 2 = DFARS (Parts 200-299). Other chapters = agency FAR supplements (GSAR, VAAR, etc.). For DFARS clauses, use chapter='2' (e.g., section='252.227-7014'). part/subpart/section accept int or string. Common prefix mistakes like section='FAR 15.305' or '48 CFR 15.305' are stripped automatically.

Get the hierarchical table of contents for a CFR title or subset. Returns a nested tree of titles, chapters, parts, subparts, and sections with identifiers, descriptions, and byte sizes. IMPORTANT: Does NOT support section-level filtering (returns 400). Use part or subpart, then walk the children to find sections. Common patterns: - chapter='1' for all FAR parts - chapter='2' for all DFARS parts - part='15' for FAR Part 15 structure - subpart='15.3' for just that subpart's sections part/subpart/chapter accept int or string.

Get the version history of a CFR section, subpart, or part. Returns a list of content versions with dates, amendment info, and whether each version was a substantive text change vs editorial. The 'substantive' field is key: True = the regulatory text actually changed. False = only editorial/formatting change. History goes back to January 2017 only. Pre-2017 changes are not tracked. part/subpart/section accept int or string.

Get the breadcrumb hierarchy path for a section or part. Returns ancestors from title down to the target node: title > chapter > subchapter > part > subpart > section. Useful for understanding where a section sits in the CFR hierarchy and what regulation it belongs to. part/section accept int or string.

Full-text search across the Code of Federal Regulations. Returns matching sections with excerpts, headings, scores, and hierarchy. CRITICAL: Set current_only=True (default) to search only in-effect text. Without it, search returns ALL historical versions including superseded, so a section amended 5 times appears 5 times. Search caps at 10,000 total results. Use hierarchy filters (title, chapter, part) to narrow if you hit the cap. Only 'relevance' ordering is supported. No date or newest sorting. last_modified_after/before use YYYY-MM-DD format and filter by the date sections were last amended. Useful for finding recent regulatory changes. per_page capped at 100 by default (server-side soft cap; API max is 5000).

Get editorial corrections for a CFR title. Returns a list of corrections with CFR references, corrective actions, error dates, and FR citations. Useful for checking whether a section's current text has been corrected since its last amendment. limit caps the number of corrections returned (default 50, max 1000). since_year further filters to corrections with year >= since_year. Title 48 has ~280 corrections across all years; use since_year to focus on recent ones.

Convenience tool: look up the current text of a FAR or DFARS clause. Pass a section identifier like '15.305', '52.212-4', '2.101', etc. Default chapter='1' (FAR). Use chapter='2' for DFARS (e.g., '252.227-7014'). Auto-resolves the latest available date. Returns parsed clean text with heading, paragraphs, and citations. Common FAR sections: 2.101 (Definitions), 9.104-1 (Responsibility), 15.305 (Proposal Evaluation), 19.502-2 (Small Business Set-Asides), 52.212-4 (Commercial Terms), 52.212-5 (Required Commercial Terms).

Compare the text of a CFR section at two different dates. Useful for understanding what changed in a regulatory amendment. Returns the parsed text at both dates side by side. You can then diff the paragraphs to identify specific changes. Dates must be in YYYY-MM-DD format and within the eCFR's tracking range (January 2017 to present). Both dates must not exceed the title's up_to_date_as_of value. This tool always returns the section-level XML parsed -- pass a small section_id like '15.305', not a whole part. Whole-part comparisons can exceed 100 KB per side.

List all sections in a FAR/DFARS part with their headings. Returns a flat list of sections extracted from the structure tree. Useful for understanding the scope of a FAR part before drilling into specific sections. Default chapter='1' (FAR). Use chapter='2' for DFARS. part_number accepts int or string.

Search for a term's definition in FAR 2.101 (master definition section). FAR 2.101 contains definitions used throughout the Federal Acquisition Regulation. This tool fetches the full section and searches for paragraphs containing the term, returning matching paragraphs with surrounding context. Note: FAR 2.101 is large (~109KB XML). This tool parses the full section server-side and returns only matching paragraphs. term must be at least 3 characters. max_matches caps returned matches (default 20, max 100); common terms like 'offeror' hit many paragraphs.

Find CFR sections that have been modified since a given date. Uses the search API with last_modified_on_or_after filter to find sections amended after the specified date. Returns section identifiers, headings, and excerpts. since_date must be in YYYY-MM-DD format. Results are capped at 10,000 by the API. Use title/chapter/part filters to narrow if needed. Common pattern: find FAR changes since a specific date to check for regulatory updates that might affect ongoing acquisitions.

Get wage data for an occupation by SOC code. This is the primary tool for querying BLS OEWS wage statistics. occ_code: 6-digit SOC code without dash (e.g., '151252' for Software Developers, '131082' for Project Management Specialists). See list_common_soc_codes() for common mappings. scope + area_code: - 'national': no area_code needed (all US) - 'state': area_code = 2-digit state FIPS (e.g., '51' for VA, '11' for DC) - 'metro': area_code = 5-digit MSA code (e.g., '47900' for DC metro, '42660' for Seattle). See list_common_metros() for codes. industry: 6-digit industry code for national-only breakdowns. '000000' = all industries (default). Common: '541000' (Professional Services), '541500' (Computer Systems), '999100' (Federal Government). Industry breakdowns only work with scope='national'. datatypes: list of 2-digit codes. Default uses IGCE set: - '04' = Annual Mean Wage - '13' = Annual Median - '11' = Annual 10th Percentile - '15' = Annual 90th Percentile Other: '01' (Employment), '03' (Hourly Mean), '08' (Hourly Median), '12' (25th Percentile), '14' (75th Percentile). CRITICAL: Data year defaults to 2024 (May 2024 estimates). Do NOT pass 2025 or 2026. OEWS data lags ~2 years. Querying the current year returns nothing. Values of '-' mean wage >= $239,200/yr (capped). '*' means sample too small.

Compare wages for one occupation across multiple metro areas. Pass a list of 5-digit MSA codes (e.g., ['47900', '42660', '12580'] for DC, Seattle, Baltimore). Returns the specified wage measure for each metro. Use list_common_metros() to find codes. datatype: '04' (Annual Mean, default), '13' (Median), '03' (Hourly Mean). Max ~12 metros per call (each metro = 1 series, 50 series limit on v2).

Compare wages across multiple occupations in one location. Pass a list of 6-digit SOC codes. Returns the specified wage measure for each occupation. Use list_common_soc_codes() to find codes. Max ~12 occupations per call.

Get wage benchmarks formatted for IGCE development. Returns annual and hourly wages at mean, median, 10th, and 90th percentiles, plus estimated burdened hourly rates using the specified burden multiplier range. BLS wages are BASE wages (no fringe, overhead, G&A, or profit). Multiply by a burden factor to estimate fully-loaded rates: - 1.5x-1.7x: lean contractor - 1.8x-2.2x: mid-range professional services (default) - 2.0x-2.5x: large contractor with clearance overhead - 2.5x-3.0x: high-overhead (SCIF, deployed) The burdened range should roughly align with GSA CALC+ ceiling rates for comparable labor categories. If CALC+ >> burdened BLS, the role may require specialized skills or clearance overhead. Document the gap. Burden multipliers must be positive and burden_low <= burden_high. Reasonable range: 1.3 (lean) to 4.0 (high-overhead/clearance).

Probe the BLS API to check if a newer OEWS data year is available. OEWS data releases annually around April/May. The server defaults to 2024 (May 2024 estimates). This tool checks if 2025 data has been published yet by querying a known-good national series. Call this once at the start of an IGCE build to ensure you're using the latest available data.

List common SOC code mappings for federal IT and professional services. Use these codes with get_wage_data() and other tools. SOC codes are 6 digits without a dash (e.g., '151252' not '15-1252'). For the full SOC list: https://www.bls.gov/oes/current/oes_stru.htm

List common metro area MSA codes for wage lookups. Use these codes with get_wage_data(scope='metro', area_code=...). Pass the 5-digit MSA code (the tool auto-pads to 7 characters). For the full MSA list: https://www.bls.gov/oes/current/msa_def.htm