Find similar records

Use `similar_filter` to start from one GovTribe record and find comparable or related records through supported GovTribe MCP search tools.

Use similar_filter when an agent has one useful GovTribe record and needs to find comparable or related records through a supported Search_* MCP tool. Similarity is useful for follow-on discovery, likely bidders, comparable awards, related opportunities, similar vendors, and past-performance research.

What `similar_filter` does

similar_filter accepts a govtribe_type and govtribe_id for a source record. GovTribe uses that source record's available AI summary to find semantically similar records in the selected search tool.

The selected tool still controls the returned record type, filters, sorts, fields, and whether rows or aggregations are returned. Check the tool page before using similar_filter; not every search tool exposes it.

When to use it

Use similar_filter when the user wants records like a known record, not merely records that share one field value.

User need	MCP pattern
Find likely bidders for an opportunity.	Search vendors or awards with `similar_filter` from the opportunity, plus agency, category, or date filters when needed.
Find predecessor or follow-on work.	Search awards, IDVs, forecasts, or opportunities with `similar_filter` from the known record.
Find comparable past performance.	Search awards using `similar_filter` from a target opportunity or award, then add vendor or category filters if needed.
Expand from one strong file or record.	Search the relevant record type with `similar_filter`, then inspect returned relationship fields.

Use direct ID filters when the user asks for records tied to a specific agency, vendor, category, vehicle, IDV, pursuit, or saved search. Use query when the important part is wording. Use similar_filter when the whole source record is the anchor.

Request shape

similar_filter uses this shape:

{
  "similar_filter": {
    "govtribe_type": "<GOVTRIBE_TYPE>",
    "govtribe_id": "<GOVTRIBE_ID>"
  }
}

The source record must exist and have enough summary content for similarity search. If the tool reports that the ID is invalid or the source record cannot be used for similarity, resolve a different source record or fall back to query plus structured filters.

Add constraints carefully

Combine similar_filter with filters when the user cares about a specific cohort, but avoid over-constraining the request before reviewing the result shape.

Add date filters for recency, due dates, award windows, or completion horizons.
Add agency, vendor, category, location, or set-aside filters only when they are part of the user's actual scope.
Use fields_to_return to keep the first pass compact.
Use aggregations and per_page: 0 when the user needs a cohort summary before individual records.

Examples

Find opportunities similar to a known opportunity:

Tool: Search_Federal_Contract_Opportunities

{
  "similar_filter": {
    "govtribe_type": "federal_contract_opportunity",
    "govtribe_id": "<FEDERAL_CONTRACT_OPPORTUNITY_ID>"
  },
  "due_date_range": {
    "from": "now/d",
    "to": "now+180d/d"
  },
  "fields_to_return": ["govtribe_id", "name", "govtribe_url", "due_date", "federal_agency"],
  "per_page": 10
}

Find comparable awards for past-performance analysis:

Tool: Search_Federal_Contract_Awards

{
  "similar_filter": {
    "govtribe_type": "federal_contract_opportunity",
    "govtribe_id": "<FEDERAL_CONTRACT_OPPORTUNITY_ID>"
  },
  "award_date_range": {
    "from": "now-5y/d",
    "to": "now/d"
  },
  "fields_to_return": [
    "govtribe_id",
    "name",
    "awardee",
    "contracting_federal_agency",
    "dollars_obligated",
    "award_date"
  ],
  "per_page": 10
}

Size a similar-work cohort before reading rows:

Tool: Search_Federal_Contract_Awards

{
  "similar_filter": {
    "govtribe_type": "federal_contract_award",
    "govtribe_id": "<FEDERAL_CONTRACT_AWARD_ID>"
  },
  "award_date_range": {
    "from": "now-3y/d",
    "to": "now/d"
  },
  "aggregations": [
    "top_awardees_by_dollars_obligated",
    "dollars_obligated_stats"
  ],
  "per_page": 0
}

How Similar differs from query and filters

query asks GovTribe to match text or meaning from a user-supplied phrase. Structured filters ask GovTribe to match specific fields or relationships. similar_filter asks GovTribe to use the source record as the semantic anchor.

Do not pair similar_filter with a broad semantic query unless one narrow clarifying phrase is genuinely needed. A broad query can compete with the source-record signal and make the request harder to reason about.

Choose a search mode and write queries: Choose when a normal query is a better fit than similar_filter.
Filter by related records and hierarchies: Use direct relationship filters when the user needs a specific agency, vendor, category, or parent-record relationship.
Manage search context: Use aggregations and focused returned fields before expanding similar results.
Search federal contract opportunities: Review one search tool that supports similar_filter.
Search federal contract awards: Review award filtering, returned fields, and aggregation options.

What similar_filter does