Filter by related records and hierarchies

Use this guide when a GovTribe MCP filter seems to include records beyond the exact value supplied. Some filters match a direct field, while others follow a relationship such as a parent agency, category family, awarded vendor role, contact, jurisdiction, IDV, vehicle, file, pursuit, or sub-award connection.

How relationship filters work

GovTribe MCP search filters use structured record relationships. When a request supplies a known agency, vendor, category, contact, jurisdiction, parent record, or workflow record ID, GovTribe searches the relationship named by the filter.

The filter name controls the question being asked. For example, vendor_ids, sub_vendor_ids, primary_consortia_member_ids, contracting_federal_agency_ids, funding_federal_agency_ids, federal_agency_ids, contact_ids, and jurisdiction_ids can point to different relationships even when they all involve familiar organizations or people.

Use the most specific filter available on the selected tool. Use query when the important part is wording in a title, summary, description, file, or source text.

Resolve values before filtering

Prefer GovTribe IDs from earlier search results when a filter expects entities.

Use Source identifiers and record matching when you need to decide whether a value is a GovTribe ID, source identifier, code, or display label.

Hierarchies and parent values

Some filters use hierarchy context so a broader value can find narrower records beneath it.

• Agency filters may include records tied to child offices, bureaus, commands, or related organization levels depending on the selected filter and search tool.
• Category filters may use parent or child NAICS, PSC, NIGP, or UNSPSC context.
• State and jurisdiction filters can separate broad state scope from county, city, school district, and other local-government geography.
• Vehicle, IDV, and subcategory filters can include records connected through a broader buying lane or parent instrument.

When a parent value is selected, results may include child agencies, child categories, or records tied to narrower related values. Request the relationship fields needed to verify the exact child value.

Organization and role filters

Organization filters are role-specific. The same organization can appear in different roles across records.

If a result is connected to the organization but the role feels wrong, check the filter name before changing the query.

Parent and connected records

Some filters match through a parent, container, or connected record rather than a field that appears prominently in the returned row.

• federal_contract_idv_ids, federal_contract_vehicle_ids, and vehicle subcategory filters can find records tied to ordering instruments, schedules, pools, lanes, SINs, or buying channels.
• State and local IDV or vehicle filters can find records connected to state and local parent contract structures.
• Government file and user file filters can use parent record, source record, workspace, pursuit, or file-bearing entity context.
• Workspace filters can narrow by pursuit, pipeline, stage, task, owner, creator, saved search, or workflow state when the selected tool exposes those filters.

Use these filters when the question is about the relationship around a record. Use record-specific tools or returned relationship fields when the agent needs to verify the exact parent, child, source, or downstream connection.

Example

This request asks for awards connected to a contracting-agency role, not just awards whose text mentions the agency name.

Tool: Search_Federal_Contract_Awards

{
  "contracting_federal_agency_ids": ["<FEDERAL_AGENCY_ID>"],
  "award_date_range": {
    "from": "now-12M/d",
    "to": "now/d"
  },
  "fields_to_return": [
    "govtribe_id",
    "name",
    "contracting_federal_agency",
    "funding_federal_agency",
    "awardee",
    "dollars_obligated"
  ],
  "per_page": 10
}

When results look broader than expected

Start by checking the exact filter names and selected values.

• If the request used a parent agency or parent category, results may include child offices, child categories, or records classified under narrower values.
• If the request used an organization ID, confirm whether the filter is for awarded vendor, vendor, contracting agency, funding agency, recipient, subcontractor, or another role.
• If the request used an IDV, vehicle, subcategory, file, pursuit, contact, jurisdiction, or state value, confirm whether the result is connected through a parent or related record.
• If the result set is still too broad, use a more specific child value, add a date or status filter, request fewer result rows, or remove one relationship filter at a time.

Related articles

• Choose a search mode and write queries: Choose keyword or semantic search and shape the query value.
• Troubleshoot search results: Adjust a search call when results are too broad, too narrow, or missing expected records.
• Contracting and funding federal agencies: Choose the right federal agency role when filtering or reviewing federal records.
• Vendor, awardee, recipient, and subcontractor roles: Distinguish awardee, recipient, prime, parent, and subcontractor relationships.
• Choosing category systems: Choose between NAICS, PSC, NIGP, UNSPSC, and Assistance Listings.