The Coworker Who Actually Asks "Wait, Which Jaguar?"
Every team has the person who answers your question at length, with total confidence, about something you never asked. Most RAG agents are that person. Ask for the price of "apple" and you get a rock-solid answer about the fruit or the company, chosen by a coin flip you never saw happen.
The fix is not a smarter model. It is one instant of humility. Knowing when to ask instead of barreling ahead.
clarifyrag asks only when it is genuinely torn. If the retrieved evidence splits cleanly across two meanings, it asks one sharp question. If one meaning clearly wins, it just answers. No committee, no interrogating you about things that were never ambiguous.
A Gate You Can Read
Zero dependencies, a plain TF-IDF retriever, and a gate that shows its work.
• Ambiguity score: the mass of the runner-up meaning over the top one. Zero is crystal clear, one is a coin flip.
• Lexical backstop: a known trap word (apple, jaguar, python, mercury) with nothing nearby to disambiguate it raises the flag even when the scores alone look borderline.
• Multi-turn: ask, take your hint, then answer, all tracked so you can see how many turns it took and whether it landed.
• Bring your own retriever: swap TF-IDF for a real vector DB behind the same interface and the ask-or-answer logic never changes.
Measuring the Right Thing
The trap was the metric. Grade on accuracy alone and you reward an agent that asks about everything. Grade on speed alone and you reward one that never asks and stays confidently wrong. So each policy is scored as accuracy minus a penalty per question, which finally makes "asks when needed" and "asks about everything" comparable instead of a shouting match about which number matters.
And the gate is never a black box. Every decision comes back with the actual sense ratio and a plain-English reason, which is worth more in a real deployment than a slightly prettier F1.
The Number
Answer everything and you get 77% accuracy at zero questions. Ask about everything and you hit 100% but nag on every obvious query. Clarify only when it counts and you get the same 100% while asking 38% fewer questions. Best of every policy tested.
7 tests green across Python 3.9 through 3.13, with the example and full benchmark on every push.