Homonym Resolution Prompt for Vector Search

This prompt is designed for vector search engineers and RAG developers who need to improve retrieval precision when user queries contain homonyms—words that are spelled the same but have different meanings. The core job-to-be-done is transforming an ambiguous user query into a contextually disambiguated query that is optimized for dense vector retrieval. The ideal user is someone who has already observed precision failures in their retrieval system, specifically where a query for 'bank' returns financial documents when the user wanted river-related content, or vice versa. You should use this prompt when your vector search index contains documents spanning multiple domains where homonyms are common, and when your existing retrieval pipeline lacks a pre-retrieval disambiguation step.

This prompt is not a general-purpose query rewriter. Do not use it for queries that are ambiguous due to underspecification, missing temporal constraints, or entity collisions that are not homonym-based. It is also not a substitute for a full entity linking system or a knowledge graph. The prompt assumes you have already identified that homonym confusion is a measurable problem in your retrieval metrics. Before implementing, you should have a test set of homonym-heavy queries with known relevant documents so you can measure recall improvement. The prompt requires a domain context to function—without a description of the corpus or the user's likely intent domain, it cannot reliably choose the correct sense of a homonym. In high-stakes domains like legal or medical search, always route the disambiguated query through a human review step before returning results to the user.

After reading this section, you should assess whether homonym confusion is a top-3 retrieval failure mode in your system. If yes, proceed to the prompt template and implementation harness. If your precision problems stem from other ambiguity types—such as acronyms, underspecified constraints, or anaphora—use one of the sibling playbooks in the Query Disambiguation and Ambiguity Resolution group instead. The next section provides the copy-ready prompt template with placeholders you can adapt to your domain.

The prompt below is designed to be dropped into a retrieval pipeline before the embedding step. It takes a raw user query and a domain context description, identifies terms with multiple meanings, selects the most likely interpretation based on the domain, and produces a rewritten query that replaces ambiguous terms with disambiguated phrases. The output includes both the rewritten query and a structured explanation of each homonym resolution so downstream systems can audit the transformation.

textCopy
You are a query disambiguation engine for a vector search system. Your job is to detect homonyms in a user query and rewrite the query to resolve ambiguity before it is embedded for dense retrieval.

## INPUT
User query: [USER_QUERY]
Domain context: [DOMAIN_CONTEXT]

## TASK
1. Identify any terms in the user query that are homonyms—words with multiple distinct meanings that could cause the vector search to retrieve irrelevant documents.
2. For each homonym, determine which meaning is most likely given the domain context.
3. Rewrite the query by replacing each homonym with a short, unambiguous phrase that captures the intended meaning. Do not add new constraints or change the query's intent.
4. If no homonyms are detected, return the original query unchanged.

## OUTPUT SCHEMA
Return a valid JSON object with these fields:
- "original_query": string, the input query exactly as received
- "homonyms_detected": array of objects, each with:
    - "term": string, the homonym word
    - "possible_meanings": array of strings, the distinct meanings identified
    - "selected_meaning": string, the meaning chosen based on domain context
    - "confidence": string, one of "high", "medium", or "low"
- "rewritten_query": string, the query with homonyms replaced by disambiguated phrases
- "no_homonyms_found": boolean, true if no homonyms were detected

## CONSTRAINTS
- Preserve the original query's intent, scope, and specificity.
- Do not introduce new entities, filters, or constraints not implied by the original query.
- If confidence is "low" for any homonym, set a top-level field "requires_clarification": true and include a "clarification_question": string field with a concise question to ask the user.
- Use the domain context to disambiguate. If the domain context is insufficient, default to the most common general meaning and flag low confidence.

## EXAMPLES
Example 1:
User query: "How do I set up a bank account for my mobile app?"
Domain context: "Fintech application development documentation"
Output:
{
  "original_query": "How do I set up a bank account for my mobile app?",
  "homonyms_detected": [
    {
      "term": "bank",
      "possible_meanings": ["financial institution", "river bank"],
      "selected_meaning": "financial institution",
      "confidence": "high"
    }
  ],
  "rewritten_query": "How do I set up a financial institution account for my mobile app?",
  "no_homonyms_found": false
}

