# Search\_Mode\_Guide

## Purpose

Use this guide to choose `search_mode` (`keyword` vs `semantic`) for GovTribe `Search_*` requests. Use it when:

* a request needs exact lookup by identifiers, codes, titles, or quoted phrases.
* a request is conceptual and needs meaning-based retrieval.
* the user asks for aggregations, counts, top-N lists, distributions, or trends.
* a request mixes strict identifiers with exploratory context and needs a tie-break decision.

## Decision Checklist

### Parameter Contract

* Omit `search_mode` to use the default keyword behavior.
* Always include `query`.
* Keep mode and query style aligned:
  * `keyword`: exact tokens, identifiers, and literal overlap.
  * `semantic`: plain-language intent and conceptual similarity.

### Aggregations Support

* Aggregations and rollups should use the default keyword behavior.
* Aggregation signals include totals, counts, top-N lists, breakdowns by field, distributions, and time-series trends.
* Set `search_mode: "semantic"` only when you intentionally want semantic retrieval; it should not be the default for aggregation-driven asks.

### Keyword Mode

* What it does:
  * prioritizes lexical and phrase overlap with typo tolerance.
* Strengths:
  * best for exact identifiers, codes, titles, quoted phrases, and short specific lookups.
  * supports aggregation workflows.
* Limitations:
  * weaker for broad conceptual asks where synonym coverage drives relevance.
* Choose `keyword` when:
  * a query includes identifier-like tokens (for example solicitation IDs, UEI/CAGE, NAICS/PSC).
  * a query includes quoted text or exact title/name intent.
  * the request is a direct lookup or navigation to a specific item.
  * the query is short and specific (roughly 1-3 salient tokens).

### Semantic Mode

* What it does:
  * prioritizes conceptual similarity and meaning over strict token overlap.
* Strengths:
  * best for exploratory requests such as “similar to,” “alternatives,” and “ways to.”
  * handles synonym-heavy and wording-variable topics.
* Limitations:
  * does not reliably support aggregation-heavy workflows.
  * can underweight strict identifier precision.
* Choose `semantic` when:
  * the request is conceptual, exploratory, or intent-driven.
  * the query reads like a question or guidance ask.
  * the topic is broad/ambiguous and depends on synonym matching.

### One-Screen Decision Checklist

* Choose `keyword` if any are true:
  * the query includes quoted text.
  * the query includes identifier-like tokens or strict codes.
  * the intent is direct lookup.
  * the user asks for aggregations or rollups.
* Choose `semantic` if any are true:
  * the request asks for similar, related, or alternative results.
  * the query is conceptual and meaning-driven.
  * the query has no unique identifiers and would benefit from synonym matching.
* Tie-breakers:
  * unique identifier plus conceptual context: choose `keyword` and keep the ID explicit.
  * no unique tokens and broad concept: choose `semantic`.
  * strict phrase plus “similar to”: choose `semantic` unless a unique ID is present.

## Examples

### Default Keyword-Behavior Examples

Exact solicitation lookup: Tool: `Search_Federal_Contract_Opportunities`

```json
{
  "query": "\"W912HQ-24-R-0123\""
}
```

Quoted phrase and entity lookup: Tool: `Search_Federal_Contract_Opportunities`

```json
{
  "query": "\"CISA\" \"endpoint detection\" RFI"
}
```

Aggregation-driven request with structured filters: Tool: `Search_Federal_Contract_Awards`

```json
{
  "query": "",
  "aggregations": ["top_awardees_by_dollars_obligated"],
  "naics_category_ids": ["541512"],
  "naics_category_ids_operator": "in"
}
```

### Semantic Mode Examples

Conceptual similarity request: Tool: `Search_Federal_Contract_Opportunities`

```json
{
  "query": "find opportunities similar to FAA SWIM support for aviation data integration",
  "search_mode": "semantic"
}
```

Alternatives-oriented discovery request: Tool: `Search_Federal_Contract_Opportunities`

```json
{
  "query": "alternatives to legacy ERP modernization support contracts for defense logistics organizations",
  "search_mode": "semantic"
}
```

Broad intent without unique identifiers: Tool: `Search_Federal_Contract_Opportunities`

```json
{
  "query": "ways to find recompete opportunities for small business cloud modernization work",
  "search_mode": "semantic"
}
```