When retrieval or refinement results rank low relative to the query, use MCP elicitation to ask the user for clarification rather than silently returning weak results. Elicitation is a feature of the retrieve and refine tools, not a separate MCP tool.
Pattern: On the modern MCP protocol (2026-07-28), use the guard pattern with InputRequiredResult. The retrieve tool checks result confidence (e.g., top-k cosine similarity below a threshold). If low, it returns an InputRequiredResult with an elicitation request: "This question didn't map well to the available data. Could you elaborate on what you're looking for?" The client prompts the user, then re-calls retrieve with the enriched query. The rewriter gets better input, retrieval improves. Same pattern applies to refine when the tool can't determine what the agent wants.
Implementation reference: FastMCP elicitation docs: https://gofastmcp.com/servers/elicitation -- specifically the guard pattern section. The tool runs from the top each round, checks ctx.input_responses for prior answers, and either asks for more or proceeds. Stateless between rounds.
Design principle: Elicitation is internal to retrieve and refine, not a separate tool in the MCP surface. The agent calls retrieve, and retrieve itself decides whether to ask for clarification. This keeps the six-tool MCP surface clean (list_sources, describe_source, retrieve, refine, write, request_access). See [[design-platform-not-agent]] memory.
Design considerations:
- Confidence threshold: what score or score distribution triggers elicitation? A single low top-1 score, or a flat distribution across top-k?
- The elicitation request should surface what the system did find (partial results) alongside the clarification ask, so the user has context for refining their query.
- Should work with the rewriter: the enriched query from elicitation gets rewritten, so the user's clarification benefits from vocabulary mapping and semantic context.
- On older MCP protocol versions, fall back to
ctx.elicit() (back-channel pattern).
Future epic -- not part of eval-convergence or refine-tool.
When retrieval or refinement results rank low relative to the query, use MCP elicitation to ask the user for clarification rather than silently returning weak results. Elicitation is a feature of the retrieve and refine tools, not a separate MCP tool.
Pattern: On the modern MCP protocol (2026-07-28), use the guard pattern with
InputRequiredResult. The retrieve tool checks result confidence (e.g., top-k cosine similarity below a threshold). If low, it returns anInputRequiredResultwith an elicitation request: "This question didn't map well to the available data. Could you elaborate on what you're looking for?" The client prompts the user, then re-calls retrieve with the enriched query. The rewriter gets better input, retrieval improves. Same pattern applies to refine when the tool can't determine what the agent wants.Implementation reference: FastMCP elicitation docs: https://gofastmcp.com/servers/elicitation -- specifically the guard pattern section. The tool runs from the top each round, checks
ctx.input_responsesfor prior answers, and either asks for more or proceeds. Stateless between rounds.Design principle: Elicitation is internal to retrieve and refine, not a separate tool in the MCP surface. The agent calls retrieve, and retrieve itself decides whether to ask for clarification. This keeps the six-tool MCP surface clean (list_sources, describe_source, retrieve, refine, write, request_access). See [[design-platform-not-agent]] memory.
Design considerations:
ctx.elicit()(back-channel pattern).Future epic -- not part of eval-convergence or refine-tool.