Clarification behavior

Clarification is the assistant handling comparable matches. It is used when the system has enough evidence to find candidates, but not enough evidence to choose one confidently.

It is different from slot filling. Slot filling asks for a missing value inside a routine. Clarification chooses among options that already matched.

When the assistant asks or offers

The assistant can clarify on conversational chat surfaces in two cases:

• Routine overlap — two or more eligible routines have triggers that match the visitor’s message closely, and they do not have a clear priority winner.
• Ambiguous corpus term — conversational retrieval finds distinct document groups for the same query, such as two different senses of a term.

Routine overlap still uses a clarifying question when there is no clear priority winner. Retrieval-sense clarification is answer-first: when there is no clear winner, Radioso answers using the strongest sense and briefly offers the other intent-phrased option inline. It rarely blocks with a menu — only when two senses are statistically indistinguishable (their confidences fall within a small ask margin), where leading with an arbitrary pick would be worse than asking.

Clarification text is an ordinary assistant message. It is generated from candidate labels and descriptions, not from raw document content or hard-coded wording. Options are phrased as possible visitor intents, not as document titles. Up to four options are considered.

When the assistant does block with a question, the message is a short lead-in followed by the options as a numbered list. The lead-in is the only part the model writes for that turn; the options are assembled from the candidate labels, so the visitor always sees every choice. The visitor can reply by naming an option or by its position, such as “the second one”.

When a visitor chooses a retrieval-sense option, Radioso answers the original question that caused the clarification and limits retrieval to the chosen document group. The short choice reply is only used to select the option.

Standalone retrieval answer calls, document search, SDK retrieval calls, and MCP retrieval tools do not ask clarifying questions. They do not have a conversation turn to resume.

What ignoring an offer does

When a visitor ignores an inline retrieval-sense offer, nothing is charged to the conversation flow. Radioso clears the pending offer and handles the visitor’s latest message as a normal turn. There is no decline message.

The same option set is not offered or asked again immediately. If a blocking clarifying question is answered with “none of these” or with an unrelated message, the pending clarification is also cleared and the assistant continues best-effort.

Why the assistant sometimes picks silently

A silent pick is expected when the system has enough signal to avoid interrupting the visitor.

Radioso silently picks when:

• one candidate clears the confidence margin over the next candidate
• routine candidates are close, but one has a unique highest authored priority
• a routine is already active, including a yielded off-topic turn
• the loop guard would otherwise ask the same clarification again
• retrieval-sense labels cannot be safely phrased as visitor intents; the trace records label_fallback
• the clarifying question could not be phrased as a real question, or fewer than two options remained presentable; the trace records phrasing_fallback

For routine activation, priority is explicit operator arbitration. If comparable routines also tie on priority, the assistant asks instead of guessing.

Why the assistant sometimes answers without clarifying

A compound question can draw its answer from more than one document without being ambiguous. For example, “What is Kriya Yoga and how do I learn it?” is one intent with two facets: what it is, and how to begin. The document groups are complementary, not competing.

In this case Radioso does not ask or offer. It answers once over all the matched groups, so the reply covers every facet. In the debug trace, this turn shows the decision none with the reason compatible_facets. The ask-rate metric counts the same turn as not_clarified (see “Measuring ask-rate”), so the trace value and the metric value differ by design. This judgment is made by the model in the conversation language, so it works the same in any language.

The same answer-without-clarifying path also covers duplicate sources. Sites accumulate these: a published page and a leftover staging draft of it, or a page that was copied and lightly edited. Both copies get ingested, so the same content matches a query twice. Asking which copy the visitor meant is a question with no useful answer, so Radioso answers once over every matched group instead. The trace records this as reason redundant_sources — a distinct value from compatible_facets so you can tell “the model merged duplicate sources” from “the model merged complementary facets” at a glance. A candidate set can mix complementary and redundant groups; when it does, the trace still records redundant_sources, since spotting a duplicate-content merge is more useful to an operator than a complementary one.

To make this call, the model reads a short passage from each group alongside the titles and metadata. Titles alone are not enough to recognise a duplicate: a published page and a draft copy of it, whose titles differ only by a word such as “new” or a leading marker, read as different subjects until you can see that they say the same thing. Passages are used only for this judgment, never to write the option labels the visitor sees. Groups that share nothing but boilerplate — a footer, a contact block, a pricing notice — are not treated as duplicates.

When the model is unsure, or the judgment is missing on any group in the set, Radioso treats the whole set as competing readings and falls back to the normal ask-or-offer behavior — even if every other group in that set was judged complementary or redundant.

For active routines, clarification asks are suppressed. This keeps the active routine as the only state waiting on the visitor’s next message.

Reading the debug view

Open the conversation debug view and look for the Clarification node in the turn flow.

The node appears between the engine and the next capability path. On a turn where the assistant asks a blocking question, it leads directly to the outcome because no routine or retrieval candidate executes yet. On a silent pick or retrieval offer, the turn continues through the routine or retrieval path.

When the agent has directives that apply, a Directives node also appears, fanning into the engine next to the message and history. On a routine-activation clarification it shows the directives that shaped the clarifying question. Only global directives apply here, because no routine is selected yet, so routine- or step-scoped directives cannot match. Open the node to see each matched directive.

The detail panel shows:

• surface — where the ambiguity came from, such as routine_activation or retrieval_sense
• decision — asked, offered, auto_picked, suppressed, or none. A compatible-facets turn shows none here; the ask-rate metric records it as not_clarified
• reason — why the turn resolved the way it did, such as clear_margin, priority, suppressed, loop_guard, label_fallback, phrasing_fallback, compatible_facets, or redundant_sources
• candidates — candidate ids, labels, and confidence values; the chosen winner and offered alternatives are labels only
• offerOutcome — whether an inline offer was accepted as an alternative or ignored, when that outcome is available on the trace
• mappingOutcome — how a later reply resolved, declined, or abandoned the pending clarification

Measuring ask-rate

Every clarification decision is counted in the metric radioso_clarification_decisions_total. It carries three labels: surface, decision, and a bounded reason. The reason explains why a turn resolved the way it did, so you can see how often the assistant asks versus resolves silently.

The label set is small and fixed, so the counter stays low-cardinality. It never contains message text, labels, or document content.

Ask-rate is the share of ambiguity-candidate turns that ended in a blocking question. The denominator must count only fresh ambiguity turns, not the later turns where a visitor answers a prior clarification. Derive it per surface from the counter:

sum(rate(radioso_clarification_decisions_total{surface="retrieval_sense",decision="asked"}[1h]))
/
sum(rate(radioso_clarification_decisions_total{surface="retrieval_sense",decision=~"asked|offered|auto_picked|suppressed|not_clarified"}[1h]))

The denominator is the fresh ambiguity decisions on that surface: asked, offered, auto_picked, suppressed, and not_clarified (reason compatible_facets or redundant_sources). It deliberately excludes the reply-resolution decisions recorded on a later turn when a visitor answers a prior ask or offer — mapped, declined, expired, offer_accepted_alternative, and offer_ignored. Those are second increments for an ask that was already counted, so including them would deflate the true ask-rate. Turns where the system found fewer than two candidates never enter the counter, because they were not ambiguous. A rising ask-rate means the assistant is interrupting more often; compare it against not_clarified and the silent-pick reasons to see where turns are going instead.