Example 2:
User query: "What is the current rate for a crane?"
Domain context: "Construction equipment rental marketplace"
Output:
{
  "original_query": "What is the current rate for a crane?",
  "homonyms_detected": [
    {
      "term": "crane",
      "possible_meanings": ["lifting machine", "bird species"],
      "selected_meaning": "lifting machine",
      "confidence": "high"
    }
  ],
  "rewritten_query": "What is the current rate for a lifting machine crane?",
  "no_homonyms_found": false
}

Example 3:
User query: "Show me the latest pitch deck"
Domain context: "Sales enablement platform"
Output:
{
  "original_query": "Show me the latest pitch deck",
  "homonyms_detected": [
    {
      "term": "pitch",
      "possible_meanings": ["sales presentation", "sports field", "musical tone", "angle of slope"],
      "selected_meaning": "sales presentation",
      "confidence": "high"
    }
  ],
  "rewritten_query": "Show me the latest sales presentation deck",
  "no_homonyms_found": false
}

To adapt this template, replace [USER_QUERY] with the raw user input and [DOMAIN_CONTEXT] with a short description of the knowledge base domain—such as "enterprise HR policy documents" or "medical device regulatory filings." The domain context is the primary signal for disambiguation, so make it specific enough to distinguish between common homonym meanings. If your system has access to user session history or role metadata, consider extending the prompt with a [USER_CONTEXT] placeholder that provides additional disambiguation signals. For production deployments, validate the output JSON against the schema before passing the rewritten query to your embedding model. If requires_clarification is true, route to a human review or clarification step rather than proceeding with a low-confidence rewrite.

This prompt is designed to sit between the user's raw query and your dense retrieval index. It should be called as a pre-retrieval transformation step: the user submits a query, your application sends it to the LLM with this prompt template, receives the disambiguated query and candidate expansions, and then executes the vector search using the rewritten output. The prompt is not a chatbot response—it is a structured query rewriter that must produce machine-consumable output. Wire it as a synchronous step in your retrieval pipeline, not as an optional enhancement. Latency budget is critical here; expect 200-500ms of added latency for the LLM call, which means you should set aggressive timeouts (1-2 seconds) and have a fallback path that sends the original query directly to retrieval if the LLM call fails or times out.

The output schema must be validated before the rewritten query hits your vector database. Require the model to return a JSON object with at minimum a rewritten_query field (the primary query to embed and search) and an expansions array of alternative phrasings for multi-query fusion. Validate that rewritten_query is a non-empty string, that expansions contains no more than [MAX_EXPANSIONS] items, and that none of the outputs are identical to the original query (which would indicate the model failed to detect or resolve any homonym). If validation fails, retry once with the same prompt plus the validation error message appended as a [CORRECTION_FEEDBACK] block. If the retry also fails, log the failure, fall back to the original query, and increment a homonym_resolution_failure metric. For high-stakes domains where incorrect disambiguation could surface misleading results, add a confidence threshold check: if the model's confidence score falls below [CONFIDENCE_THRESHOLD], route the query to a human review queue instead of proceeding automatically.

Model choice matters for this workflow. Smaller or older models often struggle with homonym detection because it requires world knowledge and contextual reasoning. Use a capable instruction-following model (GPT-4-class or equivalent) and set temperature to 0 or very low (0.0-0.1) to maximize deterministic, repeatable outputs. If you are operating in a high-throughput search system where per-query LLM calls are cost-prohibitive, consider caching: maintain an LRU cache keyed by normalized query strings so that repeated queries skip the LLM step entirely. For observability, log every resolution event with the original query, the rewritten query, the detected homonyms, the confidence score, the model version, and whether the result was served from cache, generated fresh, or fell back. This trace data is essential for debugging recall regressions and for building the homonym-heavy test sets that will measure whether this prompt actually improves retrieval precision over time.